CORE CONCEPTS
Tools & Functions
Tools extend your agent's capabilities beyond text generation. They allow agents to look up data, call APIs, update databases, send notifications, and take any action your business requires.
What Are Tools?
A tool is a function that your agent can call during a conversation. When the agent decides it needs external data or needs to perform an action, it generates a tool call with the appropriate parameters. The SDK executes the tool and feeds the result back to the agent.
The flow works like this:
- 1.User sends a message to the agent
- 2.Agent determines it needs to call a tool
- 3.SDK sends a POST request to the tool's handler URL
- 4.Handler processes the request and returns JSON
- 5.Agent uses the result to generate a response
Tool Schema Format
Tools are defined using JSON Schema for parameter validation. Here is the full schema for a tool definition:
Tool schema
{
name: string; // unique identifier (snake_case)
description: string; // what the tool does (shown to the model)
parameters: { // JSON Schema for input validation
type: "object";
properties: {
[key: string]: {
type: string; // "string", "number", "boolean", "array", "object"
description?: string;
enum?: string[];
items?: object; // for arrays
format?: string; // "email", "uri", "date-time", etc.
};
};
required?: string[]; // required parameter names
};
handler: string; // webhook URL that processes the tool call
timeout?: number; // handler timeout in ms (default: 10000)
retries?: number; // retry count on failure (default: 0)
}
Built-in vs Custom Tools
The SDK provides several built-in tools that require no webhook setup:
ToolDescription
web_searchSearch the web and return relevant results
calculatorPerform mathematical calculations
datetimeGet current date, time, and timezone data
json_validatorValidate JSON against a schema
text_summarizerSummarize long text into key points
Using built-in tools
const agent = await client.agents.create({
name: "Research Agent",
model: "claude-sonnet-4-20250514",
systemPrompt: "You are a research agent...",
tools: [
{ builtin: "web_search" },
{ builtin: "calculator" },
// Plus your custom tools
{
name: "query_database",
description: "Query the company database",
parameters: { /* ... */ },
handler: "https://api.example.com/webhooks/query",
},
],
});
Tool Handlers
Tool handlers are webhook endpoints that receive tool calls and return results. The SDK sends a POST request with the following format:
Incoming request to your handler
POST https://api.example.com/webhooks/lookup-order
Content-Type: application/json
X-YA-Signature: sha256=abc123...
{
"toolCallId": "tc_abc123",
"agentId": "agt_def456",
"executionId": "exec_ghi789",
"name": "lookup_order",
"parameters": {
"orderId": "ORD-12345"
}
}
Your handler should return a JSON response:
Handler response
// Success
{
"result": {
"orderId": "ORD-12345",
"status": "shipped",
"trackingNumber": "1Z999AA10123456784",
"estimatedDelivery": "2026-03-20"
}
}
// Error
{
"error": {
"code": "NOT_FOUND",
"message": "Order ORD-12345 not found"
}
}
Note
Verify the X-YA-Signature header to ensure requests are from YourAutomation. See the Webhooks guide for signature verification.
Tool Examples
1. Database Query
Database query tool
{
name: "query_customers",
description: "Search for customers by name, email, or account ID",
parameters: {
type: "object",
properties: {
query: { type: "string", description: "Search query" },
field: {
type: "string",
enum: ["name", "email", "account_id"],
description: "Field to search",
},
limit: { type: "number", description: "Max results (default 10)" },
},
required: ["query", "field"],
},
handler: "https://api.example.com/webhooks/customers/search",
}
2. Email Sender
Email tool
{
name: "send_email",
description: "Send an email to a customer",
parameters: {
type: "object",
properties: {
to: { type: "string", format: "email" },
subject: { type: "string", maxLength: 200 },
body: { type: "string" },
template: { type: "string", enum: ["receipt", "shipping", "return_label"] },
},
required: ["to", "subject"],
},
handler: "https://api.example.com/webhooks/email/send",
}
3. Calendar Booking
Calendar tool
{
name: "book_meeting",
description: "Schedule a meeting on the calendar",
parameters: {
type: "object",
properties: {
title: { type: "string" },
date: { type: "string", format: "date" },
time: { type: "string", description: "HH:MM format" },
duration: { type: "number", description: "Duration in minutes" },
attendees: {
type: "array",
items: { type: "string", format: "email" },
},
},
required: ["title", "date", "time", "duration"],
},
handler: "https://api.example.com/webhooks/calendar/book",
}
4. Inventory Check
Inventory tool
{
name: "check_inventory",
description: "Check product availability and stock levels",
parameters: {
type: "object",
properties: {
productId: { type: "string" },
warehouse: { type: "string", enum: ["us-east", "us-west", "eu"] },
},
required: ["productId"],
},
handler: "https://api.example.com/webhooks/inventory/check",
}
5. Slack Notification
Slack tool
{
name: "notify_slack",
description: "Send a notification to a Slack channel",
parameters: {
type: "object",
properties: {
channel: { type: "string", description: "#channel-name" },
message: { type: "string" },
urgency: { type: "string", enum: ["normal", "important", "urgent"] },
},
required: ["channel", "message"],
},
handler: "https://api.example.com/webhooks/slack/notify",
}
Error Handling
When a tool handler fails, the SDK provides the error context to the agent so it can respond appropriately:
Tool error handling
// The agent receives tool errors automatically
// You can also handle them in your execution callback:
const result = await client.agents.execute(agent.id, {
input: "Look up order ORD-99999",
onToolError: (error) => {
console.error("Tool failed:", error.toolName, error.message);
// Return a fallback response
return {
result: { error: "Order not found. Please verify the order number." },
};
},
});
If no onToolError handler is provided, the agent is informed of the error and will attempt to handle it gracefully in its response to the user.