Tracking: response schemas for the direct tools #320

Tracks adding response schemas to the direct tools (?codemode=false), from measuring how well they match real responses to advertising them as outputSchema.

outputSchema is a promise: MCP clients that validate structuredContent against it reject any result that doesn't match. Many Cloudflare API responses don't match their published schemas, so we measure and fix first, and advertise once operations are clean.

• Measure. Check every JSON response a direct tool returns, success or error, against its operation's response schema, and record each mismatch with no response values. npm run report:schema-mismatches lists them by product, operation and violation, linked to the Forge release they were checked against. feat: check direct-tool responses against forge-generated response schemas #301
• Generate response schemas in the Forge MCP target. Emit each tool's response schemas into src/generated/forge-mcp, even though tools/list doesn't send them yet. Done on the forge-mcp branch (cloudflare/forge@9561734) and picked up in feat: check direct-tool responses against forge-generated response schemas #301.
• Check against the generated schemas. The check runs in the forge tools service, which holds the schemas; the main Worker sends it the body trimmed to 25 items per array. feat: check direct-tool responses against forge-generated response schemas #301
• Soak and fix. Run the report regularly, send each owning team its operations, and fix the schemas at the source until mismatches stop. Each fix shows up as the violation disappearing under newer Forge releases.
• Advertise. Send outputSchema and structuredContent to 2026-07-28 clients (Structured output and typed direct tools for MCP 2026-07-28 clients #257), starting with operations that have had no mismatches through the soak.

Open questions

• What ends the soak: zero mismatches per operation over some period, or a mismatch rate?
• Should only clean operations get an outputSchema, or every operation at once?
• Error responses are checked to measure them, but outputSchema only covers success. Do we act on error-schema mismatches too?