Enhance MCP tool schema documentation with parameter examples

[Copilot]

The add_comment tool had a 6.67% failure rate because agents weren't providing the required item_number parameter. Schema descriptions lacked clarity on what these parameters represent and how to extract them from GitHub URLs.

Changes

Enhanced 16 MCP safe output tools with concrete parameter examples:

• add_comment: item_number now includes GitHub URL extraction example
• Number parameters across all tools: Added explicit format guidance showing numeric ID extraction from URLs

Example

Before:

"item_number": {
  "type": "number",
  "description": "The issue, pull request, or discussion number to comment on. Must be a valid existing item in the repository."
}

After:

"item_number": {
  "type": "number",
  "description": "The issue, pull request, or discussion number to comment on. This is the numeric ID from the GitHub URL (e.g., 123 in github.com/owner/repo/issues/123). Must be a valid existing item in the repository. Required."
}

Pattern Applied

All numeric ID parameters now follow:

"This is the numeric ID from the GitHub URL (e.g., <number> in github.com/owner/repo/<type>/<number>)"

Tools Enhanced

create_issue, update_discussion, close_discussion, close_issue, close_pull_request, add_comment, add_labels, add_reviewer, assign_milestone, assign_to_agent, assign_to_user, update_issue, update_pull_request, push_to_pull_request_branch, link_sub_issue, update_project

Files Modified

• actions/setup/js/safe_outputs_tools.json (source)
• pkg/workflow/js/safe_outputs_tools.json (embedded in binary)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Enhance MCP tool schema documentation with parameter examples</issue_title>
<issue_description>## 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

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

• Fixes [plan] Enhance MCP tool schema documentation with parameter examples #7951

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.