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 toolsCopy Anchor Link

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_ keyCopy Anchor Link

Authorization: Bearer cm_your_api_key

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

The tool objectCopy Anchor Link

{
  "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"
}

ParametersCopy Anchor Link

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 requirementsCopy Anchor Link

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-toolsCopy Anchor Link

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-toolsCopy Anchor Link

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}Copy Anchor Link

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

PATCH /api/v1/agent-tools/{tool_id}Copy Anchor Link

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}Copy Anchor Link

Returns 204. Requires bots:write.

POST /api/v1/agent-tools/testCopy Anchor Link

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}/testCopy Anchor Link

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 resultsCopy Anchor Link

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 timeCopy Anchor Link

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.

Pre-call toolsCopy Anchor Link

Set "phase": "pre_call" to look a caller up before the agent speaks. The tool runs once per call, before the greeting on an inbound call and before the call is placed on an outbound one, and its mapped result becomes {{variable}} values the greeting and prompt can use. A pre-call tool is never offered to the model.

• Request. Use static or context parameters. The contact_phone context key is the caller on an inbound call and the person dialled on an outbound one. A required model-facing parameter is rejected with 422, because no model fills the arguments.
• Response mapping. Each response_mapping key becomes a variable of the same name. Keys must be valid variable names (letters, digits and underscores, not starting with a digit). Only plain values are used: objects, arrays and nulls are skipped. At most 50 variables are kept, each trimmed to 200 characters.
• Timeout. The tool's timeout_seconds is used when it is between 1 and 5. Any other value, including the default of 10, falls back to 3 seconds. The whole pre-call step is capped at 4 seconds however many tools you attach.
• Precedence. Variables passed explicitly on the call (for example variables when you place a call through the API) win over pre-call values, which win over the agent's declared defaults and the built-in values.
• Failure. If a tool times out, errors or returns something unusable, the call continues without its variables. A pre-call tool never blocks or fails a call.
• Audit. The session records which pre-call tools ran and whether each succeeded, with no response values.

Use POST /api/v1/agent-tools/{tool_id}/test to check the endpoint answers; it uses placeholder context values, as described in Test results.