Add comprehensive documentation to GenerateOutputSchema (#7072)

* Initial plan

* Add comprehensive documentation to GenerateOutputSchema

- Added detailed schema generation rules
- Documented v0.4.0+ features (PropertyOrder, nullable slices)
- Added MCP requirements section
- Updated usage example to match convention
- All tests pass successfully

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: 3 people

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)
 }