​
Incoming Tools

Zylon’s assistant can seamlessly interact with external tools and functions, significantly broadening its capabilities and enabling it to handle a wider variety of tasks directly inside conversations. Tools can be invoked and managed in real time within dialogues, allowing the assistant to dynamically integrate them into its responses. Within this framework, tools fall into two main categories:
  • Built-in Tools: Built-in Tools: Zylon provides four ready-to-use tools designed for the most common scenarios.
  • Custom Tools : You can create your own tools tailored to specific workflows, defining parameters, supported operations, and unique behaviors to match specialized requirements.
Built-in vs Custom Tools: Zylon equips you with flexible built-in tools for everyday tasks, while also giving you the freedom to design custom solutions for advanced or domain-specific needs.

​
Core Configuration Fields

When integrating tools with the Messages API, you’ll work with three main configuration objects:

​
tools - Tool Specifications Array

Defines which tools are available for the AI to use during the conversation. 
interface ToolSpec {
  name: string;           // Required: Unique identifier
  type?: string;          // For built-in tools (e.g., "database_query_v1")
  description?: string;   // Necessary for custom tools
  inputSchema?: object;   // For custom tools - JSON Schema
}
The toolspec object defines a single tool and is used inside the tools parameter, which accepts an array of toolspec objects.

​
Tool Specification Requirements

  • For built-in tools, it is necessary to specify the name and type fields.
  • For custom tools, you must provide at least the following fields:
    • name: unique identifier for the tool
    • description: a human-readable explanation of what the tool does
    • input_schema: defines the structure of the input parameters expected by the tool, typically in JSON Schema format.

​
tool_choice - Selection Strategy

Controls how the AI decides when and which tools to use. 
interface ToolChoice {
  type: "auto" | "tool" | "none";  // Default: "auto"
  name?: string;                   // Name of the tool
  disable_parallel_tool_use?: boolean;  // Default: false
  validation_mode?: "eager" | "lazy";   // Default: "lazy"
}
The tool_choice parameter allows you to control the criteria for selecting which tool the AI should use and when:
  • type (Default: "auto"):
    • "auto": The system automatically decides which tool(s) to use based on the list provided in tools.
    • "tool": Instructs the system to use an specific tool.
    • "none": Instructs the system not to use any tools.
  • name (Required if type is "tool"): The name of the tool to invoke explicitly.
  • disable_parallel_tool_use (Default: false): If set to true, prevents calling multiple tools simultaneously.
  • validation_mode (Default: "lazy"):
    • "eager": Validate tool calls before execution.
    • "lazy": Validate tool calls only when actually invoked.

​
tool_context - Contextual Data

Provides the context for tools. 
type ToolContext = Array< IngestedArtifact | SqlDatabaseArtifact>
The type of tool_context depends on the tool selected, as described in Context Artifacts section of the documentation.

​
How to Configure Tool Usage

​
Using Built-in Tools

When working with built-in tools:
  1. Define your tool(s) in the tools array using name and type fields.
  2. Provide the corresponding tool_context with the appropriate artifact type that matches the tool’s requirements (see Context Artifacts).
  3. Optionally configure how tools are selected with tool_choice. By default, this is set to "auto" for dynamic tool selection.

​
Using Custom Tools

For custom tools:
  1. Specify name, description, and a valid input_schema in the tool specification.
  2. Optionally configure how tools are selected with tool_choice.

​
Context Artifacts

Different tools require specific artifact types depending on the nature of the task. Selecting the correct context artifact is essential for proper execution.
ToolIngested ArtifactSqlDatabase ArtifactNotes
semantic_search_v1✓x
tabular_analysis_v1✓x
database_query_v1x✓
web_extract_v1xxWeb URL must be included in message content

​
Ingested Artifact

Used for already processed or ingested content such as documents, spreadsheets, or HTML files. 
{
    "type": "ingested_artifact",
    "context_filter": {
        "collection": "pgpt_collection",
        "artifacts": ["artifact_id_1", "artifact_id_2"],
        "metadata_filter": [
            {
                "key": "file_id",
                "operator": "==",
                "value": "artifact_id_1"
            }
        ]
    }
}

​
SQL Database Artifact

Used for connecting and interacting with SQL databases. Allows specifying connection strings, schemas, and SSL configuration. 
{
    "type": "sql_database",
    "connection_string": "postgresql://user:pass@host:5432/db",
    "schema": "public"
}
Context Matching: Ensure your tool context matches the requirements of your selected tools. Different tools expect different artifact types.

​
Built-in Tools

Zylon provides four built-in tools available for immediate use:
ToolPurpose
semantic_search_v1Perform semantic search across documentsSemantic Search Tool
tabular_analysis_v1Analyze structured data (CSV, Excel)Tabular Analysis Tool
web_extract_v1Extract and analyze web contentWeb Extract Tool
database_query_v1Execute SQL database operationsDatabase Query Tool

​
Custom Tools

You can create custom tools tailored to your own business logic, workflows, or specific requirements. Custom Tools