Tools

Tools extend what an agent can do during a conversation.

Two Types Of Tools

The Tools page can show:

• built-in tools provided by the platform
• custom tools that you create and manage yourself

You can enable or disable tools per agent, and custom tools can be edited later.

When To Use A Tool

Use a tool when the agent needs to perform an action or fetch live data that should not live in static sources.

Examples:

• check an order status
• look up account data
• fetch structured product availability
• call an internal HTTP service

Tools vs Skills vs MCP Servers

Working With Custom Tools

The custom tool flow lets you:

• create a tool
• configure its HTTP behavior
• test it
• enable or disable it for an agent

Good Custom Tool Workflow

1. define one clear job for the tool
2. configure the request method, URL, headers, and body shape
3. test the tool with realistic inputs
4. attach it to the right agent only
5. monitor real usage in conversations before expanding scope

If the tool fails often, reduce the scope of what it tries to do instead of piling more fallback logic into the prompt.

HTTP Configuration (Canonical Fields)

A custom tool calls one HTTP endpoint. The canonical httpConfig contract has exactly these fields:

Path And Query Interpolation

Placeholders ${param} in the URL are replaced with values from the tool input:

{
  "url": "https://api.example.com/orders/${order_id}"
}

With input { "order_id": "A-1001" } the tool calls https://api.example.com/orders/A-1001. The value is URL-encoded. Missing input parameters fail the call with a clear error.

Request Body

For non-GET methods (POST, PUT, PATCH, DELETE) the full tool input object becomes the JSON request body and Content-Type: application/json is set unless you already set a Content-Type header. For GET, no body is sent.

Authentication

No Auth

Omit authConfig and set authType: "none" (the default):

{
  "url": "https://api.example.com/public/orders/${order_id}",
  "method": "GET",
  "authType": "none"
}

Bearer Token From An Environment Secret Reference

The MCP tools never accept raw bearer tokens, API keys, or passwords in httpConfig.authConfig. Instead, reference a secret that lives in the runtime environment. bearer (and api_key) auth requires authConfig.secretRef — a config that declares bearer without one is rejected with a httpConfig.authConfig.secretRef field error instead of silently going out unauthenticated:

{
  "url": "https://api.example.com/orders/${order_id}",
  "method": "GET",
  "authType": "bearer",
  "authConfig": {
    "secretRef": {
      "type": "environment",
      "name": "KRAVOS_CUSTOM_TOOL_<TENANT_ID>_TASKS_BEARER"
    }
  }
}

At execution time the runtime resolves the environment variable and sends Authorization: Bearer <value>. The resolved secret is never returned by any API or MCP tool, and it is never stored in the tool configuration — only the reference is.

API Key From An Environment Secret Reference

For api_key auth, the resolved secret is sent in the header named by authConfig.headerName (default x-api-key):

{
  "url": "https://api.example.com/orders",
  "method": "GET",
  "authType": "api_key",
  "authConfig": {
    "headerName": "x-api-key",
    "secretRef": {
      "type": "environment",
      "name": "KRAVOS_CUSTOM_TOOL_<TENANT_ID>_TASKS_API_KEY"
    }
  }
}

Secret Setup And Naming

1. Set an environment variable on the runtime that executes the agent. The name must follow the tenant-scoped convention:

   KRAVOS_CUSTOM_TOOL_<TENANT_ID>_<NAME>
   

   For example KRAVOS_CUSTOM_TOOL_tenant_1_TASKS_BEARER.

2. Reference the exact same name in authConfig.secretRef.name.

The KRAVOS_CUSTOM_TOOL_ prefix is dedicated to custom tool secrets. The reference is validated against the tenant at write time and again at execution time, so one tenant can never reference another tenant's custom-tool secret. If the variable is missing, empty, or not scoped to the runtime tenant, the tool call fails safely without leaking anything.

authType: "none" must not include a secretRef — that combination is rejected as misleading. basic auth is not available over MCP and remains dashboard-only with raw username/password values.

Static Headers

Non-secret headers are static keys in headers. Do not put secret values in headers; use authConfig.secretRef instead. Authorization, Proxy-Authorization, x-api-key, Cookie (any casing), and any header name containing auth, token, api-key, secret, credential, or password are rejected as static headers with a httpConfig.headers.<name> field error so secrets cannot bypass the secretRef rule.

Testing Custom Tools

test_custom_tool runs a real request against the endpoint. Provide exactly one of:

• toolId — tests the stored configuration of an existing tool
• httpConfig — tests an ad-hoc configuration before you create the tool

Pass the tool input in the input object. The response is the HTTP result (status, mapped data, truncation flag); auth configuration is never echoed back. Passing neither (or both) toolId and httpConfig is a validation error.

MCP Automation

Custom tools are fully manageable over Platform MCP:

• create_custom_tool — create and link a tool to an agent
• update_custom_tool — update the tool or its HTTP config
• test_custom_tool — test a stored or ad-hoc config
• list_custom_tools / get_custom_tool — read sanitized metadata (never raw auth values)

Validation failures return structured field errors such as httpConfig.url or httpConfig.authConfig.secretRef.name with the expected constraint, so autonomous clients can correct one field at a time.

Best Practices

• keep tool behavior narrow and reliable
• use sources for stable reference knowledge, not live actions
• test tools before enabling them broadly
• monitor tool-heavy voice sessions in Voice Lab if voice is enabled

Related Docs