GitHub API 的 MCP 服务器，支持文件操作、存储库管理、搜索功能等。
自动创建分支：创建/更新文件或推送更改时，如果分支不存在，则会自动创建分支
全面的错误处理：针对常见问题的清晰错误消息
Git 历史记录保存：操作无需强制推送即可维护正确的 Git 历史记录
批量操作：支持单文件和多文件操作
高级搜索：支持搜索代码、问题/PR 和用户
Related MCP server: GitHub MCP Server
本指南将帮助您在 Cline 中安装和配置 GitHub Enterprise MCP 服务器，使您能够直接通过 Cline 使用 GitHub API 功能。
您的系统上安装了 Node.js
具有适当权限的 GitHub 个人访问令牌
您的系统上安装了 Cline
git clone https://github.com/yourusername/github-enterprise-mcp.git
cd github-enterprise-mcpnpm install
npm run build这将创建一个包含已编译 JavaScript 文件的dist目录。
转到GitHub 个人访问令牌（在 GitHub 设置 > 开发人员设置中）
点击“生成新令牌”
选择您希望此令牌可以访问的存储库（公共、全部或选择）
创建具有repo范围的令牌（“完全控制私有存储库”）
或者，如果仅使用公共存储库，则仅选择public_repo范围
复制生成的token
打开 VS Code
找到 Cline MCP 设置文件：
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
将 GitHub Enterprise MCP 服务器配置添加到mcpServers对象：
{
"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": []
}
}
}将/absolute/path/to/github-enterprise-mcp/dist/index.js替换为构建的 index.js 文件的绝对路径。
找到 Claude Desktop 配置文件：
Windows： %APPDATA%\Claude\claude_desktop_config.json
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json
将 GitHub Enterprise MCP 服务器配置添加到mcpServers对象：
{
"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": []
}
}
}配置 MCP 设置后，重新启动 Cline（VS Code 或 Claude Desktop）以应用更改。
要验证 GitHub Enterprise MCP 服务器是否正确安装和配置，您可以要求 Cline 使用以下 GitHub 工具之一：
Can you search for repositories with the keyword "react" using the GitHub Enterprise MCP server?Cline 应该能够使用search_repositories工具来搜索带有关键字“react”的存储库。
为了获得交互式安装体验，请将以下文本复制并粘贴到 Cline 中，它将指导您完成安装过程：
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.安装完成后，你可以让Cline直接执行GitHub操作，例如：
“创建一个名为‘my-project’的新存储库”
“搜索与机器学习相关的存储库”
“从我的功能分支创建到主分支的拉取请求”
“获取存储库 X 中的 README.md 文件的内容”
“列出我的存储库中的未解决问题”
如果您遇到 GitHub Enterprise MCP 服务器问题：
检查 MCP 设置中 index.js 文件的路径是否正确
验证您的 GitHub 个人访问令牌是否具有必要的权限
确保 GitHub API URL 对于您的 GitHub 实例来说是正确的
检查日志中是否有任何错误消息
您可以通过添加GITHUB_API_VERSION环境变量来指定 GitHub API 版本：
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-personal-access-token",
"GITHUB_API_URL": "https://api.github.com",
"GITHUB_API_VERSION": "2022-11-28"
}对于使用不同身份验证方法的 GitHub Enterprise 实例，您可能需要提供其他配置。有关更多信息，请参阅Octokit 文档。
create_or_update_file
在存储库中创建或更新单个文件
输入：
owner （字符串）：存储库所有者（用户名或组织）
repo （字符串）：存储库名称
path （字符串）：创建/更新文件的路径
content （字符串）：文件的内容
message （字符串）：提交消息
branch （字符串）：创建/更新文件的分支
sha （可选字符串）：被替换文件的 SHA（用于更新）
返回：文件内容和提交详细信息
push_files
在一次提交中推送多个文件
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
branch （字符串）：要推送到的分支
files （数组）：要推送的文件，每个文件都有path和content
message （字符串）：提交消息
返回：更新的分支参考
search_repositories
搜索 GitHub 存储库
输入：
query （字符串）：搜索查询
page （可选数字）：分页的页码
perPage （可选数字）：每页结果数（最多 100 条）
返回：存储库搜索结果
create_repository
创建一个新的 GitHub 存储库
输入：
name （字符串）：存储库名称
description （可选字符串）：存储库描述
private （可选布尔值）：repo 是否应为私有
autoInit （可选布尔值）：使用 README 初始化
返回：创建的存储库详细信息
get_file_contents
获取文件或目录的内容
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
path （字符串）：文件/目录的路径
branch （可选字符串）：从中获取内容的分支
返回：文件/目录内容
create_issue
创建新问题
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
title （字符串）：问题标题
body （可选字符串）：问题描述
assignees （可选字符串[]）：要分配的用户名
labels （可选字符串[]）：要添加的标签
milestone （可选数字）：里程碑编号
返回：创建问题详情
create_pull_request
创建新的拉取请求
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
title （字符串）：PR 标题
body （可选字符串）：PR 描述
head （字符串）：包含更改的分支
base （字符串）：要合并到的分支
draft （可选布尔值）：创建为 PR 草稿
maintainer_can_modify （可选布尔值）：允许维护者编辑
返回：创建的拉取请求详细信息
fork_repository
派生一个存储库
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
organization （可选字符串）：要分叉的组织
返回：分叉存储库详细信息
create_branch
创建新分支
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
branch （字符串）：新分支的名称
from_branch （可选字符串）：源分支（默认为 repo default）
返回：创建的分支引用
list_issues
列出并过滤存储库问题
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
state （可选字符串）：按状态过滤（'打开'，'关闭'，'全部'）
labels （可选字符串[]）：按标签过滤
sort （可选字符串）：按（'创建'，'更新'，'评论'）排序
direction （可选字符串）：排序方向（'asc'，'desc'）
since （可选字符串）：按日期过滤（ISO 8601 时间戳）
page （可选数字）：页码
per_page （可选数字）：每页结果数
返回：问题详细信息数组
update_issue
更新现有问题
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
issue_number （数字）：要更新的问题编号
title （可选字符串）：新标题
body （可选字符串）：新的描述
state （可选字符串）：新状态（“打开”或“关闭”）
labels （可选字符串[]）：新标签
assignees （可选字符串[]）：新受让人
milestone （可选数字）：新的里程碑编号
返回：更新的问题详情
add_issue_comment
向问题添加评论
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
issue_number （数字）：要评论的问题编号
body （字符串）：评论文本
返回：创建的评论详情
search_code
在 GitHub 存储库中搜索代码
输入：
q （字符串）：使用 GitHub 代码搜索语法的搜索查询
sort （可选字符串）：排序字段（仅限“索引”）
order （可选字符串）：排序顺序（'asc' 或 'desc'）
per_page （可选数字）：每页结果数（最多 100 条）
page （可选数字）：页码
返回：带有存储库上下文的代码搜索结果
search_issues
搜索问题和拉取请求
输入：
q （字符串）：使用 GitHub 问题搜索语法的搜索查询
sort （可选字符串）：排序字段（评论、反应、创建等）
order （可选字符串）：排序顺序（'asc' 或 'desc'）
per_page （可选数字）：每页结果数（最多 100 条）
page （可选数字）：页码
返回：问题和拉取请求搜索结果
search_users
搜索 GitHub 用户
输入：
q （字符串）：使用 GitHub 用户搜索语法的搜索查询
sort （可选字符串）：排序字段（关注者、存储库、加入）
order （可选字符串）：排序顺序（'asc' 或 'desc'）
per_page （可选数字）：每页结果数（最多 100 条）
page （可选数字）：页码
返回：用户搜索结果
list_commits
获取存储库中分支的提交
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
page （可选字符串）：页码
per_page （可选字符串）：每页记录数
sha （可选字符串）：分支名称
返回：提交列表
get_issue
获取存储库中问题的内容
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
issue_number （数字）：要检索的问题编号
返回：Github Issue 对象和详细信息
get_pull_request
获取特定拉取请求的详细信息
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
返回：拉取请求详细信息，包括差异和审核状态
list_pull_requests
列出并过滤存储库拉取请求
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
state （可选字符串）：按状态过滤（'打开'，'关闭'，'全部'）
head （可选字符串）：按主管用户/组织和分支进行过滤
base （可选字符串）：按基本分支过滤
sort （可选字符串）：按（'创建'，'更新'，'受欢迎程度'，'长期运行'）排序
direction （可选字符串）：排序方向（'asc'，'desc'）
per_page （可选数字）：每页结果数（最多 100 条）
page （可选数字）：页码
返回：拉取请求详细信息数组
create_pull_request_review
对拉取请求创建评论
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
body （字符串）：评论文本
event （字符串）：审查操作（'APPROVE'，'REQUEST_CHANGES'，'COMMENT'）
commit_id （可选字符串）：提交审核的 SHA
comments （可选数组）：特定于行的注释，每行包含：
path （字符串）：文件路径
position （数字）：差异中的行位置
body （字符串）：评论文本
返回：创建评论详情
merge_pull_request
合并拉取请求
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
commit_title （可选字符串）：合并提交的标题
commit_message （可选字符串）：合并提交的额外详细信息
merge_method （可选字符串）：合并方法（'merge'，'squash'，'rebase'）
返回：合并结果详情
get_pull_request_files
获取拉取请求中更改的文件列表
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
返回：包含补丁和状态详细信息的已更改文件数组
get_pull_request_status
获取拉取请求所有状态检查的综合状态
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
返回：综合状态检查结果和个人检查详情
update_pull_request_branch
使用基础分支的最新更改来更新拉取请求分支（相当于 GitHub 的“更新分支”按钮）
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
expected_head_sha （可选字符串）：拉取请求的 HEAD ref 的预期 SHA
返回：分支更新时的成功消息
get_pull_request_comments
获取拉取请求的审核意见
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
返回：拉取请求审核评论数组，其中包含评论文本、作者和差异中的位置等详细信息
get_pull_request_reviews
获取拉取请求的评论
输入：
owner （字符串）：存储库所有者
repo （字符串）：存储库名称
pull_number （数字）：拉取请求编号
返回：拉取请求评审数组，其中包含评审状态（APPROVED、CHANGES_REQUESTED 等）、评审人和评审主体等详细信息
language:javascript ：按编程语言搜索
repo:owner/name ：在特定存储库中搜索
path:app/src ：在特定路径中搜索
extension:js ：按文件扩展名搜索
例如： q: "import express" language:typescript path:src/
is:issue或is:pr ：按类型过滤
is:open或is:closed ：按状态过滤
label:bug ：按标签搜索
author:username ：按作者搜索
例如： q: "memory leak" is:issue is:open label:bug
type:user或type:org ：按帐户类型过滤
followers:>1000 ：按关注者过滤
location:London ：按地点搜索
例如： q: "fullstack developer" location:London followers:>100
有关详细的搜索语法，请参阅GitHub 的搜索文档。
转到个人访问令牌（在 GitHub 设置 > 开发人员设置中）
选择您希望此令牌可以访问的存储库（公共、全部或选择）
创建具有repo范围的令牌（“完全控制私有存储库”）
或者，如果仅使用公共存储库，则仅选择public_repo范围
复制生成的token
要将其与 Claude Desktop 一起使用，请将以下内容添加到您的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 start此 MCP 服务器采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add-issue-commentcreate-branchcreate-issuecreate-or-update-filecreate-pull-requestcreate-pull-request-reviewcreate-repositorydelete-repositoryfork-repositoryget-enterprise-statsget-file-contentsget-issueget-license-infoget-pull-requestget-pull-request-commentsget-pull-request-filesget-pull-request-reviewsget-pull-request-statuslist-commitslist-issueslist-pull-requestslist-workflow-runslist-workflowsmerge-pull-requestpush-filessearch-codesearch-issuessearch-repositoriessearch-userstrigger-workflowupdate-issueupdate-pull-request-branchupdate-repositoryScored across 33 tools
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.
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
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
