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

# Tool servers

> Letting the assistant act on your platform, per merchant.

Knowledge lets an assistant *answer*. Tools let it *do* — look up an order,
check stock, place a cart. Those live in your product, and the assistant calls
them at conversation time over [MCP](/mcp/overview).

Nothing is copied. There is no catalogue in our database to keep in sync.

## Register per tenant

```http theme={null}
POST /api/v1/partner/tenants/{ref}/tools/
```

```json theme={null}
{
  "label": "Storefront",
  "url": "https://mcp.yourplatform.com/mcp",
  "auth_token": "token-that-identifies-this-merchant-to-you",
  "enable_tools": true
}
```

The response lists what was discovered:

```json theme={null}
{ "id": "…", "protocol_version": "2025-06-18",
  "discovered": 4, "skipped": [],
  "tools": [{"name": "search_products", "enabled": true}, …] }
```

## How multi-tenancy works

<Note>
  **One URL, one token per merchant.** You register the same endpoint for every
  tenant with a different `auth_token`, and your server resolves which merchant
  from that token.

  No tenant id travels in the URL or the tool arguments — so there is nothing for
  a confused model, or a determined customer, to change. The isolation is in a
  credential the conversation never sees.
</Note>

Rotate a merchant's token by re-registering with the same `label`; the row is
updated in place.

## Allowed hosts

Tool server hosts are allowlisted. Your hosts are added to your partner record
once, after which you can register any path on them without further approval.
Send us the hostname when you onboard.

An unlisted host returns:

```json theme={null}
{ "detail": "That tool server host is not allowed by the platform." }
```

## What happens to your tool descriptions

Descriptions reach the model's prompt, so they are treated as untrusted input:
capped at 400 characters, flattened to one paragraph, and stripped of
instruction-shaped phrases. Names are namespaced per server, and a name that
collides with a built-in (`finish_turn`, `create_booking`, …) is refused rather
than renamed.

Write descriptions for a colleague who has never seen your API. That is
genuinely the highest-leverage thing you can do for answer quality.

<Card title="Building the server" icon="wrench" href="/mcp/tool-contract">
  The tool contract, result shapes, and side-effect rules.
</Card>