> ## 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

> How your product reaches the assistant.

A tool server is an MCP server the platform calls during a conversation. It is
the only way your product influences what an assistant can do.

## The three methods

| Method       | When                                      | Purpose                                   |
| ------------ | ----------------------------------------- | ----------------------------------------- |
| `initialize` | Discovery, and when a session is demanded | Handshake; may return an `Mcp-Session-Id` |
| `tools/list` | Discovery only, never in a turn           | What you offer                            |
| `tools/call` | Mid-conversation                          | Run one tool                              |

The platform sends `MCP-Protocol-Version: 2025-06-18` and accepts either an
`application/json` body or a `text/event-stream` response.

## Sessions

If your server needs a session, answer a session-less `tools/call` with **400**
or **404**. The platform then runs `initialize`, picks up `Mcp-Session-Id`, and
retries once.

<Note>
  It tries without a session **first**, on purpose. Handshaking before every
  call would add two round trips to every tool use, inside a conversation
  someone is waiting on.
</Note>

## Timeouts

Calls time out in **10 seconds** by default, with one retry.

<Warning>
  This budget is not generous, and it is not going to be. A tool call happens
  while a customer waits for a reply. If your work takes longer, return
  immediately with what you know and let the assistant follow up — do not hold
  the connection open.
</Warning>

## What a failure does

Nothing you return can break a conversation. A timeout, a refusal, a crash —
each becomes a tool result the assistant reads and explains. It will say the
team will check and carry on.

That is a guarantee about the platform, not permission to fail: an assistant
that cannot answer is still a customer who did not get an answer.