[plan] Enhance MCP tool schema documentation with parameter examples

[github-actions]

Objective

Update MCP tool schema definitions to include clear, detailed documentation for all required parameters, with concrete examples that agents can reference.

Context

The add_comment tool has a 6.67% failure rate because agents are not providing the required item_number parameter. The current schema doesn't provide enough guidance on what this parameter is or how to use it.

Approach

1. Locate the MCP tool schema definition file (likely in actions/setup/js/ or similar)
2. Update the add_comment tool schema to include:
   • Detailed description of item_number parameter
   • Explanation that it's the numeric ID from GitHub URLs
   • Example usage showing correct format
3. Apply same enhancement pattern to other MCP safe output tools
4. Ensure schema changes are embedded in the binary via the build process

Files to Modify

Search for and update:

• MCP tool schema JSON files (likely actions/setup/js/*.cjs or pkg/workflow/js/*.cjs)
• Look for schema definitions containing safeoutputs-add_comment

Example Enhancement

Current (insufficient):

{
  "item_number": {
    "type": "number",
    "required": true
  }
}

Enhanced (clear):

{
  "item_number": {
    "type": "number",
    "required": true,
    "description": "The issue, PR, or discussion number to add a comment to. This is the numeric ID from the GitHub URL (e.g., 123 in github.com/owner/repo/issues/123). Required."
  }
}

Acceptance Criteria

• All required parameters in MCP tool schemas have detailed descriptions
• Descriptions include examples of expected values
• Schema changes are validated with make build
• Changes are tested by compiling a test workflow that uses the tools

Testing

After making changes:

make build           # Rebuild binary with updated schemas
make recompile       # Recompile test workflows
./gh-aw --help       # Verify binary works

Related to #7950

AI generated by Plan Command for discussion #7934