Tools

Tools give your agents superpowers. Connect REST APIs, databases, search engines, and custom functions so agents can take real actions in the world.

What Are Tools?

A tool is an external capability that an agent can invoke during a run. Without tools, an agent can only generate text. With tools, an agent can search the web, query databases, create tickets, send emails, and more.

Why You Need Tools

Real-world actions — Agents can fetch live data, create records, trigger workflows
Safety controls — Rate limiting, sandboxing, and approval gates per tool
Audit trail — Every tool invocation is logged with inputs and outputs
Reusability — Register once, attach to many agents

Register a Tool (Dashboard)

Open Tool Gateway Tab

Go to the dashboard and click 'Tool Gateway' in the sidebar.

Click 'Register Tool'

Click the button to open the tool registration form.

Enter Tool Details

Provide a name (e.g., 'web-search'), description, and the tool type (REST API, function, etc.).

Define Input Schema

Specify what parameters the tool accepts. This helps the AI understand how to call the tool correctly.

Set Safety Level

Choose: 'safe' (no restrictions), 'moderate' (logged), or 'dangerous' (requires approval).

Configure Rate Limits

Set how many times the tool can be called per minute/hour to prevent abuse.

Save & Test

Click Save, then use the 'Test' button to verify the tool works with sample inputs.

Register a Tool (API)

curl -X POST http://localhost:8000/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-search",
    "description": "Search the web for current information",
    "type": "rest_api",
    "endpoint": "https://api.search-provider.com/search",
    "method": "GET",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "Search query" },
        "max_results": { "type": "integer", "default": 5 }
      },
      "required": ["query"]
    },
    "safety_level": "safe",
    "rate_limit": { "max_calls": 60, "period": "minute" }
  }'

Attach Tools to an Agent

Attach Tools to Agentbash

# Update agent to include tool bindings
curl -X PUT http://localhost:8000/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["web-search", "calculator", "knowledge-search"]
  }'

Test a Tool

Test Toolbash

curl -X POST http://localhost:8000/api/v1/tools/TOOL_ID/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "query": "latest AI news" }
  }'

Safety Levels

Level	Behavior	Use For
safe	No restrictions, auto-approved	Read-only tools (search, lookup)
moderate	Logged and rate-limited	Write tools (create record, send message)
dangerous	Requires human approval	Delete, financial, or irreversible actions

Always set rate limits!

Without rate limits, a malfunctioning agent could call a tool thousands of times. Always set sensible limits, especially for paid APIs.

Best Practices

Write clear tool descriptions — the AI uses these to decide when to call the tool
Define complete input schemas with descriptions for each parameter
Start with "safe" level and increase restrictions as needed
Test every tool with the built-in test feature before attaching to agents
Use sandboxing for tools that modify external systems
Monitor the Tool Gateway tab for usage patterns and errors

Agents

Memory