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

# Tools

Tools are declarative. You add what the agent can call with `telnyx-acp add tool`, which writes it to `agent.json`, and the platform handles invocation, credentials and results. Web Search, Browser and MCP Servers are available today. The rest are on the roadmap, in preview.

* **[Web Search](https://developers.telnyx.com/docs/agents/tools/web-search.md):** Search the live web, read a page, or research a question across sources. No key to add.
* **[Browser](https://developers.telnyx.com/docs/agents/tools/agent-browser.md):** A real browser the agent drives: open a page, read it, click, fill a form, submit. On [Agent Browser](https://developers.telnyx.com/docs/agent-browser.md), an isolated session per run, no key to add.
* **[MCP Servers](https://developers.telnyx.com/docs/agents/tools/mcp-servers.md):** Connect to any remote [Model Context Protocol](https://modelcontextprotocol.io) server by URL. This is the simple case, a server and an optional credential. For governed access, use Gateway.

```bash theme={null}
telnyx-acp add tool web_search
telnyx-acp add tool browser
telnyx-acp add tool mcp --url https://mcp.deepwiki.com/mcp
telnyx-acp tools
```

`telnyx-acp tools` lists the names the model sees. A call whose execution fails returns to the model as text it can act on, not as a failed run; arguments that fail the tool's schema still fail the run.

The list can live in its own file: `telnyx-acp tools --file tools.json` moves it out of `agent.json`, which then says `"tools": "tools.json"`, and every verb reads and writes it there. [tools](https://developers.telnyx.com/docs/agents/cli/tools.md) has the flags.

## Approvals

An approval makes a tool's calls wait for a human. Mark the tool by the name the model sees, which `telnyx-acp tools` lists. A running `dev` reloads it.

```bash theme={null}
telnyx-acp set approvals.fetch_page ask
```

> [!WARNING]
>
> **Beta.** Approvals work under `telnyx-acp dev` today. On a deployed agent a run with an `ask` tool pauses, but the platform does not yet keep the approval to decide, so the run cannot be approved and fails after 15 minutes; `deploy` warns when `agent.json` has an `ask` entry. Keep `ask` out of a deployed agent until that lands.

A run that reaches `fetch_page` pauses. Under `telnyx-acp dev`, `invoke --local` ends with the approval's id instead of a reply.

```text theme={null}
telnyx-acp: run run-alice-… is waiting for approval of fetch_page (approval aitxt-mkMExPuX1IkrPyD4rHTknW4f)
  decide it with `telnyx-acp rpc <name> --conversation <id> approve aitxt-mkMExPuX1IkrPyD4rHTknW4f` (or deny); the run then finishes on its own.
```

Approve or deny it within 15 minutes, by that id.

```bash theme={null}
telnyx-acp rpc support-agent --conversation alice --local approve aitxt-mkMExPuX1IkrPyD4rHTknW4f
telnyx-acp rpc support-agent --conversation alice --local deny aitxt-mkMExPuX1IkrPyD4rHTknW4f
```

Tools that are not named run without asking (`allow`); `deny` hides a tool from the model. `telnyx-acp unset approvals.fetch_page` removes the entry.

## Limits

```bash theme={null}
telnyx-acp set limits.steps 12
```

`limits.steps` caps the model steps one run may take, 8 by default. A step is one model generation, with whatever tool calls it requests; the generation that reads their results is the next step. `limits.browserActions` caps the browser actions one run may take, 40 by default, so a model that loops cannot burn a session.

On a call, tools run only with [`voice.harness`](https://developers.telnyx.com/docs/agents/reference/agent-json#voice) on, and a tool marked `ask` is left out even then, since a call cannot wait for an approval; the agent says so once in the logs, `{"voiceTools":"left out on calls","tools":[…],"reason":"a call cannot wait for an approval"}`. Texts and `invoke` keep the full set. [Limits, Approvals, Tools](https://developers.telnyx.com/docs/agents/reference/agent-json.md#limits-approvals-tools) has the `agent.json` fields.

## On the Roadmap

These tools are in preview. An agent cannot call them yet.

* **[Gateway](https://developers.telnyx.com/docs/agents/tools/agent-gateway.md)** Preview Governed connectivity to APIs and MCP servers, with authentication, access control and policy. Reference an instance and every tool configured on it becomes available.
* **[Sandbox](https://developers.telnyx.com/docs/agents/tools/agent-sandbox.md)** Preview Sandboxed code execution for data analysis and computation.
* **[File System](https://developers.telnyx.com/docs/agents/tools/file-system.md)** Preview View, create and edit files on a CloudFS mount.