> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Enable built-in and custom tools in Messages.

<Warning>
  **Upcoming release — Zylon 1.58**

  These 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](/en/v1.57/overview).
</Warning>

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](/en/v1.58/developer-manual/get-started/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:

```bash theme={null}
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" }
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  { "valid": true, "errors": null }
  ```
</Accordion>

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:

* [Semantic Search tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool)
* [Tabular Analysis tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/tabular-analysis-tool)
* [Web Fetch tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool)
* [Web Search tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/web-search-tool)
* [Database Query tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/database-query-tool)
* [Code Execution tool](/en/v1.58/developer-manual/build-with-zylon/tools/built-in/code-execution-tool)

### 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` |

```json theme={null}
[
  { "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](#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](/en/v1.58/developer-manual/build-with-zylon/tools/custom/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](/en/v1.58/developer-manual/build-with-zylon/working-with-messages)
* Ingest content for retrieval and analysis: [Artifacts](/en/v1.58/developer-manual/build-with-zylon/working-with-artifacts)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.