fix: refine highlighted tool parameter descriptions

[RossTarrant]

Summary

Clarifies agent-facing parameter descriptions across existing GitHub MCP tools and tightens a few schemas with concise enums/examples where they prevent incorrect usage.

Why

Schema linting in #2425 found missing or insufficient parameter descriptions across many tools, causing agents to guess formats for values like Markdown bodies, search queries, branch refs, and file paths. This improves schema guidance while keeping descriptions short to avoid unnecessary token usage.

Fixes #2425

Why some highlighted params were not updated

Some highlighted parameters were intentionally left unchanged after review. The goal was not to describe every string parameter exhaustively, but to add guidance where agents were likely to misuse a value.

Parameters were left as-is when the existing name and description already gave enough context, such as common GitHub identifiers (owner, repo, issue_number, pullNumber) or standard pagination/sorting fields. Others were unchanged where extra wording would mostly repeat the parameter name without reducing ambiguity, increasing schema token usage without improving tool use.

Search and filter parameters were only expanded when the accepted syntax or format was easy to misuse. For example, GitHub search query fields were clarified because agents need to know they accept GitHub search syntax, while simple filters with enums or obvious values did not need additional text.

In short, unchanged highlighted params were reviewed and judged either self-explanatory, already constrained by enum/type, or not worth the token cost of extra description.

What changed

• Added concise descriptions for ambiguous issue, pull request, repository, gist, Actions, code scanning, Copilot, discussion, project, and search parameters.
• Added schema constraints where appropriate, including search_code.sort and sub_issue_write.method enums.
• Clarified GitHub-specific formats such as user:branch for list_pull_requests.head, repository-relative file paths, and full Git refs for code scanning filters.
• Regenerated tool snapshots and generated docs.

MCP impact

• No tool or API changes

• Tool schema or behavior changed

  Existing tool schemas changed through parameter descriptions and enum metadata only; tool behavior is unchanged.

• New tool added

Prompts tested (tool changes only)

• Variety of different prompts covering affected tools.

Security / limits

• No security or limits impact
• Auth / permissions considered
• Data exposure, filtering, or token/size limits considered

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Not needed
• Updated (README / docs / examples)

[Copilot]

Pull request overview

This PR improves agent-facing JSON schema guidance across existing GitHub MCP tools by refining parameter descriptions and adding a couple of low-risk schema constraints (enums), then regenerating tool snapshots and generated docs to match.

Changes:

• Clarified ambiguous parameter descriptions (e.g., Markdown-supported bodies, branch/ref formats, repository-relative paths, GitHub search query syntax).
• Tightened a small number of schemas with explicit enums (notably search_code.sort and sub_issue_write.method) to prevent incorrect inputs.
• Regenerated pkg/github/__toolsnaps__/* snapshots and updated generated documentation (README + docs).

Show a summary per file

File	Description
README.md	Updates generated tool docs to reflect refined parameter descriptions.
pkg/github/actions.go	Clarifies Actions tool parameter guidance (e.g., branch name vs full ref).
pkg/github/code_scanning.go	Clarifies ref filter format with concrete examples.
pkg/github/copilot.go	Clarifies base_ref expectations for the Copilot assignment tool.
pkg/github/discussions.go	Clarifies discussion comment body supports Markdown and when it’s required.
pkg/github/gists.go	Clarifies gist file content is raw content.
pkg/github/issues.go	Clarifies issue/comment body Markdown support; constrains sub_issue_write.method via enum; adds item-level descriptions for arrays.
pkg/github/issues_granular.go	Clarifies issue body parameter semantics (Markdown supported).
pkg/github/projects.go	Adds item-level descriptions for project fields array elements.
pkg/github/pullrequests.go	Clarifies PR body Markdown support and branch formats; adds item-level description for reviewers.
pkg/github/pullrequests_granular.go	Adds item-level description for reviewers; clarifies review/comment bodies support Markdown.
pkg/github/repositories.go	Clarifies repository file path semantics and raw content expectations across repo file tools.
pkg/github/search.go	Clarifies search_code.sort usage and constrains it to indexed via enum.
pkg/github/toolsnaps/actions_list.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/actions_run_trigger.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/add_comment_to_pending_review.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/add_issue_comment.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/add_pull_request_review_comment.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/add_reply_to_pull_request_comment.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/assign_copilot_to_issue.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_branch.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_gist.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_issue.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_or_update_file.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_pull_request.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/create_pull_request_review.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/delete_file.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/discussion_comment_write.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/get_file_contents.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/issue_write.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/issue_write_ff_remote_mcp_issue_fields.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/list_code_scanning_alerts.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/list_issues_ff_remote_mcp_issue_fields.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/list_pull_requests.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/projects_get.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/projects_list.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/push_files.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/request_pull_request_reviewers.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/search_code.snap	Snapshot update reflecting sort enum constraint and updated description.
pkg/github/toolsnaps/search_issues.snap	Snapshot update reflecting updated query description.
pkg/github/toolsnaps/search_pull_requests.snap	Snapshot update reflecting updated query description.
pkg/github/toolsnaps/sub_issue_write.snap	Snapshot update reflecting method enum constraint.
pkg/github/toolsnaps/submit_pending_pull_request_review.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/update_gist.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/update_issue_body.snap	Snapshot update reflecting updated parameter descriptions.
pkg/github/toolsnaps/update_pull_request.snap	Snapshot update reflecting updated parameter descriptions (including item-level reviewers description).
docs/feature-flags.md	Regenerated docs reflecting updated tool parameter descriptions.
docs/insiders-features.md	Regenerated docs reflecting updated tool parameter descriptions.

Copilot's findings

• Files reviewed: 48/48 changed files
• Comments generated: 0