Tools

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!"

You define the tool - Name, description, parameters schema, and your webhook URL
You attach it to an agent - Via dashboard or API
Agent decides when to call it - Based on the conversation and your tool’s description
Your webhook executes - Receives the parameters, performs the action, returns a response
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

{
  "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:

{
  "tool_id": "dcfae097-1b37-4444-bb0c-1a6abb0320fd",
  "tool_name": "get_weather",
  "parameters": {
    "city": "Paris",
    "units": "celsius"
  }
}

Your webhook should return JSON:

{
  "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 to define their parameters. The agent uses this schema to extract the right information from the conversation.

Basic Types

{
  "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

{
  "type": "object",
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "description": "Task priority level"
    }
  }
}

Nested Objects

{
  "type": "object",
  "properties": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zip": { "type": "string" }
      }
    }
  }
}

Attaching Tools to Agents

Via Dashboard

Go to dashboard.iwy.ai
Create or edit an agent
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:

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:

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:

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:

{
  "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:

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:

{
  "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.

Use authentication headers - Add an API key in the headers configuration
Validate the tool_id - Confirm it matches your expected tool
Validate parameters - Don’t trust that parameters are well-formed
Use HTTPS - Always use encrypted connections
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

API Reference

Single-Use Agents

Permanent Agents

Sessions

Tools

Overview

How Tools Work

Tool Configuration

Example Tool Definition

Webhook Request Format

Writing Good Tool Descriptions

Examples

Parameters Schema

Basic Types

Enum Values

Nested Objects

Attaching Tools to Agents

Via Dashboard

Via API (Permanent Agents)

Via API (Single-Use Agents)

Testing Tools

Common Use Cases

Error Handling

Security Best Practices

Quick Reference

Support

​Overview

​How Tools Work

​Tool Configuration

​Example Tool Definition

​Webhook Request Format

​Writing Good Tool Descriptions

​Examples

​Parameters Schema

​Basic Types

​Enum Values

​Nested Objects

​Attaching Tools to Agents

​Via Dashboard

​Via API (Permanent Agents)

​Via API (Single-Use Agents)

​Testing Tools

​Common Use Cases

​Error Handling

​Security Best Practices

​Quick Reference

​Support

Overview

How Tools Work

Tool Configuration

Example Tool Definition

Webhook Request Format

Writing Good Tool Descriptions

Examples

Parameters Schema

Basic Types

Enum Values

Nested Objects

Attaching Tools to Agents

Via Dashboard

Via API (Permanent Agents)

Via API (Single-Use Agents)

Testing Tools

Common Use Cases

Error Handling

Security Best Practices

Quick Reference

Support