Custom tools

Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.

Custom tools let you define a tool interface (name + JSON schema) and let the assistant choose when to call it. When it calls your tool, it returns a tool_use content block with structured input.

Prerequisites

An API token. See Backoffice Developer Console.

Requirements

In the tools array, provide:

name: unique tool name
description: what the tool does
inputSchema: JSON Schema describing the tool input

Basic request and response

This example validates a request that defines a tiny calculator tool and forces its use.

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 64,
    "messages": [
      { "role": "user", "content": "Add 5 and 7." }
    ],
    "tools": [
      {
        "name": "simple_calculator",
        "description": "Add two numbers.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "a": { "type": "number" },
            "b": { "type": "number" }
          },
          "required": ["a", "b"]
        }
      }
    ],
    "tool_choice": { "type": "tool", "name": "simple_calculator" }
  }'

Example response:

{ "valid": true, "errors": null }

To run the request, send the same body to POST /messages. When the assistant returns a tool_use block, execute your tool and include a tool_result block in the next message.

Only custom tools use tool_use and tool_result. Built-in tools run on the server and return server_tool_use blocks followed by their result; don’t send results back for them. See How built-in tool results are returned.

First Steps

Build with Zylon

Coding Agents

Custom tools

Prerequisites

Requirements

Basic request and response

​Prerequisites

​Requirements

​Basic request and response

Prerequisites

Requirements

Basic request and response