Tool descriptions: what eleven tools leave a caller guessing, and four titles #3473

Thanks for the remote MCP server. We use it through Claude, where each tool's description is what the assistant, and the person approving a call, read before using it. Most descriptions do that well. These eleven leave something to guess:

1. actions_get: whether the artifact and log methods return the file or a link to it.
2. actions_run_trigger: that deleting run logs is permanent, and what the call returns.
3. add_comment_to_pending_review: how to start the pending review it needs. It says to ask the user, not that pull_request_review_write creates one; and what the call returns.
4. issue_write: whether labels and assignees given on an update are added to the existing ones or replace them (the REST API replaces them), and whether it handles pull requests, as its title says, or only issues, as its description says.
5. merge_pull_request: which merge method is used when none is given, what expectedHeadSha guards, and that a merge is undone only by a revert.
6. push_files: whether files already at those paths are replaced, since it asks for none of the version check create_or_update_file requires, and whether the branch must already exist.
7. request_copilot_review: whether it needs a Copilot plan or uses paid Copilot requests, and that the review arrives later on the pull request, not in the reply.
8. run_secret_scanning (minor): why a repository must be named when the content is passed in.
9. search_pull_requests: it says it takes GitHub's search syntax, but gives no example or qualifier, and nothing warns that search_issues beside it matches natural language instead, so the same query behaves differently in the two.
10. sub_issue_write: it says "add", but it also removes and reorders sub-issues; and where to find a sub-issue's ID, which is not its number.
11. update_pull_request_branch (minor): whether the base branch's changes arrive by a merge or a rebase, and what expectedHeadSha guards.

Titles: the four Actions tools put "GitHub" in their titles, which a client already shows as the server's name; pull_request_review_write's title, "Write operations (create, submit, delete) on pull request reviews", is not a verb phrase; and "Run Secret Scanning" is in title case where the others use sentence case.

Hints: of the 19 tools that change things, only delete_file and actions_run_trigger set destructiveHint. On the other 17 it is unset, which the MCP specification reads as possibly destructive, so a client warns on every one. Setting it to false where a tool only adds or updates would let clients warn only where it matters.