> ## 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 contract > What your MCP server or OpenAPI description must provide, and how ImpelLabs turns it into operations. Agents read your tool names, descriptions and input schemas to decide when to call a tool and what to send. Write them for a reader who has never seen your system. ## MCP server ImpelLabs speaks MCP over Streamable HTTP: JSON-RPC in a `POST` body. It uses protocol version `2025-06-18`. Your server may answer with plain JSON or with an event stream. In a stream, ImpelLabs reads the message that has the id of its request. The calls it makes, in order: 1. `initialize`, then the notification `notifications/initialized`. If your server gives a session id in the `Mcp-Session-Id` header, ImpelLabs sends it back on later calls. 2. `tools/list`. It follows `nextCursor` until the list ends. It stops at a fixed limit of tools. 3. `tools/call` with the tool `name` and its `arguments` when an agent calls a tool. From each tool, ImpelLabs keeps `name`, `title` (or `annotations.title`), `description`, `inputSchema` and `annotations`. A tool with no name is skipped. Your tool's `name` is the operation name in ImpelLabs. ### Credentials You may give a key. ImpelLabs sends it as `Authorization: Bearer KEY`, or in a header you name. The header name must be letters, digits and hyphens, and it cannot be one that the transport sets: `accept`, `content-type`, `content-length`, `host`, `mcp-protocol-version`, `mcp-session-id`, `transfer-encoding`, `connection`, `cookie` or `user-agent`. A server that asks people to sign in works too: ImpelLabs signs in with OAuth and renews the token before it expires. ### Risk from annotations ImpelLabs sets the risk of a tool from its annotations. A tool is `read` only when `readOnlyHint` is `true` and `destructiveHint` is not `true`. Every other tool is `write`. An admin can change the risk. Set `readOnlyHint` on tools that only read. ## API with an OpenAPI description Give an OpenAPI 3 or Swagger 2 description as JSON or YAML, up to 5 MB. Give it as text, or as an address that ImpelLabs fetches. Only local `$ref` values (`#/...`) are followed. ImpelLabs makes one operation from each `get`, `post`, `put`, `patch` and `delete` under `paths`, up to 300 operations. | Source in the description | Operation | | - | - | | `operationId` | Name. Without it, the method and the path make the name. | | `summary` and `description` | Description, as one plain line of up to 400 characters. Tags and line breaks are removed. | | `parameters` in `path`, `query`, `header` | Input fields. | | `requestBody` with a JSON or form body | Input fields. If the body is not an object, one field named `body`. | | `deprecated: true` | The operation is skipped. | | A body that is not JSON | The operation is skipped. | The base address comes from `servers[0].url` (variables replaced by their defaults), `host` and `basePath` in Swagger 2, or from the address of the description. You can set `base_url` yourself. It must be an `https://` address. ### How the input schema is built * The schema is plain JSON Schema with `additionalProperties: false`. `required` lists path parameters, required parameters and required body fields. * References are resolved and `allOf` is merged. For `oneOf` and `anyOf`, ImpelLabs uses the first option. * Objects keep up to 64 properties and nest up to five levels. Properties that are `readOnly` are left out. Enums keep up to 200 values. Property names must match letters, digits, `_`, `.` and `-`, up to 64 characters. * A name that clashes gets a number added. The real name goes on the wire. * Header parameters named `authorization`, `proxy-authorization`, `cookie`, `host`, `content-length`, `content-type`, `transfer-encoding`, `connection`, `accept` or `user-agent` are left out. Your credentials set what is needed. ### Risk from the method `GET` and `HEAD` operations are `read`. Every other method is `write`. An admin can change the risk, and a risk that an admin set stays after a refresh. ### Where each input goes When an agent calls the operation, ImpelLabs sends only the fields that the operation declares. Path fields are URL-encoded into the path, query fields go in the query string, header fields go in headers, and body fields go in one JSON object. A missing path value or a missing required field stops the call before any request is made. The agent gets the message. ## Names and keys Each operation gets the key `connector..`, built from the connection name and the operation name in lower case with underscores. The key is fixed when the operation is first found. Another operation that makes the same key gets a number added. ## Changes that need a review On refresh, an existing operation goes off, with the reasons saved, if any of these is true: * Its risk went up and no admin set the risk. * New arguments appeared. * Its arguments are no longer described. * It now calls another method or path. An admin turns it on again after the review. New operations start on only when they read. A refresh that lists nothing changes nothing and reports an error. ## Related * [Results and side effects](https://docs.impellabs.tech/developers/own-tools/results.md) * [Security model](https://docs.impellabs.tech/developers/own-tools/security.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.