Overview

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.

Tools let the assistant run targeted operations (like searching artifacts, analyzing tabular data, or extracting a web page) as part of a message response. You enable tools by adding three fields to a POST /messages request:

Field	Purpose
`tools`	Which tools are allowed.
`tool_choice`	How the assistant should choose tools (`auto`, force a specific tool, or `none`).
`tool_context`	Optional context artifacts (documents or database connections).

Prerequisites

An API token. See Backoffice Developer Console.
Your Zylon hostname (replace {BASE_URL} in the examples).

Basic request and response

When you’re iterating on tool configuration, start with POST /messages/validate to validate your request body without running a model. This example enables the web fetch tool:

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": "Summarize: https://example.com/" }
    ],
    "tools": [
      { "name": "web_extract", "type": "web_extract_v1" }
    ],
    "tool_choice": { "type": "auto" }
  }'

Example response

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

To actually run the request, send the same body to POST /messages.

Built-in tools

Zylon includes a set of built-in tools you can enable by name + type:

Tool type	What it does	Requires `tool_context`
`semantic_search_v1`	Search ingested artifacts	Yes (`ingested_artifact`)
`tabular_analysis_v1`	Analyze tabular artifacts	Yes (`ingested_artifact`)
`web_extract_v1`	Fetch and extract a URL mentioned in the message	No
`web_search_v1`	Search the web from a natural language query	No
`database_query_v1`	Query a SQL database from natural language	Yes (`sql_database`)
`code_execution_v1`	Run bash commands and edit files in a sandboxed container	No

Guides:

How built-in tool results are returned

Zylon runs built-in tools on the server, inside the same request. Each call appears in the response as a server_tool_use block (ID prefix srvtoolu_), followed by its result block:

Tool	Result block
`semantic_search`, `tabular_analysis`, `database_query`, `summarize`, `present_files`, skills, MCP tools	`server_tool_result` (`content`, `is_error`)
`web_search`	`web_search_tool_result`
`web_fetch`	`web_fetch_tool_result`
Code execution: `bash_code_execution`	`bash_code_execution_tool_result`
Code execution: `text_editor_code_execution`	`text_editor_code_execution_tool_result`

[
  { "type": "server_tool_use", "id": "srvtoolu_9c0d", "name": "semantic_search", "input": { "query": "billing issues" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_9c0d",
    "content": [{ "type": "text", "text": "Customers reported duplicate charges after the plan change." }],
    "is_error": false
  }
]

Don’t send results back for built-in tools: Zylon has already run them. stop_reason: "tool_use" and tool_result blocks apply only to custom tools. Each tool guide shows its result format.

Custom tools

Custom tools let you define your own tool interface using JSON Schema. When the assistant chooses your tool, it returns a tool_use content block with structured input. See: Custom tools

Common mistakes

Using the wrong field name: tool schemas use inputSchema (not input_schema).
Missing tool context: semantic_search_v1, tabular_analysis_v1, and database_query_v1 need tool_context.
Forgetting auth: include Authorization: Bearer ... on every request.

Next steps

Learn the Messages request format: Messages
Ingest content for retrieval and analysis: Artifacts

First Steps

Build with Zylon

Coding Agents

Prerequisites

Basic request and response

Built-in tools

How built-in tool results are returned

Custom tools

Common mistakes

Next steps

​Prerequisites

​Basic request and response

​Built-in tools

​How built-in tool results are returned

​Custom tools

​Common mistakes

​Next steps

Prerequisites

Basic request and response

Built-in tools

How built-in tool results are returned

Custom tools

Common mistakes

Next steps