Tools and knowledge

Give an agent tested actions and processed reference documents.

Tools let a workflow take an action during a conversation. Knowledge documents let it retrieve reference material. Add only the actions and information needed for the task, and verify each dependency independently before using it with callers.

Available tool types

The dashboard currently provides external HTTP API, end-call, transfer-call, transfer-to-agent, calculator, MCP server, and press-phone-keys tools. Some integration choices may appear disabled or marked as coming soon; they are not available to configure as working tools. Availability can also depend on the workflow and organization.

Configure an HTTP API tool

An HTTP tool makes a real request to its configured URL. Define the method, URL, expected inputs, request body, and credential reference. Use the credential manager for authentication instead of placing secrets in an agent prompt or a model-provided parameter. Supported methods include GET, POST, PUT, PATCH, and DELETE; choose the method your receiver expects.

For an HTTP body, body_template can construct nested JSON from context and tool parameters. body_format chooses JSON or form encoding. If no body template is set, parameter values are sent as a flat JSON object for POST, PUT, and PATCH; GET and DELETE use query parameters. A model-supplied value takes precedence over a preset when both use the same key.

Example test inputs for a receiver you control:

{
  "llm_params": {
    "purpose": "athena-docs-verification",
    "test_id": "replace-with-a-unique-synthetic-marker"
  }
}

The test action sends a real request. Check the test response’s status_code and data, and inspect the receiving service for the unique marker. A success from the tool-test request proves only that request; it does not prove every model-generated argument or downstream operation will work in a live conversation.

The identifier returned when a tool is created is tool_uuid. Keep it distinct from workflow, trigger, and run identifiers. Deleting a tool archives it, so it may no longer be offered to new workflows while its record remains.

Connect an MCP server

Create a tool with the MCP Server category. Enter the server’s Streamable HTTP endpoint in MCP Server URL and select its credential if authentication is required. The endpoint must be reachable from Athena; a localhost address on your computer is not reachable as that computer’s service from Athena.

Save the tool, open its settings, and refresh the discovered catalog. Review the function names and descriptions before adding the server to an agent. Restrict exposed functions with tools_filter when needed; an empty filter exposes all functions returned by the server. Review the caller-confirmation settings for actions that change data.

The refresh API is POST /api/v1/tools/{tool_uuid}/mcp/refresh. Check its error and discovered_tools fields: the wrapper can return HTTP 200 with an error when discovery fails. An empty or failed discovery keeps the previous cached catalog. After changing the server or its permissions, confirm a fresh catalog was obtained rather than relying on an old list.

Upload and process a knowledge document

Uploading and indexing a file are separate steps. In the dashboard, add the document and wait for processing to finish before testing retrieval. The processing lifecycle is pending, processing, then completed or failed.

If you use the API directly, the flow is:

1. Request an upload URL

   Create the document entry and obtain its temporary upload URL. Use it promptly; the signed URL expires.
2. Upload the file

   Send the file bytes to the returned URL using the method and headers supplied for that upload.
3. Start processing

   Submit the document for processing after the upload succeeds.
4. Wait and verify

   Check the document status until it reaches completed, then test the agent’s answer against a question whose answer is in the document.

A file stored in the knowledge list is not necessarily searchable yet. If processing fails or retrieval is empty, check the processing status, the selected embedding configuration, and whether the workflow uses the intended knowledge source. Avoid assuming an indexed document will be available to every configuration.

For smaller reference material such as menus, price lists, or FAQs, Full Document sends the entire document to the agent on each retrieval. For larger manuals or policies, Chunked Search splits the document and retrieves relevant sections. Choose the mode that fits the document and verify the agent’s answers with representative questions; a completed processing status does not prove retrieval quality.

Removing a knowledge document deactivates it for future use; it does not guarantee physical erasure of the underlying stored object. Do not treat a successful deactivation response as a storage-purge receipt.

See Context and variables for passing values into HTTP templates.