Tools API - Paragon Documentation

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 and are authenticated with a Paragon User Token.

How it works

Find the right tools

Search Tools 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 to fetch a single tool definition by name.

Run a tool

Run Tool runs a tool on behalf of a Connected User and returns the result, or a reference to the result if it is large.

Read large results in pieces

When a result is stored, read only the parts your agent needs with Get Result, Get Result Rows, or Get Result Content.

Endpoints

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

Endpoint	Use it to
`POST /tools/search`	Find the most relevant tools for a query.
`GET /tools/{intentName}`	Fetch one tool definition by its name.
`POST /executions`	Run a tool.
`GET /executions/{executionId}`	Check on a tool run, optionally waiting for it to finish.
`POST /executions/{executionId}/cancel`	Cancel a tool run that is still in progress.
`GET /results/{resultId}`	Read the summary of a stored result.
`GET /results/{resultId}/rows`	Filter and page through the records in a stored result.
`GET /results/{resultId}/content`	Read a stored text result in slices.

Running a tool

Run Tool 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 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, the Tools API does not accept an identity or email override.

​How it works

​Endpoints

​Running a tool

​Handling large results

​Waiting for results

​Permissions