Skip to main content
An agent is worth what its tools are worth. This page covers getting your REST API in front of an agent and keeping it correct as your API moves.

​
Providers and tools

A provider is one API: a base URL, default headers, and its authentication. The tools under it are individual operations — one per endpoint you want an agent to be able to call. Create a provider with its tools in one request, or add them afterwards:
Credentials go to the vault and are never returned by a read. Each write reloads only what changed and rebuilds the agents that use it — you don’t need to rebuild anything by hand.

​
Import from OpenAPI

Paste your spec into the Studio and every operation becomes a candidate tool. Two things to fix before you accept them: Names. The model sees the tool name. An operation whose imported name is a long API summary is normalised automatically — the model-facing name is derived and de-duplicated, and the readable label moves into the description — but it’s worth checking the result. get_clients is a good name; getClientsByOrganisationIdV2Beta is not. Descriptions. This is the single highest-leverage text in your integration — more than any prompt. Describe what the endpoint returns and when to use it, in your users’ vocabulary, and name the neighbouring tool when two are easily confused.
Never describe a parameter the schema doesn’t expose. A description promising “filter by property id” when input_schema has no such field produces an agent that tries, fails, and retries. The schema is the contract; the description explains it.

​
Shaping what the agent sees

  • Prune. Import everything, attach only what an agent needs. An agent that holds 60 tools chooses worse than one holding 8.
  • Pin fixed values in the tool’s configuration rather than instructing the model to always pass them. A pin is a fact; a prompt rule is an exhortation, and small models ignore exhortations under load.
  • Set require_approval on anything that writes, charges or sends. See Approvals.
  • Set loop_responses on anything that paginates or returns large collections. See Working with large APIs.
Both flags show as badges on the tool card in the Studio, in both states, and can be flipped from the badge itself.

​
Test the tool, not your assumption

Run a tool directly, with the provider’s real method, path, auth and declared schema:
This is the fastest way to find a wrong base URL, a missing header or a schema that doesn’t match reality — before an agent meets it.
It exercises the tool, not the binding. Configuration pinned on an agent’s copy of the tool, loop_responses behaviour and approval pauses are all part of the binding, so they still need a real agent turn to verify.

​
Keeping up with your API

When your API changes, re-import the spec rather than editing tools by hand. You get a review screen before anything is applied:
  • New endpoints, collapsible and editable before you accept them.
  • Changed endpoints, one row per field — field name, current value, new value — colour-coded and editable inline.
  • Accept or reject field by field, or in bulk across the whole spec. Rejected endpoints move to an Ignored group you can revisit.
Endpoints are matched on method and path, so a renamed operation reads as an update rather than a new tool plus an orphan. Nothing is ever deleted: an endpoint missing from the spec can be marked deprecated, and that is opt-in and excluded from “Accept all”, so pasting a partial spec can’t flag your live endpoints. Tools keep their ids, so agents referencing them keep working, and hand-added tags survive. Nothing is applied until you press Apply.

​
Authentication

Providers support static credentials — bearer, API key, basic and custom headers — and three OAuth 2.0 grants: client credentials, password and refresh token, with tokens fetched and refreshed for you. Credentials can also be supplied per user at runtime, which is how you give each of your end users their own access. See Authenticating tool providers. Outbound tool requests are logged with URL, method, body length, a short body preview and a masked view of the headers, so a 401 from your upstream is diagnosable. Credential values are never written out in full.

​
Checklist

  • Provider base URL and auth verified with execute before any agent holds a tool.
  • Tool names are short, verb-first and readable; descriptions match the schema exactly.
  • Fixed arguments are pinned in configuration, not requested in a prompt.
  • Write, charge and send operations carry require_approval.
  • Paginated collections carry loop_responses.
  • Spec changes go through re-import and its review screen, never hand edits.