gh_mcp
Server Quality Checklist
Latest release: v0.8.1
- Disambiguation4/5
Tools are largely distinct, but the high number of similar read-only operations (e.g., multiple 'get' variants for PRs, reviews, checks) may require careful reading; however, each has a unique purpose.
Naming Consistency5/5All tools follow a consistent 'gh_' prefix with snake_case verb_noun pattern, making them predictable.
Tool Count2/561 tools is far above the typical well-scoped range; even for a comprehensive GitHub server, this is excessive and likely to confuse agents.
Completeness4/5Covers a wide range of GitHub operations including CRUD for issues, PRs, repos, and more, but lacks delete operations for labels, releases, and branches, which are notable omissions.
Average 4.2/5 across 60 of 61 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 55 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, idempotentHint: true, so safety is covered. The description adds no additional behavioral context beyond that, but does not contradict anything. It doesn't reveal much about pagination or response structure, but the project's schema and output schema likely cover some. Given annotations, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main purpose. However, it could be more structured by explicitly listing parameters or giving a sentence about usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and 0% schema description coverage, the description is too thin. It does not clarify the meaning of each parameter, nor does it indicate the capabilities like filtering or sorting. Output schema exists but not described, leaving the agent to guess specifics. Needs more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description provides the only semantic info for parameters. The description lists 'type: all, owner, member, public, private, fork.' but does not explain 'sort', 'direction', 'per_page', or 'username' beyond what their names imply. That is insufficient to guide correct use, especially with no enums or descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the purpose ('List repositories for a user or organization') but does not distinguish from the sibling tools like gh_search_repos or gh_get_repo. The type list is a hint but not sufficient to differentiate clearly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are given. It implies listing repos for a user/org, but doesn't mention when this is preferred over gh_search_repos or gh_get_repo. Context is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. However, the description adds no behavioral context beyond what annotations provide, such as error cases, authorization requirements, or output scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It is maximally concise while conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema, and annotations provide safety context, making the brief description adequate for basic use. However, the complete lack of parameter explanation and usage guidance leaves some gaps, though not critical for this straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention or elaborate on the owner and repo parameters. The agent receives no parameter semantics beyond the parameter names themselves, which is inadequate given low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific repository' uses a specific verb and resource, clearly indicating a single-repository read operation. It distinguishes itself from sibling tools like gh_list_repos by emphasizing 'specific' rather than listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No description is given for when to use this tool versus alternatives, and no exclusions or context are provided. The agent is left to infer from the tool name and siblings list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the annotations (readOnlyHint, idempotentHint). Since annotations already cover read-only and side-effect-free behavior, the description adds no extra context but does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential purpose without extraneous detail. It is perfectly sized for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits any contextual details such as edge cases, required permissions, or relationships between parameters. While an output schema exists (so return values are not required), the lack of additional context limits the agent's ability to handle unusual scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (owner, repo, number) with no descriptions. The description does not explain any of them, leaving the agent to infer their meanings. This is inadequate for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get details) and the target (a specific issue or pull request), with emphasis on 'specific' and inclusion of 'body'. This unambiguously conveys the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 gh_get_pr or gh_list_issues. It lacks context about scenarios, prerequisites, or distinguishing use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the state parameter values and default, which is mild contextual value, but it doesn't mention pagination, ordering, or repository access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief and front-loaded, only two short sentences. It avoids wordiness, though the state line is a fragment. Still, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and annotations present, the description doesn't need to detail returns. Missing per_page behavior and pagination guidance, plus the lack of sibling differentiation, leave some gaps but the tool is simple enough to be adequately described at a minimum level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions at all (0% coverage), so the description's note on state values ('open, closed, or all') adds some meaning. However, owner/repo and per_page are not explained, and their semantics are only inferred from titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List pull requests in a repository,' which is a specific verb and resource. While it doesn't explicitly distinguish itself from sibling tools like gh_list_issues or gh_get_pr, the resource and action are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as gh_get_pr for a single PR, or gh_list_issues for issues. The description provides no exclusions or context beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond what annotations provide—it simply states the operation without any additional details (e.g., return format, authentication requirements, or error conditions). It does not contradict annotations, but it also fails to add value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is front-loaded with the primary action and resource. There is no fluff or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple purpose (get details by ID) and an output schema is present, so return format is covered. The description is adequate for an agent to understand the tool's role. However, it could be slightly more complete by noting that workflow_id can be either an internal ID or a file name (as per GitHub API), which is a meaningful nuance. Still, given the simplicity and existing structured data, the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 does not mention any parameters or explain how owner, repo, and workflow_id are used. While the parameter names are self-explanatory, the description adds no additional meaning, leaving the agent to infer from the schema alone. This is insufficient given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Get details of a specific GitHub Actions workflow.' It uses a specific verb (get) and resource (details of a specific workflow), and the word 'specific' distinguishes it from siblings like gh_list_workflows and gh_get_run (which gets run details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific workflow ID and need its details, as opposed to listing workflows. However, it does not explicitly mention alternatives or exclusions, such as 'use gh_list_workflows to list all workflows.' It provides clear context but no explicit guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds minimal behavior context by noting state filtering and comma-separated label filtering, but does not discuss pagination behavior, rate limits, or other side effects beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the core purpose. Every sentence adds parameter-relevant value, and there is no filler or unnecessary repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and strong annotations, the description does not need to explain return values or safety. However, it lacks an explicit mention of pagination/per_page semantics and does not help distinguish this list operation from the multiple related list/search siblings, making the setup marginally adequate for a moderately parameterized tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description compensates for some parameters by explaining state allowed values and label format. However, per_page is left undocumented, and owner/repo are only implicitly obvious from the schema titles; overall the description only adds meaningful semantics for two of five parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List issues in a repository', which is a specific action with a clear resource and repository scope. This immediately distinguishes it from sibling tools like gh_get_issue (single issue) and gh_search_issues (searching across repos).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool versus alternatives such as gh_search_issues or gh_get_issue. The description simply lists the tool's function and a couple of filter parameters without explaining the best-fit use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context beyond the state parameter, which is more parameter semantics than behavior. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient—two sentences with no redundancy. It front-loads the core purpose and adds the parameter clarification. It could be slightly more informative without bloat, but it's appropriately sized for the information it contains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is adequate but not exhaustive. With an output schema present, return value explanation is unnecessary. However, the lack of pagination behavior and any notes on typical usage patterns makes it feel incomplete for a 4-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 explains only the 'state' parameter (open/closed/all with default), but omits 'owner', 'repo', and 'per_page'. While owner/repo are self-explanatory, 'per_page' (pagination control) is not described, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('milestones'), and the scope ('in a repository'). It effectively distinguishes from sibling tools like gh_list_issues or gh_list_labels by naming the specific resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the basic purpose but offers no explicit guidance on when to use this tool versus alternatives (e.g., gh_create_milestone). It does not mention exclusions or contrasting conditions, leaving usage context mostly implied by the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation is an 'additive write' and mentions preconditions like 'compare-only' and 'immutable readback', which aligns with the annotations (readOnlyHint=false, destructiveHint=false). It could elaborate on potential side effects, but the core write nature is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively verbose and repetitive, using phrases like 'exact' and 'compare-only precondition' multiple times. This redundancy impedes quick comprehension and violates conciseness, despite being structurally presented as a single cohesive paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main action and exclusions but lacks details about return values or error handling. While an output schema exists (so return explanation isn't mandatory), the description could benefit from clarifying expected outcomes or failure modes. It's adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters have detailed descriptions that add meaningful context beyond their names, such as 'expected_reviewer_login' being tied to a 'server-configured reviewer principal'. This enriches the schema's baseline coverage, justifying a score above the default 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it submits a formal GitHub CHANGES_REQUESTED review, which distinguishes it from sibling tools like approve or comment. The phrase 'exactly one' adds specificity, but the verbose wording could be simplified without losing meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides exclusions (cannot approve, merge, dismiss) but does not give positive guidance on when to prefer this tool over alternatives. It lacks explicit scenarios or conditions for use, relying on implicit inference from the exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description does not contradict these annotations but also adds no additional behavioral context beyond what the name and annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It covers the essential purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with rich annotations and an output schema. The description adequately states the purpose but lacks explicit usage guidance and parameter explanations, making it minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 explaining parameters. It only says 'a specific release', which hints that 'tag' identifies the release but does not clarify the roles of 'owner' and 'repo'. The parameter names are self-explanatory, but the description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific release' uses a specific verb ('get'), names the resource ('release'), and distinguishes it from sibling tools like gh_list_releases and gh_create_release_exact by emphasizing specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a specific release' implies this tool is for retrieving a single release by tag, contrasting with listing tools. However, no explicit alternatives or exclusions are mentioned, leaving usage guidance to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description is consistent with these annotations but adds no extra context about side effects, auth, or rate limits, so it meets the baseline for annotated tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple get operation. The annotations cover behavioral aspects, and the description implies the return value (details of the run). No additional context is needed for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions, but the names (repo, owner, run_id) are self-explanatory. The description does not add any further meaning to the parameters, so it does not exceed the baseline for self-explanatory names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'GitHub Actions workflow run', specifying it's for a specific run. It distinguishes from sibling tools like gh_list_runs (which lists runs) and gh_get_workflow (which gets workflow details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when-to-use guidance or contrast with alternatives. It is a simple functional statement without explicit usage conditions, similar to the mid example which scored 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only and idempotent behavior. The description adds nothing about expected behavior, errors, or side effects. It is not contradictory, but it does not enhance beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant phrasing. The example is useful without being verbose, and the structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose but lacks details on 'per_page' and does not mention authentication or rate limits. Given the schema richness (only two params), it is incomplete but not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two parameters (query and per_page) with no descriptions. The description explains 'query' via example but omits any explanation for 'per_page', including its purpose or default value. Thus it only partially covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search GitHub source code' and provides an example with qualifiers, which specifies the resource (code) and action (search). It distinguishes from sibling tools like gh_search_repos and gh_search_issues by explicit reference to 'source code'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for code search and mentions qualifiers, but it does not explicitly contrast with other search tools (e.g., repo or issue search). It lacks guidance on when to prefer this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide a clear behavioral profile: read-only, idempotent, open-world, and non-destructive. The description adds no extra behavioral detail beyond that, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short, focused sentence. It is front-loaded with the action and target, contains no redundancy, and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description is largely sufficient, especially with annotations and an output schema available. The main remaining gap is explaining per_page and how pagination behaves, but this is a minor omission for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptive coverage for parameters, so the description carries the burden of explaining parameter meaning. It mentions 'repository' broadly, helping for owner/repo, but it leaves per_page completely unexplained and adds little beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a concrete verb and resource: 'List labels in a repository.' This clearly identifies the operation and distinguishes it from other sibling tools like gh_create_label and gh_edit_label, as well as from list operations for issues or milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this tool when the agent needs to list labels for a repository. However, there is no explicit guidance on when not to use it, and alternative or complementary tools are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with these (no contradiction). However, it adds no extra behavioral context beyond what the annotations provide, such as pagination behavior or output limits, so it doesn't go above the baseline for a consistent read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of six words, with no fluff. Every word earns its place, 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with an output schema and comprehensive annotations, the description is mostly complete. The only minor gap is the lack of mention of pagination (especially relevant given the 'per_page' parameter), but this is not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description does not explain any parameters. While 'owner' and 'repo' are self-explanatory and 'per_page' is a common pagination parameter, the description adds no value beyond the schema, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List releases in a repository' uses a specific verb ('list') and resource ('releases in a repository'), clearly distinguishing it from sibling tools like 'gh_get_release' (singular). The phrasing is unambiguous and directly conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the verb 'list' but provides no explicit guidance on when to use this over alternatives, such as 'gh_get_release' for a single release or mention of pagination considerations. The use case is inferred from the tool name and context, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, non-destructive, and open-world. The description adds the allowed state filter values, but no further behavioral context such as pagination behavior or response shape is disclosed. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear main sentence followed by a helpful list of state values. Every part adds value, and there is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, rich annotations, and presence of an output schema, the description is largely adequate. It includes the key state filtering options, though it could briefly mention pagination via 'per_page' or clarify that only workflows, not runs, are listed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It adds useful semantics by listing valid values for the 'state' parameter, but provides no detail for 'owner', 'repo', or 'per_page' beyond their names and defaults. The parameters are relatively self-explanatory, but coverage is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('GitHub Actions workflows in a repository'). It distinguishes this tool from siblings like gh_get_workflow (specific workflow) and gh_list_runs (workflow runs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool through its 'List GitHub Actions workflows' phrasing, but it does not explicitly mention when to choose this over alternatives or provide exclusions. No alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnly, idempotent) are present and consistent. The description adds context about the polling behavior and the timeout, which is not covered by annotations, enhancing transparency about what the tool does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that clearly conveys the core functionality without unnecessary detail. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic behavior but omits details about the return value or what happens on timeout vs. completion. Given the tool's simplicity, this is acceptable but not complete; a mention of the returned run status would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names without descriptions, and the description does not explain any parameters. Since schema coverage is low, the description should compensate, but it does not define 'interval', 'exit_status', or 'timeout_seconds' meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Poll a GitHub Actions workflow run until completion or timeout.' It is specific and distinguishes from sibling tools like gh_get_run by indicating it waits for completion rather than fetching a single snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when waiting for a run to finish, but does not explicitly state when to use it over alternatives. It lacks guidance on when not to use it, such as when a simple status check suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write op), destructiveHint=false (non-destructive), and openWorldHint=true. The description adds important behavioral context: it is additive (creates exactly one PR), checks authorization, bounds optional inputs (labels, assignees, review requests), and reads them back when created. It also clarifies it does not approve, merge, or change other PRs, which goes beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, front-loaded with the main purpose and then additional context. It is efficient with no wasted words. Could structure the positive/negative statements slightly more explicitly, but it is well-sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (10 params, mostly described in schema, and an output schema exists), the description covers the essential addition of behavioral boundaries (exactly one PR, bounded inputs, exclusion of other mutations). Since output schema exists, return values need no elaboration. The only minor gap is lack of usage prerequisites (e.g., need for auth, base branch existence), but that is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 90%, so most parameters already have descriptions. The tool description adds a little by mentioning 'bounded head and base selectors' and that optional labels/assignees/review requests are bounded and read back, but it does not add new meaning beyond the schema's existing parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('create exactly one pull request from the specified bounded head and base selectors') and clearly distinguishes it from sibling tools by specifying it does not approve, merge, or change another pull request. This differentiates it from gh_merge_pr, gh_approve_pr, gh_set_pr_draft_state, and gh_edit_pr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when creating a PR, and explicitly states what it does not do (approve, merge, change another PR). However, it does not mention alternatives or any context for when to prefer this over other creation/edit tools. It provides no explicit when-not guidance or conditions like required permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations by explicitly stating it never checks out code or modifies GitHub, and clarifies the bounded-page behavior with base/head SHA inclusion. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and key constraints. Every sentence adds value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description adequately covers purpose, safety, and pagination. It could optionally mention ordering (e.g., chronological) but that is a minor gap, and the output schema likely provides return structure details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter (owner, repo, number, page, per_page) having a clear description. The tool description adds no additional parameter-level context, so it earns the baseline score of 3 without needing to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns one bounded page of commits for a pull request, along with base and head SHAs. This specific verb-resource combination distinguishes it from sibling tools like gh_get_commit (single commit) and gh_compare_commits (comparison).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates that the tool is read-only and returns a bounded page, which implies usage for safely inspecting PR commits without side effects. However, it does not explicitly name alternatives or specify when to use this vs. other listing tools like gh_list_pr_files or gh_get_pr_diff, so guidance is merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it supports all GitHub search qualifiers, which is useful but not deeply behavioral. It does not mention pagination, rate limits, or result format, but with strong annotations, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes a concrete example of qualifiers. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 1 required) and the presence of an output schema, the description is mostly complete. It covers the key usage pattern (search qualifiers) and distinguishes issues vs PRs. It could mention pagination or result limits, but the output schema likely covers return structure, so a 4 is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 explains the 'query' parameter implicitly by mentioning qualifiers, but does not explain 'sort', 'order', or 'per_page' beyond their schema defaults. The description adds some value for 'query' but leaves the other parameters to schema defaults, which is a gap given 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches GitHub issues and pull requests, with a specific verb ('Search') and resource ('GitHub issues and pull requests'). It distinguishes from siblings like gh_list_issues (which likely lists without search qualifiers) and gh_search_repos/gh_search_code by focusing on issues/PRs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it supports all GitHub search qualifiers and explicitly mentions 'is:pr' and 'is:issue' for filtering. However, it does not explicitly state when to use this tool versus alternatives like gh_list_issues or gh_search_repos, though the qualifier examples imply the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating non-read-only and non-destructive behavior, the description significantly enriches understanding with specific behavioral details: single attempt, authoritative readback verification, no retry on ambiguous creation, and explicit prohibition on delete/rename/transfer. This exceeds 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences that efficiently convey purpose, constraints, and verification behavior. It is front-loaded and every clause adds meaning, though the policy language is somewhat convoluted and could be simplified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description covers the essential behavioral context well: additivity, idempotency constraints, readback verification, and non-administrative scope. It does not detail exact prerequisites or error conditions, but the mention of policies/gates provides sufficient context for a write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, covering owner, repo, and description, while private and auto_init lack descriptions. The tool description indirectly references these fields through readback verification (visibility, description, initialization) but does not explain parameters directly. This meets the baseline for high schema coverage without full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'create exactly one repository' with a canonical OWNER/REPO target, making the purpose unmistakable. It also distinguishes this from sibling create tools (e.g., gh_create_issue, gh_create_pr, gh_create_release_exact) by focusing on repository creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about write policies and gates but does not explicitly state when to use this tool versus alternatives. It implies usage for repository creation but lacks clear exclusions or comparisons with sibling tools, such as when to prefer gh_get_repo for read-only checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false; description adds unique context like 'uses authoritative readback' and exclusions. While 'destructive write' repeats annotation, the authorization and readback details provide extra behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, densely packed with scope, exclusions, and auth context. Slightly verbose with terms like 'authoritative readback' but no wasted words; front-loaded with 'Destructive write' to warn.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high schema coverage and existing annotations, the description adequately covers scope, exclusions, and behavioral expectations. It doesn't discuss response format, but output schema exists, so not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions on all 10 parameters. The description adds no parameter-specific details beyond listing which fields are editable, so baseline 3 applies – no extra value but no contradiction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'edit metadata on exactly one pull request' with explicit fields (title, body, labels, assignees, base). Distinguishes from siblings like gh_create_pr, gh_merge_pr, gh_set_pr_draft_state by excluding those operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'after ordinary write authorization' and delineates what is not covered (draft-state, review, merge, branch deletion, head rewrite), implicitly guiding selection. Doesn't name specific sibling tools but context from sibling list suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'complete contents and blob metadata', clarifying the exact data scope, and reinforces safety ('never modifies GitHub'). This adds context beyond the annotations without being redundant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The most critical information ('Read-only', 'one repository file', 'never modifies GitHub') is front-loaded. Every word serves a purpose, and the structure is scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-file read tool with an output schema and full parameter coverage, the description is complete. It covers the operation, target scope, and safety profile without unnecessary detail. No gaps in context are apparent given the simple use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 applies. The description clarifies that 'branch, tag, or commit ref' are valid for the ref parameter, aligning with but not exceeding the schema's parameter descriptions. No additional semantic value beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'fetch' + resource 'complete contents and blob metadata for one repository file' + scope 'at a branch, tag, or commit ref'. This clearly differentiates from sibling tools like gh_get_commit or gh_get_repo, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates read-only usage ('Read-only', 'never modifies GitHub') but does not explicitly state when to prefer this tool over alternatives or mention exclusions. Usage is implied through the description but no direct comparison or when-not-to-use is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable context about pagination ('bounded page'), backward compatibility, and that filters are applied server-side, which affects result accuracy and performance. This goes beyond the annotations 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences deliver the core purpose and key behavioral notes without fluff. Every clause serves a purpose, and the information is front-loaded. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 13 parameters and available output schema, the description covers pagination ('bounded page'), filter behavior (server-side), and backward compatibility, which are critical for correct usage. Minor gaps remain (e.g., default ordering, potential errors), but the provided output schema and annotations fill in much of the remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 46%, and the description does not compensate by elaborating on parameter formats or relationships beyond naming 'exact workflow, head-SHA, event, actor, creation-range, and check-suite filters.' Since half the parameters lack schema descriptions and the description adds minimal parameter-specific insight, it falls short of compensating for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'one authoritative, bounded page of GitHub Actions workflow runs,' using a specific verb and resource. It distinguishes itself from siblings by emphasizing server-side filtering and backward compatibility, making its purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context—filters are sent to GitHub's REST route rather than applied locally—which guides when to use this tool (when server-side filtering is desired). However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral details: it is additive, never force-updates or overwrites, handles pre-existing branch cases safely (no-write if same SHA, leaves conflicts unchanged), and performs an exact-ref readback after mutation. This significantly extends beyond the annotations, revealing side effects and safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the key purpose and then enumerates safety behaviors. Every clause adds essential context without waste. It is concise yet comprehensive, achieving high value per word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (4 parameters, 100% schema coverage, output schema exists) and the description covers the key mutation semantics, edge cases, and verification behavior. It does not explain the return value format, but the output schema likely covers that. It could mention permission requirements, but the 'ordinary write authorization' hint is present. Generally complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with clear descriptions for each parameter (e.g., 'New branch name', 'GitHub repository name without owner prefix', 'Exact commit SHA'). The description itself does not add new parameter details beyond the schema, but the schema already provides sufficient meaning. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'create' and the resource ('exactly one new branch at an exact 40-character commit SHA'), which distinguishes it from the sibling tool 'gh_create_branch' likely used for branches at other refs. It precisely defines the operation scope and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for creating branches at a specific commit SHA, and the sibling 'gh_create_branch' suggests a general branch creation tool. It explains behavior when branch already exists or conflicts, but does not explicitly say 'use this when you need to create a branch at a specific SHA' or contrast with alternatives. Adequate context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the caching behavior and that it separates GitHub primary rate-limit evidence from local request-governor state, adding useful context beyond the annotations. However, the phrasing 'locally paced governed' is awkward and could be clearer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and well-structured with two sentences, but the phrase 'locally paced governed' is verbose and confusing, slightly detracting from overall clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for a simple diagnostic tool, including its purpose, caching, and output separation. It does not mention error cases, but given the tool's simplicity and no parameters, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so there is nothing to explain. The description does not need to add parameter details, and the schema fully covers this aspect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool is a read-only diagnostic for fetching GitHub API rate limit status, and it distinguishes itself from sibling tools by focusing specifically on rate limits and local request-governor state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains its caching behavior and that it does not create additional GitHub requests, but it does not explicitly state when to use this tool versus alternatives. The usage is implied but not directly contrasted with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare read-only and non-destructive behavior, the description adds that the artifact archive is never downloaded and that GitHub is never modified. This extra detail clarifies what side effects do not occur, providing behavior beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with front-loaded information: the verb and resource appear first, followed by key details and a safety note. Every phrase adds value; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple metadata retrieval tool with complete schema coverage and an output schema, the description is adequate. It explains the tool's purpose, scope, and safety, and does not need to elaborate on return values because the output schema exists. It could mention prerequisites (e.g., authentication) but annotations and context cover the core.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for owner, repo, and artifact_id. The description adds no new parameter-specific information beyond identifying artifact_id as the exact identifier, which the schema already conveys. The baseline of 3 is appropriate since the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns metadata for a single GitHub Actions artifact, specifying the fields (digest, expiry, workflow-run/head identity). It also notes it is read-only and does not download the archive, which distinguishes it from sibling tools like gh_read_artifact_file and gh_list_run_artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for metadata retrieval without downloading, contrasting with tools that download artifact files. It does not explicitly name alternative tools or provide when-not-to-use criteria, but the context is clear enough for an agent to infer appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds value by specifying exclusions (no watching, log download, workflow dispatch, approval, or GitHub write) and emphasizing the 'bounded' and 'structured' nature of the result, which goes beyond the raw annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences deliver the core purpose immediately ('Read-only: return...') and then enumerate exclusions without redundancy. Every word earns its place, matching the efficiency of the top-tier example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only getter with a rich output schema and complete annotations, the description sufficiently covers the necessary context. It clarifies the exact scope (one PR head revision) and the absence of side effects. A minor gap is the lack of detail about return value structure, but the presence of an output schema mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all parameters have meaningful schema descriptions), so the baseline is 3. The description does not add parameter-specific information beyond what the schema already provides, such as the fact that 'number' is a positive PR number or that max_checks is capped.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('return') and resource ('bounded structured summary of CI checks for one exact pull-request head revision'), precisely conveying the tool's function. It also differentiates from siblings by explicitly listing what it does not do (watching, log download, workflow dispatch, approval), which is useful for disambiguation in the large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for a read-only, scoped summary of CI checks, and explicitly states what it does not perform (no watching, logs, dispatch, approval, writes), which covers when-not-to-use. However, it does not name any specific alternative tool, unlike the high-scoring example that mentions 'use search_calls_extensive instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: 'Head mismatch or partial evidence prevents a definitive satisfied result' and 'bounded evidence', clarifying the tool's limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with 'Read-only', efficient and structured. Every word earns its place without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return details are covered there. The description covers the key behavioral nuance (exact head, partial evidence, definitive result) well enough for a tool of moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all four parameters (100% coverage), and the description's 'expected PR head' aligns with expected_head_sha but adds no extra meaning. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'aggregate' and specific resource: review, requested-reviewer, and unresolved-thread evidence. The qualifier 'only for an exact expected PR head' distinguishes it from generic PR review listing tools like gh_get_pr_reviews or gh_get_pr.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies that this is for 'an exact expected PR head' and warns that head mismatch or partial evidence invalidates a definitive result, implying when it's appropriate to use. It does not explicitly name alternative tools, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already classify the tool as read-only, idempotent, open-world, and non-destructive; the description adds meaningful behavioral detail beyond those hints by constraining the operation to exact references and explaining annotated tag handling ('peeled through bounded exact tag-object reads'). No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, starts with 'Read-only:', and front-loads the core behavior and concrete examples. The annotated-tag sentence is technical but earns its place by disclosing non-obvious behavior; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich parameter documentation and existing output schema, the description provides sufficient context for exact reference resolution: what qualifies, what is excluded, and how annotated tags are handled. It could name a direct alternative for non-exact discovery, but the explicit exclusions already cover the main decision boundary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents owner, repo, and ref, including the ref pattern and anti-patterns such as refs/, bare names, and matching prefixes. The top-level description reinforces valid forms but does not meaningfully deepen parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('resolve') and identifies the resource ('exact branch or tag reference path') with concrete examples. It explicitly rules out matching-reference or prefix discovery, distinguishing this exact lookup from any fuzzy sibling. The title alone is somewhat generic, but the description is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool is for one exact branch or tag reference and explicitly negates alternative behavior ('never performs matching-reference or prefix discovery'), making it evident that fuzzy or prefixed lookups belong elsewhere. It does not name a specific sibling tool for non-exact discovery, so it stops short of fully explicit alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (destructiveHint=true) by detailing the compare-and-swap mechanism, the inability to delete files or force-update, and the single retry policy. It also clarifies authorization requirements and the 'content-commit fine gate', providing rich behavioral context not available in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the 'Destructive write' warning, and no wasted words. Every clause adds meaningful constraint or behavior, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive write tool with an output schema and strong annotations, this description covers essential behavioral aspects: atomicity, conditional branch advance, auth requirements, and limitations (no delete, no force-update, no ambiguous retries). It is complete enough for an agent to invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptive text for every parameter. The description adds no new parameter-specific semantics; it only restates the conditional advance using expected_head_sha, which is already in the schema. Given high schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('create or replace'), resource ('repository files'), and precise behavior ('in one Git commit and conditionally advance exactly one existing branch only when its head matches expected_head_sha'). It clearly distinguishes from sibling write tools like gh_create_branch or gh_merge_pr by emphasizing atomicity and conditional branch advance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via its destructive-write warning and conditional advance, but it does not explicitly state when to use this tool versus alternatives (e.g., creating a PR, creating a branch). No exclusions or alternative tool names are mentioned, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: it explains the output includes 'explicit merge-base/status evidence,' 'independently bounded commit and changed-file metadata with completeness and SHA-256 fingerprints,' and mentions the '40-character' constraint. These details go well beyond the annotations, revealing the tool's thoroughness and data integrity guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with 'Read-only' and immediately states the core action. Every phrase adds value — no repetition or filler. It efficiently conveys scope, constraints, and output characteristics without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (6 params, output schema present, rich annotations), the description is sufficiently complete. It covers the action, constraints, and output nature, and the output schema handles return-value specifics. No gaps are apparent; the description complements the structured data effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — all six parameters have descriptions. The description does not add meaning beyond the schema; it mentions the exact-SHA constraint (already in schema patterns) and 'independently bounded' metadata (reflected in max_files and max_commits descriptions). Since the schema fully documents parameters, the description provides no additional parameter-level insight, matching the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'compare[s] two exact 40-character commit SHAs without branch or tag resolution' — a specific verb and resource. It distinguishes from sibling tools like gh_get_commit (single commit) and gh_get_pr_diff (PR-based) by emphasizing exact SHAs and the explicit merge-base/status evidence it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exact commit comparison and explicitly notes 'without branch or tag resolution,' which hints at when to use it over branch-based comparisons. However, it does not explicitly contrast with alternatives or state when not to use it, so guidance is only inferred rather than articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds the nuance that it returns verification/signature metadata 'without reinterpreting or upgrading that verification state,' which is a behavioral disclosure beyond annotations. This adds context about what the tool does not modify. The score reflects good transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with 'Read-only:' and then the core purpose. Every sentence contributes value: defining the scope (exact SHA), what is returned, and the verification-state behavior. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage, safe annotations, and an output schema (which handles return values), the description is complete. It specifies the exact input constraint (40-character SHA), the output components (tree, parents, author, etc.), and the verification behavior. No critical information is missing given the tool's simplicity and existing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: each parameter (owner, repo, commit_sha) has a clear description. The description adds minimal new parameter semantics—it reiterates the exact SHA requirement and mentions the commit is immutable, but the schema already states this. Since schema coverage is high, a baseline of 3 is appropriate, and the description doesn't meaningfully extend parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'return immutable identity and commit-object evidence for one exact 40-character commit SHA.' It specifies the resource (a commit by exact SHA) and what information is retrieved (tree SHA, parents, author, committer, message, verification metadata). This distinguishes it from sibling tools like gh_list_pr_commits (list) and gh_compare_commits (compare).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it's for retrieving a single commit by its exact 40-character SHA. While it doesn't explicitly mention alternatives or exclusions, the phrase 'exact 40-character commit SHA' makes it clear this is for a precise, single-commit lookup, not for lists or comparisons. The context is unambiguous, but there is no explicit 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat that. It adds valuable context beyond annotations: 'Missing policy visibility or head movement is reported as incomplete evidence and never interpreted as no requirement.' This clarifies how the tool handles uncertain data, which is not obvious from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that efficiently enumerates the aggregated components without redundancy. It front-loads the 'Read-only' nature and then lists all policy aspects. Every word earns its place, making it concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (aggregating six different aspects) and the existence of an output schema (which likely defines the full response structure), the description covers the key inputs and outputs adequately. It also includes the critical caveat about incomplete evidence handling, making it sufficiently complete for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as all parameters have descriptions. The tool description doesn't add additional parameter semantics beyond what the schema already provides. It mentions 'expected pull-request head' but that's a restatement of expected_head_sha's description. The description adds no extra nuance to parameters, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does with specific verbs and resources: 'aggregate effective branch/ruleset merge policy, current required checks, exact-head review/thread state, base freshness, mergeability, and allowed merge methods'. It distinguishes itself from sibling tools like gh_get_pr_checks or gh_get_pr by focusing on a comprehensive merge requirements aggregation for an exact head SHA.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('for one expected pull-request head') and includes a critical behavioral caveat about missing policy visibility, which helps the agent decide based on incomplete evidence. However, it doesn't explicitly name alternative tools or state 'use this instead of X', though the sibling context makes the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds significant transparency beyond that by stating it never checks out code, runs tests, requests approval, or modifies GitHub. It also discloses that the result reports truncation and byte counts, and includes a SHA-256 fingerprint, which is useful behavioral detail not captured in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundancy. The first sentence front-loads the core function and output characteristics; the second immediately clarifies the read-only nature and non-modification stance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 parameters, mostly simple), the description explains what the tool returns (bounded diff, truncation info, byte counts, fingerprint), its read-only nature, and its safety guarantees. An output schema exists, so return details are covered. The description is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds minimal parameter-specific nuance (e.g., 'bounded' hints at max_bytes behavior), but it does not elaborate on formats or defaults beyond what the schema already states, so it neither compensates nor degrades.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns a bounded unified diff or patch for the exact base and head commit SHAs of a PR, distinguishing it from siblings that list PR metadata, files, or commits. It also specifies that it is read-only and never modifies state, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by describing exactly what it returns and explicitly listing actions it never performs (checkout, tests, approval, modifications), which helps agents avoid misuse. However, it does not explicitly name alternative tools for cases where a read-only diff is not suitable, so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the specific outputs returned but does not disclose extra behaviors like authentication requirements or rate limits. It adds some value but not rich context, consistent with the lower bar set by comprehensive annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that precisely conveys the tool's purpose with zero waste. It earns its place entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema present, the description covers the essential scope completely. It does not need to explain return formats since the output schema handles that. For a zero-parameter info tool, this is fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and per the rubric, zero parameters warrant a baseline of 4. There is nothing more to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns three specific pieces of information: gh CLI version, authentication status, and active account. This specific verb+resource combination distinguishes it from sibling tools that focus on repositories, issues, PRs, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly say when to use this tool versus alternatives, but its zero-parameter nature and focus on the gh CLI environment make it obviously for checking setup. Siblings are all domain-specific, so there is no real overlap, but explicit exclusion is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint), the description adds valuable context about bounded pages, exact commit provenance, pagination completeness, and the unchanged PR head snapshot. This provides significant additional behavioral insight beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads 'Read-only' and packs in all key behaviors without redundancy. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, output schema available), the description covers core behavior, pagination semantics, and snapshot consistency. It is complete without needing to explain return values, which the output schema handles.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description itself does not elaborate on parameters, but the schema already documents each field adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a bounded page of typed pull-request reviews with specific attributes like commit provenance and pagination completeness. It uses specific verbs and resource, effectively distinguishing it from sibling PR-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving PR review data in a read-only manner, but it does not explicitly mention alternatives or when not to use this tool. No exclusions or comparisons to sibling tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context about search capabilities without contradicting these annotations, which is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of only two sentences, yet conveys the purpose and key usage examples without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and usage sufficiently for a search tool. It does not detail pagination or output format, but these are not critical given the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the input parameters beyond giving query examples. It omits clarification for sort, order, and per_page, leaving their meanings to be inferred from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches GitHub repositories, which is a specific and unambiguous action. It distinguishes from sibling tools like gh_get_repo or gh_list_repos by using the verb 'search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on using GitHub search qualifiers with examples, and even gives specific tips for excluding forks and archived repos. This is clear when-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that this is an 'additive write' (non-destructive), attempted once through a specific endpoint, and that it readback verifies via the immutable comment ID. It also communicates the lack of merge/review capability. This adds meaningful behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the primary purpose and uses each sentence to add value: action, mechanics, verification, and exclusion. There is no wasted text or repetition of schema annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for an agent to decide when and how to invoke the tool: it identifies the endpoint, notes the write authorization requirement, explains readback verification, and disambiguates from review/merge operations. It could mention expected side effects or rate limits, but given the output schema and annotations, the description is largely complete for this simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it mentions 'body' and 'Markdown comment' but the schema already describes these. It does not compensate for any coverage gaps since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Additive write' and uses a specific verb 'post' to state it creates a comment on a specified issue or pull request. It clearly defines the resource (issue/PR), the content (bounded Markdown comment), and the mechanism (issue-comments REST endpoint). It also distinguishes itself from siblings by stating 'It is not a formal pull-request review and cannot merge.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool (to comment on an issue or PR) and explicitly excludes the review/merge capability, guiding an agent away from using it for those purposes. It doesn't explicitly name alternative tools, but the exclusion is enough to differentiate it from related siblings like gh_comment_pr_review or gh_merge_pr.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds valuable behavioral details: the tool performs an authoritative semantic readback after mutation and never automatically retries ambiguous edits. It also clarifies scope (no deletion, no issue content mutation), going well beyond the annotations and providing critical safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the critical 'Destructive write' warning, and every phrase adds value. It efficiently covers the purpose, behavior, and scope without extraneous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key aspects: mutation, readback, no-retry, scope, and authorization requirements. With an output schema present, return values are handled externally. Minor gap: it does not mention consequences of partial parameter updates or rate limits, but these are not essential for this tool's completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented. The description mentions the editable fields (name, color, description) but does not add new meaning about parameter interactions, constraints, or defaults beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits exactly one existing label's name, color, or description, which is a specific verb+resource+scope. It also differentiates from siblings by explicitly noting it does not delete labels or mutate issue content, distinguishing it from label deletion and issue editing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (edit an existing label) and clarifies it does not delete labels, but it does not explicitly name alternative tools like gh_create_label. It provides context that this is for edits only and requires write authorization, but lacks explicit 'use instead of' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations present, the description adds substantial behavioral context: it is additive, caller cannot select credentials, the server verifies multiple preconditions, the write is attempted once, and an immutable review-ID readback verifies APPROVED state, actor, head, and body. It also explicitly rules out fallback comments, merges, dismissals, and ambiguous retries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds necessary behavioral or safety information. It is front-loaded with the core action and then systematically covers preconditions, credential handling, verification, and non-behaviors without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with moderate complexity, the description covers purpose, preconditions, side effects, failure semantics, actor constraints, and verification. With an output schema available and rich annotations, no significant contextual gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with clear descriptions, so the baseline applies. The description reinforces the meaning of expected_head_sha and expected_reviewer_login, but it does not add significant parameter-specific meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: submit exactly one formal GitHub APPROVED review at a supplied exact pull-request head. It is clearly distinguished from sibling tools by explicitly saying it never comments as a fallback, merges, or dismisses reviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes its use case clear by emphasizing approval at an exact head and requiring an expected reviewer login. It also implicitly excludes fallback behaviors such as commenting or merging, but it does not explicitly name alternative tools like gh_request_pr_changes or gh_comment_pr_review.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds critical behavioral details: 'Additive write' confirms non-destructiveness, 'attempted once' clarifies no internal retry, and 'immutable review-ID readback verifies actor, state, head, and body' discloses the verification mechanism. It also states limitations such as inability to approve or merge. This provides substantial transparency beyond the minimal annotation signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action. Every sentence adds value: the first defines what it does, the second specifies the use case and state limitation, the third details behavioral guarantees and exclusions. No redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (write operation with verification and constraints) and the presence of an output schema, the description covers all essential aspects: the operation, the one-time attempt, verification, and explicit non-capabilities. It is complete enough for an agent to select and invoke correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description reinforces the binding to 'exact PR head' and mentions that body is verified in readback, but adds no new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema carries full semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'submit exactly one formal GitHub COMMENTED review' for the 'supplied exact PR head'. It distinguishes itself from siblings by explicitly noting it 'cannot approve' and that 'COMMENTED is never reported as GitHub APPROVED', which differentiates it from gh_approve_pr and gh_request_pr_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'explicit same-author fallback for recording an external or Central disposition'. It also states exclusions: 'cannot select reviewer credentials, approve, merge, or retry an ambiguous mutation automatically', which implies when not to use. However, it does not explicitly name alternative tools, relying on sibling context for such inferences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explaining that it performs an authoritative readback when stable identity is available and that it never retries ambiguous mutations. It also explicitly states it does not edit, close, comment, or delete existing issues, providing full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured, with each sentence carrying relevant information about the operation, gates, readback, retry behavior, and scope. No unnecessary fluff is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides complete context about the mutation's behavior, including the readback confirmation, retry policy, and explicit scope limitations. Given that an output schema exists, the lack of return value details is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions are comprehensive for all parameters, covering owner, repo, title, body, labels, and assignees with constraints. The tool description does not add further parameter-specific meaning, so it stays at the baseline given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates exactly one issue in a target repository, which is a specific verb-resource pair. It also specifies 'additive write', distinguishing it from edit or delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement of write gate and repository policy, indicating when it's allowed, but it does not explicitly contrast with alternative tools like edit or state change. However, the 'additive write' phrasing implies usage for creation, which is fairly explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that one mutation attempt is followed by authoritative semantic readback, that it never overwrites or retries ambiguous creates, and that it does not edit issues or delete labels. This adds significant behavioral context regarding auth, scope, and post-action verification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the core purpose and then concisely add critical behavioral details. Every sentence earns its place; there is no fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool, the description covers auth, non-idempotency, exact scope, post-write readback, and what it avoids. With a full schema and output schema present, the description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds that name, color, and description are 'explicitly bounded,' which reinforces but does not extend the schema constraints. It does not add new parameter-specific semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('create exactly one new repository label') and clearly distinguishes from siblings by stating it does not edit issues or delete labels. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is additive, creates one label, and never overwrites an existing label, implying that editing should be done elsewhere. It also notes ordinary write authorization as a prerequisite. It does not explicitly name alternative tools, but the exclusions help an agent decide when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds significant context: it is a destructive write requiring ordinary authorization, performs a single mutation attempt with semantic readback, never auto-retries ambiguous mutations, and does not circumvent repository policy. This goes well beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with 'Destructive write', no redundant phrases, and every sentence adds distinct information. The structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool, the description covers authorization, scope (one issue), readback verification, retry policy, and exclusions. Output schema covers return values, so omitting them here is appropriate. The description is complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 91%, so the baseline is 3. The description briefly lists mutable field categories but does not clarify per-parameter semantics such as null handling or interaction between add/remove arrays. This adds little beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits metadata on exactly one existing issue and enumerates the mutable fields (title, body, labels, assignees, milestone). It distinguishes itself from siblings by explicitly listing what it does not do (close/reopen, post comments, delete), removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides when-to-use context ('exactly one existing issue', 'ordinary write authorization') and when-not-to-use exclusions (does not close/reopen, post comments, delete, bypass policy). However, it does not explicitly name alternative tools for these excluded actions, stopping short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool never reruns, cancels, deletes, or dispatches workflows and never requests input, which goes beyond the annotations. It also discloses bounded output with truncation metadata and fingerprinting, providing meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the read-only nature and core function, with no wasted words. Every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, meaningful annotations, and an output schema, the description sufficiently completes the picture. It conveys safety, scope, boundedness, and return characteristics without redundancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 5 parameters with full coverage, so the description adds little parameter-specific detail. The mention of 'bounded' and 'exact run attempt' aligns with the max_bytes and attempt parameters but does not explain them beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('return') and resource ('bounded failed-step log text for one exact GitHub Actions run attempt'), clearly distinguishing it from siblings like gh_get_run_logs and gh_get_job_logs. It also includes distinctive scope details such as truncation metadata and SHA-256 fingerprint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies its use case: retrieving bounded failed-step log text from a specific run attempt. It does not explicitly name alternatives or state when not to use it, but the context is clear enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds concrete context: 'one noninteractive GET request' and a clear list of prohibited actions. This goes beyond annotations, addressing what the agent can safely expect. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. No filler, every word contributes. First sentence states the core functionality, second clarifies boundaries. Highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only GET with 3 parameters and an output schema, the description fully covers the behavior. It includes all necessary constraints and emphasizes read-only nature. Given the output schema exists, no return format explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for each parameter. The description adds no new detail about parameters beyond confirming the PR number reference. Baseline of 3 is appropriate since schema handles the semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returns bounded metadata and exact base/head commit SHAs for a single pull request. The verb 'return' with specific resources ('metadata', 'SHAs') distinguishes it from siblings like gh_get_pr_diff or gh_get_pr_reviews, which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for read-only snapshot retrieval and explicitly lists what the tool cannot do (create comments, submit reviews, merge, request approval, modify state). It does not name alternative tools for specific needs (e.g., diff, reviews), but the exclusions provide guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint false, but the description adds valuable behavioral context: 'performs no review write and never mints a reviewer installation token.' It also specifies the 'exact-head' constraint and 'advisory' nature, going beyond what annotations convey about token and side-effect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the key phrase 'Read-only exact-head preflight' front-loaded. Every clause adds either functional output details or explicit non-behavior, with no filler or redundant repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description sufficiently covers the return entities (author, identities, eligibility flags) and the key constraints (read-only, no token minting, exact SHA). It explains what to expect and what not to expect, making it complete without needing to detail output schemas or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description reinforces the importance of expected_head_sha via 'exact-head preflight', but this does not add new parameter-level meaning beyond what the schema already states. Hence, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb "report" with a clear resource: pull-request review eligibility. It enumerates the exact outputs (author, ordinary GitHub identity, configured reviewer identity, eligibility of APPROVED/COMMENTED reviews), distinguishing it from sibling tools like gh_get_pr_review_state or gh_approve_pr by emphasizing it is a read-only preflight that performs no writes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as a "preflight" advisory call, implying it should be used before attempting a review write. It does not explicitly name alternative tools (e.g., 'use gh_approve_pr to approve'), but the read-only advisory nature provides strong contextual guidance, so it misses the highest bar only for lacking explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. The description adds substantial behavioral detail: stable job-ID order, never uses ZIP endpoint, supports byte cap/tail/markers, sha256 fingerprinting, and explicitly excludes mutation/dispatch operations. This goes well beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense single paragraph that front-loads the core purpose ('Read-only: stream bounded log evidence...') and every sentence adds value (method, exclusions, selection modes, fingerprinting). No wasted words—exemplary conciseness for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations cover safety, the description provides complete context: it explains the enumeration method, stable ordering, selection bounds (byte cap/tail/markers), and explicitly lists unsupported operations. It is sufficient for an agent to understand scope and behavior without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 8 parameters with descriptions (100% coverage). Description adds minimal extra parameter meaning, though it confirms markers are literal and mentions 'UTF-8 byte cap' aligning with max_bytes. Since schema already does the heavy lifting, a baseline 3 is appropriate; description doesn't significantly extend parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'streams bounded log evidence for one exact GitHub Actions workflow run attempt' by enumerating jobs and reading plaintext job-log endpoints. It explicitly differentiates from alternatives by noting the attempt is mandatory and never replaced, and it excludes operations like rerun/cancel/delete, distinguishing it from gh_get_failed_run_logs and gh_get_job_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: read-only, exact attempt, bounded output, and explicitly states what it does not do (no regex, shell, rerun, etc.). It clarifies the attempt is never silently replaced. However, it does not explicitly name alternative tools for different scenarios, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavioral traits beyond the annotations: it downloads to temporary server state, never extracts, and rejects traversal, absolute paths, duplicates, symlinks, etc. This adds substantial safety context that the annotations (readOnlyHint, idempotentHint, destructiveHint) do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the core purpose and then efficiently lists safety constraints. Every sentence adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and comprehensive parameter descriptions, the description fully covers the tool's behavior, including pagination, return of normalized paths and sizes, and the read-only nature. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter has a meaningful schema description (e.g., artifact_id as 'Exact workflow artifact identifier'). The tool description itself does not add extra parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to inspect a specific GitHub Actions artifact ZIP and return a bounded page of normalized file paths and sizes. It explicitly differentiates itself from siblings like gh_get_artifact and gh_read_artifact_file by focusing on listing file metadata without extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it is for reading artifact contents and never modifies GitHub. It does not explicitly name alternatives or state when not to use it, but the bounded page and read-only nature make it clear this is for listing file information. The sibling context provides additional cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint/idempotentHint/destructiveHint, but the description adds valuable behavioral context: the page is bounded, patches may be absent/truncated by GitHub, and it never modifies GitHub. This goes beyond the annotations and helps set expectations for response completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'Read-only' and the core function, then a caveat and pointer to the diff tool. Every sentence earns its place with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% schema parameter coverage, the description provides essential behavioral nuances (pagination bounds, patch truncation, exact SHAs) and a clear sibling alternative. It is fully sufficient for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description reinforces pagination ('bounded page') and page semantics but does not add detailed parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a bounded page of files changed by a pull request, with exact base/head SHAs. It distinguishes itself from gh_get_pr_diff by explicitly naming that sibling for the unified diff, and the read-only nature is front-loaded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use this tool vs. gh_get_pr_diff: if you need the bounded unified diff, use gh_get_pr_diff. This is clear alternative guidance and excludes the diff use case, making the tool's specific role unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only/idempotent; description reinforces with 'never downloaded' and 'never modified' and clarifies pagination bounds ('one bounded page'). This adds confidence-context for agent planning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, front-loaded with 'Read-only', zero filler. Every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing with full schema and strong annotations, this description is complete. It covers side effects, pagination, and matching semantics; output schema handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all six parameters with descriptions; description offers minimal extra parameter-level detail beyond 'bounded page' and reiteration of exactness. The schema does the heavy lifting, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies verb ('read-only return'), resource ('immutable GitHub Actions artifact metadata'), and scope ('for an exact workflow run', 'one bounded page'). Distinguishes from artifact file download and other list tools by emphasizing no download and no modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that this is a safe read operation and that name filtering is exact, but never names alternatives among the many sibling tools. An explicit pointer to e.g. gh_list_artifact_files for files or gh_get_artifact for download would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: 'one bounded page' (pagination behavior), 'exact run attempt' (scope of attempt), and explicit exclusions (logs, watching, dispatch). This enriches the agent's understanding of side effects and limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'Read-only,' immediately convey the tool's safety and scope. Every clause adds information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool with annotations covering safety and an output schema present, the description sufficiently covers key behaviors (bounded page, no logs, exact attempt, non-mutating). It does not need to explain return values because an output schema exists, and it gives the agent enough to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with detailed descriptions (e.g., 'Exact run attempt; omit for the latest attempt'), yielding 100% schema coverage. The description does not add parameter-specific meaning beyond what the schema already states, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'return one bounded page of jobs and step metadata' for a specific GitHub Actions run attempt. It identifies the resource (jobs/metadata) and scope (exact attempt), and distinguishes it from siblings like gh_list_runs, gh_watch_run, and gh_get_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-not guidance: it 'downloads no logs, performs no watching or workflow dispatch, and never modifies GitHub.' This implicitly tells the agent to use alternative tools for those concerns, but it does not explicitly name those alternatives (e.g., gh_get_run_logs, gh_watch_run), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already flag destructiveHint and readOnlyHint, the description adds significant context: 'Destructive write' frames the mutating scope, 'Ordinary write authorization and the separate PR-merge fine gate are required' reveals the fine-grained auth prerequisite, and the head-SHA match discloses the concurrency-safety condition. The explicit list of non-behaviors (no admin bypass, no branch deletion, no forced revision, no blind retry) prevents dangerous assumptions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, each carrying distinct weight: sentence one declares action + conditions, sentence two covers authorization, sentence three enumerates explicit exclusions. It front-loads the critical signal ('Destructive write'), uses a parallel structure for the negatives ('cannot... , delete... , force... , or blindly retry'), and contains zero filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-stakes destructive write operation with output schema present, the description is complete: it covers the safety condition (head SHA), the authorization model (write + fine gate), and what the tool explicitly will not do (bypass, force, retry). The schema and output schema cover parameters and return shape, so the description focuses exactly where the risk lies — the happy-path and refusal semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of parameters with descriptions, setting baseline at 3. The description adds modest value by priming expected_head_sha and method as the central safety and strategy controls — helping the agent understand which parameters matter for authorization vs. layout. However, it never names individual parameters like body, subject, owner, or repo, so the marginal semantic contribution over the schema is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'merge exactly one pull request using the explicit merge strategy only,' combining a specific verb, resource, and the key safety mechanism (head SHA match). It unambiguously differentiates this from all 61 siblings — none of which perform merges — and the constraint 'while its head matches expected_head_sha' captures the tool's unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: it names the required authorization level ('ordinary write authorization'), the special 'PR-merge fine gate,' and lists what the tool cannot do ('cannot use administrator bypass, delete the branch, force a changed revision, or blindly retry'). This effectively communicates when the tool will refuse work, giving the agent strong decision signals. It stops short of naming explicit alternative sibling tools, though the negative-capability list implies when to seek alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral details: only valid UTF-8 text/JSON is returned, content is bounded by max_bytes and a server cap, sha256 fingerprints the complete file, the ZIP is temporary and never extracted, and GitHub is never modified. This enriches the annotation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the read-only nature and then packs essential constraints (exact path, unexpired artifact, UTF-8, boundaries, hashing, ZIP handling) without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to explain return values. It covers constraints, safety, and behavior thoroughly for a read-only tool. With 100% schema coverage and rich annotations, the description is fully adequate and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions providing clarity (100% coverage), so the description does not need to add parameter-specific semantics. The description mentions max_bytes and sha256 but these are implied by the schema; the description adds no new parameter-level detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves one exact normalized file path from one exact, unexpired GitHub Actions artifact. It uses the specific verb 'retrieve' and distinguishes this from sibling tools like listing or getting artifact metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies 'one exact' path and 'unexpired' artifact, making it clear this is for precise reads, not listings. However, it does not explicitly name alternatives (e.g., gh_list_artifact_files) or state when not to use it, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond annotations: it is additive, performs readback of the created milestone, avoids automatic retries on ambiguity, and does not affect issues or existing milestones. This aligns with annotations (non-read-only, non-idempotent, non-destructive) with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action and followed by important clarifications. It is slightly verbose but each sentence conveys essential information without excessive padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations and schema descriptions, the description provides sufficient additional context about operational behavior (readback, no retries, no assignment) to fully understand the tool's scope and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions title, description, due date, and state, which cover most parameters, but does not explicitly address owner and repo (though these are standard). Bounds are referenced but not specified beyond schema constraints, adding some value without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates exactly one repository milestone with specific fields (title, description, due date, state). It also distinguishes from siblings by noting it does not assign issues or edit existing milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implicit usage context ('after ordinary write authorization', 'never retried automatically') and clarifies it does not edit or assign, but does not explicitly name alternative tools or provide a clear 'use this instead of X' directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavioral traits: it is an additive write (not destructive), it verifies target identity, optionally requires absence of tag and releases, performs exactly one governed creation request, verifies release/tag commit/latest state, and never retries ambiguous mutations. This goes beyond the annotations (which already indicate non-read-only, non-idempotent, non-destructive) by explaining the verification and single-attempt behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and every sentence adds value. It uses three sentences to cover purpose, conditions, and behavioral guarantees without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, multiple verification steps, conditional behavior), the description covers the essential context: what it does, how it handles state (absence checks), single-request guarantee, and verification steps. An output schema exists, but it's not shown here; the description is complete for selecting and invoking correctly. It could include error cases, but the verification steps imply common failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains key parameters implicitly: 'exact 40-character target commit SHA' maps to expected_target_sha, 'optionally requires the tag and every release state including drafts to be absent' covers expected_tag_absent and expected_release_absent, and 'explicit latest state' maps to make_latest. However, some parameters like draft, prerelease, body, and name are only defined in the schema, not in the description. Given 64% schema coverage, the description adds meaningful context for the central parameters but not all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'create one GitHub release using an exact 40-character target commit SHA' with specific verification and safeguards. It distinguishes from siblings by the 'exact' target and the explicit verification steps, setting it apart from generic release creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when an exact target commit SHA is required and release/tag absence must be ensured. It doesn't explicitly state alternatives or when-not-to-use, but the 'exact' qualifier and verification details provide clear context. It could be improved by naming an alternative for flexible releases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already say destructive and non-readonly, but the description goes much further: it discloses active-state verification, expected_ref_sha binding, branch/tag ambiguity rejection, existing-run rejection, bounded input enforcement, request of return_run_details, and no automatic re-dispatch. This is substantial extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the critical 'Destructive write' warning and wastes no words on filler. However, it is a dense run-on sentence with repeated policy terminology, so slightly more structured formatting could improve scannability without sacrificing the important safety caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and safety-sensitive nature, the description is exceptionally thorough: it covers the exact authorization context, validation checks, duplicate-run rejection, input bounds, and idempotency behavior. Since an output schema exists, the description does not need to enumerate return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema fully documents each parameter, the description adds meaningful relational constraints: expected_workflow_path must match workflow_id, expected_ref_sha must match ref, inputs must be bounded, and duplicate runs are rejected. This clarifies why the mandatory parameters exist together and how the tool's guarantees are achieved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names the concrete action: 'dispatch exactly one positive workflow ID' at a verified ref, with the word 'exact' repeated throughout to make the tool's specialty unmistakable. It also distinguishes this mutating dispatch tool from the many read-only workflow inspection siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this dangerous action is allowed: after authorization gates, exact-path verification, ref SHA matching, and duplicate-run rejection. It does not explicitly name alternatives or exclusions, but the sibling list contains no other workflow-dispatch tool, so the usage context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint and idempotentHint annotations by explicitly disclosing that it does not call GitHub, spawn a subprocess, request approval, or modify state. This gives the agent strong safety guarantees for a local read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences: the first states exactly what the tool returns, the second states what it avoids doing. Every clause earns its place and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter local diagnostic tool with a useful output schema and strong annotations, this description is complete. It fully conveys purpose, scope, and non-behavior with no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there are no parameter details for the description to expand on. The 0-parameter baseline of 4 applies; no additional parameter explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'return,' and identifies the resource as 'this MCP server,' then lists the exact data fields returned: deployed version, tool-schema version, transport, tool count, and write-policy status. It also explicitly labels the tool as a 'local diagnostic' that does not call GitHub, distinguishing it from the GitHub-focused gh_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is a local server diagnostic, not a GitHub API operation. It does not explicitly name an alternative sibling tool or provide when-not-to-use phrasing, but the statement 'This tool does not call GitHub' strongly implies when this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already mark destructiveHint=true and readOnlyHint=false, the description adds crucial details: 'exactly one issue' (scope), 'only when current state matches' (precondition), 'Pull requests are rejected' (limitation), 'mutation is attempted once' (retry behavior), and 'authoritative readback verifies the final state' (post-action verification). These exceed annotation coverage and provide behavioral expectations not captured elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, each adding distinct information: action+precondition, PR exclusion, reason logic, and post-verification. No filler or repetition. The opening phrase 'Destructive write' immediately signals risk, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 required params and conditional logic, but the description covers the core behavioral contract: state transition, precondition, reason constraints, single attempt, readback verification, and separation from comments. An output schema exists, so return format needn't be described. Rate limits and auth are likely common across tools and not necessary. This is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, so baseline is 3. The description adds value by mapping state_reason to new_state (closing requires completed/not_planned/duplicate; reopening requires reopened), which the schema only vaguely states as 'compatible'. It also clarifies that number refers to exactly one issue. This supplemental logic improves parameter understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'close or reopen exactly one issue' with a specific precondition (expected_state match). It distinguishes from sibling tools like gh_edit_issue (which edits fields) and gh_create_issue by focusing on state transitions. The phrase 'Pull requests are rejected' further differentiates from PR manipulation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use only when the issue's current state matches expected_state, and explicitly excludes PRs and comments ('comments remain a separate tool'). It doesn't explicitly name alternatives but implies when to use this over generic edit tools. The precondition and reason restrictions provide strong usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as destructive and non-idempotent, but the description adds critical context: it changes no unrelated metadata, is attempted once, and reads back authoritatively to verify head identity and draft state. This goes beyond the annotation flags and provides a clear safety contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler. The opening 'Destructive write' immediately sets expectations, and every clause adds meaning about scope, preconditions, and verification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—conditional mutation with 6 required parameters and a destructive action—the description covers the essential aspects: what it does, under what conditions, what it doesn't touch, and how it verifies success. The existence of an output schema means return-value details are not needed in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, so the baseline is 3. The description adds semantic value by framing expected_head_sha and expected_is_draft as 'preconditions' and new_is_draft as the 'requested state', clarifying how the parameters interact in the mutation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'transition exactly one pull request between draft and ready-for-review' with explicit conditions. It differentiates from siblings like gh_edit_pr by emphasizing the exact-head precondition and the targeted scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a conditional, precise draft-state transition is needed with preconditions on head SHA and current draft state. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for a capable agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: it is additive, never moves or deletes refs, performs an authoritative bounded readback, and never blindly retries an ambiguous mutation. This complements the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, safety model, verification behavior, and the key alternative are all covered in four sentences with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with concurrency and safety considerations, the description covers purpose, authorization, base resolution, verification, and exclusions. The presence of an output schema means return-value details are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the base parameter by explaining that branch-name bases are resolved to an exact commit and full SHAs are rejected, and it clarifies the issue linkage requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Additive write: create exactly one branch linked to the specified issue,' which names a specific verb, resource, and scope. It also explicitly distinguishes itself from the sibling gh_create_branch_from_sha by rejecting full commit SHAs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is for creating a branch linked to an issue after ordinary write authorization. It also explicitly names the alternative tool for caller-supplied immutable bases: 'use gh_create_branch_from_sha for a caller-supplied immutable base.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is fully transparent: it declares read-only behavior, idempotency (implied by 'read-only' and confirmed by annotations), non-destructive nature, and the fact that it never downloads an archive. It also mentions fingerprinting (sha256) and verification steps, giving insight into internal operations. This aligns perfectly with the annotations (readOnly, idempotent, non-destructive).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense, covering purpose, constraints, supported options, and exclusions in a compact paragraph. Each sentence adds value (e.g., 'never downloads a workflow-run log archive' clarifies side effects, 'sha256 fingerprints' adds transparency). No superfluous words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the extensive sibling tools list, this description clearly distinguishes gh_get_job_logs from related tools like gh_get_run_logs or gh_get_failed_run_logs by emphasizing exact job and attempt, read-only streaming, and no archive download. The presence of an output schema and the tool's focused scope make the description complete for selecting this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 8 parameters have detailed descriptions in the schema (100% coverage), and the tool description adds semantic context for key parameters: start_marker is explicitly 'never treated as a regex', tail_bytes returns 'final bounded UTF-8 bytes', max_bytes is 'capped by server policy', and attempt is 'exact'. This enriches the schema and clarifies parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is extremely specific: it clearly states this tool retrieves logs for a single exact GitHub Actions job and explicit attempt, is read-only, and supports bounded streaming with options like byte caps and markers. It also lists what operations it does not expose (regex, shell, rerun, cancel, delete, dispatch), leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it is read-only, streams bounded plaintext logs, never downloads a workflow-run archive, and verifies attempt membership before and after retrieval. It also clarifies that start/end markers are literal, not regex, and that max_bytes is capped by server policy, which helps the agent use it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/fvanevski/gh_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server