Skip to main content
POST
Search Tools
Use this endpoint to find the most relevant Tools for a given query, rather than loading all available Tools. This is especially useful for AI agent implementations where your user may have hundreds of available Tools — Search lets you dynamically select only the Tools relevant to the current task.

Filtering

You can narrow search results using the request body parameters:
  • integrations — Restrict results to specific integrations (e.g. ["salesforce", "hubspot"]).
  • categories — Restrict results to integration categories (e.g. ["crm"]).
  • topK — Set the number of Tools to return. Defaults to 8.
  • maxSideEffect — Exclude Tools that can change data beyond a given level. See Side Effects.

Token Budget

Use maxToolTokens to constrain the total token size of returned Tool schemas. Tools are included in relevance order until the budget is exhausted. This is useful for fitting tool schemas into your LLM’s context window without manual truncation. When maxToolTokens is set:
  • If topK is also set, at most topK tools are returned, further constrained by the token budget.
  • If topK is omitted, as many tools as fit within the budget are returned (up to 50).

Side Effects

Every Tool in the results has a sideEffect that describes what it does in the connected app: Each Tool also has an approvalRequired flag. It is false for read Tools and true for everything else, including unknown. Use it to decide when your agent should ask the user to confirm before running a Tool.

Limiting results by side effect

Set maxSideEffect to the most impactful kind of Tool you want returned. Each level includes the levels below it: Tools with a sideEffect of unknown are excluded whenever maxSideEffect is set. The number of Tools removed by this setting is returned in usage.omittedForSideEffect, so you can tell the difference between a search that matched nothing and one where results were filtered out.

Running Tools

Run Tool currently only runs read Tools. Running any other Tool, including unknown Tools, returns a 403 with the error code EXEC_SIDE_EFFECT_NOT_PERMITTED. Pass maxSideEffect: "read" when searching if you want to return only Tools your agent can run.

Authorizations

Authorization
string
header
required

Your Paragon User Token (JWT), which you can generate using your project's signing keys.

Path Parameters

projectId
string<uuid>
required

Query Parameters

diagnostics
enum<string>
Available options:
1

Body

application/json
query
string
required
Required string length: 1 - 1024
topK
integer
default:8
Required range: 1 <= x <= 50
maxToolTokens
integer
Required range: 1 <= x <= 100000
integrations
string[]
Minimum array length: 1
categories
string[]
Minimum array length: 1
maxSideEffect
enum<string>
Available options:
read,
write,
delete,
send
connectedOnly
boolean
default:false
rerank
boolean
default:true

Opt out only. true cannot enable reranking when the deployment has it off.

Response

Ranked tools.

tools
object[]
required
searchQuery
string
required
errors
object[]
required
usage
object
required
trace
object

Present only when diagnostics=1.