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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (get details) and 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource '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.

Does 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.