MCP Tool Annotations

Every tool exposed by the Closient MCP server carries a structured annotations object that tells the host (Claude, Claude Desktop, the Connectors Directory validator, third-party MCP clients) whether the tool mutates state and whether repeated calls are safe to retry. This is required by the MCP specification and by the Anthropic Connectors Directory submission process — servers that omit the annotations are rejected at submission time.

Annotation fields

Each tool sets a subset of the following hints. They are advisory — agents and hosts use them to decide whether to gate a call behind a confirmation prompt, or whether retrying after a transport error is safe.

Field	Meaning
`readOnlyHint`	`true` → the tool performs no state changes. Hosts may invoke without confirmation.
`destructiveHint`	`true` → the tool may destructively modify user-visible state (delete, overwrite).
`idempotentHint`	`true` → repeated calls with identical arguments yield identical effects.
`openWorldHint`	`false` → the tool reads only from Closient-controlled data (catalog, resolver rules).
`title`	Human-readable label for UIs that prefer a polished name over the snake-case tool name.

readOnlyHint=true and destructiveHint=true are mutually exclusive. A CI test (test_destructive_hint_implies_not_read_only) enforces this.

Closient’s policy

We use a narrow reading of destructiveHint: it means destructive changes — deletes, overwrites, revocations, cancellations — not “any mutation.” A tool that adds a record without erasing prior state is flagged readOnlyHint=false without destructiveHint. The trade-off: destructiveHint=true causes most hosts to render an extra “are you sure?” prompt before the call. That’s the right UX before deleting a brand claim or canceling a subscription, and the wrong UX before generating a QR code or recording an audit event. We reserve the hint for the former.

Per-tool annotations

Tool	`readOnlyHint`	`destructiveHint`	`idempotentHint`	Notes
`ping`	`true`	—	`true`	Health probe; no auth, no I/O.
`validate_gtin`	`true`	—	`true`	Pure validation — no DB access.
`resolve_gtin`	`true`	—	`true`	DB read against the resolver-rule hierarchy.
`lookup_product`	`true`	—	`true`	DB read against the product catalog.
`search_products`	`true`	—	`true`	Hybrid semantic + lexical catalog search.
`get_product_detail`	`true`	—	`true`	Rolled-up product read (images, ingredients, nutrition).
`compare_products`	`true`	—	`true`	Side-by-side read across 2-5 GTINs.
`check_availability`	`true`	—	`true`	Nearby-offer read via PostGIS.
`generate_qr_url`	`false`	—	`true`	Builds a Digital Link URL and records the call via `@user_action`. State-mutating but not destructive.
`create_product`	`false`	—	`false`	Creates a new catalog row; not idempotent (a second call with the same GTIN conflicts).
`update_product`	`false`	—	`true`	Updates scalar fields on an existing row. Additive, not destructive.
`upload_product_image`	`false`	—	`false`	Adds a new image; does not overwrite existing ones.
`delete_product_image`	`false`	`true`	`false`	Deletes user-visible data.
`upload_product_document`	`false`	—	`false`	Adds a new document.
`update_product_document`	`false`	—	`false`	Edits metadata / optionally replaces the file on an existing document.
`delete_product_document`	`false`	`true`	`false`	Deletes user-visible data.
`add_product_video`	`false`	—	`false`	Adds a new video link.
`update_product_video`	`false`	—	`false`	Edits an existing video’s fields.
`delete_product_video`	`false`	`true`	`false`	Deletes user-visible data.
`set_product_nutrition`	`false`	`true`	`true`	Wholesale-replaces the nutrition panel — rows omitted from the call are deleted.
`set_product_ingredients`	`false`	`true`	`true`	Wholesale-replaces the parsed ingredient list.

generate_qr_url was the lone non-read-only tool through C-344; C-4038 added the brand-owner product write tools above, five of which (delete_product_image, delete_product_document, delete_product_video, set_product_nutrition, set_product_ingredients) are the first tools to carry destructiveHint=true — they either delete a record outright or wholesale-replace a panel/list, dropping anything the caller didn’t re-list. The current destructive set is pinned by test_destructive_tools_match_pinned_set in backend/closient/tests/test_mcp_tool_annotations.py — the test fails loudly if a future contributor flips a bit without updating policy.

Wire format

Annotations are serialized as a nested object on each entry of the tools/list response. Pydantic’s exclude_none=True mode drops fields that weren’t set, so the wire payload is minimal:

{
  "name": "lookup_product",
  "title": "Look Up Product",
  "description": "Look up structured product data by GTIN. ...",
  "inputSchema": { "type": "object", "properties": { ... } },
  "annotations": {
    "title": "Look Up Product",
    "readOnlyHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

You can verify the shape against a running server with the MCP Inspector or a one-off curl:

curl -sS https://www.closient.com/mcp/http \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Adding a new tool

When you register a new tool with @mcp.tool() in backend/closient/mcp_tools.py:

Pass annotations=ToolAnnotations(...) with at least one of readOnlyHint / destructiveHint set.
Add a row to the per-tool table above and to the parametrized test_tool_read_only_hint_matches_policy test.
If the tool is destructive, update test_destructive_tools_match_pinned_set so the assertion still reflects ground truth.

The CI test test_every_registered_tool_has_annotations is the safety net — a missing annotation fails the suite before it can ship.

Getting Started

Developer Questions

User Guides

Technical Guides

MCP Server

Agent Skills

Compliance

Concepts

API Reference

Resources

MCP Tool Annotations

Annotation fields

Closient’s policy

Per-tool annotations

Wire format

Adding a new tool

​Annotation fields

​Closient’s policy

​Per-tool annotations

​Wire format

​Adding a new tool

Annotation fields

Closient’s policy

Per-tool annotations

Wire format

Adding a new tool