Skip to main content
Tools extend agent capabilities beyond conversation. The platform provides builtin tools (database_query, database_write, http_request, code_execute, storage_read, storage_write, web_search, web_scrape) and lets you create custom tools that call your own endpoints. Custom tools are defined with a name, description, JSON Schema for inputs, and an endpoint URL that the platform calls when the agent uses the tool.

​
Common Patterns

List available tools with GET /api/tools to see both builtin and custom tools. Create custom tools with a clear description and input schema — agents use the description to decide when to call the tool. Assign tools to agents via the agent tools API (POST /api/agents/{id}/tools).

​
GET /api/tools

List all tools (builtin: database_query, database_write, http_request, code_execute, storage_read, storage_write, web_search, web_scrape + custom). 
response = requests.get(f"{BASE_URL}/api/tools", headers=headers)

​
POST /api/tools

Create a custom tool. Required: name, description, type, input_schema. The route also accepts an optional config object — for HTTP-callable tools, the runtime reads config.endpoint, config.method (default POST), config.headers, and config.timeout_seconds when an agent invokes the tool.
​
name
string
required
Display name; agents see this when deciding to call the tool.
​
description
string
required
Free-text description; the LLM uses it to decide when to call the tool.
​
type
string
required
Free-form tag (≤50 chars). Stored verbatim; not used by runtime dispatch. Pick something descriptive (e.g. http).
​
input_schema
object
required
JSON Schema for the tool’s arguments. Not validated at create-time; passed straight through.
​
config
object
Tool-specific config. For custom HTTP tools, set { endpoint, method?, headers?, timeout_seconds? } here — that’s where the runtime reads them.
Top-level endpoint_url / method / headers are silently dropped at create-time — only name, description, type, input_schema, and config are persisted. type is stored as a free-form String(50); the runtime does NOT switch on it. Agent-tool dispatch uses the assignment’s own tool_type (builtin vs custom), not the Tool’s type field.
{
  "name": "weather_lookup",
  "description": "Get current weather for a city",
  "type": "http",
  "input_schema": {
    "type": "object",
    "properties": { "city": { "type": "string" } },
    "required": ["city"]
  },
  "config": {
    "endpoint": "https://api.weather.com/v1/current",
    "method": "GET"
  }
}

response = requests.post(f"{BASE_URL}/api/tools", headers=headers, json={
    "name": "weather_lookup",
    "description": "Get current weather",
    "type": "http",
    "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    "config": {"endpoint": "https://api.weather.com/v1/current", "method": "GET"},
})

​
GET /api/tools/

Get a tool definition by ID.
​
id
string
required
Tool ID
response = requests.get(f"{BASE_URL}/api/tools/{tool_id}", headers=headers)

​
PUT /api/tools/

Update a custom tool.
​
id
string
required
Tool ID
response = requests.put(f"{BASE_URL}/api/tools/{tool_id}", headers=headers, json={"description": "Updated"})

​
DELETE /api/tools/

Delete a custom tool.
​
id
string
required
Tool ID
response = requests.delete(f"{BASE_URL}/api/tools/{tool_id}", headers=headers)

​
Error Responses

Tool routes return {"error": "<message>"}.
StatusDescription
400Missing required field (name, description, type, or input_schema) on POST
404No tool exists with the given ID