Tools

Tools give AI agents the ability to interact with external systems, APIs, and data sources. They're the "hands" that let agents take actions in the real world.

What are Tools?

Tools are HTTP endpoints that agents can call during execution. Each tool:

Has a clear purpose - Look up data, send emails, update records, etc.
Defines parameters - What inputs the tool needs
Returns structured data - JSON responses the agent can understand
Includes authentication - API keys, bearer tokens, etc.

How Agents Use Tools

When an agent needs to perform an action, it:

Analyzes the user's request
Selects the appropriate tool based on descriptions
Extracts parameters from the conversation
Calls the tool API endpoint
Processes the response
Continues or responds to the user

Example:

User: "What's the weather in San Francisco?"

Agent thinks: The user wants weather info. I have get_weather tool.
Agent calls: get_weather(city="San Francisco")
Tool returns: {"temp": 65, "conditions": "Foggy"}
Agent responds: "It's 65°F and foggy in San Francisco"

Creating Tools

Step 1: Go to My Tools

Navigate to My Tools
Click Create Tool

Step 2: Define Basic Info

Fill in the tool details:

Name - Unique identifier (e.g., order_lookup, send_email)
Description - When and how the agent should use this tool (be specific!)
HTTP Method - GET, POST, PUT, DELETE, PATCH
URL - The API endpoint to call

Example:

Name: order_lookup
Description: Look up customer order details by order ID. Returns status, items, shipping info, and tracking number.
Method: GET
URL: https://api.yourcompany.com/orders/{order_id}

Step 3: Add Parameters

Define what inputs the tool accepts:

Parameter name - Variable name
Type - string, number, boolean, array, object
Required - Whether this parameter is mandatory
Description - What this parameter represents

Example:

{
  "order_id": {
    "type": "string",
    "required": true,
    "description": "The customer's 5-digit order ID"
  }
}

Step 4: Configure Headers (Optional)

Add authentication and headers:

{
  "Authorization": "Bearer YOUR_API_TOKEN",
  "Content-Type": "application/json"
}

Step 5: Test & Save

Click Create to save your tool. It's now available to use in your agents!

Tool Examples

Weather API

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "method": "GET",
  "url": "https://api.weather.com/current",
  "parameters": {
    "city": {
      "type": "string",
      "required": true,
      "description": "City name (e.g., 'San Francisco')"
    }
  }
}

Database Query

{
  "name": "customer_lookup",
  "description": "Find customer details by email or customer ID",
  "method": "GET",
  "url": "https://api.yourcompany.com/customers/{customer_id}",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "parameters": {
    "customer_id": {
      "type": "string",
      "required": true
    }
  }
}

Send Notification

{
  "name": "send_email",
  "description": "Send email notification to a customer",
  "method": "POST",
  "url": "https://api.sendgrid.com/v3/mail/send",
  "headers": {
    "Authorization": "Bearer SENDGRID_KEY",
    "Content-Type": "application/json"
  },
  "parameters": {
    "to": {"type": "string", "required": true},
    "subject": {"type": "string", "required": true},
    "body": {"type": "string", "required": true}
  }
}

Data Processing

{
  "name": "analyze_sentiment",
  "description": "Analyze sentiment of customer feedback",
  "method": "POST",
  "url": "https://api.yourcompany.com/sentiment",
  "parameters": {
    "text": {
      "type": "string",
      "required": true,
      "description": "Text to analyze"
    }
  }
}

Math Calculation

{
  "name": "calculate",
  "description": "Perform mathematical calculations",
  "method": "POST",
  "url": "https://api.mathjs.org/v4/",
  "parameters": {
    "expr": {
      "type": "string",
      "required": true,
      "description": "Math expression (e.g., '2 + 2', 'sqrt(16)')"
    }
  }
}

Best Practices

Naming

Use Clear, Descriptive Names:

✅ order_lookup, send_email, get_weather
❌ do_thing, api_call, tool1

Follow Convention:

Use snake_case: customer_lookup
Be specific: send_slack_message not send_message
Action-oriented: create_ticket not ticket

Descriptions

Be Specific About When to Use:

✅ "Look up customer order details by order ID. Use this when the user asks about order status, shipping, or tracking."

❌ "Get order info"

Include What is Returned:

✅ "Returns order status, items list, shipping address, tracking number, and estimated delivery date."

❌ "Returns data"

Parameters

Provide Clear Descriptions:

{
  "user_id": {
    "type": "string",
    "description": "Unique user identifier in format 'USR-12345'"
  }
}

Use Type Validation:

{
  "email": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    "description": "Valid email address"
  },
  "age": {
    "type": "number",
    "minimum": 0,
    "maximum": 120
  }
}

Mark Required Fields:

Only mark truly required parameters as required: true
Provide defaults for optional parameters when possible

Error Handling

Return Structured Errors:

{
  "success": false,
  "error": "Order not found",
  "error_code": "ORDER_NOT_FOUND",
  "message": "No order exists with ID 12345",
  "suggestion": "Please verify the order ID and try again"
}

Use HTTP Status Codes:

200 - Success
400 - Invalid parameters
401 - Authentication failed
404 - Resource not found
500 - Server error

Security

Protect API Keys:

Store keys in environment variables
Use headers for authentication
Never expose keys in URLs

Validate Inputs:

Use type checking
Add format validation (regex patterns)
Set min/max constraints

Rate Limiting:

Consider rate limits on your APIs
Return clear error messages when limits are hit

Performance

Keep Tools Fast:

Optimize your API endpoints
Cache frequent queries
Use efficient database queries
Return only needed data

Timeout Handling:

Tools should respond within 30 seconds
Return partial results if processing takes long
Use async processing for long tasks

Using Tools in Agents

Once created, tools can be added to any agent:

Go to My Agents
Create or edit an agent
In the Tools section, select from your available tools
The agent can now use these tools during execution

See AI Agents for complete agent setup.

Testing Tools

Test Directly

Before adding to an agent, test tools independently:

curl -X GET "https://api.yourcompany.com/orders/12345" \
  -H "Authorization: Bearer YOUR_TOKEN"

Test with Agents

Use the Playground to test tools with agents:

Go to your agent's detail page
Click Playground
Ask a question that should trigger the tool
Watch the execution steps to see:
Which tool was called
What parameters were used
What response was returned

Debugging

Tool Not Being Called?

Check description - Is it clear when to use this tool?
Check agent prompt - Does it mention the tool?
Check parameters - Are they well-defined?

Tool Failing?

Test endpoint directly - Use curl or Postman
Check authentication - Verify headers and tokens
Check parameters - Match API requirements exactly
Review error messages - Look at tool_output in execution steps

Wrong Parameters?

Improve descriptions - Be more specific about format
Add examples - Show sample values in descriptions
Use validation - Add patterns, min/max, enums

Next Steps

AI Agents - Build agents that use your tools
API Reference - Programmatic access
Pricing & Credits - Cost details

Documentation

Tools

What are Tools?

How Agents Use Tools

Creating Tools

Step 1: Go to My Tools

Step 2: Define Basic Info

Step 3: Add Parameters

Step 4: Configure Headers (Optional)

Step 5: Test & Save

Tool Examples

Weather API

Database Query

Send Notification

Data Processing

Math Calculation

Best Practices

Naming

Descriptions

Parameters

Error Handling

Security

Performance

Using Tools in Agents

Testing Tools

Test Directly

Test with Agents

Debugging

Tool Not Being Called?

Tool Failing?

Wrong Parameters?

Next Steps