# Tool calls

## Tools and their names

Each operation in the version becomes a tool. Its name is the `x-agentify` or `x-mcp` name if the operation has one, else its operationId, else its method and path, with anything but letters, digits, `_`, `.` and `-` turned into `_`. A deprecated operation is left out. The tool's description is the operation's summary and description, and its title the summary when it's short.

Each parameter is an argument of the same name. If two would clash, the location goes in front, such as `query_id`.

Each tool carries hints for the client: reads are marked read-only, `DELETE`, `PUT` and `PATCH` destructive, and everything but `POST` and `PATCH` idempotent.

## Arguments are checked first

Before anything is sent, the arguments are checked against the tool's input schema: types, required properties, `additionalProperties`, items, `enum`, `const`, lengths, item counts, ranges and four formats. Values nested deeper than 8 levels aren't checked, and neither is anything else, such as `pattern`: both are left to your API. A failed check names each path that's wrong, never the value, and nothing is sent.

## The request

One request to your verified host, built from the tool, the arguments and the stored credential only. Nothing of the agent's own request is copied, its `Authorization` least of all.

- The path is your base URL plus the operation's path, with each path argument encoded. A value of `.` or `..`, or a path that would leave the base URL, is refused.
- Query and header arguments go where the document puts them.
- An argument can never set `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `Host`, `Content-Length`, `Content-Type`, `Accept`, `Accept-Encoding`, `Connection`, `Transfer-Encoding`, `X-Api-Key`, `Api-Key`, `X-Forwarded-For`, `Forwarded`, `X-Request-Id`, `Traceparent`, `Tracestate`, `User-Agent`, `X-Real-Ip`, `X-Payment`, or any `X-Agentify-*`, `Mcp-*` or `Payment-*` header.
- We send `Accept`, our own `User-Agent`, which names hosted MCP, and `X-Agentify-Operation` with the tool's name.
- The body, if the operation has one, is the body argument as JSON, with the operation's content type.
- The credential goes on last, so no argument can replace it.

It's sent once: never retried, and never redirected. It's cut off after 15 seconds.

## The answer

- A `2xx` answer comes back as text, JSON pretty-printed, read up to 1 MB. A longer one is cut, with a note saying so.
- A body that isn't text is described, by its size and type, instead of shown.
- A redirect comes back as an error with its `Location`. Another status comes back as an error with the start of its body.
- If your API echoes the credential back, the agent sees `[credential]` instead.

[Errors](errors) lists every message an agent can get.

## Where this comes from

- `app/hosted-mcp/_lib/upstream.ts`
- `app/hosted-mcp/_lib/validate.ts`
- `app/hosted-mcp/_lib/server.ts`
- `app/api/readiness/_lib/agentify/convert.ts`