Tools API

Discover Tools

GET /tools/{agent_id}

Returns available tools for an agent in OpenAI function-calling format. Only returns tools that are enabled and available (validation passed, credentials configured).

Response:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather conditions for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"},
            "units": {"type": "string", "enum": ["metric", "imperial"]}
          },
          "required": ["city"]
        }
      },
      "metadata": {
        "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
        "artifact_title": "Weather Lookup Tool",
        "per_query_tokens": 5
      }
    }
  ]
}

Rate limit: 60/minute

Execute Tool

POST /tools/{agent_id}/execute

Execute a marketplace tool by name.

Request:

{
  "tool_name": "get_weather",
  "input": {
    "city": "San Francisco",
    "units": "metric"
  }
}

Input JSON must be under 100 KB. Tool name must match ^[a-zA-Z_][a-zA-Z0-9_]{0,127}$.

Response (success):

{
  "success": true,
  "output": {
    "city": "San Francisco",
    "temperature": 18,
    "conditions": "partly cloudy",
    "humidity": 72,
    "wind_speed": 5.2
  },
  "error": null,
  "execution_time_ms": 230,
  "tokens_charged": 5
}

Response (tool error):

{
  "success": false,
  "output": null,
  "error": "External API returned 503",
  "execution_time_ms": 1500,
  "tokens_charged": 0
}

Error codes:

Code	When
400	Invalid tool name format
402	Insufficient token balance
404	Agent or tool not found
428	Tool requires credentials not yet configured
502	Tool execution failed
504	Tool execution timed out (30-second limit)

Rate limit: 30/minute

Credential Status

GET /tools/{agent_id}/status

Returns credential status for all tools, including tools that are unavailable because of missing credentials.

Response:

{
  "tools": [
    {
      "tool_name": "get_weather",
      "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "complete",
      "missing_keys": []
    },
    {
      "tool_name": "analyze_keywords",
      "artifact_id": "660e8400-e29b-41d4-a716-446655440001",
      "status": "pending",
      "missing_keys": ["SEO_API_KEY"]
    }
  ]
}

Status values:

not_required - tool doesn't need any credentials
complete - all required credentials are provided
pending - one or more required keys are missing

Rate limit: 60/minute

Tool Registry

GET /tools/{agent_id}/registry

Returns all registry entries with full detail, including disabled tools.

Response:

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
    "tool_name": "get_weather",
    "description": "Get current weather conditions for a city.",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
    "per_query_tokens": 5,
    "required_keys": ["WEATHER_API_KEY"],
    "provided_keys": ["WEATHER_API_KEY"],
    "credentials_status": "complete",
    "is_enabled": true,
    "is_available": true,
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
]

Rate limit: 60/minute

Toggle Tool

PATCH /tools/{agent_id}/{tool_name}/toggle

Enable or disable a tool.

Request:

{
  "enabled": true
}

Response: Returns the updated ToolRegistryEntry (same shape as registry items above).

A tool can be enabled but still unavailable if credentials are missing or validation hasn't passed. The is_available field reflects the actual availability.

Rate limit: 30/minute

Tool Detail

GET /tools/{agent_id}/{tool_name}/detail

Get detailed information about a specific tool, including its manifest and test cases.

Response:

{
  "tool_name": "get_weather",
  "artifact_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Get current weather conditions for a city.",
  "docstring": "Get current weather conditions for a city.\n\nArgs:\n    city: City name\n    units: Temperature units",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string"},
      "units": {"type": "string", "enum": ["metric", "imperial"]}
    },
    "required": ["city"]
  },
  "per_query_tokens": 5,
  "credentials_status": "complete",
  "is_enabled": true,
  "is_available": true,
  "manifest": {
    "network": ["api.openweathermap.org"],
    "secrets": [
      {"key": "WEATHER_API_KEY", "label": "Weather API Key", "help": "Get yours at openweathermap.org/api"}
    ]
  },
  "test_cases": [
    {"inputs": {"city": "London"}, "expected_output_contains": ["temperature"]}
  ]
}

Rate limit: 60/minute

Tool Settings

PATCH /agents/{agent_id}/tool-settings

Update the agent's tool approval mode.

Request:

{
  "approval_mode": "auto"
}

Response:

{
  "approval_mode": "auto"
}

Values: "auto" or "manual". When switching to auto, all tools with passing validation and complete credentials are enabled automatically.

Rate limit: 10/minute

Authentication

All endpoints require an x-api-key header:

x-api-key: your-api-key

The API key must belong to the agent's owner.

Next Steps

Environment Variables API - manage tool credentials
Tools SDK Reference - Python SDK wrapper
Use Marketplace Tools - practical guide

Tools API

On this page