Clarify and improve behavior when tool output fails schema validation

[dgenio]

Description

Summary

Tools can declare outputSchema, and the SDK validates the returned value against this schema after the tool executes. If validation fails:

• the tool’s side effects (DB writes, external calls, etc.) have already occurred,
• the client receives an error that may not clearly indicate the state of the underlying operation.

This issue proposes clarifying the behavior and exploring patterns to reduce confusion and risk.

Problems

• Side effects happen before validation: There is no built-in notion of a “transactional” tool whose effects are rolled back on validation failure.
• Ambiguous client behavior: Clients do not know whether they should retry after a validation error, since the tool may have partially succeeded.

Proposal

1. Clarify semantics in documentation

   • Document that:
     • tool execution occurs before validation,
     • validation failures indicate an inconsistency between implementation and declared schema.

2. Provide patterns for transactional tools

   • Offer a decorator or pattern (@mcp.tool(transactional=True)) for tools where users implement their own rollback logic, or
   • provide guidance on using explicit “job status” resources that separate side effects from the final structured response.

3. Distinct error indication

   • Use a specific error code / category for “output schema validation failed” so clients can treat it differently from generic tool failures.

Why this matters

• Correctness: Users understand what has happened when a validation error is returned.
• Resilience: Clear patterns for dealing with side effects reduce the likelihood of inconsistent states.
• Schema evolution: Changing schemas becomes less surprising when the semantics are well-documented.

Acceptance criteria

• [ ] Behavior on output schema validation failure is clearly documented.
• [ ] Validation errors use a distinct, documented error code/category.
• [ ] Recommended patterns are documented for tools with significant side effects.

References

No response