Skip to main content
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:
FieldPurpose
toolsWhich tools are allowed.
tool_choiceHow the assistant should choose tools (auto, force a specific tool, or none).
tool_contextOptional context artifacts (documents or database connections).

​
Prerequisites

  • An API token. See Token Management.
  • 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" }
  }'

{ "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 typeWhat it doesRequires tool_context
semantic_search_v1Search ingested artifactsYes (ingested_artifact)
tabular_analysis_v1Analyze tabular artifactsYes (ingested_artifact)
web_extract_v1Fetch and extract a URL mentioned in the messageNo
web_search_v1Search the web from a natural language queryNo
database_query_v1Query a SQL database from natural languageYes (sql_database)
Guides:

​
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