diff --git a/pkg/cli/mcp_schema.go b/pkg/cli/mcp_schema.go
index 3216b9487b8..8585a484708 100644
--- a/pkg/cli/mcp_schema.go
+++ b/pkg/cli/mcp_schema.go
@@ -5,27 +5,28 @@ import (
 )
 
 // GenerateOutputSchema generates a JSON schema from a Go struct type for MCP tool outputs.
-// This helper uses the github.com/google/jsonschema-go package to automatically generate
-// schemas from Go types, leveraging struct tags for descriptions and constraints.
+// The schema conforms to JSON Schema draft 2020-12 and draft-07.
 //
-// The schema is generated with default options which respect:
-// - json tags for field names
-// - jsonschema tags for descriptions and constraints
-// - omitempty to mark optional fields
+// Schema generation rules:
+//   - json tags define property names
+//   - jsonschema tags define descriptions
+//   - omitempty/omitzero mark optional fields
+//   - Pointer types include null in their type array
+//   - Slices allow null values (jsonschema-go v0.4.0+)
+//   - PropertyOrder maintains deterministic field ordering (v0.4.0+)
 //
-// Example usage:
+// MCP Requirements:
+//   - Tool output schemas must be objects (not arrays or primitives)
+//   - All properties should have descriptions for better LLM understanding
+//   - Required vs optional fields must be correctly specified
 //
-//	type MyOutput struct {
-//	    Name  string `json:"name" jsonschema:"description=Name of the item"`
-//	    Count int    `json:"count,omitempty" jsonschema:"description=Number of items"`
-//	}
+// Example:
 //
-//	schema, err := GenerateOutputSchema[MyOutput]()
-//	tool := &mcp.Tool{
-//	    Name:         "my-tool",
-//	    Description:  "My tool description",
-//	    OutputSchema: schema,
+//	type Output struct {
+//	    Name string `json:"name" jsonschema:"Name of the user"`
+//	    Age  int    `json:"age,omitempty" jsonschema:"Age in years"`
 //	}
+//	schema, err := GenerateOutputSchema[Output]()
 func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
 	return jsonschema.For[T](nil)
 }