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

# Available tools

> Tools the Inspack MCP server exposes.

The Inspack MCP server exposes six active tools and five retained, retired tools. Authenticate with your Inspack API key as a bearer token (see [Connect a client](https://docs.inspack.com/mcp/connect.md)). Auth is enforced at the transport — every request must carry a valid bearer token before any tool dispatch happens.

For the recommended end-to-end flow (file drop → review), see [How a review works](https://docs.inspack.com/mcp/overview.md#how-a-review-works).

## `prepare_upload`

Initialize a backend upload version with `readable: {filename, content_type, bytes, sha256?}`. Optional inputs are `asset_id`, `originals` (same file shape), `callback_url`, and `org_id` (system tokens only). This replaces the old `{filename, mime_type}` arguments.

Returns backend `asset_id`, `version`, `folder`, `status_url`, and `uploads` unchanged. Each slot has `url`, `path`, `role`, `expires_at`, `max_bytes`, and `required_headers`. PUT every file with all returned headers verbatim and no bearer credentials. Signing, caps, expiry, and processing are owned by the backend. Then call `process_upload` and `get_upload_status`. See [upload lifecycle and exact header examples](https://docs.inspack.com/public-upload-api.md).

## `process_upload`

Call with `{asset_id, version}` after all PUTs succeed, plus an optional `ctx`. System tokens also provide an explicit `org_id`. MCP maps `version` to the public process body field `asset_current_version` and forwards `ctx` unchanged.

| `ctx.operation` | Effect |
| - | - |
| omitted / `asset_for_review` | Full extraction for a review: previews, classification, panels where applicable, content. |
| `inspector_extraction` + `inspector_type` (+ `on_question`) | Draft inspectors from a brief, master label, brand guidelines or safety data sheet. Pauses with a question when the detected asset type does not fit, unless `on_question` is `proceed` or `stop`. |
| `reference_asset` | Previews and classification only. |
| `answer_question` + `run_id`, `question_id`, `option_id` | Resume a paused run with one of its question's options. |

Returns the backend result unchanged: `status`, `deduplicated`, `stages`, `run_id`, `operation`, and `question` (null unless the run paused). Follow the returned version when it reuses an earlier version. A `status` of `awaiting_input` carries a `question` with `message` and `options[]` (`id`, `label`, `ctx`); render them generically and answer with this tool. A stale or conflicting answer is a 409 upstream error, an option the question does not offer 400, an invalid `ctx` `invalid_upload_input` before any call. Repeating an accepted intent returns the current state. No review credits consumed.

## `get_upload_status`

Call with `{asset_id, version}` (plus an explicit `org_id` for system tokens). MCP maps `version` to the public status query field `asset_current_version`. Reads one status snapshot without internal polling and returns `{status: VersionStatusView, content: ArtifactEnvelope | null}`. The status carries the newest run's `operation`, `original_ctx`, `effective_ctx`, `run_id`, `waiting_for_run_id`, and `question` (with its `answer` once resolved); `latest` is scoped to that run. `awaiting_input` means a question to answer with `process_upload`; `cancelled` is terminal with no content from that run. Hydrates the latest content artifact server-side using the caller's token, restricted to configured storage and matching artifact identity. Tokens are sent only to the portal and redirects are refused. Read or contract failures return explicit errors.

Inspect stage failures. Running and partial versions may already have content; failed versions may have no content. Clients control polling. Convert `content.payload` text/grounding into text review objects; the envelope itself is not a review object. The normal payload has `image_urls: []`; use `status.latest.render.url` for a visual image object. MCP `review` temporarily fetches canonical protected upload images and encodes data URLs server-side. No review credits consumed.

## `review`

Review one shared list of text and image objects with one or more inspectors. The response includes each inspector's results and aggregated findings together. This replaces the inspect-then-aggregate workflow.

### Input

| Field | Type | Required | Description |
| - | - | - | - |
| `objects` | array | For inspector runs | Content shared by all inspectors. Each entry is `{ "type": "text", "content": "..." }` or `{ "type": "image", "content": "https://..." }`, with optional object-specific `ctx`. Images may be public raster URLs, image data URLs, or canonical upload image URLs that MCP temporarily hydrates with the caller's key. Fetched PNG/JPEG/WEBP/GIF images are limited to 20 MiB total and a 30-second read timeout. Process documents with the upload lifecycle first. |
| `inspector_ids` | number\[] | For selected inspectors | IDs from `get_inspectors`. Use `[id]` for one inspector or several IDs for the same content. Send separate review requests for different content. |
| `context_selection` | enum | No | `requested` (backend default) applies inspector context and rule scopes; `none` forwards objects unchanged. |
| `include_recommendations` | boolean | No | Default `false`. Add recommended inspectors; requires `asset_type` and `industry` when running inspectors. |
| `ctx` | object | For finding operations | Typed context with `operation: question_about_existing_finding` or `summarize_findings` (the deprecated alias `summary_existing_findings` is accepted and normalized). See the [finding operation examples](https://docs.inspack.com/public-review-api#typed-finding-operations). |

The full contract also supports recommendation context (`asset_type`, `industry`, `countries`, `brand_id`, `product_name`, `use_case`, and `max_recommendations`), `doc_context`, `insights_locale`, memory via `previous_inspections`, and prior question/answer pairs via `session_context`. The customer's organization comes from authentication. See the [review contract and migration guide](https://docs.inspack.com/public-review-api) and [API reference](https://docs.inspack.com/api-reference/introduction.md) for the complete schemas.

```json theme={null}
{
  "objects": [{ "type": "text", "content": "Your marketing copy" }],
  "inspector_ids": [123, 456]
}
```

### Output

Read `inspector_results` for each inspector's violations and `summaries` for the aggregated findings. Inspect `inspector_errors` even on a successful HTTP response; some or all inspectors can fail. Zero violations with no inspector errors is a successful review. The response also preserves `state`, `operation`, `selected_inspectors`, `memory`, `blocks`, and conversation metadata (`document_version`, `review_revision`, `finding_id`).

Each request that runs inspectors costs one review credit, regardless of inspector count. Questions and summaries of supplied findings are free; a summary with omitted or null `ctx.summaries` first runs inspectors and costs one credit. HTTP, transport, or contract failures and wholly failed inspector runs refund an applied charge. Partial successes and zero-violation results retain it. System tokens are exempt.

## `get_inspectors`

List the inspectors available to the calling organization. Returns inspector descriptors (id, name, etc.). Pass their IDs in `inspector_ids` to `review`.

### Input

No input. The caller's organization is inferred from the bearer API key.

### Output

An array of inspector descriptors.

## `doc_parse`

Retired and retained for migration guidance. The legacy schema still accepts `file_url`, optional `output_type` (`html`/`md`), and optional `pdf_images_mode` (`pages`/`extract`/`none`). Calls return `isError: true` with `error.code: tool_retired`, `replacement: prepare_upload`, and instructions for `prepare_upload → PUT → process_upload → get_upload_status`. No upstream parsing or review credits consumed. See the [migration guide](https://docs.inspack.com/public-upload-api.md).

## `report_export`

Generate the server-side Insights Report PDF for an existing Inspack document.

### Input

| Field | Type | Required | Description |
| - | - | - | - |
| `documentId` | string | Yes | Unique identifier of the Inspack document to render as a PDF. |

### Output

A PDF resource link:

```json theme={null}
{
  "type": "resource_link",
  "uri": "https://app.inspack.com/api/v1/documents/report-export?documentId=doc-uuid-123",
  "name": "Insights Report.pdf",
  "mimeType": "application/pdf"
}
```

## Retired tools

The following tools remain registered with their legacy input schemas for migration guidance. Every call returns `isError: true` with `error.code: tool_retired`, `error.replacement: review`, and migration instructions. Retired calls make no upstream requests and consume no review credits. See the [migration guide](https://docs.inspack.com/public-review-api).

### `inspect`

Retired. Call `review` with `inspector_ids: [id]` and the same `objects` list. The legacy `inspector_id` field is rejected by `review`.

### `inspect_multiple`

Retired. Call `review` with one shared `objects` list and `inspector_ids: [id1, id2]`. If the old `inspectionInput` entries contain different content, send separate review requests. `review` does not accept `inspectionInput` or `documentId`.

### `aggregate`

Retired. `review` returns both `inspector_results` and aggregated `summaries`, so remove the separate aggregation call. Standalone aggregation of supplied raw violations is retired; `review` rejects the legacy `inspections` field. To summarize existing findings, use typed `ctx.operation: summarize_findings` with `ctx.summaries` as described in the [finding operation examples](https://docs.inspack.com/public-review-api#typed-finding-operations).

### `start_upload`

Retired. Call `process_upload` with the same `{asset_id, version, org_id?}` arguments and an optional `ctx`; omit `ctx` for the previous behaviour (full extraction for a review). Calls return `isError: true` with `error.code: tool_retired`, `replacement: process_upload`, and migration instructions, and make no upstream request. See the [migration guide](https://docs.inspack.com/public-upload-api.md#migrating-from-start-and-start_upload).

## Errors

All tools share the same error envelope:

* **`auth_required`** — no API key was sent. Add `Authorization: Bearer <key>` to your MCP client config.
* **`upstream_unavailable`** — Inspack couldn't be reached. Retry shortly.
* **`tool_retired`** — a retired tool was called. Follow its replacement and migration instructions.
* **Inspector / upstream errors** — invalid IDs, malformed input, rate limits, and similar are surfaced from the upstream response with their original status and code.
* **`invalid_upload_input`** — upload arguments failed validation; use the backend file shape including exact byte length.
* **`upstream_contract_error`** — malformed upload response, unsafe artifact URL, or mismatched artifact identity.
* **`artifact_read_error`** — the content artifact could not be retrieved; retry or check backend/storage status.
* **`image_read_error`** — a protected review image could not be retrieved or is invalid/oversized; review was not submitted. This MCP-only workaround is temporary; shared public-review handling is tracked in [ENG-2074](https://linear.app/getgenai/issue/ENG-2074/public-visual-review-cannot-read-protected-upload-images-consistently).
* **`request_cancelled`** — the client cancelled the upload request.
* **PUT failures** — use backend signed-slot errors and expiry values. The old custom upload relay returns HTTP 410 with migration guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.