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

# Connecting your API as tools

> Import an OpenAPI spec, shape the tools your agents see, keep them in sync as your API changes, and test them before an agent does.

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:

```text theme={null}
POST   /v1/tool-providers            # provider, optionally with its API tools
POST   /v1/tools                     # one tool under a provider
PATCH  /v1/tool-providers/:id/tools  # many tools in one write
GET    /v1/tool-providers            # summary: tool count, auth type, which agents use it
GET    /v1/tool-providers/:id        # provider plus every tool, in full
```

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.

<Warning>
  **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.
</Warning>

## 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](/docs/approvals).
* **Set `loop_responses`** on anything that paginates or returns large
  collections. See [Working with large APIs](/docs/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:

```bash theme={null}
curl -X POST https://api.sidenet.ai/v1/tools/TOOL_ID/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "property_id": "prop_123" } }'
```

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.

<Note>
  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.
</Note>

## 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](/docs/tool-auth).

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.