Add comprehensive documentation to GenerateOutputSchema

[Copilot]

The GenerateOutputSchema function lacked detail on schema generation rules and MCP requirements, making it difficult for users to understand how to properly define tool output schemas.

Changes

• Schema generation rules: Documents how json tags define property names, jsonschema tags provide descriptions, omitempty/omitzero mark optional fields, pointer types include null, and v0.4.0+ features (nullable slices, PropertyOrder)
• MCP requirements: Clarifies that tool outputs must be objects with descriptions on all properties and correct required/optional field specification
• Example: Simplified usage example with correct tag format

// GenerateOutputSchema generates a JSON schema from a Go struct type for MCP tool outputs.
// The schema conforms to JSON Schema draft 2020-12 and draft-07.
//
// 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+)
//
// 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
//
// Example:
//
//	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]()

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add comprehensive documentation to GenerateOutputSchema</issue_title>
<issue_description>## Objective

Add detailed documentation to GenerateOutputSchema explaining schema generation rules and MCP requirements.

Context

The function currently has minimal documentation. Users need to understand how schema generation works and what MCP tool outputs require.

Implementation

Add comprehensive godoc comment to GenerateOutputSchema function:

// GenerateOutputSchema generates a JSON schema from a Go struct type for MCP tool outputs.
// The schema conforms to JSON Schema draft 2020-12 and draft-07.
//
// 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+)
//
// 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
//
// Example:
//
//     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)
}

Files to Modify

• pkg/cli/mcp_schema.go - Add documentation to GenerateOutputSchema

Acceptance Criteria

• Function has comprehensive godoc comment
• Documentation explains schema generation rules
• Documentation explains MCP requirements
• Documentation includes usage example
• References v0.4.0 features (PropertyOrder, nullable slices)
  Related to [plan] Upgrade and enhance google/jsonschema-go integration #6830

AI generated by Plan Command for discussion #6818

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add comprehensive documentation to GenerateOutputSchema #6834

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.