Tools API

Manage agent tools, including OpenAPI import and tool clusters.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/tools	List tools
POST	/api/agents/{id}/tools	Create tool
POST	/api/agents/{id}/tools/import-openapi	Import OpenAPI spec
DELETE	/api/agents/{id}/tools?id={toolId}	Delete tool
DELETE	/api/agents/{id}/tools/cluster/{name}	Delete tool cluster

List Tools

GET /api/agents/{id}/tools

Returns all tools sorted by cluster, then name.

Response

{
  "success": true,
  "data": [
    {
      "id": "tool-123",
      "name": "getPetById",
      "description": "Get pet by ID",
      "type": "http",
      "configuration": {
        "baseUrl": "https://petstore.swagger.io/v2",
        "pathTemplate": "/pet/{petId}",
        "method": "GET",
        "pathParams": ["petId"],
        "queryParams": []
      },
      "isEnabled": true,
      "cluster": "Petstore"
    }
  ]
}

Create Tool

POST /api/agents/{id}/tools
Content-Type: application/json

Request Body

{
  "name": "search_database",
  "description": "Search the knowledge base for information",
  "type": "http",
  "configuration": {
    "url": "https://api.example.com/search",
    "method": "POST",
    "headers": "{\"Authorization\": \"Bearer ...\"}"
  },
  "cluster": "my_api"
}

The cluster field is optional. If provided, the tool is grouped under that cluster name.

Import OpenAPI Spec

POST /api/agents/{id}/tools/import-openapi
Content-Type: application/json

Request Body

{
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "cluster": "petstore"
}

Field	Type	Required	Description
url	string	One of url or spec	URL to an OpenAPI 3.x JSON spec
spec	object	One of url or spec	Inline OpenAPI spec object
cluster	string	No	Group name for imported tools. Defaults to info.title from the spec

Response

{
  "success": true,
  "data": [
    {
      "id": "uuid-1",
      "name": "getPetById",
      "description": "Find pet by ID",
      "type": "http",
      "configuration": {
        "baseUrl": "https://petstore.swagger.io/v2",
        "pathTemplate": "/pet/{petId}",
        "method": "GET",
        "pathParams": ["petId"],
        "queryParams": []
      },
      "isEnabled": true,
      "cluster": "petstore"
    }
  ]
}

What Gets Created

For each path + HTTP method combination in the spec:

• Tool name: operationId from the spec, or auto-generated as {method}_{path_slug}
• Description: summary or description from the operation
• Configuration: baseUrl, pathTemplate, method, pathParams, queryParams
• Type: Always http

Delete Tool

DELETE /api/agents/{id}/tools?id={toolId}

Deletes a single tool by ID.

Delete Tool Cluster

DELETE /api/agents/{id}/tools/cluster/{clusterName}

Deletes all tools belonging to a cluster.

Response

{
  "success": true,
  "data": {
    "deleted": 5
  }
}

Tool Types

Type	Description
http	HTTP endpoint call (including OpenAPI-imported tools)
javascript	Custom JavaScript function
mcp	MCP server tool

Tool Configuration Fields

HTTP Tools (manual)

Field	Description
url	Full endpoint URL
method	HTTP method (GET, POST, PUT, DELETE)
headers	JSON string of request headers

HTTP Tools (OpenAPI-imported)

Field	Description
baseUrl	Base server URL from the spec
pathTemplate	Path with parameter placeholders (e.g. /pet/{petId})
method	HTTP method
pathParams	Array of path parameter names
queryParams	Array of query parameter names