Skip to content

fix: refine highlighted tool parameter descriptions #2588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RossTarrant wants to merge 2 commits into
base: main
Choose a base branch
from
+166 −135
Open

fix: refine highlighted tool parameter descriptions #2588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15c2a5d
Clarify tool parameter schemas
RossTarrant Jun 1, 2026
39bc63d
Add missing toolsnap
RossTarrant Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -621,7 +621,7 @@ The following sets of tools are available:
- `inputs`: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
- `method`: The method to execute (string, required)
- `owner`: Repository owner (string, required)
- `ref`: The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method. (string, optional)
- `ref`: Branch or tag name to run the workflow on. Required for 'run_workflow' method. (string, optional)
- `repo`: Repository name (string, required)
- `run_id`: The ID of the workflow run. Required for all methods except 'run_workflow'. (number, optional)
- `workflow_id`: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml). Required for 'run_workflow' method. (string, optional)
Expand Down Expand Up @@ -655,7 +655,7 @@ The following sets of tools are available:
- `owner`: The owner of the repository. (string, required)
- `page`: Page number for pagination (min 1) (number, optional)
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
- `ref`: The Git reference for the results you want to list. (string, optional)
- `ref`: Git ref to filter by, e.g. refs/heads/main or refs/pull/123/merge. (string, optional)
- `repo`: The name of the repository. (string, required)
- `severity`: Filter code scanning alerts by severity (string, optional)
- `state`: Filter code scanning alerts by state. Defaults to open (string, optional)
Expand Down Expand Up @@ -689,7 +689,7 @@ The following sets of tools are available:

- **assign_copilot_to_issue** - Assign Copilot to issue
- **Required OAuth Scopes**: `repo`
- `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
- `base_ref`: Branch or ref the agent starts from; defaults to the repository default branch (string, optional)
- `custom_instructions`: Optional custom instructions to guide the agent beyond the issue body. Use this to provide additional context, constraints, or guidance that is not captured in the issue description (string, optional)
- `issue_number`: Issue number (number, required)
- `owner`: Repository owner (string, required)
Expand Down Expand Up @@ -732,7 +732,7 @@ The following sets of tools are available:

- **discussion_comment_write** - Manage discussion comments
- **Required OAuth Scopes**: `repo`
- `body`: Comment content (required for 'add', 'reply', and 'update' methods) (string, optional)
- `body`: Comment content. Markdown supported. Required for 'add', 'reply', and 'update' methods. (string, optional)
- `commentNodeID`: The Node ID of the discussion comment (required for 'reply', 'update', 'delete', 'mark_answer', and 'unmark_answer' methods). For 'reply', this is the top-level comment to reply to; GitHub Discussions only support one level of nesting. (string, optional)
- `discussionNumber`: Discussion number (required for 'add' and 'reply' methods) (number, optional)
- `method`: Write operation to perform on a discussion comment.
Expand Down Expand Up @@ -785,7 +785,7 @@ The following sets of tools are available:

- **create_gist** - Create Gist
- **Required OAuth Scopes**: `gist`
- `content`: Content for simple single-file gist creation (string, required)
- `content`: Raw content for the single gist file (string, required)
- `description`: Description of the gist (string, optional)
- `filename`: Filename for simple single-file gist creation (string, required)
- `public`: Whether the gist is public (boolean, optional)
Expand All @@ -801,7 +801,7 @@ The following sets of tools are available:

- **update_gist** - Update Gist
- **Required OAuth Scopes**: `gist`
- `content`: Content for the file (string, required)
- `content`: Raw content for the gist file (string, required)
- `description`: Updated description of the gist (string, optional)
- `filename`: Filename to update or create (string, required)
- `gist_id`: ID of the gist to update (string, required)
Expand All @@ -828,7 +828,7 @@ The following sets of tools are available:

- **add_issue_comment** - Add comment to issue
- **Required OAuth Scopes**: `repo`
- `body`: Comment content (string, required)
- `body`: Comment body; Markdown supported. (string, required)
- `issue_number`: Issue number to comment on (number, required)
- `owner`: Repository owner (string, required)
- `repo`: Repository name (string, required)
Expand Down Expand Up @@ -857,7 +857,7 @@ The following sets of tools are available:
- **issue_write** - Create or update issue
- **Required OAuth Scopes**: `repo`
- `assignees`: Usernames to assign to this issue (string[], optional)
- `body`: Issue body content (string, optional)
- `body`: Issue body; Markdown supported. (string, optional)
- `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
- `issue_number`: Issue number to update (number, optional)
- `labels`: Labels to apply to this issue (string[], optional)
Expand Down Expand Up @@ -897,7 +897,7 @@ The following sets of tools are available:
- `owner`: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
- `page`: Page number for pagination (min 1) (number, optional)
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
- `query`: Search query using GitHub issues search syntax (string, required)
- `query`: Search query using GitHub issues search syntax. The tool adds is:issue and, when owner/repo are provided, repo:owner/repo; examples: "crash label:bug", "author:octocat updated:>=2024-01-01". (string, required)
- `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
- `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)

Expand Down Expand Up @@ -1062,7 +1062,7 @@ The following sets of tools are available:

- **add_comment_to_pending_review** - Add review comment to the requester's latest pending pull request review
- **Required OAuth Scopes**: `repo`
- `body`: The text of the review comment (string, required)
- `body`: Review comment body; Markdown supported (string, required)
- `line`: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional)
- `owner`: Repository owner (string, required)
- `path`: The relative path to the file that necessitates a comment (string, required)
Expand All @@ -1075,28 +1075,28 @@ The following sets of tools are available:

- **add_reply_to_pull_request_comment** - Add reply to pull request comment
- **Required OAuth Scopes**: `repo`
- `body`: The text of the reply (string, required)
- `body`: Reply body; Markdown supported (string, required)
- `commentId`: The ID of the comment to reply to (number, required)
- `owner`: Repository owner (string, required)
- `pullNumber`: Pull request number (number, required)
- `repo`: Repository name (string, required)

- **create_pull_request** - Open new pull request
- **Required OAuth Scopes**: `repo`
- `base`: Branch to merge into (string, required)
- `body`: PR description (string, optional)
- `base`: Base branch name to merge into, e.g. main (string, required)
- `body`: PR description; Markdown supported (string, optional)
- `draft`: Create as draft PR (boolean, optional)
- `head`: Branch containing changes (string, required)
- `head`: Branch containing changes, or owner:branch for a fork (string, required)
- `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
- `owner`: Repository owner (string, required)
- `repo`: Repository name (string, required)
- `title`: PR title (string, required)

- **list_pull_requests** - List pull requests
- **Required OAuth Scopes**: `repo`
- `base`: Filter by base branch (string, optional)
- `base`: Filter by base branch name. (string, optional)
- `direction`: Sort direction (string, optional)
- `head`: Filter by head user/org and branch (string, optional)
- `head`: Filter by head user/org and branch, in user:branch format. (string, optional)
- `owner`: Repository owner (string, required)
- `page`: Page number for pagination (min 1) (number, optional)
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
Expand Down Expand Up @@ -1150,13 +1150,13 @@ The following sets of tools are available:
- `owner`: Optional repository owner. If provided with repo, only pull requests for this repository are listed. (string, optional)
- `page`: Page number for pagination (min 1) (number, optional)
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
- `query`: Search query using GitHub pull request search syntax (string, required)
- `query`: Search query using GitHub pull request search syntax. Qualifiers such as is:pr and repo:owner/repo are applied automatically when appropriate; examples: "review-requested:@me", "author:octocat updated:>=2024-01-01". (string, required)
- `repo`: Optional repository name. If provided with owner, only pull requests for this repository are listed. (string, optional)
- `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)

- **update_pull_request** - Edit pull request
- **Required OAuth Scopes**: `repo`
- `base`: New base branch name (string, optional)
- `base`: New base branch name, e.g. main. (string, optional)
- `body`: New description (string, optional)
- `draft`: Mark pull request as draft (true) or ready for review (false) (boolean, optional)
- `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
Expand All @@ -1182,18 +1182,18 @@ The following sets of tools are available:

- **create_branch** - Create branch
- **Required OAuth Scopes**: `repo`
- `branch`: Name for new branch (string, required)
- `from_branch`: Source branch (defaults to repo default) (string, optional)
- `branch`: New branch name, without refs/heads/ (string, required)
- `from_branch`: Source branch name; defaults to the repository default branch (string, optional)
- `owner`: Repository owner (string, required)
- `repo`: Repository name (string, required)

- **create_or_update_file** - Create or update file
- **Required OAuth Scopes**: `repo`
- `branch`: Branch to create/update the file in (string, required)
- `content`: Content of the file (string, required)
- `message`: Commit message (string, required)
- `branch`: Branch name to create/update the file in (string, required)
- `content`: Raw file content (string, required)
- `message`: Commit message for this change (string, required)
- `owner`: Repository owner (username or organization) (string, required)
- `path`: Path where to create/update the file (string, required)
- `path`: Repository-relative file path to create or update (string, required)
- `repo`: Repository name (string, required)
- `sha`: The blob SHA of the file being replaced. Required if the file already exists. (string, optional)

Expand All @@ -1207,10 +1207,10 @@ The following sets of tools are available:

- **delete_file** - Delete file
- **Required OAuth Scopes**: `repo`
- `branch`: Branch to delete the file from (string, required)
- `message`: Commit message (string, required)
- `branch`: Branch name to delete the file from (string, required)
- `message`: Commit message for the delete commit (string, required)
- `owner`: Repository owner (username or organization) (string, required)
- `path`: Path to the file to delete (string, required)
- `path`: Repository-relative path to the file to delete (string, required)
- `repo`: Repository name (string, required)

- **fork_repository** - Fork repository
Expand All @@ -1231,7 +1231,7 @@ The following sets of tools are available:
- **get_file_contents** - Get file or directory contents
- **Required OAuth Scopes**: `repo`
- `owner`: Repository owner (username or organization) (string, required)
- `path`: Path to file/directory (string, optional)
- `path`: Repository-relative file or directory path (string, optional)
- `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
- `repo`: Repository name (string, required)
- `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
Expand Down Expand Up @@ -1296,7 +1296,7 @@ The following sets of tools are available:

- **push_files** - Push files to repository
- **Required OAuth Scopes**: `repo`
- `branch`: Branch to push to (string, required)
- `branch`: Branch name to push the commit to (string, required)
- `files`: Array of file objects to push, each object with path (string) and content (string) (object[], required)
- `message`: Commit message (string, required)
- `owner`: Repository owner (string, required)
Expand All @@ -1308,7 +1308,7 @@ The following sets of tools are available:
- `page`: Page number for pagination (min 1) (number, optional)
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
- `query`: Search query (GitHub code search REST). Implicit AND between terms; supports `OR`, `NOT`, and `"quoted phrase"` for exact match. Qualifiers: `repo:owner/repo`, `org:`, `user:`, `language:`, `path:dir` (prefix match), `filename:exact.ext`, `extension:`, `in:file`, `in:path`, `size:`, `is:archived`, `is:fork`. Max 256 chars. Examples: `WithContext language:go org:github`; `"package main" repo:o/r`; `func extension:go path:cmd repo:o/r`; `NOT TODO language:go repo:o/r`. (string, required)
- `sort`: Sort field ('indexed' only) (string, optional)
- `sort`: Sort field. Use 'indexed' to sort by recently indexed files. (string, optional)

- **search_commits** - Search commits
- **Required OAuth Scopes**: `repo`
Expand Down
22 changes: 11 additions & 11 deletions docs/feature-flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ runtime behavior (such as output formatting) won't appear here.
- **create_pull_request** - Open new pull request
- **Required OAuth Scopes**: `repo`
- **MCP App UI**: `ui://github-mcp-server/pr-write`
- `base`: Branch to merge into (string, required)
- `body`: PR description (string, optional)
- `base`: Base branch name to merge into, e.g. main (string, required)
- `body`: PR description; Markdown supported (string, optional)
- `draft`: Create as draft PR (boolean, optional)
- `head`: Branch containing changes (string, required)
- `head`: Branch containing changes, or owner:branch for a fork (string, required)
- `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
- `owner`: Repository owner (string, required)
- `repo`: Repository name (string, required)
Expand All @@ -54,7 +54,7 @@ runtime behavior (such as output formatting) won't appear here.
- **Required OAuth Scopes**: `repo`
- **MCP App UI**: `ui://github-mcp-server/issue-write`
- `assignees`: Usernames to assign to this issue (string[], optional)
- `body`: Issue body content (string, optional)
- `body`: Issue body; Markdown supported. (string, optional)
- `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
- `issue_number`: Issue number to update (number, optional)
- `labels`: Labels to apply to this issue (string[], optional)
Expand All @@ -76,7 +76,7 @@ runtime behavior (such as output formatting) won't appear here.
- **issue_write** - Create or update issue
- **Required OAuth Scopes**: `repo`
- `assignees`: Usernames to assign to this issue (string[], optional)
- `body`: Issue body content (string, optional)
- `body`: Issue body; Markdown supported. (string, optional)
- `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
- `issue_fields`: Issue field values to set or clear. Each item requires 'field_name' and exactly one of 'value', 'field_option_name', or 'delete: true'. (object[], optional)
- `issue_number`: Issue number to update (number, optional)
Expand Down Expand Up @@ -125,7 +125,7 @@ runtime behavior (such as output formatting) won't appear here.

- **create_issue** - Create Issue
- **Required OAuth Scopes**: `repo`
- `body`: Issue body content (optional) (string, optional)
- `body`: Issue body (optional); Markdown supported. (string, optional)
- `owner`: Repository owner (username or organization) (string, required)
- `repo`: Repository name (string, required)
- `title`: Issue title (string, required)
Expand Down Expand Up @@ -162,7 +162,7 @@ runtime behavior (such as output formatting) won't appear here.

- **update_issue_body** - Update Issue Body
- **Required OAuth Scopes**: `repo`
- `body`: The new body content for the issue (string, required)
- `body`: Issue body; Markdown supported. (string, required)
- `issue_number`: The issue number to update (number, required)
- `owner`: Repository owner (username or organization) (string, required)
- `repo`: Repository name (string, required)
Expand Down Expand Up @@ -209,7 +209,7 @@ runtime behavior (such as output formatting) won't appear here.

- **add_pull_request_review_comment** - Add Pull Request Review Comment
- **Required OAuth Scopes**: `repo`
- `body`: The comment body (string, required)
- `body`: Review comment body; Markdown supported (string, required)
- `line`: The line number in the diff to comment on (optional) (number, optional)
- `owner`: Repository owner (username or organization) (string, required)
- `path`: The relative path of the file to comment on (string, required)
Expand All @@ -222,7 +222,7 @@ runtime behavior (such as output formatting) won't appear here.

- **create_pull_request_review** - Create Pull Request Review
- **Required OAuth Scopes**: `repo`
- `body`: The review body text (optional) (string, optional)
- `body`: Review body (optional); Markdown supported (string, optional)
- `commitID`: The SHA of the commit to review (optional, defaults to latest) (string, optional)
- `event`: The review action to perform. If omitted, creates a pending review. (string, optional)
- `owner`: Repository owner (username or organization) (string, required)
Expand All @@ -240,15 +240,15 @@ runtime behavior (such as output formatting) won't appear here.
- `owner`: Repository owner (username or organization) (string, required)
- `pullNumber`: The pull request number (number, required)
- `repo`: Repository name (string, required)
- `reviewers`: GitHub usernames to request reviews from (string[], required)
- `reviewers`: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], required)

- **resolve_review_thread** - Resolve Review Thread
- **Required OAuth Scopes**: `repo`
- `threadID`: The node ID of the review thread to resolve (e.g., PRRT_kwDOxxx) (string, required)

- **submit_pending_pull_request_review** - Submit Pending Pull Request Review
- **Required OAuth Scopes**: `repo`
- `body`: The review body text (optional) (string, optional)
- `body`: Review body; Markdown supported (string, optional)
- `event`: The review action to perform (string, required)
- `owner`: Repository owner (username or organization) (string, required)
- `pullNumber`: The pull request number (number, required)
Expand Down
Loading
Loading