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

[dgenio]

Hi maintainers 👋 — wanted to follow up on this issue.

PR #2227 was submitted by @lavish0000 to address the docs part of this (acceptance criterion 1), but it was closed because the issue hadn't been triaged yet.

Could someone confirm whether this issue is in scope and label it ready for work if so? I'm happy to move forward with a PR — starting small with just the documentation clarification — once there's maintainer buy-in on the direction.

Thank you!