The GitHub Enterprise MCP Server enables programmatic interaction with GitHub and GitHub Enterprise, covering repository management, file operations, issue tracking, pull requests, code search, and CI/CD workflows.
Repository Management
Search, create, update, delete, and fork repositories
Retrieve file/directory contents
List commits on a branch
Branch & File Operations
Create branches from any source branch
Create or update a single file
Push multiple files in a single commit
Issues
List, get, create, and update issues (with labels, assignees, milestones)
Add comments to issues
Pull Requests
List, get, create (including drafts), and merge PRs (configurable merge methods)
Create reviews (approve, request changes, comment)
Get changed files, status checks, review comments, and reviews
Update a PR branch with the latest base branch changes
Search
Search repositories, code, issues/PRs, and users using GitHub's advanced search syntax
CI/CD Workflows
List workflows and workflow runs (filterable by branch/status)
Trigger workflow runs programmatically
Miscellaneous
Get license information and GitHub Enterprise statistics
Supports GitHub Personal Access Tokens with configurable endpoints for both GitHub.com and GitHub Enterprise
Enables Git operations like creating branches, pushing changes, managing commits, and preserving Git history when performing file operations through the GitHub API.
Provides comprehensive GitHub API access, enabling file and repository management, code/issues/PRs/users search, branch creation, issue tracking, pull request workflows, and commit history retrieval through the GitHub platform.
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 Enterprise MCP Server create a new issue in my-project repo titled 'Fix login 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
Related MCP server: GitHub MCP Server
This guide will help you install and configure the GitHub Enterprise MCP server in Cline, enabling you to use GitHub API functionality directly through Cline.
Node.js installed on your system
A GitHub Personal Access Token with appropriate permissions
Cline installed on your system
git clone https://github.com/yourusername/github-enterprise-mcp.git
cd github-enterprise-mcpnpm install
npm run buildThis will create a dist directory with the compiled JavaScript files.
Go to GitHub Personal Access Tokens (in GitHub Settings > Developer settings)
Click "Generate new token"
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
Copy the generated token
Open VS Code
Locate the Cline MCP settings file at:
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Add the GitHub Enterprise MCP server configuration to the mcpServers object:
{
"mcpServers": {
"github-enterprise": {
"command": "node",
"args": [
"/absolute/path/to/github-enterprise-mcp/dist/index.js"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-personal-access-token",
"GITHUB_API_URL": "https://api.github.com" // For GitHub.com
// For GitHub Enterprise, use your instance URL, e.g., "https://github.yourdomain.com/api/v3"
},
"disabled": false,
"autoApprove": []
}
}
}Replace /absolute/path/to/github-enterprise-mcp/dist/index.js with the absolute path to the built index.js file.
Locate the Claude Desktop configuration file at:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Add the GitHub Enterprise MCP server configuration to the mcpServers object:
{
"mcpServers": {
"github-enterprise": {
"command": "node",
"args": [
"/absolute/path/to/github-enterprise-mcp/dist/index.js"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-personal-access-token",
"GITHUB_API_URL": "https://api.github.com" // For GitHub.com
// For GitHub Enterprise, use your instance URL, e.g., "https://github.yourdomain.com/api/v3"
},
"disabled": false,
"autoApprove": []
}
}
}After configuring the MCP settings, restart Cline (VS Code or Claude Desktop) to apply the changes.
To verify that the GitHub Enterprise MCP server is properly installed and configured, you can ask Cline to use one of the GitHub tools:
Can you search for repositories with the keyword "react" using the GitHub Enterprise MCP server?Cline should be able to use the search_repositories tool to search for repositories with the keyword "react".
For an interactive installation experience, copy and paste the following text into Cline, and it will guide you through the installation process:
I want you to help me install the GitHub Enterprise MCP server. Here's what I need you to do:
1. First, explain what the GitHub Enterprise MCP server is and what capabilities it will give you.
2. Guide me through the installation process:
- Help me clone the repository (if I haven't already)
- Help me install dependencies and build the project
- Guide me through creating a GitHub Personal Access Token if I don't have one
- Help me configure the MCP settings in either VS Code or Claude Desktop
- Verify the installation is working
3. Show me some examples of how I can use the GitHub Enterprise MCP server once it's installed.
Please start by explaining what the GitHub Enterprise MCP server is and what it will allow you to do for me.After installation, you can ask Cline to perform GitHub operations directly, such as:
"Create a new repository called 'my-project'"
"Search for repositories related to machine learning"
"Create a pull request from my feature branch to main"
"Get the contents of the README.md file in repository X"
"List open issues in my repository"
If you encounter issues with the GitHub Enterprise MCP server:
Check that the path to the index.js file is correct in your MCP settings
Verify that your GitHub Personal Access Token has the necessary permissions
Ensure that the GitHub API URL is correct for your GitHub instance
Check the logs for any error messages
You can specify a GitHub API version by adding the GITHUB_API_VERSION environment variable:
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-personal-access-token",
"GITHUB_API_URL": "https://api.github.com",
"GITHUB_API_VERSION": "2022-11-28"
}For GitHub Enterprise instances that use different authentication methods, you may need to provide additional configuration. Refer to the Octokit documentation for more information.
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
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
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
Copy the generated token
To use this with Claude Desktop, add the following to your claude_desktop_config.json:
{
"mcpServers": {
"github": {
"command": "node",
"args": [
"/path/to/github-enterprise-mcp/dist/index.js"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}# Install dependencies
npm install
# Build the project
npm run build
# Start the server
npm startThis 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 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool adds a comment but doesn't mention whether this requires authentication, what permissions are needed, if it's idempotent, or what happens on success/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 directly states the tool's purpose with zero 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 4 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain parameter meanings, behavioral traits, or what to expect upon completion. The description should provide more context given the lack of structured documentation.
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 have descriptions in the schema. The tool description doesn't explain what 'owner', 'repo', 'issue_number', or 'body' mean or how they should be formatted. It adds no parameter semantics beyond what's implied by the tool name.
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 specific verb+resource. However, it doesn't differentiate from potential sibling tools like 'update-issue' which might also modify issues, though the distinction is somewhat implied by the specific action of commenting.
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-issue' for other issue modifications, nor does it mention prerequisites such as requiring an existing issue. It simply states what the tool does 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 new branch in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| branch | Yes | Name for the new branch | |
| from_branch | No | Source branch to create from (defaults to the repository's default branch) | |
| owner | Yes | Repository owner | |
| 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 the action ('Create') but doesn't mention permissions required, whether it's idempotent, error conditions, or what happens if the branch already exists. 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 any wasted words. 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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or behavioral nuances. Given the complexity of GitHub operations, more context about permissions, conflicts, or typical workflows would be 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 4 parameters thoroughly. The description adds no additional parameter information 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 branch in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'create-repository' or 'create-pull-request' beyond the obvious resource difference, missing explicit distinction.
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, when not to use it, or how it relates to sibling tools like 'update-pull-request-branch' or 'fork-repository', leaving usage context entirely implicit.
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 the full burden of behavioral disclosure. It states the tool creates an issue but lacks details on permissions needed, rate limits, whether it's idempotent, 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 that gets straight to the point with no wasted words. It's appropriately sized for a basic tool definition and front-loaded with the core 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 the tool's complexity (7 parameters, mutation operation), lack of annotations, 0% schema coverage, and no output schema, the description is insufficient. It doesn't explain parameters, behavioral traits, or return values, leaving the agent with inadequate information to use the 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?
The schema description coverage is 0%, meaning none of the 7 parameters are documented in the schema. The description adds no parameter information beyond implying 'owner', 'repo', and 'title' might be involved (from required fields), but it doesn't explain what these parameters mean, their formats, or optional fields like 'body' or 'labels'. This fails to compensate for the schema gap.
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 resource ('in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update-issue' or 'list-issues' beyond the basic verb, 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 like 'update-issue' or 'list-issues', nor does it mention prerequisites such as repository access or authentication requirements. It only states what the tool does, not when or why to choose it.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('create or update') but fails to describe critical traits: whether it requires authentication, what happens on conflicts (e.g., if SHA is omitted for updates), if it's idempotent, rate limits, or error conditions. This leaves significant gaps in understanding the tool's behavior beyond the basic action.
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 or redundancy. It is appropriately sized and front-loaded, making it easy to parse quickly. Every word earns its place, adhering to best practices for conciseness.
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 in GitHub (with no annotations and no output schema), the description is incomplete. It lacks details on authentication needs, error handling, return values, and how it differs from sibling tools like 'push-files'. For a tool that performs writes in a collaborative environment, this leaves too much unspecified 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 already documents all parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't clarify the interaction between 'sha' and 'content' or explain default behaviors). This meets the baseline for high schema coverage but doesn't enhance parameter understanding.
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 ('create or update') and resource ('a single file in a GitHub repository'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'push-files' (which might handle multiple files) or 'get-file-contents' (which is read-only), leaving some room for improvement in sibling distinction.
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 (e.g., authentication, repository permissions), when to choose this over 'push-files' for batch operations, or any constraints (e.g., file size limits). This lack of context makes it challenging for an agent to select this tool appropriately among siblings.
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 the full burden of behavioral disclosure. It states the action ('create') which implies a write operation, but doesn't disclose any behavioral traits like authentication requirements, rate limits, what happens on failure, whether the PR is automatically opened or requires further steps, or how conflicts are handled. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how the tool 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 states the core purpose without unnecessary words. It's perfectly front-loaded with the essential information. There's zero waste or redundancy in the phrasing.
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 8 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what happens after creation (e.g., PR status, review process), error conditions, authentication needs, or GitHub-specific behaviors. The agent lacks crucial context about how this tool interacts with the GitHub ecosystem and what to expect from its execution.
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). It doesn't explain relationships between parameters (e.g., that 'head' and 'base' must be different branches), provide examples, or clarify edge cases. With complete schema documentation, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't 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 action ('create') and resource ('pull request in a GitHub repository'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'create-issue' or 'create-branch' by specifying the type of resource being created. However, it doesn't explicitly differentiate from 'merge-pull-request' or 'update-pull-request-branch' in terms of when to create versus modify existing pull requests.
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 existing branches), when not to use it (e.g., if changes aren't ready for review), or how it differs from similar tools like 'create-issue' for non-code changes. The agent must 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.
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. It states the action ('Create a review') but doesn't mention permissions required, whether this is a write operation, rate limits, or what happens when invoked (e.g., notifications sent, review status changes). 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 with zero wasted words. It's appropriately sized and front-loaded, immediately conveying the core purpose 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?
For a mutation tool with 7 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain behavioral aspects like permissions, side effects, or return values, leaving significant gaps in understanding how 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?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 where 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 a review') and target ('on a pull request'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'add-issue-comment' or 'get-pull-request-reviews', which could create confusion about when to use this specific tool versus 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 'add-issue-comment' or 'get-pull-request-reviews'. The description doesn't mention prerequisites, appropriate contexts, or exclusions, 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.
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 the full burden of behavioral disclosure. While 'Create' implies a write operation, it doesn't specify important behavioral aspects like whether this requires specific GitHub permissions, rate limits, what happens on duplicate names, or the response format. 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 that gets straight to the point with zero wasted words. It's appropriately sized for a straightforward creation 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?
For a repository creation tool with no annotations and no output schema, the description is insufficient. It doesn't address important contextual aspects like authentication requirements, error conditions (e.g., duplicate names), what the tool returns, or how it differs from similar tools. The 100% schema coverage helps with parameters but doesn't compensate for the broader contextual 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?
The description doesn't mention any parameters, but the input schema has 100% description coverage with clear documentation for all 4 parameters. The baseline score of 3 is appropriate since the schema does the heavy lifting of parameter documentation, though the description adds no additional semantic context beyond the basic purpose.
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 this from sibling tools like 'fork-repository' or 'update-repository' which also involve repository creation or modification, 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 like 'fork-repository' (for creating from an existing repo) or 'update-repository' (for modifying existing ones). It also doesn't mention prerequisites such as authentication requirements or account permissions needed to create repositories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Confirmation for deletion (must be true) | |
| owner | Yes | Repository owner | |
| 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. 'Delete' implies a destructive, irreversible mutation, but the description doesn't explicitly warn about permanence, data loss, or authentication requirements. It lacks critical context like whether deletion is immediate, if forks are affected, or what happens to issues/pull requests, which is essential for a high-risk 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. Every word earns its place by conveying essential information without redundancy or fluff.
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 high-risk nature of deletion, no annotations, and no output schema, the description is incomplete. It fails to address critical behavioral aspects like irreversibility, permissions, or error conditions. For a destructive tool with 3 parameters, this minimal description leaves significant gaps that could lead to misuse 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%, so the input schema fully documents the three parameters (owner, repo, confirm) with clear descriptions. The description adds no additional parameter semantics beyond what's in the schema, such as explaining the purpose of the 'confirm' boolean as a safety measure. This meets the baseline for high schema coverage but doesn't enhance understanding.
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 GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'update-repository' or 'create-repository' beyond the obvious verb difference, missing an opportunity to clarify its specific destructive role in the repository lifecycle.
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., ownership permissions), irreversible consequences, or when deletion is appropriate compared to archiving or other repository management tools in the sibling list. This leaves the agent with insufficient context for safe decision-making.
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?
No annotations are provided, so the description carries full burden. It states the action ('Fork') but doesn't disclose behavioral traits like whether this requires authentication, rate limits, what happens to existing forks, or the response format. 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 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 with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or important behavioral context like authentication needs. Given the complexity of forking (which involves permissions and network effects), more guidance 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 three parameters. The description adds minimal value beyond the schema by implying the 'organization' parameter is optional and defaults to personal account, but doesn't provide additional syntax or format details. 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 ('Fork') and resource ('a GitHub repository'), with specific destination options ('to your account or specified organization'). It distinguishes from siblings like 'create-repository' (new repo) and 'delete-repository' (removal).
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 when needing to copy a repository, but doesn't explicitly state when to use this versus alternatives like 'create-repository' for a new repo or clarify prerequisites. It mentions the default personal account behavior, which provides some context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get GitHub Enterprise statistics (only available for GitHub Enterprise)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 only mentions availability for GitHub Enterprise, missing critical details such as whether this is a read-only operation, authentication requirements, rate limits, or the format of returned statistics. This leaves significant gaps for an agent to understand how to invoke it safely and 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 and key constraint. It is front-loaded with the main action and resource, with no wasted words or redundant information, making it highly concise and well-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 the complexity of enterprise statistics (which could include various metrics), no annotations, and no output schema, the description is incomplete. It fails to explain what statistics are returned, their format, or any behavioral traits like data freshness or access controls, leaving the agent with insufficient context for 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?
The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline of 4 is applied as it meets expectations for a parameterless tool.
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 ('GitHub Enterprise statistics'), making the purpose understandable. It distinguishes itself from siblings by focusing on enterprise-level statistics rather than repository, issue, or pull request operations. However, it doesn't specify what specific statistics are included, 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 implicit guidance by stating 'only available for GitHub Enterprise,' indicating it should be used in enterprise contexts. However, it lacks explicit when-to-use scenarios, comparisons to alternatives (like general GitHub stats tools if they existed), or prerequisites beyond the enterprise requirement.
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. It states the action but does not cover critical aspects like authentication needs, rate limits, error handling, or whether it returns raw content, metadata, or both. This leaves significant gaps for an agent to understand operational traits.
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 unnecessary words. It is 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?
Given the lack of annotations and output schema, the description is incomplete. It does not explain return values (e.g., file content vs. directory listing), error conditions, or behavioral constraints like GitHub API limits. For a tool with 4 parameters and no structured output info, 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?
The input schema has 100% description coverage, clearly documenting all four parameters (owner, repo, path, branch). The description adds no additional semantic details beyond what the schema provides, such as path format examples or branch defaults. 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 ('a file or directory from a GitHub repository'), making the purpose understandable. However, it does not explicitly differentiate from sibling tools like 'search-code' or 'get-pull-request-files', which might also retrieve content in different contexts, so it misses full sibling distinction.
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, such as 'search-code' for broader searches or 'get-pull-request-files' for PR-specific content. It lacks explicit context, prerequisites, or exclusions, offering minimal usage direction.
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?
No annotations are provided, so the description carries full burden. It mentions 'Get details' but doesn't disclose behavioral traits such as authentication requirements, rate limits, error handling (e.g., for non-existent issues), or response format. This is a significant gap for a tool with zero annotation coverage, though it correctly indicates a read operation without contradiction.
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.
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), the description is incomplete. It lacks details on authentication, error cases, return values, and parameter semantics, which are critical for an AI agent to invoke the tool correctly. The conciseness comes at the cost of necessary 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 0%, so the description must compensate. It mentions 'specific issue in a GitHub repository,' which hints at parameters like issue number and repository identifiers, but doesn't explain the meaning of 'owner,' 'repo,' or 'issue_number' (e.g., owner as GitHub username/organization, repo as repository name, issue_number as numeric ID). This adds minimal value beyond the bare 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 verb ('Get details') and resource ('specific issue in a GitHub repository'), making the purpose understandable. It distinguishes from siblings like 'list-issues' (which retrieves multiple issues) and 'update-issue' (which modifies an issue). However, it doesn't specify what details are included (e.g., title, body, comments, labels), 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 implies usage when details of a specific issue are needed, but doesn't explicitly state when to use it versus alternatives like 'list-issues' for multiple issues or 'search-issues' for filtered searches. No guidance on prerequisites (e.g., authentication, repository access) or exclusions is provided, leaving usage context partially ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about commonly used licenses on GitHub
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 'get' operation (implying read-only), but doesn't disclose behavioral traits like rate limits, authentication needs, data freshness, or what 'commonly used' means. For a 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 gets straight to the point with no wasted words. It's appropriately sized for a simple tool and front-loads the core purpose 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 the tool's simplicity (0 parameters, no output schema), the description is minimally adequate but could be more complete. It doesn't explain what information is returned about licenses or how 'commonly used' is defined. With no annotations and no output schema, users need more context about what to expect from this 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?
The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description doesn't need to compensate for any parameter gaps, and it appropriately doesn't mention parameters. Baseline for 0 parameters is 4.
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 tool's purpose with a specific verb ('Get information') and resource ('commonly used licenses on GitHub'), making it immediately understandable. It doesn't explicitly differentiate from siblings, but since no other tool mentions licenses, the purpose is sufficiently distinct in 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for license queries, or what specific information is returned. With many sibling tools for GitHub operations, users need more direction on when license info is appropriate.
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 for behavioral disclosure. It states this is a read operation ('Get'), which implies non-destructive behavior, but doesn't mention authentication requirements, rate limits, error conditions, or what 'details' specifically includes (e.g., metadata, diff, comments). This leaves significant gaps for a tool that likely interacts with a complex 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 immediately conveys the core purpose without any wasted words. It's appropriately sized for a straightforward read operation and is 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 tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'details' includes (e.g., whether it returns metadata, diff, or linked resources), which is critical given the many sibling tools that fetch specific PR components. The agent would be left guessing about the response structure and scope.
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 information beyond what's already in the schema, which has 100% coverage with clear descriptions for all three required parameters. The baseline score of 3 reflects that the schema adequately documents parameters, so the description doesn't need to compensate, but also doesn't add value like explaining 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 ('Get details') and resource ('a specific pull request'), making the purpose immediately understandable. However, it doesn't differentiate this tool from similar siblings like 'get-pull-request-comments' or 'get-pull-request-files', which also retrieve pull request information but focus on specific 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. With siblings like 'list-pull-requests' (for multiple PRs) and 'get-pull-request-status' (for status only), there's no indication that this tool returns comprehensive details for a single PR, leaving the agent to guess based on naming alone.
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 the full burden of behavioral disclosure. It states a read operation ('Get'), implying it's likely safe and non-destructive, but doesn't confirm this or detail other traits like rate limits, authentication needs, pagination, or the format of returned comments. For a 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 that directly states the tool's function without any fluff or redundancy. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place, achieving optimal conciseness.
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 (fetching data with three parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the return values look like (e.g., comment structure, pagination), behavioral constraints, or error conditions. For a read operation with no structured output documentation, more context 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?
The input schema has 100% description coverage, clearly documenting all three required parameters (owner, repo, pull_number). The description adds no additional parameter semantics beyond implying the tool fetches comments for a specific pull request, which is already evident from the schema. This meets the baseline score when schema coverage is high.
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 purpose immediately understandable. It distinguishes from siblings like 'get-pull-request' or 'get-pull-request-reviews' by specifying comments rather than general PR data or reviews. However, it doesn't explicitly contrast with these siblings in the text, preventing 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 related tools like 'get-pull-request-reviews' for review-level comments or 'add-issue-comment' for adding comments, nor does it specify prerequisites such as needing an existing pull request. This leaves the agent to infer usage from context 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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states a read operation ('Get'), implying it's non-destructive, but doesn't mention authentication requirements, rate limits, pagination, error conditions, or what the returned file list includes (e.g., patch details, status). For a 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 that directly states the tool's purpose with zero wasted words. It's appropriately sized for a straightforward read operation 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 the tool's moderate complexity (3 required parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, output format, and usage context. Without annotations or output schema, the agent must infer these aspects, making the description incomplete for confident tool selection and 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?
The input schema has 100% description coverage, thoroughly documenting all three parameters (owner, repo, pull_number). The description adds no additional parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting without compensating for any gaps.
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 the resource 'list of files changed in a pull request', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get-pull-request' or 'get-pull-request-comments', which would require more specific scope definition 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 'get-pull-request' (which might include file info) or 'list-commits' (which could show file changes). There's no mention of prerequisites, context, or exclusions, leaving usage decisions entirely to the agent's inference.
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?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It implies a read-only operation ('Get'), but doesn't detail authentication needs, rate limits, pagination, error conditions, or the structure of returned reviews. For a tool with zero annotation coverage, this is a significant gap in transparency about how it behaves in practice.
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 front-loads the core purpose ('Get the reviews') and efficiently specifies the target ('on a pull request'). Every word earns its place, making it highly concise and well-structured for quick comprehension.
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 pull request review tool with no annotations and no output schema, the description is incomplete. It doesn't explain what a 'review' entails, the return format, or behavioral aspects like permissions or limitations. While the schema covers inputs, the overall context for effective tool use is lacking, especially for a read operation that likely returns structured data.
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 fully documented in the schema itself. The description adds no additional meaning beyond implying that these parameters identify a specific pull request to fetch reviews from. This meets the baseline score of 3, as the schema handles the heavy lifting without needing compensation from 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 ('Get') and resource ('reviews on a pull request'), making the tool's purpose immediately understandable. It distinguishes itself from siblings like 'get-pull-request-comments' by specifying reviews rather than comments. However, it doesn't explicitly mention what constitutes a 'review' (e.g., approval, changes requested) or differentiate from 'create-pull-request-review', which slightly limits specificity.
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 an existing pull request), compare to related tools like 'get-pull-request' or 'get-pull-request-comments', or specify scenarios where reviews are relevant (e.g., code review workflows). This leaves the agent to infer usage from context alone.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get') but doesn't clarify if this is a read-only operation, what permissions are required, how it handles missing data, or the format of the returned status (e.g., aggregated state vs. detailed checks). This leaves significant gaps for an agent to understand the tool's 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 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 tool's moderate complexity (fetching status checks), lack of annotations, and no output schema, the description is minimally adequate but incomplete. It specifies what is retrieved but omits critical context like authentication needs, error handling, or output format, which could hinder an agent's ability 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?
The input schema has 100% description coverage, clearly documenting all three required parameters (owner, repo, pull_number). The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints, so it 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') 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 focus on different aspects of pull requests.
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. The description doesn't mention prerequisites (e.g., needing repository access) or compare it to related tools like 'get-pull-request' (which might include status info) or 'list-workflow-runs' (which could provide check details).
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 but offers minimal behavioral insight. It mentions 'Get list' which implies a read-only operation, but doesn't disclose pagination behavior (despite 'page' and 'perPage' parameters), rate limits, authentication requirements, or what the output looks like. This leaves significant gaps for an agent to understand how the tool 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 front-loads the core purpose without unnecessary words. Every part ('Get list', 'commits', 'branch', 'GitHub repository') contributes directly to understanding the tool's function.
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, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain parameter meanings, behavioral traits like pagination or authentication, or what the return value contains. The agent would struggle to use this tool correctly 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 description must compensate but adds no parameter information. It mentions 'branch' which loosely relates to the 'sha' parameter (often used for branch names), but doesn't explain what 'owner', 'repo', 'page', or 'perPage' mean or how they interact. This leaves 5 parameters largely undocumented.
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 resource ('commits of a branch in a GitHub repository'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'list-issues' or 'list-pull-requests', but the specificity of 'commits' provides natural distinction.
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, rate limits, or how it compares to similar listing tools (e.g., for pagination or filtering). The agent must infer usage from the name and parameters alone.
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 issues
| 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 but offers minimal insight. It mentions filtering but doesn't describe pagination behavior (implied by 'page' and 'per_page' parameters), rate limits, authentication needs, or what the output looks like. For a tool with 9 parameters and no output schema, 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 with zero wasted words. It's front-loaded with the core action ('List and filter'), making it easy to scan and understand 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 (9 parameters, no annotations, no output schema), the description is severely incomplete. It doesn't explain parameter usage, output format, pagination, or behavioral constraints, leaving the agent with significant gaps in understanding how to invoke the 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 0%, so the description must compensate but fails to do so. It mentions filtering generically but doesn't explain any of the 9 parameters (e.g., what 'since' expects, how 'labels' work, or the meaning of 'state' enums). This leaves critical semantics undocumented.
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 tool's purpose with a specific verb ('List and filter') and resource ('repository issues'), making it immediately understandable. It distinguishes from siblings like 'get-issue' (single issue) and 'search-issues' (broader search), though it doesn't explicitly name these 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?
The description provides no guidance on when to use this tool versus alternatives like 'search-issues' or 'get-issue'. It mentions filtering but doesn't clarify scope, prerequisites, or exclusions, 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.
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 but reveals almost nothing about behavior. It doesn't disclose whether this is a read-only operation, what authentication is needed, whether it supports pagination (implied by parameters but not stated), rate limits, or what the return format looks like. 'List and filter' implies reading, but lacks crucial operational details.
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 phrase that front-loads the core functionality. Every word earns its place with zero waste or redundancy, making it immediately scannable and understandable.
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 9 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the relationship between parameters, what the output contains, pagination behavior, or error conditions. The agent would need to infer too much from the parameter schema alone.
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 all parameters are documented in the schema. The description adds no additional parameter semantics beyond the basic 'filter' hint, which is already covered by the schema's detailed parameter descriptions. 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 'List and filter repository pull requests' clearly states the verb ('list and filter') and resource ('repository pull requests'), making the purpose immediately understandable. It distinguishes itself from siblings like 'get-pull-request' (singular) and 'list-issues', but doesn't explicitly differentiate from other list/filter tools like 'list-issues' 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 when to choose this over 'search-issues' (which might include PRs) or 'get-pull-request' (for a specific PR), nor does it specify prerequisites like authentication or repository access requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workflow runs in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | Filter by branch name | |
| owner | Yes | Repository owner | |
| page | No | Page number | |
| perPage | No | Items per page | |
| repo | Yes | Repository name | |
| status | No | Filter by run status | |
| workflow_id | No | Workflow ID or file 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 basic action but doesn't mention pagination behavior (implied by page/perPage parameters), rate limits, authentication requirements, or what the output format looks like. For a list operation with 7 parameters, 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 states the core purpose without unnecessary words. It's appropriately sized for a straightforward list operation and gets directly to the point with zero wasted verbiage.
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 7 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain the filtering capabilities (branch, status, workflow_id), pagination behavior, or what information is returned. The agent would need to rely heavily on the schema and trial-and-error 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?
The schema description coverage is 100%, meaning all parameters are documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema. According to the rules, when schema coverage is high (>80%), the baseline score is 3 even with no param info 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 ('List') and resource ('workflow runs in a GitHub repository'), making the purpose immediately understandable. However, it doesn't distinguish this tool from similar sibling tools like 'list-workflows' or 'list-issues', which would require more specific differentiation to earn 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. There's no mention of when this tool is appropriate, what prerequisites might exist, or how it differs from related tools like 'list-workflows' or 'trigger-workflow'. 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.
List workflows in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| page | No | Page number | |
| perPage | No | Items per page | |
| 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. 'List workflows' implies a read-only operation, but it doesn't specify whether this requires authentication, what format the output takes, whether results are paginated (though schema suggests pagination), or any rate limits. For a tool with 4 parameters and no 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, clear sentence with zero wasted words. It's front-loaded with the essential information and doesn't include any unnecessary elaboration. This is an excellent example of conciseness for a straightforward listing operation.
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 tools, the description is insufficiently complete. It doesn't explain what a 'workflow' means in GitHub context, what information is returned, how results are structured, or how this differs from related workflow operations. For a tool in a rich GitHub API context with many alternatives, more contextual information would be 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 all parameters are documented in the schema itself. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'GitHub repository' which aligns with the owner/repo parameters, but provides no additional context about parameter usage, relationships, or constraints. Baseline 3 is appropriate when schema does the documentation 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 'List workflows in a GitHub repository' clearly states the action (list) and resource (workflows in a GitHub repository), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'list-workflow-runs' or 'trigger-workflow', but the verb+resource combination is specific enough 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. With siblings like 'list-workflow-runs' and 'trigger-workflow' available, there's no indication of when this listing function is appropriate versus those other workflow-related operations. The description only states what it does, not when it should be selected.
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 the full burden of behavioral disclosure. 'Merge a pull request' implies a write operation that modifies repository state, but it doesn't disclose critical traits like required permissions (e.g., write access), whether it's destructive (merging typically is irreversible), rate limits, or what happens on success/failure (e.g., branch deletion). This leaves significant gaps for safe agent invocation.
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 action without fluff. It's appropriately front-loaded and earns its place by conveying the core purpose, though it could benefit from additional 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?
Given the complexity of a merge operation (a write action with potential side effects), no annotations, and no output schema, the description is incomplete. It lacks information on behavioral traits, usage context, and expected outcomes, making it inadequate for safe and effective agent use without relying heavily on 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 100%, so the schema already documents all 6 parameters thoroughly. The description adds no parameter-specific information beyond the tool name implying 'pull request' as a resource, which is redundant with the schema. Baseline 3 is appropriate as the schema does the heavy lifting, but no extra value is added.
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 action (merge) and resource (pull request), but it's vague about scope and doesn't differentiate from siblings like 'update-pull-request-branch' which might also involve merging operations. It provides basic purpose but lacks specificity about what merging entails in this 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 on when to use this tool versus alternatives like 'update-pull-request-branch' or other pull request management tools. The description doesn't mention prerequisites (e.g., pull request must be in a mergeable state) or exclusions, leaving usage context entirely implicit.
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 lacks critical behavioral details. It states the action ('push') but doesn't disclose whether this requires write permissions, how conflicts are handled, if it overwrites existing files, rate limits, or what happens on failure. The 'single commit' detail is useful but 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?
Single sentence, front-loaded with the core action, zero wasted words. Every element ('push multiple files', 'GitHub repository', 'single commit') earns its place by specifying scope and constraint efficiently.
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 behavioral context (permissions, side effects, error handling), usage guidance versus siblings, and output expectations. The 100% schema coverage helps parameters but doesn't compensate for missing operational 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 parameters are fully documented in the schema. The description adds no additional parameter semantics beyond implying 'files' are processed together in one commit. This meets the baseline of 3 when schema does the heavy lifting, but doesn't compensate for any gaps (none exist here).
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 ('push multiple files') and target ('to a GitHub repository') with the specific constraint 'in a single commit'. It distinguishes from siblings like 'create-or-update-file' (single file) and 'list-commits' (read-only), but doesn't explicitly differentiate from all write operations like 'create-branch' or 'merge-pull-request'.
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-or-update-file' (which handles single files) or other repository modification tools. The description implies batch file operations but doesn't specify prerequisites (e.g., authentication, repository access) or exclusions (e.g., not for deleting files).
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 but offers minimal behavioral insight. It mentions 'search' but doesn't disclose rate limits, authentication needs, pagination behavior, or what the search encompasses (e.g., file types, repositories). This is inadequate for a tool with 4 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 wasted words. It's 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 4 parameters with 0% schema coverage, no annotations, and no output schema, the description is severely incomplete. It doesn't explain search syntax, result format, limitations, or error handling, leaving critical gaps for effective tool 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 0%, so the description must compensate but doesn't. It doesn't explain what 'q' (the required query parameter) should contain, how 'order' applies to results, or the purpose of 'page' and 'per_page'. The description adds no meaning beyond the bare 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 ('Search for code') and target ('across GitHub repositories'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'search-issues' or 'search-repositories' beyond the 'code' focus, so it's not fully distinguished 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?
The description provides no guidance on when to use this tool versus alternatives like 'search-issues' or 'search-repositories'. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on 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 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 mentions 'search' but doesn't describe key behaviors like pagination handling (implied by 'page' and 'per_page' parameters), rate limits, authentication requirements, or the format of search results. For a search tool with 5 parameters and no annotation coverage, this leaves significant gaps in understanding how the tool operates.
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 ('Search for issues and pull requests'), making it easy to parse. However, it could be more structured by including brief usage notes, but as-is, it avoids redundancy and waste.
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 (5 parameters, no output schema, and no annotations), the description is incomplete. It doesn't explain search behavior, result formatting, error handling, or how parameters interact (e.g., 'q' with 'sort'). For a search tool that likely returns paginated results, more context is needed to guide effective use, especially without annotations to fill in 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 0%, so the description must compensate for undocumented parameters. It only mentions 'issues and pull requests' as search targets, which loosely relates to the 'q' parameter but doesn't explain its syntax (e.g., GitHub search query format) or the purpose of other parameters like 'order', 'sort', 'page', and 'per_page'. The description adds minimal value beyond the schema, failing to clarify parameter usage effectively.
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 tool's purpose as 'Search for issues and pull requests across GitHub repositories', which includes a specific verb ('Search') and resources ('issues and pull requests'). It distinguishes itself from siblings like 'list-issues' by indicating it searches across repositories rather than listing within a specific one. However, it doesn't explicitly differentiate from 'search-code' or 'search-repositories' in terms of search 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 like 'list-issues', 'search-code', or 'get-issue'. It doesn't mention prerequisites, such as needing authentication or repository access, or specify use cases like cross-repository searches versus single-repository queries. Without such context, an agent might struggle to choose between this and sibling tools.
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?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Search for GitHub repositories' implies a read-only operation but doesn't mention authentication requirements, rate limits, pagination behavior beyond what's in the schema, or what the output format looks like. For a search tool with no 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 states the core purpose without unnecessary words. It's appropriately sized for a search 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 search tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the search results contain, how they're structured, or any behavioral aspects like authentication needs or rate limits. The 100% schema coverage helps with parameters, but overall context for proper tool usage 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 three parameters thoroughly. The description adds no additional parameter information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does all the parameter documentation 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 ('Search for') and resource ('GitHub repositories'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'search-code', 'search-issues', or 'search-users', which all search GitHub but target 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. With multiple search tools available (search-code, search-issues, search-users), there's no indication that this is specifically for repository searches versus other GitHub entities. No context about prerequisites or limitations is mentioned.
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. It only states the basic purpose without mentioning authentication requirements, rate limits, pagination behavior (implied by parameters but not explained), or what the search returns. For a search tool with 5 parameters, 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 extremely concise with just 4 words, front-loading the essential purpose without any wasted words. While it's under-specified, it's not verbose or poorly 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?
For a search tool with 5 parameters (one required), 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain what the search returns, how to use the parameters, or any behavioral context. The agent would struggle to use this tool effectively without additional 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?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The tool description doesn't mention any parameters at all, failing to compensate for the complete lack of schema documentation. Parameters like 'q' (required search query), 'sort', 'order', 'page', and 'per_page' are entirely undocumented 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 'Search for users on GitHub' clearly states the action (search) and resource (users on GitHub), but it's vague about scope and lacks differentiation from sibling tools like search-code, search-issues, and search-repositories. It doesn't specify what aspects of users are searchable or how this differs from other search tools.
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. The description doesn't mention prerequisites, limitations, or how it compares to other search tools in the sibling list. An agent would need 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.
Trigger a workflow run in a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | No | Workflow inputs | |
| owner | Yes | Repository owner | |
| ref | Yes | Git reference (branch, tag, SHA) | |
| repo | Yes | Repository name | |
| workflow_id | Yes | Workflow ID or file 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 ('trigger') but doesn't explain what happens after triggering (e.g., runs asynchronously, may fail, requires permissions, rate limits, or what the response looks like). This leaves 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, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it highly efficient and 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 insufficient. It doesn't cover behavioral aspects like error handling, permissions, or response format, leaving the agent with incomplete context for safe and 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 already documents all parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced 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 ('trigger') and resource ('workflow run in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list-workflow-runs' or 'list-workflows', which are related but distinct 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., needing repository access), when not to use it, or how it differs from similar tools like manually starting workflows in the UI or using other automation methods.
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 full burden for behavioral disclosure. It states this is an update operation but doesn't mention permissions required, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with 9 parameters, 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 basic tool description 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 complex mutation tool with 9 parameters, 0% schema coverage, no annotations, and no output schema, the description is severely incomplete. It doesn't address behavioral aspects, parameter meanings, usage context, or expected outcomes, leaving the agent with insufficient information to use the 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 0%, so the description must compensate but adds no parameter information beyond what's implied by 'update an existing issue.' It doesn't explain what parameters like 'assignees', 'milestone', or 'state' do, their formats, or which fields are required versus optional. This leaves most parameters semantically unclear.
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 ('existing issue in a GitHub repository'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'update-pull-request-branch' or 'update-repository' beyond the issue focus, 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., needing an existing issue), contrast with 'create-issue' for new issues, or specify scenarios where this is appropriate over other update tools in the sibling list.
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 but lacks critical behavioral details. It doesn't disclose whether this operation requires specific permissions, is reversible, affects other branches, or has rate limits. 'Update' implies mutation, but the safety profile and side effects are undocumented.
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 scope appropriately, making it easy to parse 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It misses behavioral context (permissions, side effects), usage guidance, and output details. Given the complexity of updating a pull request branch, more information is needed for safe and 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 parameters are fully documented in the schema. The description adds no additional meaning about parameters beyond implying 'pull_number' identifies the target. Baseline 3 is appropriate as the schema handles 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 ('pull request branch') with specific scope ('with the latest changes from the base branch'). It distinguishes from siblings like 'merge-pull-request' by focusing on branch synchronization rather than final integration, though it doesn't explicitly name 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?
The description provides no guidance on when to use this tool versus alternatives like 'merge-pull-request' or 'create-branch', nor does it mention prerequisites (e.g., branch conflicts, permissions) or typical workflows. It only states what the tool does, 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.
Update an existing GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | Archive/unarchive repository | |
| default_branch | No | Change default branch | |
| description | No | New description | |
| has_issues | No | Enable/disable issues | |
| has_projects | No | Enable/disable projects | |
| has_wiki | No | Enable/disable wiki | |
| owner | Yes | Repository owner | |
| private | No | Change privacy setting | |
| 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. While 'Update' implies a mutation operation, the description doesn't specify what permissions are required, whether changes are reversible, what happens to unspecified fields, or any rate limits. For a mutation tool with 9 parameters and 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 core purpose without any wasted words. It's appropriately sized for a tool with a clear primary function and doesn't bury important information in unnecessary verbiage.
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 insufficiently complete. It doesn't address authentication requirements, error conditions, what the tool returns, or behavioral constraints. The agent would need to guess about many important aspects of using 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?
The schema description coverage is 100%, with all 9 parameters clearly documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema. According to the scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info 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 ('Update') and target resource ('an existing GitHub repository'), making the purpose immediately understandable. It distinguishes this from creation tools like 'create-repository' by specifying 'existing', but doesn't explicitly differentiate from other update tools like 'update-issue' or 'update-pull-request-branch' 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 (like authentication needs), when to choose this over other repository modification tools, or any constraints on usage. The agent must 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.
Every tool has a clearly distinct purpose targeting specific GitHub resources and actions. There is no overlap or ambiguity—tools like 'get-pull-request-comments' and 'get-pull-request-reviews' are clearly differentiated, and operations like 'create-issue' vs 'update-issue' are well-separated.
All tools follow a consistent verb_noun pattern with hyphens (e.g., 'create-branch', 'list-issues', 'get-file-contents'). The naming is predictable and uniform across all 33 tools, making them easily readable and parsable.
With 33 tools, the count is borderline high for a typical MCP server scope, which often ranges from 3-15 tools. While GitHub Enterprise is a broad domain, this many tools might feel heavy and could overwhelm agents, though it's not extreme.
The toolset provides comprehensive CRUD and lifecycle coverage for GitHub operations, including repositories, issues, pull requests, files, workflows, and searches. There are no obvious gaps—core workflows are fully supported with no dead ends.
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
Dive into the world of open-source with the GitHub Repo Explorer! Utilize the powerful GitHub
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lessinthought/github-enterprice-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
