From 61a417f2e587b85150237e5749d1a0af57006b6c Mon Sep 17 00:00:00 2001
From: Lovish Arora <46993225+lavish0000@users.noreply.github.com>
Date: Fri, 6 Mar 2026 05:51:47 +0100
Subject: [PATCH 1/2] docs: clarify structured output validation timing

---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index 487d48bee..29e3f9175 100644
--- a/README.md
+++ b/README.md
@@ -394,6 +394,23 @@ Structured results are automatically validated against the output schema
 generated from the annotation. This ensures the tool returns well-typed,
 validated data that clients can easily process.
 
+##### Validation Timing and Side Effects
+
+Output-schema validation happens after the tool function returns. If a tool
+performs side effects before returning, those side effects are not rolled back
+when structured-output validation fails.
+
+A validation failure means the tool implementation and its declared schema are
+out of sync. Treat it as a server bug, not as a signal that the operation was
+safe to retry.
+
+For tools with important side effects, prefer patterns that make the state
+explicit, for example:
+
+- return an operation or job identifier and expose completion state separately
+- separate "start work" from "fetch result" into different tools or resources
+- keep the structured result shape stable and version schema changes carefully
+
 **Note:** For backward compatibility, unstructured results are also
 returned. Unstructured results are provided for backward compatibility
 with previous versions of the MCP specification, and are quirks-compatible

From a97704bcd884c2e4c9aaca56f183b710dcf05f9d Mon Sep 17 00:00:00 2001
From: Lovish Arora <46993225+lavish0000@users.noreply.github.com>
Date: Fri, 6 Mar 2026 06:36:17 +0100
Subject: [PATCH 2/2] docs: move validation guidance to README.v2

---
 README.md    | 17 -----------------
 README.v2.md | 17 +++++++++++++++++
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 29e3f9175..487d48bee 100644
--- a/README.md
+++ b/README.md
@@ -394,23 +394,6 @@ Structured results are automatically validated against the output schema
 generated from the annotation. This ensures the tool returns well-typed,
 validated data that clients can easily process.
 
-##### Validation Timing and Side Effects
-
-Output-schema validation happens after the tool function returns. If a tool
-performs side effects before returning, those side effects are not rolled back
-when structured-output validation fails.
-
-A validation failure means the tool implementation and its declared schema are
-out of sync. Treat it as a server bug, not as a signal that the operation was
-safe to retry.
-
-For tools with important side effects, prefer patterns that make the state
-explicit, for example:
-
-- return an operation or job identifier and expose completion state separately
-- separate "start work" from "fetch result" into different tools or resources
-- keep the structured result shape stable and version schema changes carefully
-
 **Note:** For backward compatibility, unstructured results are also
 returned. Unstructured results are provided for backward compatibility
 with previous versions of the MCP specification, and are quirks-compatible
diff --git a/README.v2.md b/README.v2.md
index bd6927bf9..8360b1536 100644
--- a/README.v2.md
+++ b/README.v2.md
@@ -393,6 +393,23 @@ Structured results are automatically validated against the output schema
 generated from the annotation. This ensures the tool returns well-typed,
 validated data that clients can easily process.
 
+##### Validation Timing and Side Effects
+
+Output-schema validation happens after the tool function returns. If a tool
+performs side effects before returning, those side effects are not rolled back
+when structured-output validation fails.
+
+A validation failure means the tool implementation and its declared schema are
+out of sync. Treat it as a server bug, not as a signal that the operation was
+safe to retry.
+
+For tools with important side effects, prefer patterns that make the state
+explicit, for example:
+
+- return an operation or job identifier and expose completion state separately
+- separate "start work" from "fetch result" into different tools or resources
+- keep the structured result shape stable and version schema changes carefully
+
 **Note:** For backward compatibility, unstructured results are also
 returned. Unstructured results are provided for backward compatibility
 with previous versions of the MCP specification, and are quirks-compatible