Preserves Git history for repository operations, with support for branch creation, commit management, and maintaining proper version control without force pushing.
Provides comprehensive access to GitHub's API, enabling file operations (creating, updating, retrieving), repository management (creating, forking, branching), search functionality across code/issues/users, and issue/PR workflows (creating, commenting, reviewing, merging).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GitHub MCP Server create a new issue in my-app repo: 'Fix login bug' with label 'bug'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for the GitHub API, enabling file operations, repository management, search functionality, and more.
Automatic Branch Creation: When creating/updating files or pushing changes, branches are automatically created if they don't exist
Comprehensive Error Handling: Clear error messages for common issues
Git History Preservation: Operations maintain proper Git history without force pushing
Batch Operations: Support for both single-file and multi-file operations
Advanced Search: Support for searching code, issues/PRs, and users
Project Management: Complete toolset for GitHub Projects (classic) management, including creating projects, managing columns, and working with cards
create_or_update_file
Create or update a single file in a repository
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
path (string): Path where to create/update the file
content (string): Content of the file
message (string): Commit message
branch (string): Branch to create/update the file in
sha (optional string): SHA of file being replaced (for updates)
Returns: File content and commit details
push_files
Push multiple files in a single commit
Inputs:
owner (string): Repository owner
repo (string): Repository name
branch (string): Branch to push to
files (array): Files to push, each with path and content
message (string): Commit message
Returns: Updated branch reference
search_repositories
Search for GitHub repositories
Inputs:
query (string): Search query
page (optional number): Page number for pagination
perPage (optional number): Results per page (max 100)
Returns: Repository search results
create_repository
Create a new GitHub repository
Inputs:
name (string): Repository name
description (optional string): Repository description
private (optional boolean): Whether repo should be private
autoInit (optional boolean): Initialize with README
Returns: Created repository details
get_file_contents
Get contents of a file or directory
Inputs:
owner (string): Repository owner
repo (string): Repository name
path (string): Path to file/directory
branch (optional string): Branch to get contents from
Returns: File/directory contents
create_issue
Create a new issue
Inputs:
owner (string): Repository owner
repo (string): Repository name
title (string): Issue title
body (optional string): Issue description
assignees (optional string[]): Usernames to assign
labels (optional string[]): Labels to add
milestone (optional number): Milestone number
Returns: Created issue details
create_pull_request
Create a new pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
title (string): PR title
body (optional string): PR description
head (string): Branch containing changes
base (string): Branch to merge into
draft (optional boolean): Create as draft PR
maintainer_can_modify (optional boolean): Allow maintainer edits
Returns: Created pull request details
fork_repository
Fork a repository
Inputs:
owner (string): Repository owner
repo (string): Repository name
organization (optional string): Organization to fork to
Returns: Forked repository details
create_branch
Create a new branch
Inputs:
owner (string): Repository owner
repo (string): Repository name
branch (string): Name for new branch
from_branch (optional string): Source branch (defaults to repo default)
Returns: Created branch reference
list_issues
List and filter repository issues
Inputs:
owner (string): Repository owner
repo (string): Repository name
state (optional string): Filter by state ('open', 'closed', 'all')
labels (optional string[]): Filter by labels
sort (optional string): Sort by ('created', 'updated', 'comments')
direction (optional string): Sort direction ('asc', 'desc')
since (optional string): Filter by date (ISO 8601 timestamp)
page (optional number): Page number
per_page (optional number): Results per page
Returns: Array of issue details
update_issue
Update an existing issue
Inputs:
owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number to update
title (optional string): New title
body (optional string): New description
state (optional string): New state ('open' or 'closed')
labels (optional string[]): New labels
assignees (optional string[]): New assignees
milestone (optional number): New milestone number
Returns: Updated issue details
add_issue_comment
Add a comment to an issue
Inputs:
owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number to comment on
body (string): Comment text
Returns: Created comment details
search_code
Search for code across GitHub repositories
Inputs:
q (string): Search query using GitHub code search syntax
sort (optional string): Sort field ('indexed' only)
order (optional string): Sort order ('asc' or 'desc')
per_page (optional number): Results per page (max 100)
page (optional number): Page number
Returns: Code search results with repository context
search_issues
Search for issues and pull requests
Inputs:
q (string): Search query using GitHub issues search syntax
sort (optional string): Sort field (comments, reactions, created, etc.)
order (optional string): Sort order ('asc' or 'desc')
per_page (optional number): Results per page (max 100)
page (optional number): Page number
Returns: Issue and pull request search results
search_users
Search for GitHub users
Inputs:
q (string): Search query using GitHub users search syntax
sort (optional string): Sort field (followers, repositories, joined)
order (optional string): Sort order ('asc' or 'desc')
per_page (optional number): Results per page (max 100)
page (optional number): Page number
Returns: User search results
list_commits
Gets commits of a branch in a repository
Inputs:
owner (string): Repository owner
repo (string): Repository name
page (optional string): page number
per_page (optional string): number of record per page
sha (optional string): branch name
Returns: List of commits
get_issue
Gets the contents of an issue within a repository
Inputs:
owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number to retrieve
Returns: Github Issue object & details
delete_issue
Deletes an issue from a GitHub repository using GraphQL API
Inputs:
owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number to delete
Returns: Deletion confirmation with repository information
get_pull_request
Get details of a specific pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
Returns: Pull request details including diff and review status
list_pull_requests
List and filter repository pull requests
Inputs:
owner (string): Repository owner
repo (string): Repository name
state (optional string): Filter by state ('open', 'closed', 'all')
head (optional string): Filter by head user/org and branch
base (optional string): Filter by base branch
sort (optional string): Sort by ('created', 'updated', 'popularity', 'long-running')
direction (optional string): Sort direction ('asc', 'desc')
per_page (optional number): Results per page (max 100)
page (optional number): Page number
Returns: Array of pull request details
create_pull_request_review
Create a review on a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
body (string): Review comment text
event (string): Review action ('APPROVE', 'REQUEST_CHANGES', 'COMMENT')
commit_id (optional string): SHA of commit to review
comments (optional array): Line-specific comments, each with:
path (string): File path
position (number): Line position in diff
body (string): Comment text
Returns: Created review details
merge_pull_request
Merge a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
commit_title (optional string): Title for merge commit
commit_message (optional string): Extra detail for merge commit
merge_method (optional string): Merge method ('merge', 'squash', 'rebase')
Returns: Merge result details
get_pull_request_files
Get the list of files changed in a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
Returns: Array of changed files with patch and status details
get_pull_request_status
Get the combined status of all status checks for a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
Returns: Combined status check results and individual check details
update_pull_request_branch
Update a pull request branch with the latest changes from the base branch (equivalent to GitHub's "Update branch" button)
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
expected_head_sha (optional string): The expected SHA of the pull request's HEAD ref
Returns: Success message when branch is updated
get_pull_request_comments
Get the review comments on a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
Returns: Array of pull request review comments with details like the comment text, author, and location in the diff
get_pull_request_reviews
Get the reviews on a pull request
Inputs:
owner (string): Repository owner
repo (string): Repository name
pull_number (number): Pull request number
Returns: Array of pull request reviews with details like the review state (APPROVED, CHANGES_REQUESTED, etc.), reviewer, and review body
create_project
Create a new project in a GitHub repository
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
name (string): Name of the project
body (optional string): Description of the project
Returns: Created project details
get_project
Get details about a specific project
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
project_number (number): The project number
Returns: Project details
update_project
Update an existing project's details
Inputs:
project_id (number): The unique identifier of the project
name (optional string): New name of the project
body (optional string): New description of the project
state (optional string): State of the project ('open' or 'closed')
Returns: Updated project details
list_projects
List all projects in a GitHub repository
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
state (optional string): Filter projects by state ('open', 'closed', 'all')
page (optional number): Page number for pagination (starts at 1)
per_page (optional number): Number of results per page (max 100)
Returns: Array of project details
create_project_column
Create a new column in a project
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
project_number (number): The project number
name (string): Name of the column
Returns: Created column details
list_project_columns
List all columns in a project
Inputs:
project_id (number): The unique identifier of the project
page (optional number): Page number for pagination (starts at 1)
per_page (optional number): Number of results per page (max 100)
Returns: Array of project column details
update_project_column
Update an existing project column
Inputs:
column_id (number): The unique identifier of the column
name (string): New name of the column
Returns: Updated column details
delete_project_column
Delete a project column
Inputs:
column_id (number): The unique identifier of the column
Returns: Success message
add_card_to_column
Add a new card to a project column
Inputs:
owner (string): Repository owner (username or organization)
repo (string): Repository name
column_id (string): The ID of the column to add card to
content_type (string): Type of content for the card ('Issue', 'PullRequest', 'Note')
content_id (optional number): ID of the issue or pull request (required if content_type is Issue or PullRequest)
note (optional string): The note content for the card (required if content_type is Note)
Returns: Created card details
list_column_cards
List all cards in a project column
Inputs:
column_id (number): The unique identifier of the column
archived_state (optional string): Filter by card archived state ('all', 'archived', 'not_archived')
page (optional number): Page number for pagination (starts at 1)
per_page (optional number): Number of results per page (max 100)
Returns: Array of card details
move_card
Move a card to a different position or column
Inputs:
card_id (number): The unique identifier of the card
position (string): The position of the card ('top', 'bottom', or 'after:')
column_id (optional number): The column ID to move the card to
Returns: Success message
delete_card
Delete a card from a project
Inputs:
card_id (number): The unique identifier of the card
Returns: Success message
list_organization_projects
List all projects in a GitHub organization (at organization level, not repository level)
Inputs:
org (string): Organization name
state (optional string): Filter projects by state ('open', 'closed', 'all')
page (optional number): Page number for pagination
per_page (optional number): Number of results per page (max 100)
Returns: Array of organization project details
Related MCP server: GitHub Enterprise MCP Server
list_organization_projects_v2
List projects V2 in a GitHub organization using GraphQL API
Inputs:
org (string): Organization name
first (optional number): Number of projects to fetch (max 100)
after (optional string): Cursor for pagination
orderBy (optional object): How to order the projects
Returns: Array of projects with pagination info
get_project_v2
Get details of a GitHub project V2 using GraphQL API
Inputs:
id (string): The node ID of the project
Returns: Detailed project information including fields and views
create_project_v2
Create a new GitHub project V2 using GraphQL API
Inputs:
ownerId (string): The node ID of the organization or user
title (string): Title of the project
description (optional string): Description of the project
Returns: Created project details
update_project_v2
Update a GitHub project V2 using GraphQL API
Inputs:
projectId (string): The node ID of the project
title (optional string): New title for the project
description (optional string): New description for the project
closed (optional boolean): Whether to close the project
Returns: Updated project details
add_item_to_project_v2
Add an issue or pull request to a GitHub project V2 using GraphQL API
Inputs:
projectId (string): The node ID of the project
contentId (string): The node ID of the issue or pull request to add
Returns: Added item details
list_project_v2_items
List items in a GitHub project V2 using GraphQL API
Inputs:
projectId (string): The node ID of the project
first (optional number): Number of items to fetch (max 100)
after (optional string): Cursor for pagination
filterBy (optional object): Filters for the items
Returns: Array of project items with their field values
update_project_v2_item_field
Update a field value for an item in a GitHub project V2 using GraphQL API
Inputs:
projectId (string): The node ID of the project
itemId (string): The node ID of the item
fieldId (string): The node ID of the field
value (any): The new value for the field
Returns: Updated item details
Deprecation Warning: GitHub has announced that Projects (classic) is being deprecated in favor of the new Projects experience. Tools 27-39 work with the classic version of Projects, which may be removed in the future. For the new GitHub Projects experience, use tools 40-46 instead.
language:javascript: Search by programming language
repo:owner/name: Search in specific repository
path:app/src: Search in specific path
extension:js: Search by file extension
Example: q: "import express" language:typescript path:src/
is:issue or is:pr: Filter by type
is:open or is:closed: Filter by state
label:bug: Search by label
author:username: Search by author
Example: q: "memory leak" is:issue is:open label:bug
type:user or type:org: Filter by account type
followers:>1000: Filter by followers
location:London: Search by location
Example: q: "fullstack developer" location:London followers:>100
For detailed search syntax, see GitHub's searching documentation.
Create a GitHub Personal Access Token with appropriate permissions:
Go to Personal access tokens (in GitHub Settings > Developer settings)
Select which repositories you'd like this token to have access to (Public, All, or Select)
Create a token with the repo scope ("Full control of private repositories")
Alternatively, if working only with public repositories, select only the public_repo scope
For using the Projects V2 tools, make sure to include the project scope as well
Copy the generated token
To use this with Claude Desktop, add the following to your claude_desktop_config.json:
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/tuanle96/mcp-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@earnbasejs/mcp-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}Docker build:
docker build -t mcp/github -f src/github/Dockerfile .This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Add a new card to a project column
| Name | Required | Description | Default |
|---|---|---|---|
| column_id | Yes | The ID of the column to add card to | |
| content_id | No | ID of the issue or pull request (required if content_type is Issue or PullRequest) | |
| content_type | Yes | Type of content for the card | |
| note | No | The note content for the card (required if content_type is Note) | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Add' implies a write/mutation operation, but the description doesn't mention required permissions, whether this creates a permanent record, potential side effects, error conditions, or what happens if the column doesn't exist. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a tool with good schema documentation and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'adding a card' means operationally, what the tool returns, error conditions, or how it differs from similar sibling tools. The 100% schema coverage helps with parameters but doesn't compensate for missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema (like explaining relationships between content_type and other parameters). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a new card') and target resource ('to a project column'), providing specific verb+resource. However, it doesn't distinguish this tool from sibling tools like 'add_item_to_project_v2' or 'move_card', which also manipulate project cards/items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'add_item_to_project_v2' or 'create_project_column'. It doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to an existing issue
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| issue_number | Yes | ||
| owner | Yes | ||
| repo | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Add a comment' implies a write/mutation operation, the description doesn't address critical aspects like required permissions, rate limits, whether the comment is editable/deletable, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the core purpose immediately. Every word earns its place in conveying the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't address parameter meanings, behavioral traits, or output expectations. While conciseness is good, the description lacks necessary context for the agent to use this tool effectively beyond basic inference from the name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 4 parameters (owner, repo, issue_number, body) are documented in the schema. The description adds no parameter information beyond what's implied by the tool name ('issue' hints at issue_number). It doesn't explain what 'owner' and 'repo' refer to, the format of 'issue_number', or constraints on 'body'. This fails to compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment') and target resource ('to an existing issue'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from potential sibling tools like 'update_issue' or 'create_issue' that might also involve commenting functionality, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., issue must exist), exclusions, or comparisons to sibling tools like 'update_issue' or 'get_issue' that might be relevant in different contexts. The agent receives minimal contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an issue or pull request to a GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| contentId | Yes | The node ID of the issue or pull request to add | |
| projectId | Yes | The node ID of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it's an 'Add' operation (implying mutation) but doesn't disclose behavioral traits like required permissions, whether it's idempotent, rate limits, error conditions, or what happens on success (e.g., returns an item ID). This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It front-loads the core action and resource, and every word ('using GraphQL API') adds relevant context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations, no output schema, and 2 parameters, the description is incomplete. It lacks behavioral context (e.g., permissions, side effects), usage guidelines, and output details, making it inadequate for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters ('contentId' as node ID of issue/PR, 'projectId' as node ID of project). The description adds no additional meaning beyond the schema, such as format examples or constraints, but the schema is comprehensive, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('an issue or pull request to a GitHub project V2'), specifying the API type ('GraphQL API'). It distinguishes from siblings like 'add_card_to_column' (which targets columns) and 'create_project_v2' (which creates projects), but doesn't explicitly contrast with 'update_project_v2_item_field' (which modifies fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing node IDs), exclusions (e.g., not for adding non-issue/PR items), or comparisons to siblings like 'add_card_to_column' (for project V1) or 'update_project_v2_item_field' (for modifying fields).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new branch in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | Name for the new branch | |
| from_branch | No | Optional: source branch to create from (defaults to the repository's default branch) | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Create') which implies a write operation, but doesn't mention permission requirements, rate limits, whether the branch becomes active immediately, or what happens on failure. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a straightforward tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address authentication requirements, error conditions, what the tool returns, or how it differs from related operations. The 100% schema coverage helps with parameters, but overall context for safe and effective use is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline expectation when the schema does the heavy lifting, but doesn't provide additional context about parameter relationships or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new branch in a GitHub repository'), making the purpose immediately understandable. It doesn't specifically differentiate from sibling tools like 'fork_repository' or 'create_pull_request' which also involve branch-like operations, but it's sufficiently specific for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (like authentication needs), when not to use it, or how it relates to sibling tools like 'create_pull_request' or 'fork_repository' which might be alternatives for certain scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new issue in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| assignees | No | ||
| body | No | ||
| labels | No | ||
| milestone | No | ||
| owner | Yes | ||
| repo | Yes | ||
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It states it creates an issue but doesn't describe what happens after creation (e.g., issue number assignment, notifications), authentication requirements, rate limits, error conditions, or whether the operation is idempotent. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately front-loaded with the core action and resource, making it easy to parse quickly despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters, 0% schema description coverage, no annotations, and no output schema, the description is insufficiently complete. It covers the basic purpose but lacks crucial details about parameters, behavioral expectations, error handling, and output format. The agent would need to guess about many aspects of tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for 7 parameters, the description provides no parameter information beyond what's implied by the tool name. It doesn't explain what 'owner', 'repo', 'title', 'body', 'assignees', 'labels', or 'milestone' represent, their formats, or constraints. The description fails to compensate for the complete lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new issue') and target resource ('in a GitHub repository'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'update_issue' or 'get_issue' by specifying creation rather than modification or retrieval. However, it doesn't explicitly differentiate from other creation tools like 'create_project' or 'create_pull_request' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., repository access), when not to use it (e.g., for updating existing issues), or how it differs from similar creation tools like 'create_pull_request'. The agent must infer usage from the tool name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a single file in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | Branch to create/update the file in | |
| content | Yes | Content of the file | |
| message | Yes | Commit message | |
| owner | Yes | Repository owner (username or organization) | |
| path | Yes | Path where to create/update the file | |
| repo | Yes | Repository name | |
| sha | No | SHA of the file being replaced (required when updating existing files) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but doesn't mention critical details like required permissions (e.g., write access to the repo), whether it's idempotent, potential side effects (e.g., creating commits), or error handling. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It's front-loaded and wastes no words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a file mutation tool with 7 parameters, no annotations, and no output schema, the description is inadequate. It lacks details on behavior, usage context, and output format, leaving the agent with insufficient information to use the tool effectively beyond basic parameter passing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning beyond what's in the schema, such as explaining parameter interactions or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create or update') and resource ('a single file in a GitHub repository'), making the purpose unambiguous. However, it doesn't distinguish this tool from sibling tools like 'push_files' or 'get_file_contents', which might handle similar file operations, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't clarify if this is preferred over 'push_files' for single-file operations or when to use 'get_file_contents' for reading instead. This lack of context leaves the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Description of the project | |
| name | Yes | Name of the project | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation, implying mutation, but doesn't mention permissions required, rate limits, whether it's idempotent, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's appropriately sized and front-loaded with the essential information about what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation, error conditions, or behavioral aspects. The description should provide more context given the complexity of creating a project in GitHub.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't mention any parameters at all, but schema description coverage is 100% (all 4 parameters have descriptions in the schema). According to the rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter information in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new project') and the resource ('in a GitHub repository'), which is specific and unambiguous. However, it doesn't distinguish this from sibling tools like 'create_project_v2' or 'create_repository', which would require explicit differentiation for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_project_v2' or 'create_repository', nor does it mention prerequisites or context for usage. It simply states what the tool does without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new column in a project
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the column | |
| owner | Yes | Repository owner (username or organization) | |
| project_number | Yes | The project number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation, implying it's a write/mutation tool, but doesn't mention permission requirements, rate limits, whether it's idempotent, or what happens on success/failure. This leaves significant behavioral gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation (e.g., returns column ID, error conditions), permission requirements, or how it differs from similar tools. The 100% schema coverage helps but doesn't compensate for the missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description adds no additional parameter context beyond what's in the schema, meeting the baseline expectation but not providing extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new column in a project'), making the purpose immediately understandable. However, it doesn't distinguish this tool from similar siblings like 'create_project' or 'update_project_column', which would require explicit differentiation for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'update_project_column' or 'list_project_columns', nor does it mention prerequisites or contextual constraints. It simply states what the tool does without usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Description of the project | |
| ownerId | Yes | The node ID of the organization or user | |
| title | Yes | Title of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is a creation operation but doesn't disclose behavioral traits like required permissions, whether this creates public/private projects by default, rate limits, error conditions, or what happens on success. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple creation tool and front-loads the essential information (create, GitHub project V2, GraphQL API). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, what permissions are required, how it differs from 'create_project', or typical error conditions. Given the complexity of GitHub projects and the lack of structured behavioral information, the description should provide more context about this write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (ownerId, title, description) with clear descriptions. The tool description adds no additional parameter information beyond what's in the schema. With complete schema coverage, the baseline is 3 even without parameter details in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new GitHub project V2'), and specifies the API method ('using GraphQL API'). It distinguishes from the sibling 'create_project' by specifying V2, but doesn't explain the functional difference between project versions. The purpose is clear but could better differentiate from its sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'create_project' (the V1 version) or 'create_repository'. The description mentions 'V2' but doesn't explain when V2 projects are appropriate versus V1. There's no mention of prerequisites, permissions needed, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new pull request in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | The name of the branch you want the changes pulled into | |
| body | No | Pull request body/description | |
| draft | No | Whether to create the pull request as a draft | |
| head | Yes | The name of the branch where your changes are implemented | |
| maintainer_can_modify | No | Whether maintainers can modify the pull request | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| title | Yes | Pull request title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention that this is a write operation (implied by 'create'), potential authentication requirements, rate limits, error conditions, or what happens on success (e.g., returns a PR object). For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core function without unnecessary words. It's appropriately sized for a tool with comprehensive schema documentation and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex write operation with 8 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what happens after creation, error handling, authentication needs, or how this differs from similar tools. The schema handles parameter documentation, but the description fails to provide necessary behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific information beyond what's already in the schema (which has 100% coverage with clear descriptions for all 8 parameters). This meets the baseline of 3 for high schema coverage, but doesn't provide additional context like parameter relationships or GitHub-specific conventions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and resource ('new pull request in a GitHub repository'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'merge_pull_request' or 'update_pull_request_branch', which would require explicit differentiation for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_issue' or 'list_pull_requests', nor does it mention prerequisites such as having appropriate repository permissions or existing branches. It's a basic statement of function without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a review on a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The body text of the review | |
| comments | No | Comments to post as part of the review | |
| commit_id | No | The SHA of the commit that needs a review | |
| event | Yes | The review action to perform | |
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create a review' implies a write/mutation operation, but it doesn't specify permissions required (e.g., collaborator status), whether reviews are editable/deletable, rate limits, or what happens on success/failure. It lacks context about the review's impact (e.g., blocking merges) or return format, leaving significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately understandable. Every word earns its place without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or error handling, nor does it explain the purpose of key parameters like 'event' or 'comments'. Given the complexity and lack of structured data, it should provide more context to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 7 parameters (owner, repo, pull_number, body, event, commit_id, comments). The description adds no parameter-specific information beyond what's in the schema, such as explaining the 'event' enum values (APPROVE, REQUEST_CHANGES, COMMENT) in practical terms. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a review on a pull request' clearly states the action (create) and target resource (review on a pull request). It distinguishes this from sibling tools like 'add_issue_comment' or 'get_pull_request_reviews' by specifying creation rather than retrieval or commenting on issues. However, it doesn't explicitly differentiate from 'update_pull_request_branch' or other pull request-related tools beyond the basic verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing pull request access), when not to use it (e.g., for simple comments vs. formal reviews), or refer to sibling tools like 'get_pull_request_reviews' for checking existing reviews. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new GitHub repository in your account
| Name | Required | Description | Default |
|---|---|---|---|
| autoInit | No | Initialize with README.md | |
| description | No | Repository description | |
| name | Yes | Repository name | |
| private | No | Whether the repository should be private |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like authentication requirements, rate limits, whether it's idempotent, what happens on duplicate names, or what the response contains. For a mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool that creates resources with 4 parameters and no annotations or output schema, the description is insufficient. It doesn't explain what happens after creation, error conditions, authentication needs, or how it differs from similar tools. The context demands more completeness than provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, but it correctly implies the 'name' parameter is central. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new GitHub repository in your account'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'fork_repository' or specify what type of account (user vs. organization), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'fork_repository' or 'create_project'. The description only states what it does without context about prerequisites, when it's appropriate, or what happens after creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a card from a project
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | The unique identifier of the card |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Delete') but fails to mention critical details like whether the deletion is permanent, requires specific permissions, triggers side effects (e.g., notifications), or has rate limits. This is inadequate for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it easy to parse and understand quickly. It is appropriately sized for the tool's simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits (e.g., permanence, permissions), usage context, and expected outcomes, leaving significant gaps in understanding how to invoke it safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'card_id' documented as 'The unique identifier of the card'. The description adds no additional meaning beyond this, such as format examples or sourcing tips, but the schema provides sufficient baseline information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a card from a project'), providing a specific verb+resource combination. However, it does not distinguish this tool from sibling deletion tools like 'delete_issue' or 'delete_project_column', which reduces clarity in a context with multiple deletion operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, such as other deletion tools (e.g., 'delete_issue') or related operations (e.g., 'move_card'). It lacks context about prerequisites, constraints, or typical use cases, leaving the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an issue from a GitHub repository using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| issue_number | Yes | ||
| owner | Yes | ||
| repo | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is a deletion using GraphQL API, implying a destructive, irreversible operation, but lacks details on permissions required, rate limits, error handling, or what happens upon success (e.g., confirmation). This is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Delete an issue') without unnecessary words. Every part earns its place by specifying the resource and API type, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive mutation with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions or outcomes, parameter details, or usage context, leaving significant gaps for an AI agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It adds no information about 'owner', 'repo', or 'issue_number' beyond what the schema's property names imply. For example, it doesn't clarify that 'owner' is a GitHub username/organization or that 'issue_number' is an integer. This leaves parameters poorly documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('an issue from a GitHub repository'), making the purpose immediately understandable. It distinguishes from siblings like 'update_issue' or 'get_issue' by specifying deletion. However, it doesn't explicitly differentiate from 'delete_card' or other deletion tools, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing admin permissions), when not to use it (e.g., for archiving instead), or direct alternatives among siblings like 'update_issue' for closing issues. Without such context, usage is unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a project column
| Name | Required | Description | Default |
|---|---|---|---|
| column_id | Yes | The unique identifier of the column |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Delete' which implies a destructive mutation, but doesn't disclose critical behaviors: whether deletion is permanent or reversible, what happens to associated cards (e.g., moved or deleted), required permissions, or error conditions (e.g., invalid column_id). This leaves significant gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with zero wasted words. It's front-loaded with the core action and resource, making it highly efficient. No structural issues or redundancy are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, the description is insufficient. It lacks details on behavior (e.g., side effects, permissions), output (e.g., success confirmation or error messages), and context relative to siblings (e.g., how it differs from 'delete_card'). Given the complexity and risk of deletion, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'column_id' documented as 'The unique identifier of the column'. The description doesn't add any meaning beyond this, such as where to obtain the ID or format examples. Baseline 3 is appropriate since the schema adequately defines the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a project column'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_card' or 'delete_issue' beyond the resource name, nor does it specify what type of project (e.g., GitHub Project v1 vs v2) it refers to, which is relevant given siblings like 'list_project_columns' and 'update_project_column'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing column_id from 'list_project_columns'), exclusions (e.g., cannot delete columns with cards), or related tools like 'update_project_column' for modifications instead of deletion. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fork a GitHub repository to your account or specified organization
| Name | Required | Description | Default |
|---|---|---|---|
| organization | No | Optional: organization to fork to (defaults to your personal account) | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It states the action but doesn't disclose critical traits like authentication requirements, rate limits, whether it's a write operation, what happens on success/failure, or if it triggers notifications. 'Fork' implies a write, but this isn't explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool (forking implies writing) with no annotations and no output schema, the description is incomplete. It lacks details on authentication, permissions, error handling, return values, or how it fits into the GitHub workflow context. This leaves significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (owner, repo, organization). The description adds no additional meaning beyond implying the default behavior for 'organization' (personal account), which is already covered in the schema description. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fork') and resource ('a GitHub repository') with the destination ('to your account or specified organization'). It's specific but doesn't explicitly differentiate from siblings like 'create_repository' which creates a new repository rather than forking an existing one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication, permissions), when not to use it, or how it compares to similar tools like 'create_repository' or 'clone' operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the contents of a file or directory from a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | Branch to get contents from | |
| owner | Yes | Repository owner (username or organization) | |
| path | Yes | Path to the file or directory | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It mentions reading ('Get') but doesn't specify whether this requires authentication, rate limits, what happens with non-existent paths, or if it returns raw content vs. metadata. For a tool with 4 parameters and no annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality without unnecessary words. Every part of the sentence ('Get the contents of a file or directory from a GitHub repository') directly contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain return values (e.g., file content vs. directory listing), error conditions, or authentication requirements. For a read operation in a GitHub context with many sibling tools, more contextual information is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters (owner, repo, path, branch) with clear descriptions. The description adds no additional meaning beyond implying the tool operates on GitHub repositories, which is redundant with the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the contents') and resource ('file or directory from a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate from similar sibling tools like 'search_code' or 'get_pull_request_files', which could also retrieve file-related information in different contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_code' for broader searches or 'get_pull_request_files' for PR-specific content. It lacks context about prerequisites (e.g., needing repository access) or typical use cases, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific issue in a GitHub repository.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_number | Yes | ||
| owner | Yes | ||
| repo | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Get details' which implies a read-only operation, but doesn't mention authentication requirements, rate limits, error conditions, or what details are returned. This leaves significant gaps for a tool interacting with an external API.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a simple retrieval tool and front-loads the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 required parameters, no annotations, no output schema), the description is insufficient. It doesn't explain parameter meanings, return values, error handling, or how it differs from similar tools. For a GitHub API tool, this leaves too many unknowns for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so parameters are completely undocumented in structured fields. The description mentions 'specific issue in a GitHub repository' which implies parameters for identifying the issue and repository, but doesn't name or explain the three required parameters (owner, repo, issue_number) or their formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get details') and resource ('specific issue in a GitHub repository'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_issues' or 'search_issues', which would require more specific language about retrieving a single issue by identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_issues' or 'search_issues'. It mentions retrieving a 'specific issue' but doesn't clarify prerequisites (e.g., needing the issue number) or exclusions (e.g., not for bulk retrieval).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific project
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| project_number | Yes | The project number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Get details' which implies a read-only operation, but it doesn't disclose behavioral traits like authentication requirements, rate limits, error handling, or what 'details' includes (e.g., fields returned, format). For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Get details about a specific project'. It's front-loaded with the core action and resource, with zero wasted words. Every part earns its place by conveying the essential purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 required parameters, no annotations, no output schema, and many sibling tools), the description is incomplete. It doesn't address key contextual aspects like what 'details' includes, how it differs from 'get_project_v2', or prerequisites (e.g., repository access). For a read operation in a crowded toolset, more guidance is needed to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear descriptions for 'owner', 'repo', and 'project_number'. The description adds no meaning beyond the schema—it doesn't explain parameter relationships (e.g., that 'owner' and 'repo' identify the repository containing the project) or provide context like valid formats. With high schema coverage, the baseline is 3, and the description doesn't compensate with extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details about a specific project' clearly states the verb ('Get') and resource ('project'), but it's vague about what 'details' entails and doesn't differentiate from sibling tools like 'get_project_v2', 'list_projects', or 'list_organization_projects'. It specifies 'specific project' which implies it retrieves a single item, but this distinction isn't explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_project_v2', 'list_projects', and 'list_organization_projects', the description doesn't clarify if this is for GitHub Projects v1 vs. v2, single vs. multiple projects, or organization vs. repository contexts. The agent must infer usage from the parameter schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The node ID of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it's a read operation ('Get details'), but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or what 'details' include. For a tool with no annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes the API type (GraphQL) as useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'details' are returned, potential errors, or usage constraints. Given the complexity of GitHub projects and lack of structured data, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'id' documented as 'The node ID of the project'. The description adds no additional parameter semantics beyond implying it retrieves details for a specific project ID. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and resource ('a GitHub project V2'), specifying it uses the GraphQL API. It distinguishes from generic 'get_project' by specifying V2, though it doesn't explicitly differentiate from 'list_project_v2_items' or 'update_project_v2' in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_project' (for V1) or 'list_project_v2_items'. The description implies it's for retrieving details of a specific project, but doesn't mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific pull request
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it 'gets details' without disclosing behavioral traits. It doesn't mention whether this is a read-only operation, requires authentication, has rate limits, returns specific data structures, or handles errors. This leaves significant gaps for an agent to understand how to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple retrieval tool and front-loads the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool with three parameters. It doesn't explain what details are returned (e.g., title, state, author), how errors are handled, or any behavioral context. For a retrieval tool in a GitHub context, this leaves too many unknowns for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (owner, repo, pull_number) with clear descriptions. The description adds no additional meaning beyond implying these parameters identify a specific pull request, which is already obvious from the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get details') and resource ('specific pull request'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'list_pull_requests' (which lists multiple) and 'get_pull_request_comments' (which focuses on comments). However, it doesn't specify what details are included, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing repository access), contrast with 'list_pull_requests' for multiple PRs, or specify scenarios where detailed PR information is required versus just status or files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the review comments on a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't mention whether this is a read-only operation, what permissions might be required, whether results are paginated, or what format the comments are returned in. For a data retrieval tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the tool's core function without any wasted words. It's appropriately sized for a straightforward data retrieval tool and gets directly to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'review comments' encompasses versus regular comments, doesn't indicate the return format or structure, and provides no context about authentication requirements or rate limits. The agent would be left guessing about important implementation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all three parameters clearly documented in the schema itself. The tool description adds no additional parameter information beyond what's already in the schema descriptions, so it meets but doesn't exceed the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('review comments on a pull request'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_pull_request_reviews' or 'get_pull_request_files', which could cause confusion about what specific type of pull request data this tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_pull_request_reviews' and 'get_pull_request_files' available, there's no indication of what distinguishes this tool (comments) from those other pull request data retrieval tools, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of files changed in a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get the list of files changed') but does not describe key traits like whether this is a read-only operation, what the output format includes (e.g., file paths, change types), or any rate limits or authentication requirements. This leaves significant gaps for a tool that interacts with pull requests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words, efficiently conveying the core purpose. It is front-loaded and appropriately sized for a simple retrieval tool, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of pull request operations, lack of annotations, and no output schema, the description is incomplete. It does not explain behavioral aspects like read-only nature, output structure, or error handling, which are critical for an AI agent to use the tool correctly in context with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'owner', 'repo', and 'pull_number'. The description does not add any parameter-specific details beyond what the schema provides, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the description does not compensate but also does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('list of files changed in a pull request'), making the purpose specific and understandable. However, it does not explicitly distinguish this tool from sibling tools like 'get_pull_request', 'get_pull_request_comments', or 'get_pull_request_reviews', which also retrieve pull request data but focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing a valid pull request number, or compare it to sibling tools like 'get_pull_request' for general pull request info or 'list_commits' for commit-level changes, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the reviews on a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get the reviews' but doesn't specify if this is a read-only operation, what permissions are required, how data is returned (e.g., pagination, format), or any rate limits. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words, making it highly concise and front-loaded. Every word contributes to stating the tool's purpose efficiently, earning a top score for brevity and clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool that likely returns structured data (reviews). It doesn't explain what 'reviews' entail (e.g., approval status, comments), the return format, or error handling, leaving gaps that could hinder effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'owner', 'repo', and 'pull_number'. The description doesn't add any parameter-specific details beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the reviews on a pull request' clearly states the action (get) and resource (reviews on a pull request), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get_pull_request_comments' or 'get_pull_request', which might retrieve related but different data, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid pull request), exclusions, or comparisons to siblings like 'get_pull_request_comments' for comments instead of reviews, leaving usage context implicit at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the combined status of all status checks for a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves status checks but doesn't explain what 'combined status' means, whether it includes details like individual check results, error handling, or rate limits. This leaves significant gaps for a tool that likely interacts with external systems.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of pull request status checks (which often involve external CI/CD systems) and the lack of annotations and output schema, the description is insufficient. It doesn't explain the return format, error cases, or behavioral nuances, leaving the agent with incomplete information for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters (owner, repo, pull_number). The description adds no additional meaning beyond what's in the schema, such as format examples or constraints, resulting in the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('combined status of all status checks for a pull request'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_pull_request' or 'get_pull_request_reviews', which reduces it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios where this is preferred over other pull request-related tools or any prerequisites, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all cards in a project column
| Name | Required | Description | Default |
|---|---|---|---|
| archived_state | No | Filter by card archived state | |
| column_id | Yes | The unique identifier of the column | |
| page | No | Page number for pagination (starts at 1) | |
| per_page | No | Number of results per page (max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a list operation but doesn't mention pagination behavior (implied by parameters but not described), rate limits, authentication requirements, or what happens with archived cards. The description is minimal and doesn't provide adequate behavioral context for a tool with filtering and pagination capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core functionality without any wasted words. It's appropriately sized for a list operation and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters (including filtering and pagination), no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, how archived cards are handled, pagination behavior, or error conditions. The minimal description leaves significant gaps in understanding how to effectively use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any parameter semantics beyond what's in the schema - it mentions 'project column' which relates to 'column_id' but provides no additional context about column identification or the relationship between columns and cards.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all cards') and target resource ('in a project column'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'list_project_v2_items' or 'list_project_columns' which might have overlapping functionality in the same domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are multiple list/search tools in the sibling set (list_issues, list_project_columns, list_project_v2_items, search_issues, etc.), but no indication of which scenarios call for this specific column-card listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of commits of a branch in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | ||
| page | No | ||
| perPage | No | ||
| repo | Yes | ||
| sha | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't describe whether this is a read-only operation (implied but not stated), pagination behavior (though parameters suggest it), rate limits, authentication requirements, or what the return format looks like. The description merely restates the basic function without adding behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every word earns its place, making it easy to parse quickly. No structural issues or redundancy are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no annotations, no output schema), the description is inadequate. It doesn't explain parameter usage, behavioral traits like pagination or authentication, or what the output contains. For a tool with multiple parameters and no structured guidance, more descriptive context is needed to help the agent use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information beyond what's inferable from the tool name. It doesn't explain what 'owner', 'repo', 'sha', 'page', or 'perPage' mean, their expected formats, or how they interact (e.g., that 'sha' specifies the branch). The description fails to provide semantic context for any of the 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get list') and target resource ('commits of a branch in a GitHub repository'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_pull_requests' or 'list_issues', which would require mentioning it's specifically for commit history rather than other repository elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication needs), when not to use it, or how it compares to similar listing tools in the sibling set. The agent must infer usage purely from the tool name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issues in a GitHub repository with filtering options
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | ||
| labels | No | ||
| owner | Yes | ||
| page | No | ||
| per_page | No | ||
| repo | Yes | ||
| since | No | ||
| sort | No | ||
| state | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'List issues' implies a read operation, the description doesn't address important behavioral aspects like pagination behavior (implied by 'page' and 'per_page' parameters but not explained), rate limits, authentication requirements, error conditions, or what the output looks like. The mention of 'filtering options' is helpful but insufficient for a mutation-free tool with 9 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a listing tool, though it could be slightly more informative without losing conciseness. The structure is straightforward and front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, 3 with enums, no output schema, and no annotations), the description is insufficiently complete. For a tool with this many filtering options and no structured output documentation, the description should provide more guidance about what the tool returns, how pagination works, and the meaning of key parameters. The current description leaves too much undefined for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for all 9 parameters, the description provides minimal parameter semantics. It mentions 'filtering options' which hints at the purpose of parameters like 'labels', 'state', and 'since', but doesn't explain any specific parameters, their formats, or constraints. For example, it doesn't clarify that 'owner' and 'repo' are required, what 'since' expects (ISO timestamp), or what the enums mean. The description adds some value but doesn't adequately compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('issues in a GitHub repository'), making the purpose unambiguous. It also mentions 'filtering options' which adds specificity. However, it doesn't explicitly distinguish this tool from sibling tools like 'search_issues' or 'get_issue', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'search_issues' and 'get_issue' available, there's no indication of when this listing approach is preferable versus searching or fetching individual issues. The description only states what the tool does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in a GitHub organization (at organization level, not repository level)
| Name | Required | Description | Default |
|---|---|---|---|
| org | Yes | Organization name | |
| page | No | Page number for pagination | |
| per_page | No | Number of results per page (max 100) | |
| state | No | Filter projects by state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the scope ('organization level') but lacks critical behavioral details: it doesn't disclose that this is a read-only operation (implied by 'list'), doesn't mention authentication requirements, rate limits, pagination behavior beyond parameters, or what the output format looks like. For a tool with no annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all projects in a GitHub organization') and adds necessary scope clarification in parentheses. Every word earns its place with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool with 4 parameters and sibling tools. It covers purpose and scope adequately but lacks behavioral context (e.g., read-only nature, auth needs, output format) and explicit differentiation from alternatives. For a list tool with moderate complexity, this is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters (org, page, per_page, state) with descriptions and enum for 'state.' The description adds no additional parameter semantics beyond what's in the schema, such as default values or constraints like 'max 100' for per_page (already in schema). Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all projects') and resource ('in a GitHub organization'), with explicit scope clarification ('at organization level, not repository level'). It distinguishes from repository-level operations but doesn't explicitly differentiate from sibling tools like 'list_projects' or 'list_organization_projects_v2'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'at organization level, not repository level,' which helps differentiate from repository-scoped tools. However, it doesn't provide explicit guidance on when to use this versus similar sibling tools like 'list_projects' or 'list_organization_projects_v2,' nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects V2 in a GitHub organization using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor for pagination | |
| first | No | Number of projects to fetch (max 100) | |
| orderBy | No | How to order the projects | |
| org | Yes | Organization name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions 'GraphQL API' which hints at the underlying technology, but doesn't describe key behaviors: whether this is a read-only operation, potential rate limits, authentication requirements, pagination behavior beyond the schema, or what the output looks like. For a list operation with no annotations, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a list operation and front-loads the core purpose immediately. Every word earns its place in conveying the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain the return format, error conditions, or behavioral characteristics needed for proper use. The mention of 'GraphQL API' provides some context but doesn't compensate for the missing behavioral and output information that would help an agent use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain parameter relationships, default values, or usage patterns. With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't add value but the schema compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('projects V2 in a GitHub organization'), and specifies the API method ('using GraphQL API'). It distinguishes from the sibling 'list_organization_projects' by indicating this is a 'V2' version, though it doesn't explicitly contrast their differences. The purpose is specific but could better differentiate from the non-V2 sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_organization_projects' or other project-listing tools. It mentions 'GraphQL API' but doesn't explain why this matters or when to choose this over REST-based tools. No explicit when/when-not instructions or prerequisites are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all columns in a project
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (starts at 1) | |
| per_page | No | Number of results per page (max 100) | |
| project_id | Yes | The unique identifier of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it 'List all columns' but doesn't disclose behavioral traits like pagination behavior (implied by parameters but not described), rate limits, authentication needs, or what 'all' means in context. The description is minimal and lacks necessary operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple list operation and front-loaded with the core purpose, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple but operational tool (list with pagination), the description is incomplete. It doesn't cover behavioral aspects like pagination, return format, or error conditions, leaving gaps that could hinder correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters (project_id, page, per_page). The description adds no additional meaning beyond the schema, such as explaining relationships between parameters or usage nuances. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('columns in a project'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_column_cards' or 'list_projects', which would require specifying it's about project columns specifically (not cards or projects themselves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing a project_id), when not to use it, or how it differs from related sibling tools such as 'list_column_cards' or 'get_project'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| page | No | Page number for pagination (starts at 1) | |
| per_page | No | Number of results per page (max 100) | |
| repo | Yes | Repository name | |
| state | No | Filter projects by state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a list operation (implied read-only) but doesn't mention pagination behavior (implied by parameters but not explicit), rate limits, authentication requirements, or what the output looks like. This is inadequate for a tool with 5 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core purpose and efficiently communicates the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, pagination behavior, error conditions, or how it differs from sibling listing tools. The context signals indicate significant complexity that isn't addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional parameter semantics beyond implying repository context. Baseline 3 is appropriate when the schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('projects in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_organization_projects' or 'list_project_v2_items', which list similar resources in different contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_organization_projects' or 'list_project_v2_items'. It also doesn't mention prerequisites or constraints beyond what's implied by the parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items in a GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor for pagination | |
| first | No | Number of items to fetch (max 100) | |
| projectId | Yes | The node ID of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions the GraphQL API but doesn't describe key behaviors: whether it's read-only, pagination details beyond schema hints, rate limits, authentication needs, or what the output looks like. This is inadequate for a tool with parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes the API method without unnecessary details, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no annotations, no output schema), the description is incomplete. It lacks behavioral context (e.g., read-only status, output format), usage guidance, and doesn't compensate for the missing output schema, leaving gaps for an AI agent to understand how to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters like 'after' for pagination and 'first' with a max of 100. The description adds no additional meaning beyond the schema, such as explaining how 'projectId' relates to GitHub projects or pagination behavior. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('items in a GitHub project V2'), specifying the API method ('using GraphQL API'). It distinguishes from siblings like 'list_issues' or 'list_projects' by focusing on project items, though it doesn't explicitly contrast with 'list_project_columns' or 'list_column_cards'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the description implies it's for listing project items, it doesn't mention when to choose this over other list tools (e.g., 'list_project_columns' for columns) or prerequisites like needing a project ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and filter repository pull requests
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Filter by base branch name | |
| direction | No | The direction of the sort | |
| head | No | Filter by head user or head organization and branch name | |
| owner | Yes | Repository owner (username or organization) | |
| page | No | Page number of the results | |
| per_page | No | Results per page (max 100) | |
| repo | Yes | Repository name | |
| sort | No | What to sort results by | |
| state | No | State of the pull requests to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'list and filter' but doesn't describe pagination behavior (implied by page/per_page parameters), rate limits, authentication requirements, whether it's read-only, or what the return format looks like. For a tool with 9 parameters and no output schema, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without waste. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no annotations, no output schema), the description is inadequate. It doesn't explain the return format, pagination behavior, authentication needs, or how it differs from similar tools. For a list/filter operation with rich parameters, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly with descriptions and enums. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline but doesn't provide extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list and filter' and the resource 'repository pull requests', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_pull_request' (singular) or 'list_issues', which would require explicit comparison to achieve a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_pull_request' (for single PRs), 'list_issues' (for issues instead of PRs), or 'search_issues' (which might include PRs). There's no context about prerequisites or when this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge a pull request
| Name | Required | Description | Default |
|---|---|---|---|
| commit_message | No | Extra detail to append to automatic commit message | |
| commit_title | No | Title for the automatic commit message | |
| merge_method | No | Merge method to use | |
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the action ('merge') without any context. It doesn't mention that this is a destructive/write operation, potential side effects (e.g., closes the pull request, creates a merge commit), authentication requirements, rate limits, or what happens on failure. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words, with zero wasted language. It's front-loaded with the core action and resource, making it immediately understandable. Every word earns its place, though this conciseness comes at the cost of completeness in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after merging (e.g., does it return success status, the merge commit SHA?), error conditions, or behavioral constraints. The 100% schema coverage helps with parameters, but overall context for safe and effective use is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain the relationship between parameters or provide usage examples). This meets the baseline of 3 when the schema does the heavy lifting, but the description doesn't compensate with any extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Merge a pull request' clearly states the verb ('merge') and resource ('pull request'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'update_pull_request_branch' or 'create_pull_request', which would require more specific language about what merging entails versus other pull request operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., pull request must be in a mergeable state), exclusions (e.g., cannot merge if there are conflicts), or when to choose other tools like 'update_pull_request_branch' for different operations. This leaves the agent without context for appropriate tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a card to a different position or column
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | The unique identifier of the card | |
| column_id | No | The column ID to move the card to | |
| position | Yes | The position of the card (top, bottom, or after:<card_id>) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('move') but doesn't describe what happens during the move (e.g., whether it's atomic, if it affects other cards, permission requirements, or error conditions). For a mutation tool with zero annotation coverage, this is a significant gap in transparency about its behavior and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without redundancy. It's appropriately sized and front-loaded, making it easy to parse quickly. Every word earns its place by conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation with 3 parameters) and lack of annotations or output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or return values, which are critical for safe and effective use. For a tool that modifies data, this minimal description leaves significant gaps in understanding its full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (card_id, column_id, position) with their types and constraints. The description adds no additional meaning beyond what's in the schema—it doesn't explain parameter interactions (e.g., column_id is optional) or provide examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('move') and resource ('card') with the specific action of repositioning it ('to a different position or column'). It distinguishes from sibling tools like 'delete_card' or 'list_column_cards' by focusing on relocation rather than deletion or listing. However, it doesn't explicitly differentiate from similar tools like 'update_project_v2_item_field' which might also affect card positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing card and column IDs), when not to use it (e.g., for creating cards), or direct alternatives among siblings like 'update_project_v2_item_field' for similar positioning tasks. Usage is implied by the action but not explicitly contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push multiple files to a GitHub repository in a single commit
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | Branch to push to (e.g., 'main' or 'master') | |
| files | Yes | Array of files to push | |
| message | Yes | Commit message | |
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose critical behavioral traits like authentication requirements, rate limits, error handling, whether it overwrites existing files, or what happens on failure. The description is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that clearly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks information about return values, error conditions, authentication requirements, and behavioral constraints that would help an agent use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('push multiple files'), resource ('to a GitHub repository'), and scope ('in a single commit'). It distinguishes from sibling tools like 'create_or_update_file' (which handles single files) by emphasizing batch operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_or_update_file' for single files or 'create_commit' for different commit structures. It lacks context about prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code across GitHub repositories
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | ||
| page | No | ||
| per_page | No | ||
| q | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but provides minimal information. It mentions searching across repositories but doesn't describe what the search returns, pagination behavior, rate limits, authentication requirements, or whether this is a read-only operation. The agent must infer these critical behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 6 words, front-loading the essential information with zero wasted words. Every word contributes directly to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what the search returns, how results are structured, or provide any context about the search scope beyond 'across GitHub repositories.' The agent lacks sufficient information to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 4 parameters (1 required), the description provides no information about any parameters. It doesn't mention the required 'q' query parameter or optional pagination parameters, leaving the agent to rely solely on the schema without semantic context about what constitutes a valid search query or how pagination works.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for code') and resource ('across GitHub repositories'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling search tools like 'search_issues' or 'search_repositories' beyond specifying the search target is 'code' rather than issues or repositories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer searching code over searching issues/repositories, nor does it specify any prerequisites or constraints for using this search functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for issues and pull requests across GitHub repositories
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | ||
| page | No | ||
| per_page | No | ||
| q | Yes | ||
| sort | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('search') but doesn't cover critical traits like authentication needs, rate limits, pagination behavior (implied by 'page' and 'per_page' params but not explained), or what the output looks like (no output schema). This is a significant gap for a search tool with multiple parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It lacks parameter explanations, behavioral context (e.g., search syntax, limits), and output details, making it inadequate for an agent to use the tool effectively without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description adds no semantic information about parameters—it doesn't explain 'q' as a query string, 'order' as sorting direction, 'sort' as criteria, or 'page'/'per_page' for pagination. With 5 parameters (1 required) and no schema help, the description fails to compensate, leaving parameters largely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('search') and resource ('issues and pull requests') with scope ('across GitHub repositories'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'search_code', 'search_repositories', or 'search_users', which all search GitHub but for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling search tools (e.g., 'search_code' for code, 'search_repositories' for repos) or non-search tools like 'list_issues' for unfiltered listing, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for GitHub repositories
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (default: 1) | |
| perPage | No | Number of results per page (default: 30, max: 100) | |
| query | Yes | Search query (see GitHub search syntax) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'search' but doesn't describe what the search returns (e.g., repository metadata), rate limits, authentication needs, or pagination behavior beyond what's in the schema. This is inadequate for a tool with potential complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and multiple sibling search tools, the description is incomplete. It doesn't explain return values, differentiate from other searches, or cover behavioral aspects like rate limits, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (query, page, perPage) with descriptions. The description adds no additional parameter semantics beyond implying GitHub as the platform, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search for GitHub repositories' clearly states the verb ('Search') and resource ('GitHub repositories'), making the purpose immediately understandable. However, it doesn't differentiate from sibling search tools like 'search_code' or 'search_issues', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_code' or 'search_issues', nor does it mention any prerequisites or contextual constraints. It's a basic statement of function without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for users on GitHub
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | ||
| page | No | ||
| per_page | No | ||
| q | Yes | ||
| sort | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Search for users' implies a read-only operation, but it doesn't describe authentication requirements, rate limits, pagination behavior, or what constitutes a successful search. The description is too minimal to provide adequate behavioral context for a search tool with 5 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just 4 words. It's front-loaded with the core purpose and wastes no words. While it may be too brief for completeness, it achieves perfect conciseness for what it does cover.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 0% schema coverage, no annotations, no output schema), the description is inadequate. It doesn't explain what the search returns, how results are structured, authentication requirements, or parameter usage. For a search tool with multiple configuration options, this minimal description leaves too many questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but provides no parameter information. The description doesn't mention any parameters, their purposes, or how they affect the search. For a tool with 5 parameters including a required query parameter and multiple enums, this is a significant gap in documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search for users on GitHub' clearly states the action (search) and resource (users on GitHub), but it's vague about scope and doesn't distinguish from sibling search tools like search_code, search_issues, and search_repositories. It specifies the platform (GitHub) which is helpful context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention when this search is appropriate compared to other user-related operations or other search tools on the server. There's no indication of prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing issue in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| assignees | No | ||
| body | No | ||
| issue_number | Yes | ||
| labels | No | ||
| milestone | No | ||
| owner | Yes | ||
| repo | Yes | ||
| state | No | ||
| title | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It states this is an update operation but doesn't mention required permissions, whether changes are reversible, rate limits, or what happens when invalid parameters are provided. For a mutation tool with 9 parameters, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 7 words, front-loading the essential information without any wasted words. It follows a clear 'verb + resource' structure that makes the tool's purpose immediately apparent despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 9 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what fields can be updated, what the response looks like, error conditions, or authentication requirements. Given the complexity of GitHub issue updates and the complete lack of structured documentation, the description should provide much more contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for all 9 parameters, the description provides no additional semantic information about any parameters. It doesn't explain what 'owner' and 'repo' refer to, what format 'issue_number' should be in, or what the 'state' enum values mean. The description fails to compensate for the complete lack of parameter documentation in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('an existing issue in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'update_project' or 'update_pull_request_branch' that also perform updates on different GitHub resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'create_issue', 'delete_issue', 'get_issue', and 'list_issues', there's no indication of when updating is appropriate versus creating new issues or retrieving existing ones. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project's details
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | New description of the project | |
| name | No | New name of the project | |
| project_id | Yes | The unique identifier of the project | |
| state | No | State of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't cover permissions, side effects, error conditions, or response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any unnecessary words. It's front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens during the update, potential impacts, or what is returned. Given the complexity of updating a project and the lack of structured data, more context is needed to make this tool usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all parameters are documented in the schema itself. The description doesn't add any additional meaning or context beyond what's in the schema, such as explaining relationships between parameters or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('update') and resource ('an existing project's details'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'update_project_column' or 'update_project_v2', which also update project-related entities, so it doesn't fully distinguish itself from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'update_project_column' or 'update_project_v2', nor are there any prerequisites or exclusions mentioned. The description only restates the basic function without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project column
| Name | Required | Description | Default |
|---|---|---|---|
| column_id | Yes | The unique identifier of the column | |
| name | Yes | New name of the column |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Update' implies a mutation operation, the description doesn't disclose important behavioral traits like required permissions, whether this operation is reversible, what happens to existing data in the column, error conditions, or rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence with zero wasted words. It's front-loaded with the essential information (update operation on project column) and doesn't include any unnecessary elaboration. This is an example of efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't address behavioral aspects (permissions, side effects, error handling), doesn't differentiate from similar sibling tools, and provides no information about what the tool returns. Given the complexity of project management operations and the lack of structured metadata, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (column_id and name) with clear descriptions. The description doesn't add any parameter semantics beyond what's in the schema - it doesn't explain format requirements, constraints, or provide examples. With complete schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and target resource ('an existing project column'), providing specific verb+resource pairing. However, it doesn't distinguish this tool from similar sibling tools like 'update_project', 'update_project_v2', or 'update_project_v2_item_field', which all involve updating project-related entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are multiple update-related sibling tools (update_project, update_project_v2, update_project_v2_item_field, update_issue), but the description doesn't clarify when this specific column update tool is appropriate versus those other update operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| closed | No | Whether to close the project | |
| description | No | New description for the project | |
| projectId | Yes | The node ID of the project | |
| title | No | New title for the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'Update' implying mutation but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes the API method, making it appropriately sized and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a mutation tool with 4 parameters, the description is incomplete. It lacks behavioral context, usage guidelines, and details on return values or errors. For a tool that modifies GitHub projects, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (projectId, title, description, closed). The description adds no additional meaning beyond what the schema provides, such as format details or constraints. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('a GitHub project V2'), and specifies the API method ('using GraphQL API'). It distinguishes from siblings like 'update_project' (likely V1) and 'update_project_v2_item_field' (field-specific). However, it doesn't explicitly contrast with all siblings, missing some nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'update_project' (likely V1) or 'update_project_v2_item_field'. The description lacks context about prerequisites, such as needing an existing project ID, or when not to use it (e.g., for creating projects).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a field value for an item in a GitHub project V2 using GraphQL API
| Name | Required | Description | Default |
|---|---|---|---|
| fieldId | Yes | The node ID of the field | |
| itemId | Yes | The node ID of the item | |
| projectId | Yes | The node ID of the project | |
| value | No | The new value for the field |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is an update operation, implying mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it states the action, target, and API method without redundancy. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or behavioral context like side effects. For a 4-parameter tool that modifies data, more detail is needed to guide the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters (projectId, itemId, fieldId, value) with clear descriptions. The description adds no additional meaning beyond implying these IDs are for GraphQL nodes, which aligns with the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a field value') and the target resource ('for an item in a GitHub project V2'), specifying it uses the GraphQL API. It distinguishes from siblings like 'update_issue' or 'update_project_v2' by focusing on item fields, though it doesn't explicitly contrast with similar tools like 'update_project_v2'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing existing project, item, and field IDs), exclusions, or how it differs from siblings like 'update_project_v2' or 'add_item_to_project_v2', leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a pull request branch with the latest changes from the base branch
| Name | Required | Description | Default |
|---|---|---|---|
| expected_head_sha | No | The expected SHA of the pull request's HEAD ref | |
| owner | Yes | Repository owner (username or organization) | |
| pull_number | Yes | Pull request number | |
| repo | Yes | Repository name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates a mutation ('update') but doesn't specify permissions required, whether it's reversible, rate limits, or what happens on failure (e.g., conflicts). For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is minimal. It covers the basic purpose but lacks details on behavior, error handling, or output. Given the complexity (updating a pull request branch) and absence of structured fields, it should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter semantics beyond implying the tool updates a branch, which aligns with the schema's parameters (owner, repo, pull_number, expected_head_sha). Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update') and resource ('pull request branch') with specific scope ('with the latest changes from the base branch'). It distinguishes from siblings like 'merge_pull_request' or 'create_pull_request' by focusing on branch synchronization rather than merging or creation. However, it doesn't explicitly differentiate from all sibling tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'merge_pull_request' or 'create_pull_request', nor does it mention prerequisites or exclusions. It states what the tool does but not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0add_card_to_columnadd_issue_commentadd_item_to_project_v2create_branchcreate_issuecreate_or_update_filecreate_projectcreate_project_columncreate_project_v2create_pull_requestcreate_pull_request_reviewcreate_repositorydelete_carddelete_issuedelete_project_columnfork_repositoryget_file_contentsget_issueget_projectget_project_v2get_pull_requestget_pull_request_commentsget_pull_request_filesget_pull_request_reviewsget_pull_request_statuslist_column_cardslist_commitslist_issueslist_organization_projectslist_organization_projects_v2list_project_columnslist_project_v2_itemslist_projectslist_pull_requestsmerge_pull_requestmove_cardpush_filessearch_codesearch_issuessearch_repositoriessearch_usersupdate_issueupdate_projectupdate_project_columnupdate_project_v2update_project_v2_item_fieldupdate_pull_request_branchMost tools have distinct purposes targeting specific GitHub resources and actions, such as add_card_to_column vs. move_card. However, some overlap exists between project-related tools (e.g., create_project vs. create_project_v2) and search tools (search_code, search_issues, search_repositories, search_users), which could cause minor confusion. Descriptions help clarify, but the sheer number of tools increases cognitive load.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_issue, get_file_contents, and list_pull_requests. There are no deviations in style (e.g., no camelCase mixed in), making the naming predictable and readable. This consistency aids in understanding and using the tool set effectively.
With 47 tools, the count is borderline high for a GitHub server, feeling heavy and potentially overwhelming. While GitHub is a broad domain, this many tools might indicate over-specialization or fragmentation. A more streamlined set could improve usability without sacrificing functionality, as some tools could be consolidated.
The tool set provides comprehensive coverage of GitHub's core functionalities, including repositories, issues, pull requests, projects, files, and search. It supports full CRUD/lifecycle operations (e.g., create, get, update, delete for issues and projects) and handles advanced workflows like project management and pull request reviews. No obvious gaps are present for the intended domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Manage repositories, users, releases, and automate GitHub workflows
Ask any GitHub repository a question. Get source-backed answers.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tuanle96/mcp-github'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
