Agent Tools

A custom tool is one of your own read-only HTTP endpoints, described so a model can call it mid-conversation. These routes are the API behind the console's Tools screen: create the definition, test it against your real endpoint, and attach it to one agent or to all of them.

Custom tools vs built-in tools

Two different mechanisms, and this page covers only the first.

A tool with bot_id: null is available to every agent in the workspace. Set bot_id to scope it to one.

Credential class: dashboard JWT or a cm_ key

Authorization: Bearer cm_your_api_key

Base URL for every example: https://api.callmissed.com. Errors are {"detail": "..."}.

The tool object

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tenant_id": "a0b1c2d3-4455-6677-8899-aabbccddeeff",
  "bot_id": null,
  "name": "search_products",
  "description": "Search the catalogue by keyword. Returns price, stock, the product link and an image URL.",
  "method": "GET",
  "url": "https://api.yourstore.com/agent/products/search",
  "header_params": [
    { "name": "X-API-Key", "type": "string", "description": "", "required": false, "source": "static", "secret": true, "value": null }
  ],
  "path_params": [],
  "query_params": [
    { "name": "q", "type": "string", "description": "what the customer is looking for", "required": true, "source": "llm", "secret": false, "value": null }
  ],
  "body_params": [],
  "response_mapping": {},
  "timeout_seconds": 10,
  "phase": "on_call",
  "enabled": true,
  "has_secrets": true,
  "created_at": "2026-09-08T12:00:00Z",
  "updated_at": "2026-09-08T12:00:00Z"
}

Parameters

Each parameter says where it goes on the wire (its location) and where its value comes from (its source).

Locations: header, path, query, body. At most 20 each.

Sources:

A context parameter's value is a key, not a literal, and must be one of contact_phone, contact_name, contact_email, conversation_id. The model cannot see or set it, and that is what makes an order lookup safe. If the conversation has no such value (a voice call with no linked contact), the parameter is omitted unless you mark it required, in which case the call fails cleanly instead of running an unscoped query.

Endpoint requirements

Your URL must be reachable on the public internet. Requests to private, loopback and cloud-metadata addresses are refused at save time and again on every request, including after each redirect, so a hostname re-pointed later does not get through either. At most 3 redirects are followed.

A response is read up to 32 KB and truncated past it, with truncated: true on the result. Return the handful of fields a customer actually asks about rather than a full catalogue document. /docs/connect-your-store covers how to shape a response for a model.

GET /api/v1/agent-tools

Lists the workspace's tools, newest first, up to 500. Requires bots:read.

curl "https://api.callmissed.com/api/v1/agent-tools?bot_id=b1f2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer cm_your_api_key"

Returns an array of tool objects.

POST /api/v1/agent-tools

Creates a tool. Returns 201 and the tool object. Requires bots:write.

Takes every field of the tool object except the server-set ones (id, tenant_id, has_secrets, created_at, updated_at), plus bot_id, phase and enabled.

curl -X POST https://api.callmissed.com/api/v1/agent-tools \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_order_status",
    "description": "Look up the caller'\''s most recent orders and their delivery status. Use when a customer asks where their order is.",
    "method": "GET",
    "url": "https://api.yourstore.com/agent/orders",
    "header_params": [
      { "name": "X-API-Key", "source": "static", "value": "your_endpoint_key" }
    ],
    "query_params": [
      { "name": "phone", "source": "context", "value": "contact_phone", "required": true }
    ],
    "timeout_seconds": 10
  }'

GET /api/v1/agent-tools/{tool_id}

One tool object. 404 if it belongs to another workspace. Requires bots:read.

PATCH /api/v1/agent-tools/{tool_id}

Every field is optional. Returns the updated tool object. Requires bots:write.

The whole definition is re-validated on each update, because the URL and the path parameters constrain each other. Omitting a parameter list keeps the stored one; sending a list replaces it.

curl -X PATCH https://api.callmissed.com/api/v1/agent-tools/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

DELETE /api/v1/agent-tools/{tool_id}

Returns 204. Requires bots:write.

POST /api/v1/agent-tools/test

Runs a definition that has not been saved, so you can check an endpoint before committing to it. Requires bots:write.

Takes the same body as POST /api/v1/agent-tools, plus arguments: the values a model would have supplied for the llm parameters.

curl -X POST https://api.callmissed.com/api/v1/agent-tools/test \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_products",
    "description": "Search the catalogue by keyword.",
    "method": "GET",
    "url": "https://api.yourstore.com/agent/products/search",
    "query_params": [ { "name": "q", "source": "llm", "required": true } ],
    "arguments": { "q": "line follower kit" }
  }'

POST /api/v1/agent-tools/{tool_id}/test

The same run for a saved tool, using its stored secrets. Requires bots:write.

curl -X POST https://api.callmissed.com/api/v1/agent-tools/7c9e6679-7425-40de-944b-e07fc1f90ae7/test \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "q": "line follower kit" } }'

Test results

Both test endpoints return 200 with a result object, whether or not your endpoint answered. A failure of yours is reported in the body, not as an HTTP error on ours.

{
  "ok": true,
  "status": 200,
  "result": { "count": 1, "products": [{ "id": "kit-104", "price": 1180 }] },
  "truncated": false
}

error comes from a fixed vocabulary so that nothing about the failure leaks back through the model. status is null with it unless the failure happened part-way through a redirect chain, in which case it carries the status of the last hop:

At reply time

A tool is offered to the model when all of these hold: enabled is true, phase is on_call, and the tool is either scoped to the agent handling the conversation or workspace-wide (bot_id: null).

Connecting the tool is half the job. The agent's instructions decide whether it uses it well, and Connect Your Store has a prompt you can adapt.