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

# Tools API

> Give your agent the capabilities it needs to act across your users' connected apps.

The Tools API lets your agent search Paragon's pre-built library of thousands of actions, run them on behalf of your users, and re-query large results to keep your agent's context small. Requests are sent to the [Agent OS base URL](https://docs.useparagon.com/agent-os/overview.md#base-url) and are authenticated with a Paragon User Token.

## How it works

**1. Find the right tools**

[Search Tools](https://docs.useparagon.com/agent-os/tools/search.md) returns the tools most relevant to what your user is asking for, so you don't have to load every available tool into your agent. Use [Get Tool](https://docs.useparagon.com/agent-os/tools/get-tool.md) to fetch a single tool definition by name.

**2. Run a tool**

[Run Tool](https://docs.useparagon.com/agent-os/tools/create-execution.md) runs a tool on behalf of a Connected User and returns the result, or a reference to the result if it is large.

**3. Read large results in pieces**

When a result is stored, read only the parts your agent needs with [Get Result](https://docs.useparagon.com/agent-os/tools/get-result.md), [Get Result Rows](https://docs.useparagon.com/agent-os/tools/get-result-rows.md), or [Get Result Content](https://docs.useparagon.com/agent-os/tools/get-result-content.md).

## Endpoints

Every path starts with `/api/tools/projects/{projectId}`.

| Endpoint | Use it to |
| - | - |
| [`POST /tools/search`](https://docs.useparagon.com/agent-os/tools/search) | Find the most relevant tools for a query. |
| [`GET /tools/{intentName}`](https://docs.useparagon.com/agent-os/tools/get-tool) | Fetch one tool definition by its name. |
| [`POST /executions`](https://docs.useparagon.com/agent-os/tools/create-execution) | Run a tool. |
| [`GET /executions/{executionId}`](https://docs.useparagon.com/agent-os/tools/get-execution) | Check on a tool run, optionally waiting for it to finish. |
| [`POST /executions/{executionId}/cancel`](https://docs.useparagon.com/agent-os/tools/cancel-execution) | Cancel a tool run that is still in progress. |
| [`GET /results/{resultId}`](https://docs.useparagon.com/agent-os/tools/get-result) | Read the summary of a stored result. |
| [`GET /results/{resultId}/rows`](https://docs.useparagon.com/agent-os/tools/get-result-rows) | Filter and page through the records in a stored result. |
| [`GET /results/{resultId}/content`](https://docs.useparagon.com/agent-os/tools/get-result-content) | Read a stored text result in slices. |

## Running a tool

[Run Tool](https://docs.useparagon.com/agent-os/tools/create-execution.md) runs one tool, named by `intentName`, with the inputs you pass in `args`.

### Handling large results

Use `outputMode` to control whether a tool's result is returned directly or stored for you to read later:

| Mode | Behavior |
| - | - |
| `auto` (default) | Returns the result directly if it is at most 4000 tokens. Larger results are stored. |
| `inline` | Always returns the full result directly. |
| `reference` | Always stores the result and returns a `resultId` for you to read from. |

Stored results are available for 24 hours.

### Waiting for results

By default, a request waits up to 25 seconds for the tool to finish. If it finishes in time, you get the result with a `200`. If it is still running, you get a `202` with a `Location` header pointing to the execution. Poll [Get Execution](https://docs.useparagon.com/agent-os/tools/get-execution.md) until it settles.

To change how long a request waits, send a `Prefer: wait=<seconds>` header. Use `wait=0` to return immediately.

## Permissions

Tools always run as the Connected User identified by your Paragon User Token. Unlike the [Context API](https://docs.useparagon.com/agent-os/context/overview.md), the Tools API does not accept an `identity` or `email` override.