Skip to main content

​
How it Works

When you add a custom tool to your API request, Zylon follows these steps:
  1. Analyzes user intent: Zylon determines if your custom tool is appropriate for answering the user’s query.
  2. Awaits implementation: Returns the tool call for you to process and implement the actual functionality.

​
Important Notes

  • Custom tools require you to define the name, description, and input_schema.
  • The input_schema follows JSON Schema specification.
  • No tool_context is required for custom tools.

​
Example Usage

In this practical example, we create a simple calculator tool that performs basic arithmetic operations.
1

Define Custom Tool

Create your custom tool by defining its name, description, and input schema. Then call the API with your custom tool definition.
curl --location 'https://<your-host>/api/gpt/v1/messages' \
--header 'Authorization: Bearer <your-token>' \
--header 'x-org: default' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {
      "role": "user",
      "content": "Calculate the sum of 5 and 7"
    }
  ],
  "tools": [
    {
      "name": "simple_calculator",
      "description": "Performs basic arithmetic operations like addition",
      "input_schema": {
        "type": "object",
        "properties": {
          "operation": {
            "type": "string",
            "enum": ["add"]
          },
          "operands": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 2,
            "maxItems": 2
          }
        },
        "required": ["operation", "operands"]
      }
    }
  ],
  "tool_choice": {
    "type": "tool",
    "name": "simple_calculator"
  }
}'
2

Response

The system responds with the structured tool call that matches your input schema. You then need to implement the actual functionality:
 {
   "id": "msg_2a8d92b196344ce79027913550999b44",
   "type": "message",
   "role": "assistant",
   "content": [
       {
           "type": "tool_use",
           "start_timestamp": "2025-09-24T14:28:52.825850Z",
           "stop_timestamp": "2025-09-24T14:28:54.230904Z",
           "id": "toolu_01997c208fd97f2f9ba7c374eadad060",
           "name": "simple_calculator",
           "input": {
               "operation": "add",
               "operands": [
                   5,
                   7
               ]
           }
       }
   ],
   "model": "private-gpt",
   "stop_reason": "tool_use",
   "stop_sequence": null,
   "usage": {
       "input_tokens": null,
       "output_tokens": null
   }
}