From 201fe10e3e3616ce76da8d39a0b058492323c70e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 3 Aug 2026 16:18:36 +0000
Subject: [PATCH] docs(mcp-openapi): document x-zilla-mcp extension and
 tools.title/annotations

The options.tools reference only documented description/summary/input/output
overrides, and never mentioned the x-zilla-mcp OpenAPI vendor extension
(title/description/annotations) that mcp-kafka-connect and mcp-schema-registry
use via overlay to supply MCP metadata without an authored options.tools entry
or editing the vendored spec. Adds tools.title and tools.annotations (with its
four hint children), corrects the tools.description precedence chain, and adds
an info callout documenting the x-zilla-mcp extension shape and fallback order.
---
 .../bindings/mcp-openapi/.partials/options.md | 66 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/src/reference/config/bindings/mcp-openapi/.partials/options.md b/src/reference/config/bindings/mcp-openapi/.partials/options.md
index 75d36bcd..f24c1cb8 100644
--- a/src/reference/config/bindings/mcp-openapi/.partials/options.md
+++ b/src/reference/config/bindings/mcp-openapi/.partials/options.md
@@ -26,6 +26,7 @@ options:
         bearerAuth: my_guard
   tools:
     create_pr:
+      title: Create Pull Request
       description: Create a pull request to merge one branch into another.
       summary: "Created pull request #${result.number}"
       input:
@@ -103,6 +104,26 @@ Specific version of the registered OpenAPI document.
 
 Catalog reference resolving an [OpenAPI Overlay](https://github.com/OAI/Overlay-Specification) document, applied to the OpenAPI document before it is parsed. Overlay actions can patch or extend the base document — for example, to add a `security` requirement or `servers` entry — without duplicating it. Uses the same shape as [`specs.catalog`](#specs-catalog).
 
+::: info The `x-zilla-mcp` operation extension
+An OpenAPI operation — whether authored directly in the base document or added by an `overlay` action — may carry an `x-zilla-mcp` object to supply MCP-specific metadata without an authored [`options.tools`](#options-tools) override:
+
+```yaml
+paths:
+  /pulls:
+    post:
+      operationId: create_pr
+      x-zilla-mcp:
+        title: Create Pull Request
+        description: Open a pull request from one branch into another.
+        annotations:
+          readOnlyHint: false
+          destructiveHint: false
+          idempotentHint: false
+```
+
+[`tools.title`](#tools-title), [`tools.description`](#tools-description), and each [`tools.annotations`](#tools-annotations) hint fall back to this extension before falling back further still. This is how [`mcp-kafka-connect`](../mcp-kafka-connect/client.md) and [`mcp-schema-registry`](../mcp-schema-registry/client.md) supply real tool titles, descriptions, and annotations for their bundled specs via an `overlay`, without editing the vendored OpenAPI document itself.
+:::
+
 #### specs.security
 
 > `object` as map of named `string`
@@ -115,11 +136,17 @@ Maps each OpenAPI `securityScheme` name declared by the specification to the nam
 
 Overrides for MCP tools generated from routed OpenAPI operations. The named key is the tool name — either an explicit route's [`when[].tool`](#when-tool), or the automatic name assigned to a bulk-selected operation (see [`routes`](#routes)).
 
+#### tools.title
+
+> `string`
+
+Tool title surfaced to MCP clients by `tools/list`, overriding the operation's `x-zilla-mcp.title` vendor extension (see above). OpenAPI operations have no native title field, so a tool without either an override or the extension has no title.
+
 #### tools.description
 
 > `string`
 
-Tool description surfaced to MCP clients by `tools/list`, overriding the OpenAPI operation's own `description`, which is itself the fallback before the operation id.
+Tool description surfaced to MCP clients by `tools/list`, overriding — in order — the operation's `x-zilla-mcp.description` vendor extension (see above), its own native `description`, and finally its operation id.
 
 #### tools.summary
 
@@ -172,6 +199,43 @@ Specific version of the registered schema.
 
 Model overriding the schema generated from the OpenAPI operation's success response, surfaced as the tool-call `structuredContent`. Uses the same shape as [`tools.input`](#tools-input).
 
+#### tools.annotations
+
+> `object`
+
+Behavior hints surfaced to MCP clients by `tools/list`, overriding the operation's `x-zilla-mcp.annotations` vendor extension (see above), itself the fallback before an HTTP-method-derived default. Each hint resolves independently — overriding one does not require overriding the others.
+
+```yaml
+annotations:
+  readOnlyHint: false
+  destructiveHint: false
+  idempotentHint: false
+```
+
+#### annotations.readOnlyHint
+
+> `boolean`
+
+Whether the tool only reads data without modifying any state. Defaults to `true` for a `GET` or `HEAD` operation, otherwise unset.
+
+#### annotations.destructiveHint
+
+> `boolean`
+
+Whether the tool may perform a destructive update. Defaults to `true` for a `DELETE` operation, otherwise unset.
+
+#### annotations.idempotentHint
+
+> `boolean`
+
+Whether calling the tool repeatedly with the same arguments has no additional effect beyond the first call. Defaults to `true` for a `PUT` or `DELETE` operation, otherwise unset.
+
+#### annotations.openWorldHint
+
+> `boolean` | Default: `false`
+
+Whether the tool interacts with an open-ended set of external entities, rather than a fixed, closed set. Always defaults to `false` unless overridden or supplied by the `x-zilla-mcp` extension.
+
 #### options.resources
 
 > `object` as map of named `object`