> ## Documentation Index > Fetch the complete documentation index at: https://docs.iwy.ai/llms.txt > Use this file to discover all available pages before exploring further. # Tools > Extend your agents with custom functions via webhooks ## Overview Tools are custom functions that give your agents the ability to interact with external services. When a user asks your agent to do something that requires external data or actions, the agent can call a tool to fulfill the request. **Tools work with both agent types.** You can attach tools to Single-Use agents and Permanent agents. The tool definitions are always stored in your account and managed via the dashboard or API. *** ## How Tools Work ``` User: "What's the weather in Paris?" ↓ Agent recognizes it needs weather data ↓ Agent calls your `get_weather` tool ↓ Your webhook receives: { "city": "Paris" } ↓ Your webhook returns: { "temperature": 18, "conditions": "Sunny" } ↓ Agent: "It's currently 18°C and sunny in Paris!" ``` 1. **You define the tool** - Name, description, parameters schema, and your webhook URL 2. **You attach it to an agent** - Via dashboard or API 3. **Agent decides when to call it** - Based on the conversation and your tool's description 4. **Your webhook executes** - Receives the parameters, performs the action, returns a response 5. **Agent uses the response** - Incorporates the data into its reply *** ## Tool Configuration Each tool consists of: | Field | Required | Description | | ------------------- | -------- | -------------------------------------------------------- | | `name` | Yes | Function name (snake\_case recommended) | | `description` | Yes | What the tool does—helps the agent decide when to use it | | `server_url` | Yes | Your webhook endpoint URL | | `parameters_schema` | Yes | JSON Schema defining expected inputs | | `method` | No | HTTP method (default: POST) | | `headers` | No | Custom headers for authentication | | `timeout_seconds` | No | Request timeout (default: 20s, max: 300s) | ### Example Tool Definition ```json theme={"dark"} { "name": "get_weather", "description": "Fetches the current weather for a given city. Use this when the user asks about weather conditions.", "server_url": "https://your-api.com/weather", "parameters_schema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string", "description": "City name (e.g., 'Paris', 'New York')" }, "units": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature units (default: celsius)" } } }, "method": "POST", "headers": { "x-api-key": "your-webhook-api-key" }, "timeout_seconds": 15 } ``` *** ## Webhook Request Format When the agent calls your tool, your webhook receives a POST request with: ```json theme={"dark"} { "tool_id": "dcfae097-1b37-4444-bb0c-1a6abb0320fd", "tool_name": "get_weather", "parameters": { "city": "Paris", "units": "celsius" } } ``` Your webhook should return JSON: ```json theme={"dark"} { "temperature": 18, "conditions": "Partly cloudy", "humidity": 65 } ``` **Your webhook must respond within the timeout.** If your webhook takes too long, the tool call will fail and the agent will tell the user it couldn't complete the action. Default timeout is 20 seconds. *** ## Writing Good Tool Descriptions The `description` field is critical—it tells the agent when to use the tool. Write descriptions that: **Do:** * Explain what the tool does in plain language * Mention trigger phrases users might say * Specify what information the tool provides **Don't:** * Be vague ("Does stuff with data") * Assume the agent knows your business context ### Examples | Good | Bad | | ---------------------------------------------------------------------------------------------------------------------- | ---------------- | | "Fetches the current weather for a given city. Use when the user asks about weather, temperature, or conditions." | "Weather tool" | | "Searches the product catalog and returns matching items. Use when users ask about products, prices, or availability." | "Product search" | | "Books an appointment at the specified date and time. Use when users want to schedule a meeting or consultation." | "Booking system" | *** ## Parameters Schema Tools use [JSON Schema](https://json-schema.org/) to define their parameters. The agent uses this schema to extract the right information from the conversation. ### Basic Types ```json theme={"dark"} { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "description": "User's email address" }, "quantity": { "type": "integer", "description": "Number of items", "minimum": 1, "maximum": 100 }, "subscribe": { "type": "boolean", "description": "Whether to subscribe to newsletter" } } } ``` ### Enum Values ```json theme={"dark"} { "type": "object", "properties": { "priority": { "type": "string", "enum": ["low", "medium", "high"], "description": "Task priority level" } } } ``` ### Nested Objects ```json theme={"dark"} { "type": "object", "properties": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" } } } } } ``` *** ## Attaching Tools to Agents ### Via Dashboard 1. Go to [dashboard.iwy.ai](https://app.iwy.ai) 2. Create or edit an agent 3. In the "Tools" section, select the tools you want to attach ### Via API (Permanent Agents) When creating or updating a permanent agent, include the tool IDs: ```bash theme={"dark"} curl -X POST https://api.iwy.ai/v1/agent \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support Agent", "configuration": { "llm": { ... }, "tool_calling": { "selected_tool_ids": [ "dcfae097-1b37-4444-bb0c-1a6abb0320fd", "582bf240-4b4d-4df3-bfac-83c955d4d49b" ] } } }' ``` ### Via API (Single-Use Agents) Single-use agents can also use tools by including the tool IDs in the configuration: ```bash theme={"dark"} curl -X POST https://api.iwy.ai/v1/ephemeral-agent \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "configuration": { "llm": { ... }, "tool_calling": { "selected_tool_ids": ["dcfae097-1b37-4444-bb0c-1a6abb0320fd"] } }, "ttl_seconds": 600 }' ``` *** ## Testing Tools Before attaching a tool to an agent, test it to make sure your webhook is working correctly: ```bash theme={"dark"} curl -X POST https://api.iwy.ai/v1/tool/YOUR_TOOL_ID/test \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "parameters": { "city": "Paris" } }' ``` The response shows exactly what was sent to your webhook and what it returned: ```json theme={"dark"} { "success": true, "execution_time_ms": 234, "request_sent": { "url": "https://your-api.com/weather", "method": "POST", "payload": { "tool_id": "...", "tool_name": "get_weather", "parameters": { "city": "Paris" } } }, "response_received": { "status": 200, "body": { "temperature": 18, "conditions": "Sunny" } } } ``` You can also validate parameters without calling your webhook: ```bash theme={"dark"} curl -X POST https://api.iwy.ai/v1/tool/YOUR_TOOL_ID/test \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "parameters": { "city": "Paris" }, "validate_only": true }' ``` *** ## Common Use Cases | Tool Type | Example | Webhook Does | | ---------------- | ----------------------- | ----------------------------------------------------- | | **Data lookup** | Check order status | Queries your database, returns order info | | **Search** | Find products | Searches catalog, returns matching items | | **Booking** | Schedule appointment | Creates a calendar entry, returns confirmation | | **Calculation** | Get shipping quote | Calculates based on inputs, returns price | | **Integration** | Create support ticket | Calls external API (Zendesk, etc.), returns ticket ID | | **Notification** | Send confirmation email | Triggers email service, returns success status | *** ## Error Handling If your webhook returns an error or times out, the agent will gracefully handle it: | Scenario | Agent Behavior | | ----------------------- | ------------------------------------------- | | Webhook returns 4xx/5xx | Tells user the action couldn't be completed | | Webhook times out | Tells user the service is taking too long | | Invalid parameters | May ask user for clarification | Your webhook can return error details that the agent can communicate: ```json theme={"dark"} { "error": true, "message": "No appointments available on that date" } ``` *** ## Security Best Practices **Your webhook URL is called from iwy's servers, not the user's browser.** This means you can trust the request, but you should still validate it. 1. **Use authentication headers** - Add an API key in the `headers` configuration 2. **Validate the tool\_id** - Confirm it matches your expected tool 3. **Validate parameters** - Don't trust that parameters are well-formed 4. **Use HTTPS** - Always use encrypted connections 5. **Limit permissions** - Your webhook should only do what's necessary *** ## Quick Reference | Endpoint | Method | Description | | ----------------- | ------ | ------------------- | | `/tool` | GET | List all tools | | `/tool` | POST | Create a new tool | | `/tool/{id}` | GET | Get tool details | | `/tool/{id}` | PATCH | Update tool | | `/tool/{id}` | DELETE | Delete tool | | `/tool/{id}/test` | POST | Test tool execution | *** ## Support Need help? [Contact us](https://www.iwy.ai/contact)