MCP: Show valid update syntax in tool schemas #2631
Description
Make the advertised update-tool schemas show the JSON that Data API actually accepts, including operators such as $set and $unset. Clients should be able to construct valid update requests from the schema and examples. Internal Java field names do not explain that syntax.
This is an independent follow-up under #2408 and remains under the schema work in #2604. Reuse #2619's approach while keeping this ticket focused on update arguments.
This ticket is done when examples for updateOne, updateMany, and findOneAndUpdate validate against the generated schema and parse with the real Data API deserializer. Cover supported operators, extended JSON, optional values, and malformed inputs without changing accepted API syntax.
Status on October 23, 2026
PR #2651 fixes this. It describes the twelve supported update operators in the shared update clause schema, with contract tests and tools/list tests for all three update tools. It builds on #2619, which merged on October 23, so it is the next MCP PR for review. This stays under #2604.
Implementation requirements and source references
MCP tracking: #2408. Schema parent: #2604, part of #2596.
Tracking correspondence: Related changelog IDs are listed below. This is an independent follow-up, outside the launch milestone unless promoted for a demonstrated release blocker. Shared requirement IDs remain stable across the delivery plan and #2408.
Why
A client uses the advertised tool schema to construct a request. Data API update arguments accept operators such as $set and $unset, but the Java UpdateClause record stores an internal field named updateOperationDefs. Generating a schema from that field does not explain the JSON the API accepts.
PR #2619 covers filter, sort, hybrid-limit, and rerank-option schemas. It does not cover update clauses, so this is a distinct follow-up rather than a second copy of that work.
Work
- Describe the accepted update-operator JSON for
updateOne,updateMany, andfindOneAndUpdate. - Add useful descriptions and examples.
- Reuse the schema customizer and contract-test approach in fix: advertise Data API clause JSON in MCP schemas #2619.
Done when
Advertised examples validate against the generated schema and parse with the real Data API deserializer. Cover supported operators, extended JSON values, optional/null behavior, and malformed input without changing the API's accepted syntax.
This fixes an existing tool-schema problem and is not required by the package upgrade. Keep it under #2604 and coordinate with #2619.
Modern protocol and OAuth acceptance details
Validate generated schemas under JSON Schema 2020-12. Preserve fractional minimum/maximum/default in a focused schema fixture rather than forcing integer-only schema values. Do not loosen actual integer command constraints or invent update operators. This is existing schema quality work, distinct from the framework-wide schema audit in #2625.
Changelog traceability
- m10 Support the current schema model, lines 49–52 — Required audit.
- S1 Preserve fractional schema numbers, lines 103 — Required regression.
Normative detail: Streamable HTTP, authorization, caching.
Required base protocol/schema behavior remains owned by #2625 and verified by #2626. This follow-up owns only its stated enhancement or proven gap.
Activity
[-]Advertise Data API update operators in MCP schemas[/-][+]MCP: Advertise Data API update operators in tool schemas[/+][-]MCP: Advertise Data API update operators in tool schemas[/-][+]MCP: Describe update operators correctly in tool schemas[/+][-]MCP: Describe update operators correctly in tool schemas[/-][+]MCP: Show valid update syntax in tool schemas[/+]