> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Attach a tool to an agent

1. Create and save the tool in **Tools**.
2. Open the agent's canvas and edit a Start Call or Agent node.
3. Select the resource in **Tools**, and describe its use conditions and failure behavior in the node prompt.
4. Repeat for every node that needs access, save the draft, and validate it. Tools are not automatically available on all nodes.
5. Test a path that invokes it, inspect the result in the run, then publish the tested workflow.

| Tool | Detailed setup |
| - | - |
| End Call, Calculator | [Built-in actions](https://docs.tryopencomputer.com/guides/built-in-actions.md) |
| Transfer Call, Transfer To Agent | [Call transfers](https://docs.tryopencomputer.com/guides/transfers.md) |
| MCP Server | [External MCP tools](https://docs.tryopencomputer.com/guides/mcp.md) |
| Press Phone Keys | [Phone menus](https://docs.tryopencomputer.com/guides/phone-menus.md) |
| Authentication | [Credentials](https://docs.tryopencomputer.com/guides/credentials.md) |
| Knowledge files | [Knowledge setup](https://docs.tryopencomputer.com/guides/knowledge.md) |

## Press Phone Keys for IVR navigation

**Press Phone Keys** is a built-in tool for navigating automated phone menus on the supported Athena Voice / LiveKit SIP phone-call path. Create it in **Tools** and attach it to the workflow nodes that need keypad access. It supports `0–9`, `*`, and `#`, up to 16 keys per action.

The agent's **Phone Menus (Keypad)** and **Wait Quietly on Hold** settings default to on; attaching the keypad tool is still a required setup step. Use the [phone menus and hold guide](https://docs.tryopencomputer.com/guides/phone-menus.md) for configuration, an example call flow, and reviewing whether the intended department was reached.

## Configure an HTTP API tool

1. Create an **External HTTP API** tool and set **Tool Name** and **Description**.
2. Set **HTTP Method**, **Endpoint URL**, and **Timeout (ms)**. Use an endpoint you control for the initial check.
3. Define **LLM Parameters** for values the model should supply and **Preset Parameters** for configured or context-derived values. Set required inputs and their descriptions so the model knows what to collect.
4. Select authentication through [Credentials](https://docs.tryopencomputer.com/guides/credentials.md), add any nonsecret custom headers, and configure the body template/format when needed.
5. For a supported Athena voice action that needs consent, enable **Ask the caller before running**. Check approval, refusal, and an unclear response against a harmless test receiver; a gated request needs a clear yes.
6. Save, use the HTTP-tool test with synthetic arguments, and inspect both the receiver and the returned status/data. Attach it to the node and perform a conversation-level test before publishing.

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:

```json theme={null}
{
  "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](https://docs.tryopencomputer.com/guides/context.md) for passing values into HTTP templates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.