docs: record Kong's MCP tool-generation limits and our workarounds

The domains' tools: arrays are hand-maintained, and that has now cost two
defects an agent found the hard way — create-product could never succeed, and
list-products cannot paginate, which let a model answer a product count that
looked right and did not come from the data.

Five limits measured against decK v1.64.0 and Kong Gateway 3.15, each
reproduced rather than read: per-tool ACLs cannot express a consumer-group
model and fail silently; the four MCP behavioural annotations are not
generated; response schemas are not generated although the plugin consumes them
for structuredOutput; servers is taken as the upstream target; every content
type is copied and every operation exposed.

FastMCP run on the same spec is recorded as a comparison point — it closes
three of the five out of the box — with the reason we are not adopting it: it
would move per-tool authorization out of the realm and into application code.

Also records that MCP Composer and MCP Runner never shipped, so none of this is
waiting on an imminent release.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -7,6 +7,13 @@ Per-domain gateway infrastructure (`Gateway`, `GatewayConfiguration`,
 `KonnectAPIAuthConfiguration`) does NOT live here — see the dedicated
 `dataplane-<domain>` repos, to avoid write contention across domains.
 
+## MCP-TOOL-GENERATION.md
+
+How the domains' MCP tool definitions are produced, the five limits of Kong's
+`deck file openapi2mcp` generator, and the workaround each one forces. Read it
+before editing any `<domain>-api/kong/mcp/ai-mcp-proxy.yaml` by hand — that file
+is hand-maintained today, and that is precisely the problem it documents.
+
 ## flux/
 
 The Flux Operator (`flux-system` namespace) that everything else in this