Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well. It discloses the card UI with one button per option, explains that the user's selection appears as an 'I selected:' message, and warns the agent not to continue until that message appears.

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?

Every sentence earns its place: the core purpose is front-loaded, the usage guidance is direct, and the behavioral example and blocking warning are necessary for correct invocation. It is detailed but not padded.

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 fully equips an agent to call the tool correctly: what it does, when to use it, what the user sees, how the response arrives, and what to do afterward. The reference to github_get_skill('interactive-ui') provides a path for deeper workflow context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-specific meaning beyond the schema, though the example prompt and option behavior are consistent with 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 states a specific verb and resource: 'Present the user with a set of options to choose from.' It is clearly distinguished from the GitHub sibling tools by framing this as an interactive user-decision tool, not a repository operation.

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?

It explicitly states when to call the tool ('when you need the user to make a decision between discrete alternatives') and gives an alternative to avoid ('don't ask the user to type their choice in chat'). It also adds the critical after-call instruction to stop and wait for the user's response.

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 it is a non-readonly, open-world, non-idempotent, non-destructive write, and the description adds the important extra context of GitHub's server-side rejection rules for lines and paths outside the diff. It also explains the SHA anchoring behavior, though it does not say what happens on retry (e.g. whether a duplicate comment is created), which matters given idempotentHint=false.

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?

Front-loaded with the core action, then constraints, then workflow pointer; almost every sentence carries information. The trailing 'See #517.' is an opaque issue reference that adds little for an agent and could be dropped.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with an output schema and partial param documentation, the description covers the hard constraints an agent would otherwise get wrong (hunk containment, side semantics, SHA pinning) plus a skill pointer for conventions. Only duplicate/retry behavior and error responses are left unaddressed.

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 only 40% schema coverage across 10 params, the description usefully compensates: it clarifies that a deleted line exists only on LEFT, that `line` must fall in a diff hunk, that the path must appear in the diff, and that `head_sha` from github_get_pr_content maps to expected_head_sha. repo_owner/repo_name/pr_number/comment_body remain self-evident, so remaining gaps are minor.

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?

States a specific verb and resource ('Adds an inline review comment to a line, or to a range of lines, in a file within a PR'), which cleanly separates it from github_add_pr_comments and github_reply_to_review_comment. An agent knows immediately this is the line-anchored review comment tool.

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?

Gives concrete preconditions rather than just context: the line must be inside a diff hunk, the path must be in the diff, deleted lines need side LEFT, and head_sha should come from github_get_pr_content as expected_head_sha. It does not name the alternatives (e.g. github_add_pr_comments for non-inline comments, github_reply_to_review_comment for threads), so routing is only partly covered.

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 convey that this is a non-read-only, non-idempotent, non-destructive action. The description adds a workflow hint but no additional behavioral detail such as permissions, side effects, or rate limits, so it provides little value 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 short and front-loaded, with the main action in the first sentence and a useful workflow pointer in the second. It could be considered slightly too terse, but every sentence earns its place and there is no 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?

For a simple tool with annotations and an output schema, this is minimally viable. However, it lacks parameter descriptions and does not clarify whether this adds a top-level comment versus an inline comment, which is relevant given the sibling tool github_add_inline_pr_comment.

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 explain any parameter semantics. It does not mention that 'comment' is the body text, how repo_owner/repo_name/pr_number are used, or any format expectations, leaving the parameters entirely self-explanatory by name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description states a clear action and resource: 'Adds a comment to a specific pull request.' It is specific enough to identify the operation, but it does not explicitly distinguish this from the sibling github_add_inline_pr_comment, which is a closely related tool.

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 'Workflow and conventions: github_get_skill("pr-review")' line implies this tool should be used as part of the pr-review workflow, giving some contextual guidance. However, it does not explicitly state when to prefer this over alternatives like github_add_inline_pr_comment or github_reply_to_review_comment.

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 annotations already mark the operation as idempotent, but the description adds concrete detail: a retry returns the existing card and neither adds nor overwrites anything. This goes beyond the annotation's bare flag. It does not cover permissions or side effects, but the mutation/safety profile is sufficiently disclosed.

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 short and front-loaded, with the core action stated first and the idempotency behavior immediately after. The awkward typo 'One the board already holds' and the somewhat clipped second sentence reduce polish, but there is no wasted 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?

The reference to github_get_skill('project-boards') and the presence of an output schema compensate for some missing detail. However, for a tool with five required parameters and very low schema coverage, an agent still lacks essential param semantics needed to construct a correct invocation without external lookup.

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 only 20%, and the tool description does not compensate for the undocumented parameters. It does not explain the distinction between project_owner and repo_owner, what project_number refers to, or how the five required parameters relate. The only semantic help lies in the schema's issue_number description and the phrase 'issue or pull request.'

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 ('Puts') and names the exact resource: an issue or pull request onto a project board. This clearly separates it from siblings like github_remove_from_project, github_set_project_field, or github_list_project_items. The idempotency note further clarifies the operation's 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 gives clear context for the operation but does not explicitly state when to choose it over alternatives or when not to use it. The pointer to github_get_skill('project-boards') implies the agent should fetch workflow conventions, which is helpful but indirect. The idempotency note usefully signals that retrying is safe.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds real context beyond that: 'Neither can be undone' and 'GitHub decides what the token may remove', which tells the agent the outcome depends on token scope rather than the tool. It does not cover error behavior or rate limits, which keeps it from a 5.

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 irreversibility warning and the token-scope caveat are front-loaded and earn their place. 'See #543' is a dangling reference with no meaning to an agent, and appending the skill pointer as a trailing 'Workflow and conventions' line is slightly wasteful but still useful.

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?

An output schema exists and annotations carry the destructive/non-idempotent profile, so the description only needs to cover intent and risk, which it does. Minor gaps are the relationship between the path and graphql parameters and what failure looks like when the token lacks permission.

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 every parameter already carries a description, and the baseline is 3. The description adds the framing that there are two modes (path-DELETE vs GraphQL mutation), which helps the agent pick between the path/graphql/variables parameters, but it does not clarify mutual exclusivity or defaults.

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?

States a specific verb and resource: a raw DELETE to any path under api.github.com, or a GraphQL mutation that removes something. The phrase 'for a removal no other tool makes' implicitly separates it from dedicated siblings like github_delete_branch, github_delete_release, and github_delete_tag, though it never names them.

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?

'for a removal no other tool makes' gives a clear selection rule against the dedicated delete tools, and 'Workflow and conventions: github_get_skill("api-requests")' points to required setup knowledge. It stops short of explicit when-not guidance, such as warning that branch/release/tag deletion should go to the specialized 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: reads are governed by the token's scopes and permission failures surface the missing scope name. It says nothing about rate limiting or pagination of list endpoints, which would have pushed it higher.

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 core capability and the sibling exclusion are front-loaded in the first sentence, with the skill pointer last. 'See #543' is opaque to an agent and is the one piece that does not earn its place, but the remaining text is tight.

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?

An output schema exists, so return shapes need no explanation, and the annotations carry the safety profile. For a zero-required-parameter passthrough tool, the description covers purpose, fallback positioning, auth behavior, and where to find conventions; nothing essential to correct invocation is missing.

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 path, params, graphql, variables, and max_bytes are already documented in the schema, including the mutation refusal and byte cap. The description adds no syntax, path-format, or parameter-interaction detail (e.g., that path and graphql are mutually exclusive), so 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?

States a specific verb and resource ('Sends a GET to any path under api.github.com') and the GraphQL variant in the same breath. The clause 'for an endpoint no other tool covers' explicitly separates it from the many specific siblings like github_api_write, github_api_delete, and the typed getters.

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?

Gives a clear selection rule: use this only for endpoints not covered by another tool, which implies the higher-level siblings are preferred. It lacks an explicit pointer to github_search_api_routes for discovering routes, and no when-not conditions are spelled out beyond the fallback rule.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds real context beyond that: 'GitHub decides what the token may change' tells the agent authorization is delegated to the token, and the DELETE clause explains why the destructive hint is false despite this being a write tool. It does not cover rate limits or failure modes, so it is strong but not exhaustive.

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 short paragraphs, front-loaded with the capability and then the routing rule; nearly every clause earns its place. The only weak element is the bare 'See #543' reference, which conveys nothing to an agent that cannot resolve the issue tracker.

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?

An output schema and full annotations exist, so the description need not explain return values. For a generic open-world write endpoint it supplies the safety boundary, the auth model and the workflow pointer, which are the pieces an agent is most likely to get wrong; only error/rate-limit expectations are absent.

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 83%, so the schema already documents path, body, method, max_bytes and the GraphQL fields. The description adds no syntax, format or constraint detail for any parameter, leaving it at the baseline appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description names the exact verbs accepted (POST, PATCH, PUT), the resource (any path under api.github.com), and the GraphQL mutation variant, then explicitly distinguishes itself from github_api_delete. An agent can identify what this tool is for without opening the schema.

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?

It states the selection rule twice over: 'for a change no other tool makes' steers the agent toward dedicated siblings first, and 'A DELETE, and a mutation that deletes or removes something, belong to github_api_delete' gives the exact exclusion boundary with the reason. It also points to github_get_skill('api-requests') for conventions.

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 (which only declare it is a non-readonly, non-idempotent, non-destructive write), the description discloses that GitHub signs the commit, that the signed mutation takes a single parent, and that merge commits are therefore unsigned. The tree-base rule ('starts from the second parent's, so files carries every file the branch changes as it should read after the merge') is genuinely non-obvious behavioral context. It stops short of stating failure modes such as non-fast-forward rejections or required permissions.

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 core behavior is front-loaded in the first sentence and the merge caveat follows logically. The trailing 'See #547' is an unanchored issue reference that adds no usable meaning to an agent and is the main piece of dead weight.

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 7-parameter mutation tool with an output schema (so return values need no explanation), the description covers the operation, the delete semantics, signing behavior, and merge-tree semantics. An agent has what it needs to construct a correct call for both the normal and merge 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?

Schema coverage is 71%, and the description adds real meaning for the trickiest parameter: 'parents' is explained as the head the files were read at plus the commit to merge, and the consequence for the 'files' contents under merge is spelled out. repo_owner, repo_name and message get no added meaning, but those are largely self-evident or already documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The opening sentence gives a specific verb and resource ('Commits text files to a branch') plus the exact semantics of the files map, including null-means-delete. It also carves out a boundary against the sibling github_create_empty_commit by explaining that this tool writes file content while that one creates an empty commit.

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?

It states the conditions that select the merge path ('A second parent makes a merge commit through the Git Database API') and points the agent at github_get_skill('pr-management') for workflow conventions. It does not explicitly say when to prefer this over direct Git Database API writes via github_api_write, which keeps it short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (which only indicate a non-read-only, non-idempotent, non-destructive write), the description discloses critical behavioral details: re-runs keep first-run privileges, Dependabot has a read-only token, Dependabot stops rebasing unless the message includes [dependabot skip], and GitHub signs the commit. These are high-value operational insights an agent would not get from structured fields.

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 core purpose is front-loaded in the first sentence, and the subsequent details about Dependabot and signed commits are valuable. The references to #490 and #534 and the workflow pointer are slightly extraneous but not distracting; the description remains efficiently 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?

The tool has an output schema, so return values need not be explained. Annotations cover the safety profile, and the description adds the necessary operational caveats around Dependabot and CI triggering. Together with the schema, an agent has enough information to invoke this 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 description coverage is 71%, so the schema already documents most parameters. The description adds context about the default message's [dependabot skip] behavior, but it does not explain branch/pr_number interplay, expected_head_sha, or allow_default_branch beyond what the schema already provides. Baseline 3 is appropriate when the schema carries most of the parameter semantics.

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: 'Pushes a commit that changes no file, so CI starts a new run.' It distinguishes itself from file-changing commit tools like github_commit_files by emphasizing 'changes no file', and it explains the CI trigger rationale. An agent can identify the exact operation without opening the schema.

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 a clear context for use: triggering CI without modifying files, with additional Dependabot caveats. It does not explicitly name alternatives or when not to use this tool versus github_commit_files or github_update_pr_branch, but the purpose itself makes the primary use case evident.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds meaningful behavioral context: the 'mcp' label is appended only on create and never re-added by update tools, and the label set is replaced on update. This is a subtle side-effect disclosure that goes beyond the annotations. It doesn't mention rate limits or auth, but the label behavior is the key non-obvious trait.

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 compact and front-loaded with the core action. The label behavior warning is placed first because it's the most important non-obvious detail, and the workflow pointer is a single sentence. It earns its place without bloat.

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 values are covered. The description covers the main behavioral quirk (mcp label handling) and points to a skill for workflow conventions. It doesn't explain prerequisites like repo existence or permissions, but the openWorldHint and the skill pointer mitigate that. For a create tool with 7 params, this is reasonably 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 43%, so the schema documents labels, mcp_label, and milestone. The description adds the crucial semantic that labels are appended with 'mcp' unless mcp_label is False, which clarifies the mcp_label parameter. However, it doesn't add meaning for repo_owner, repo_name, title, or body beyond their names, and the schema already covers the label-related parameters. 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 clear verb and resource ('Creates a new issue') and distinguishes create from update tools by noting the label behavior difference. It doesn't explicitly name sibling alternatives like github_update_issue, but the create-vs-update contrast is enough to orient an agent.

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 a workflow convention: call github_get_skill('issue-management') for workflow details. It also explains when the 'mcp' label is appended (create tools only, when mcp_label is enabled), which helps an agent decide between create and update tools. It doesn't explicitly say 'use update_issue instead when...' but the context is 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 indicate a non-read-only, non-idempotent, non-destructive mutation. The description adds meaningful behavioral detail beyond annotations: duplicate titles cause failure due to per-repository uniqueness, and existing milestones should be edited rather than recreated. It does not disclose further side effects, but the key failure mode is covered.

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 compact, front-loads the core behavior, and immediately follows with the most important constraint and alternative. Every sentence earns its place, including the pointer to the workflow skill.

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?

An output schema exists and annotations cover the safety profile, so return values and mutation risks need less explanation. However, with six parameters and very low schema coverage, the description does not fully equip an agent to set state, due_on, or description correctly. The duplicate-title caveat and update alternative are useful, but parameter clarity remains a gap.

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 only 17%, so the description must compensate for undocumented parameters, but it does not explain repo_owner, repo_name, state, due_on, or description. It adds only that 'title' must be unique per repository. This is minimal value over the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description states the operation as 'Opens a milestone' and names the resource, and it distinguishes itself from github_update_milestone by explaining that duplicate titles fail and should be edited instead. However, 'opens' is less direct than 'creates', and the intended action relies partly on the tool title to disambiguate.

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 explicitly gives a when-not condition: duplicate titles fail because titles are unique per repository, and the agent is directed to github_update_milestone for that case. It also points to a workflow skill, github_get_skill('issue-management'), providing additional usage context. This is clear 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 cover the basic safety profile (readOnly false, destructive false, etc.), and the description adds meaningful behavior beyond that: labels are applied in a second call because the create endpoint accepts none, and the response exposes whether the token could write labels. This is useful non-obvious context, though auth and rate-limit details are omitted.

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 front-loads the purpose in the first sentence. The label-handling detail is useful but phrased awkwardly, and the skill pointer is terse. There is no filler, but the second sentence could be clearer.

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 nine parameters and only 22% schema coverage, the description leaves much to inference. It helps on label behavior but does not explain required fields, preconditions, or the overall workflow, instead pointing to an external skill. The output schema exists, so return values are covered, but the description is not complete enough for a tool of this 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 description coverage is only 22%, so the description bears the burden of explaining parameters. It adds some semantics around the labels parameter (second-call application and failure visibility), but the six required parameters—repo_owner, repo_name, title, body, head, base—and mcp_label are entirely undescribed in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The first sentence states clearly that the tool creates a new pull request, using a specific verb and resource. This distinguishes it from sibling create tools like github_create_issue and github_create_milestone without merely restating the tool name.

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?

There is no explicit guidance on when to use this tool versus alternatives such as github_update_pr or github_create_issue. The reference to github_get_skill('pr-management') defers to an external skill rather than stating when to choose this tool, and no prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description transparently explains that overwriting published notes cannot be undone, precisely describes the update-path parameter subset, and tells the agent to read 'updated' on the reply. However, annotations declare destructiveHint=false while the description describes an irreversible overwrite, which is an annotation 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 front-loaded with the core behavior and uses the second paragraph for necessary edge-case nuance. The reference to '#401' is cryptic and may not help an agent, but the overall length is justified by the behavioral complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, an output schema, and non-obvious update semantics, the description covers the surprising behaviors an agent needs to know, including dropped parameters and changelog replacement. It also points to a skill for conventions. The main weakness is the annotation contradiction rather than missing invocation 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 only 10%, and the description compensates by explaining the meaning of if_exists, the behavior of make_latest and generate_release_notes, and how body replaces the generated changelog. It does not explain obvious required fields like repo_owner, repo_name, tag_name, and release_name, but those are self-evident from naming.

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 precise action with a specific resource: 'Publishes a release for a tag.' It also clarifies the behavior when the tag already has a release, which distinguishes create semantics from tag creation or release update. It does not explicitly name sibling tools, but the core purpose 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 text gives a concrete decision rule: fail by default on an existing release, or pass if_exists='update' to deliberately overwrite. It also directs the agent to github_get_skill('release-management') for workflow conventions. It does not compare directly with github_update_release, but the usage context is 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 indicate a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds useful behavioral nuance by explaining that providing a message creates an annotated tag storing the message, while omitting it creates a lightweight ref. This goes beyond 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 compact and front-loaded: the core action is stated immediately, followed by the critical behavioral distinction, then a workflow reference. Every sentence contributes useful information without 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?

The description is adequate for a straightforward create operation, especially with an output schema present and annotations covering safety. However, it omits guidance on parameter semantics and does not clarify how this tool fits against release-related siblings, leaving some context gaps for an agent unfamiliar with the GitHub API.

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 only 20%, and the description does not compensate for the missing parameter documentation. It indirectly clarifies the 'message' parameter's side effect, but repo_owner, repo_name, tag_name, and sha are left without meaningful explanatory text beyond the schema's bare type declarations.

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 operation: 'Creates a new tag' with the specific resource being a Git tag. It goes beyond the title by distinguishing annotated tags from lightweight refs, which makes the tool's scope unmistakable and separates it from related tools like github_delete_tag or github_create_release.

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 an implied usage context through the workflow pointer 'github_get_skill('release-management')', which suggests this tool participates in a release-management workflow. However, it does not explicitly state when to prefer this tool over alternatives such as github_create_release or github_list_tags, nor does it define exclusion criteria.

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 idempotentHint=false, but the description adds genuinely new behavior: which branches are guarded, and the consequence of force (deleting a PR's source branch closes that PR). Deduction for the unexplained dangling reference "See #536", which conveys nothing to an agent without tracker access.

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?

Front-loaded and tight: the action, the two safety rules, the force consequence, then the workflow pointer. The "See #536" fragment is the only sentence that doesn't earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, single-purpose delete tool with an output schema and rich annotations, this covers what an agent actually needs: refusal conditions, the force trade-off, a concurrency guard param, and where to find conventions. Nothing material about correct invocation is missing.

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 only 40% across 5 params, so the description should carry more weight; it explains force in behavioral terms (closes the open PR) but says nothing about expected_head_sha's conditional-refusal role, leaving that to the schema's own one-liner. The three required params (owner/name/branch) are self-evident and need no elaboration.

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?

Opens with a specific verb and resource ("Deletes a branch") and immediately scopes it with two refusal rules, so the agent knows exactly which branches are eligible. No sibling tool does branch deletion, so no further differentiation is needed.

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?

Gives concrete when-not conditions (default branch always refused; branch with an open PR refused unless force) plus a pointer to github_get_skill('pr-management') for workflow/conventions. It stops short of naming an alternative tool for the cases where deletion is refused, leaving the agent to infer the fallback.

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, but the description adds crucial nuance: the tag is preserved by default, delete_tag=True removes the ref the delete_tag tool would not, and the absence of a force flag is justified by the ordering (release deletion first) to prevent dangling releases. This is genuinely useful behavioral detail 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 compact and logically ordered: core action, default behavior, flag explanation, design rationale, then a workflow pointer. The #404 reference is a minor cryptic note, but it does not derail the message.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with a clear side-effect story, the description covers what gets deleted, under what conditions, and references a skill for deeper conventions. The output schema exists, so return-value detail is not needed. It could have mentioned irreversibility explicitly, but annotations already signal destructive, so this is a minor gap.

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 only 25% (only delete_tag has a description). The description enriches delete_tag semantics by explaining what it does to the tag and why, and it contextualizes tag_name as the release's published tag. The other parameters are straightforward from their 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 opening sentence 'Deletes a release' is a precise verb+resource statement. It further distinguishes itself from the sibling github_delete_tag by explaining the tag survives unless delete_tag is set, making the tool's scope 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 explains when delete_tag=True is appropriate and how it interacts with the sibling delete_tag tool, and it points to github_get_skill('release-management') for workflow conventions. It does not explicitly list all alternatives, but it gives enough context for the key decision between removing a release vs. a tag.

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 destructiveHint annotation, it discloses a specific failure mode (refusal without force), the workaround (force), and the underlying consequence (release left without the code it names). This materially supplements the annotation context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs front-load the core purpose, then provide the critical edge case and a terse pointer to workflow guidance. 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?

For a simple destructive tag deletion with an output schema and destructiveHint, the description covers the key behavioral hazard and workflow route. It is only held back by the undocumented required identifier parameters.

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 only 25% schema description coverage, the description was responsible for compensating, but repo_owner, repo_name, and tag_name are left entirely to naming conventions. The force parameter is effectively restated from the schema, so no substantive semantic value is added beyond it.

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 'Deletes a tag,' a specific verb and resource that clearly identifies the operation and distinguishes it from siblings like github_create_tag, github_list_tags, and github_delete_release. The added release-points nuance does not blur the 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?

It gives a clear condition: a tag a release points at is refused unless force is set, explaining why. It also points the agent to github_get_skill('release-management') for workflow conventions, though it doesn't explicitly state when to prefer this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the annotations by disclosing client-side validation (inputs beyond 25 are refused before any request is sent) and the return_run_details behavior — that GitHub otherwise answers 204 with no run information. That is genuinely useful behavior the schema and annotations do not convey.

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?

Front-loads the action and constraints in two tight sentences. The 'See #503' issue reference is opaque to an agent that cannot read issue trackers and does not earn 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?

An output schema exists, so return values need not be explained, and the description correctly notes that return_run_details is what makes the response useful. For a 5-parameter mutation with annotation coverage, this leaves little an agent needs missing.

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 60%; the description adds that inputs must be keyed by the names the workflow file declares and restates the 25 cap. It does not clarify repo_owner, repo_name, or the integer-vs-filename ambiguity of workflow_id beyond what the schema already says.

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?

States a specific verb (starts) and resource (a workflow that declares workflow_dispatch), plus the scoping mechanism (on ref, with inputs). No sibling tool does anything similar, and the precondition 'declares a workflow_dispatch trigger' prevents misfires on non-dispatchable workflows.

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?

A precondition is given (the workflow must declare workflow_dispatch) and a conventions pointer to github_get_skill('pr-management'), but there is no explicit when-not-to-use or named alternative. Usage is implied rather than routed.

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 openWorldHint, covering safety. The description adds a useful behavioral trait: it reads directly from the issue rather than the search index, ensuring immediate consistency after a write. This goes beyond what annotations provide and is relevant for agents choosing between direct reads and search.

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, with the core purpose in the first sentence and the consistency behavior in the second. The 'See #358' reference is slightly extraneous, and the 'Workflow and conventions' line is brief but not clutter. Overall, it is efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-issue fetch, the description covers the key aspects: what data is returned, the direct-read consistency, and a pointer to a skill for workflow. An output schema exists, so return details are covered. It does not address auth or edge cases, but these are less critical given the simplicity and existing annotations.

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 carries full responsibility for parameter semantics. It only clarifies issue_number via 'by number', but provides no detail on repo_owner or repo_name. While these names are self-explanatory, the description does not explicitly map them to the schema, and per the rule it must compensate for low coverage. It does not fully do so.

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 'fetches' and the resource 'a single issue by number', listing the returned fields (body, labels, assignees, milestone). It also differentiates from search-based access by noting it reads directly from the issue, distinguishing it from sibling tools like github_search_issues_prs.

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 a usage scenario by stating it reads straight from the issue rather than the search index, so it sees a write immediately. This hints at when to prefer this over search, but it does not explicitly name alternatives or state when not to use it. The reference to github_get_skill('issue-management') suggests further guidance but is not explicit about tool 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 cover the safety profile (readOnly, non-destructive), and the description adds genuinely useful behavioral context: the tail-preserving cap and the one-minute redirect to a storage host where the download proceeds without the token. That auth nuance is not derivable from annotations or 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?

Three sentences, front-loaded with purpose and cap behavior; each earns its place except the cryptic 'See #500' reference which adds little for an agent without issue context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers the cap/tail behavior and the redirect/auth nuance, leaving only the undocumented repo_owner/repo_name fields as a minor gap.

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 50%: job_id and max_bytes are documented in the schema, and the description restates the max_bytes tail-cap behavior rather than adding new meaning. repo_owner and repo_name are undocumented in both schema and description, so compensation is incomplete.

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?

States a specific verb (fetches) and resource (GitHub Actions job's log) with a clear scope constraint (capped at max_bytes, keeps the tail). It is easily distinguishable from siblings like github_rerun_job or github_get_pr_status_checks.

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?

Usage is only implied via the rationale that 'a job reports its failure last, so a cut keeps the tail', which hints at failure debugging. The schema ties job_id to github_get_pr_status_checks and the description points to github_get_skill('pr-analysis'), but there is no explicit when/when-not guidance or named alternative for fetching logs.

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 establish read-only and open-world behavior; the description goes beyond by disclosing the no-commits edge case (returns None) and the race/re-reading caveat that a later push changes the result. This is useful behavioral information not present in the structured fields. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core behavior is stated in two short front-loaded sentences, and the workflow pointer is a compact convention hint. There is no filler or redundant elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read of a commit SHA, the description covers the dynamic nature of the result, the default-branch behavior, and the no-commits edge case, while the output schema covers the return shape and annotations cover safety. Missing auth or rate-limit details are not significant for this low-complexity 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?

Only ref has a schema description, so coverage is low, and the description mostly restates ref's schema semantics without adding new detail. repo_owner and repo_name are left to their names and are not clarified. Thus the description does not compensate for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

States a specific action and resource: it fetches the SHA of the newest commit, with explicit fallback to the default branch when ref is omitted. The behavior is precise enough to distinguish it from the sibling GitHub tools, even though no sibling is named. It is not a tautology or vague.

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 for when to call it: to read the newest commit SHA on a ref or default branch, and notes the result is ephemeral rather than a stable pin. It also points to a release-management skill for workflow conventions. It lacks explicit alternatives or exclusion wording, but the intended use case is evident.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds one genuine behavioral convention — that a skill must be loaded first ('Workflow and conventions: github_get_skill('pr-analysis')') — but otherwise says nothing about scope, rate limits, or what 'details' includes.

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 short sentences with no filler and the purpose front-loaded. The second line is terse to the point of being cryptic — 'pr-analysis' is never explained — but it is not wasteful.

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?

An output schema exists, so return values need not be described, and the read-only nature is covered by annotations. What is missing for a three-param, zero-coverage tool is any parameter meaning and any disambiguation from the many PR siblings, leaving the definition only minimally 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% across three required parameters, so the description carries the full burden and adds no meaning at all — no format for repo_owner/repo_name, no note that pr_number is per-repository. The parameter names are largely self-explanatory, which prevents a score of 1, but nothing compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

States a specific verb and resource ('Fetches the content/details of a specific pull request'), which is immediately actionable. However, 'content/details' is vague and does not distinguish this from close siblings such as github_get_pr_diff, github_get_pr_status_checks, or the generic github_api_read, so an agent cannot route unambiguously on the description alone.

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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives despite several overlapping PR-read siblings. The only contextual hint is a pointer to github_get_skill('pr-analysis'), which signals a workflow prerequisite but does not explain under what conditions this tool is the right choice.

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, non-destructive, open-world. The description adds real behavioral context beyond that: the response is capped, and bytes_total is always the untruncated size so a truncated reply reveals what was omitted. That is exactly the truncation semantics an agent needs. Minor deduction for the unparseable 'See #314 and #514' references.

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 core sentence leads with the operation and the cap, and the truncation explanation follows directly. 'See #314 and #514' is opaque to an agent that cannot resolve issue numbers and is the one phrase that does not earn 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?

An output schema exists, so return values need not be spelled out, and the description still explains the truncation/size contract. What is missing is routing versus the sibling diff/content tools, which matters given how many PR-reading tools are in this set.

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?

Only 25% schema coverage, but the three undocumented params are self-evident (repo_owner, repo_name, pr_number). The description reinforces max_bytes and explains the bytes_total relationship, which is meaning the schema does not supply on its own for output interpretation.

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?

States a specific verb (fetches) and resource (net unified diff of a specific pull request) with the cap already named. The word 'net' plus 'diff' distinguishes it from a raw files listing, but it never mentions the closest sibling github_get_pr_content, so an agent still has to guess which one returns the patch.

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?

There is a pointer to a workflow skill ('github_get_skill(pr-analysis)') which implies context of use, and the max_bytes=0 trick is described in the schema. But the description gives no explicit when-to-use/when-not and no comparison against github_get_pr_content or the inline-comment siblings.

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, so no side-effect disclosure is needed. The description adds useful behavioral context by clarifying that the returned issues are the ones linked to auto-close on merge, which is not visible from the schema or 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 definition is brief and front-loads the primary purpose in the first sentence. The second sentence is terse but somewhat cryptic, directing the agent to github_get_skill('pr-analysis') without explaining why, so the structure is good but not flawless.

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 three-parameter tool with an output schema, the description covers the key semantic behavior. It omits explicit parameter and workflow detail, but the low complexity and available schema make it reasonably 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 the three parameters. It never mentions repo_owner, repo_name, or pr_number, though the phrase 'pull request' indirectly points at pr_number. The parameter names are inferable, but the description adds almost no explicit semantic 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 first sentence clearly states a specific verb and resource: it returns issues that will be auto-closed when a pull request is merged. This makes the tool's operation evident, though it does not explicitly differentiate from sibling tools like github_get_pr_content or github_pr_issue_analyser_ui.

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 only usage-related text is the cryptic 'Workflow and conventions: github_get_skill('pr-analysis')', which instructs the agent to fetch a skill rather than explaining when to prefer this tool over alternatives. No when-to-use, when-not-to-use, or alternative routing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the contextual detail that the output feeds into github_set_project_field, which is useful. It does not mention errors, rate limits, or output format details, but given the annotations and simple read operation, this is acceptable.

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 brief and front-loaded with the core purpose, followed by a concise workflow instruction. It contains no fluff, though it could be slightly more structured with explicit when-to-use phrasing. Overall it's 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?

The description covers the core functionality and references a skill for conventions, which adds context. Since an output schema exists (as indicated by context signals), the return structure is already defined elsewhere. The description is sufficient for an agent to know when and why to invoke it, though it omits edge cases or error scenarios which are minor for a read-only list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100% with both parameters (project_owner and project_number) clearly described. The description adds no additional meaning about parameters, so the baseline of 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?

The description clearly states the tool lists a project's fields and the options for single-select fields, and explicitly connects it to github_set_project_field's expected naming. This distinguishes it from sibling tools like list_project_items and set_project_field. The verb 'lists' and the resource 'project fields' are specific.

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 before github_set_project_field by noting it provides the names that tool expects. It also instructs the agent to call github_get_skill('project-boards') as a workflow step, giving explicit guidance on prerequisites. However, it does not explicitly contrast with alternative tools or state when not to use it, so it's strong but not fully 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?

Excellent disclosure beyond annotations: it explains pagination caps, the supplemental drain logic, that truncation yields truncated=True and downgrades overall to 'unknown' to prevent acting on a partial view, and that head_sha is None when no commit resolves. This is exactly the behavioral context an agent needs.

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?

Front-loaded with the core purpose and then the behavioral caveats. It is somewhat dense with internal constant names (MAX_STATUS_CHECKS_SUITE_PAGES, MAX_STATUS_CHECKS_RUN_PAGES_PER_SUITE) and an issue reference (#515), but each sentence carries meaningful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained. The description adds the truncation/failure-mode and head_sha-none edge cases that an agent wouldn't otherwise know, making it complete for correct invocation and interpretation.

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% for 3 parameters, so the description bears the burden. It never describes repo_owner, repo_name, or pr_number, though they are standard GitHub identifiers that are largely self-evident. It does clarify the head_sha output semantics, but that is not an input parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

States a specific verb and resource: 'Return the CI check runs and commit status for a pull request's HEAD commit.' This is unmistakable and no sibling tool covers CI check status, so an agent can select it directly.

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 purpose implies when to use it (need CI status for a PR), and it points to github_get_skill('pr-analysis') for workflow conventions. However, it never explicitly contrasts with alternatives like github_get_pr_content or github_get_job_log, so routing 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=true and destructiveHint=false, so the agent knows this is a safe read. The description adds the specific selection behavior (by tag or latest) and the fact it fetches exactly one release, which goes beyond the generic read-only hint. It does not mention side effects, but there are none per annotations. The description enriches the 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 sentence with the core behavior front-loaded, followed by a separate line pointing to a skill. There is zero fluff. It is perfectly concise and structured for quick parsing by an agent.

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 a simple fetch operation with an output schema (present but not shown) and annotations covering safety. The description covers the selection logic and the required parameters implicitly through the schema. It does not mention edge cases like tag-not-found, but for a straightforward read operation with an output schema, this is sufficient. The workflow hint adds extra context. Overall, the agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is only 33% (only tag_name has a description). The tool description clarifies the tag_name parameter by saying 'by tag or the latest published one', which maps directly to the omit-for-latest behavior. However, it gives no additional meaning for repo_owner and repo_name, which are standard parameters but remain undocumented in the schema. The description partially compensates for the low coverage but not fully; it focuses on the optional parameter while leaving required ones self-explanatory.

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 'Fetches' and a specific resource 'one release', and explicitly defines the selection criterion 'by tag or the latest published one'. This clearly distinguishes it from github_list_releases which fetches multiple releases, and from github_create_release which writes. The purpose is unambiguous and differentiates from siblings.

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 fetching a single release, contrasting with a list operation. It also includes a workflow hint 'github_get_skill('release-management')' which signals that the agent should retrieve a skill for workflow context. While not explicitly stating when not to use it (e.g., use list for multiple releases), the 'one' versus 'latest' language gives a clear contextual cue, and the skill pointer provides additional guidance. There is no explicit alternative named, but the intent 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 declare readOnlyHint and destructiveHint, but the description adds valuable behavior: windowed reads, bytes_total representing the whole file, next_offset for continuation, and the guarantee that a partial read is not mistaken for the full file. This is meaningful beyond what the annotations alone communicate.

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 compact and front-loaded, with the core behavior in the first sentence and the directory exclusion immediately after. The references to '#409' and 'github_get_skill('pr-analysis')' are terse and slightly cryptic, but they do not add bloat.

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 an output schema present, the description does not need to explain return values, yet it still highlights the key continuation semantics (bytes_total and next_offset) and provides a routing rule for directories plus a workflow convention. The brief '#409' reference is the only noticeably under-specified element.

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 already documents ref, path, limit, and offset clearly, and the description reinforces the limit/offset windowing concept. However, repo_owner and repo_name have no schema descriptions and the description does not clarify them, so at 67% schema coverage the description does not fully compensate for the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description states a specific operation — reading one file from a repository at a ref — and distinguishes it from directory handling by explicitly routing directories to github_list_repository_tree. This clears up the main ambiguity against sibling tools like github_get_pr_content and github_get_pr_diff.

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 an explicit when-not: directories belong to github_list_repository_tree. It also points the agent to a workflow skill via github_get_skill('pr-analysis'), though it does not enumerate all alternatives or edge cases like when to prefer PR-specific content 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?

Beyond readOnly/openWorld annotations, it discloses the weekly-history UTC-day approximation, per-page/per-repo cost, and truncated semantics. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and since format are front-loaded, and the cost/truncation sentences add needed context without filler. It is long but dense; could be trimmed slightly but still earns its length.

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?

Good coverage of behavior, cost, and truncation with an output schema present, but the undocumented `top_n` and `max_repos` parameters create a real gap. An agent cannot fully understand the result-limit and repo-scan-limit semantics from 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 description coverage is 0%, so the description must carry parameter meaning; it only explains `since` (format/default). `top_n`, `max_repos`, and `username` are left to inference, which is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

States a specific verb and resource: 'Return the repos owned by username that received the most new stars since a given date.' It also clarifies the ranking and differentiates from general repo listing/search siblings by focusing on star growth since a date.

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 concrete prompts like 'which repos gained the most stars in the last 30 days' and explains cost/truncation tradeoffs, signaling when it is appropriate. It does not explicitly compare against alternatives, but the use-case framing is enough to route an agent.

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=true and destructiveHint=false, so safety is covered. The description adds useful context: the same content is available as a skill:// resource, which informs how the tool behaves. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero wasted words. The core purpose is front-loaded, and the resource note is a helpful addition without being verbose.

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 one parameter and an output schema, so the description covers purpose and usage sufficiently. It mentions the resource alternative, which adds completeness. It could explicitly mention when to use it vs. github_list_skills, but that's implied and not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 100%, with the name parameter already described as 'Skill name as github_list_skills reports it, e.g. pr-review'. The description does not add extra meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description clearly states 'Reads one skill in full' – a specific verb and resource. It also distinguishes itself from github_list_skills by focusing on a single skill and mentions the skill:// resource alternative, which sets it apart from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides implicit guidance: use this tool to read a skill's full content, and notes that if a client reads resources, this tool is unnecessary. It doesn't explicitly name alternatives like github_list_skills, but the resource note gives clear context for when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and destructiveHint, so the description doesn't need to repeat that. It adds valuable context about date formats and the cumulative nature of repo_stars, and it points to a skill for conventions. This exceeds the annotation baseline without contradicting it.

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 compact, with the main purpose front-loaded and supporting details (date formats, sibling tool, skill) neatly organized. It avoids redundancy and wastes no words.

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 tool with an output schema, the description covers the essentials: purpose, filtering, date formats, and a notable behavioral nuance. The only gap is the max_results parameter semantics, which is minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 0%, so the description must compensate. It explains org/repo filtering and gives precise date formats for since/until, but it does not mention max_results or its effect. This partial coverage earns a 3 – helpful but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description clearly states the action ('Get user activities') and the resource, and adds filtering dimensions (org, repo, date range) that distinguish it from other get tools. It also explicitly references the sibling github_get_repo_stars_since for a specific use case, making the 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?

It provides a concrete alternative (github_get_repo_stars_since) and a workflow hint (github_get_skill('user-activity')). However, it doesn't explicitly state when NOT to use this tool or compare against other user-activity-related tools, leaving some selection responsibility to the agent.

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 the read-only, non-destructive, open-world profile, so the description's real contribution is the wait semantics: polling until every run completes, a server-side cap so a task finishes before its worker is reassigned, and the meaning of timed_out when a run was still incomplete. That explains the otherwise puzzling idempotentHint=false for a read tool. It still omits error behavior and how the cap value is chosen.

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 opening sentence is well front-loaded, and the wait/timed_out sentences each earn their place. However, 'See #537' is an opaque issue reference with no resolvable meaning for an agent, and the skill cross-reference adds tail clutter that dilutes an otherwise tight paragraph.

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?

An output schema exists, so return-value documentation is not required, yet the description still explains the semantically important timed_out field. Behavioral edge cases are covered for the wait path. Minor gaps remain: what happens if neither run_id nor head is supplied, and how errors or an empty run set are reported.

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 only 60%, and the description compensates: it establishes that head means 'branch, tag or SHA whose commit to read every run of' and is mutually exclusive with run_id ('in place of run_id'), and it explains wait_seconds as a polling window that the server caps. repo_owner and repo_name remain unexplained but are self-evident.

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 ('Reads a workflow run') and enumerates both selection modes: by id, or every run on the commit a head names. It implicitly separates itself from github_dispatch_workflow by noting the run_id is the value that dispatch returns, but it never names a sibling tool outright to force differentiation.

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?

It clarifies when to use each selector ('by id, or every run on the commit that head names, in place of run_id'), which is genuine routing guidance. It does not say when to use this instead of adjacent tools like github_get_job_log or github_get_pr_status_checks, nor when a wait is worth requesting versus polling separately; the pointer to github_get_skill('pr-analysis') offloads conventions elsewhere.

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, so the safety profile is covered structurally. The description adds modest value by disclosing the shape of the result (head commit plus protection status), but says nothing about pagination behavior, rate limits, or the surprising idempotentHint=false for what is a pure read.

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 short sentences with the core capability front-loaded, which is efficient. The second sentence is a terse convention pointer that reads more like an internal note than actionable guidance, slightly reducing its usefulness 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?

Annotations and an output schema are both present, so return values and the read-only nature need not be spelled out. What remains missing is pagination guidance for a potentially long branch list and any explanation of how to use the protected filter, which is the one non-trivial parameter.

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 only 40%: per_page and protected are documented in the schema, but page, repo_owner, and repo_name carry no descriptions. The prose does not compensate for this gap, mentioning no parameter at all. repo_owner/repo_name are largely self-evident, but page and its interaction with per_page/default of 50 are left entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description names a specific verb and resource ("Lists a repository's branches") and even states the fields returned: the head commit and protection-rule coverage. It does not, however, distinguish this tool from closely related siblings such as github_list_tags, github_list_repository_tree, or github_delete_branch, so an agent still has to infer which listing tool applies.

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 only usage direction is a pointer to github_get_skill('pr-management'), which implies a workflow exists but does not say when to call this tool rather than the other branch-related tools. There are no exclusions, no prerequisites beyond the required repo identifiers, and no guidance on when filtering by protection status is appropriate.

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 establish the safe read-only profile (readOnlyHint=true, destructiveHint=false). The description adds useful return-semantics detail about issue counts, but does not disclose pagination or state behavior; these are covered by the schema, so the description is adequate but not rich.

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 short sentences, with the core behavior front-loaded and the workflow instruction kept to one line. No wasted words or redundant restatement 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?

For a simple read-only list with an output schema and annotated safety profile, the description plus schema covers the essentials. The main missing piece is explicit routing guidance versus sibling tools, but that is already penalized under usage_guidelines.

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?

Only 40% of parameters have schema descriptions; repo_owner, repo_name, and page are otherwise undocumented. The description does not compensate by explaining parameter roles beyond the phrase 'a repository's', and it does not clarify paging or state filtering.

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 ('Lists a repository's milestones') and adds a distinctive output detail ('with the count of issues in each'), which clearly differentiates it from siblings like github_create_milestone, github_update_milestone, and github_set_issue_milestone.

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?

There is no explicit when-to-use or alternative guidance; the intended use is implied by the listing verb. The 'Workflow and conventions' line points to a skill rather than explaining when this tool is preferred over other issue/milestone 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so safety is largely covered. The description adds the crucial behavioral constraint that the query is hard-pinned to is:open, which is non-obvious from the schema and prevents wasted calls.

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?

Front-loads the core behavior and the limitation, then the alternative, with no filler sentences. The trailing pointer to github_get_skill is terse but adds navigational value rather than noise.

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?

Scope, exclusions, alternative tool, and safety profile are all covered, and an output schema exists so return values need no explanation. Nothing an agent needs in order to call this correctly is missing.

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% and the enum values (pr/issue, filtering modes) are fully documented in the schema itself. The description adds no parameter-level syntax, defaults, or interaction details, 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?

States a specific verb and resource ("Lists open pull requests or issues") and immediately names the sibling that handles everything else. An agent can distinguish it from github_search_issues_prs without opening either schema.

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?

Explicitly states the fixed scope (is:open), the exclusion (closed and merged items are out of reach), and the exact alternative (github_search_issues_prs) for both those items and any unsupported qualifier. It also routes the agent to github_get_skill for workflow conventions.

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=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral nuance beyond annotations: inline comments carry file and line information, and the tool is positioned to support follow-up review continuity. This is meaningful contextual behavior not present in the schema or 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 compact and front-loaded with the core action. The second sentence provides targeted value about inline comments, and the workflow pointer is a single line. No filler or redundant restatement of the title or schema.

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 an output schema present and annotations covering the read-only safety profile, the description does not need to document return values or side effects. It adds a workflow reference and clarifies the meaning of inline vs conversation comments. A small gap is the lack of guidance on pagination or large PRs, but the schema's page/per_page parameters partially cover this, so the description is reasonably complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is only 33%, so the description should compensate for undocumented parameters. It does not explain repo_owner, repo_name, pr_number, page, or per_page beyond the generic phrase 'on a pull request.' The only parameter insight added is about inline comments carrying file/line, which overlaps with the schema's kind description. Required parameters are self-explanatory by name, but the description still leaves much of the parameter semantics to inference.

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 identifies a specific verb and resource: 'Lists the comments on a pull request.' It also clarifies the difference between conversation and inline comments by noting that inline comments carry file and line context. However, it does not explicitly differentiate this tool from sibling tools like github_list_pr_reviews, so it stops short of full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The workflow line 'github_get_skill('pr-review')' implies this tool fits into a PR review workflow and suggests the agent fetch a skill for conventions. This gives context but does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions or competing tools such as github_list_pr_reviews.

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, covering safety. The description adds valuable behavioral details beyond this: it discloses that the board is a GraphQL connection using cursor-based pagination and instructs to 'pass next_cursor back as after until has_more comes back false'. This is useful context not present 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?

The description is concise and front-loaded: it states the purpose first, then explains pagination, and finally points to a skill. Every sentence serves a purpose without fluff or repetition.

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 an output schema present, the description does not need to detail return values. It covers the essential usage context, including paging mechanics. It could mention prerequisite knowledge or edge cases, but it directs to a skill for workflow, which fills gaps. Overall, it is sufficiently complete for a read-only listing 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 50%, with only `after` and `per_page` having descriptions. The description adds clarity for `after` by explaining its role in pagination, which goes slightly beyond the schema's description. However, it does not compensate for the missing descriptions of the required parameters `project_owner` and `project_number`, though these are self-explanatory given the tool's name and purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description clearly states the action ('Lists what is on a project board with each card's field values') and adds the purpose ('so a backlog can be read by Status rather than one issue at a time'). This makes the tool's role distinct from other list tools like github_list_milestones or github_list_releases, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides clear context for use (reading backlog by status) and explains paging behavior. It also points to github_get_skill('project-boards') for workflow conventions, offering additional guidance. However, it does not explicitly mention alternatives or when not to use the tool, but the purpose is specific enough to guide 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?

With annotations already marking readOnly/openWorld and not destructive, the description adds useful behavioral context: GitHub resolves account type for both users and orgs, and pagination uses an opaque cursor with a has_more sentinel. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The operational content is front-loaded in three readable sentences plus a skill pointer. The phrase 'the number each other board tool takes' is awkward and 'See #465' is cryptic, which keeps it from a perfect score.

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 output schema and annotations cover return shape and safety, and the description fills in paging and account-resolution behavior. It is slightly incomplete on when to prefer this over item-level siblings, and the unresolved '#465' reference leaves one thread dangling.

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, but the description adds semantic value by explaining that the listed board number is exactly what other board tools take and by giving the cursor-chaining rule for the 'after' parameter. This is a modest but real increment over 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 opens with a specific verb and resource: 'Lists the Projects (v2) boards a user or organisation owns.' It further clarifies that the result includes the same board number other board tools consume, which distinguishes it from item-level siblings like github_list_project_items. This is more than a restatement of the tool name.

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?

It gives concrete operational guidance: cursor paging ('pass next_cursor back as after until has_more comes back false') and a workflow pointer ('github_get_skill("project-boards")'). It does not explicitly say when to avoid this tool or name an alternative, so it stops short of a full 5.

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 the operation read-only and non-destructive, and the description adds meaningful behavioral detail: ordering is oldest first, each result includes author and verdict, and reviews are distinct from comments. This goes beyond annotation coverage without contradicting it, though it leaves external reference '#408' unexplained.

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 compact and front-loaded with the core behavior, followed by a useful distinction and workflow note. Each sentence earns its place, though '#408' is a cryptic reference that may not help an agent.

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 relatively simple read-only list tool with an output schema, the description covers the essential behavior, ordering, content, and the key sibling distinction. It also provides workflow guidance for interpreting results, making it complete enough for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is only 40%, with only page and per_page documented. The description does not compensate by explaining repo_owner, repo_name, or pr_number, even though those names are fairly standard. It does not add parameter-level meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description uses a specific verb and resource: 'Lists the reviews submitted on a pull request, oldest first, each with its author and verdict.' It clearly differentiates itself from github_list_pr_comments, so an agent can distinguish this tool from its nearest sibling without opening the schema.

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?

It explicitly names the alternative tool (github_list_pr_comments) and explains when to use it instead: for line and thread comments, not approvals. It also gives a follow-up workflow, telling the agent to read requested_reviewers from github_get_pr_content to distinguish 'nobody reviewed' from 'nobody asked', and points to a skill for conventions.

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, so the safety profile is known. The description adds the ordering behavior ('newest first') but does not disclose pagination details, rate limits, or other runtime traits. No contradiction with annotations exists.

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 front-loaded with the core purpose. The second sentence about the workflow skill is short but may add procedural noise; still, there is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list operation with an output schema, the core semantics are present and the ordering is specified. However, it lacks explicit sibling differentiation and leaves required parameters undocumented, making it minimally adequate rather than fully self-sufficient.

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 only 25%, with repo_owner, repo_name, and page undocumented in the schema. The description does not explain these parameters beyond saying 'a repository's releases,' which only weakly implies the need for owner and name. This does not compensate for the 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 states a specific action and resource: 'Lists a repository's releases, newest first.' This makes the listing intent and ordering clear. It does not explicitly distinguish itself from siblings like github_get_release or github_list_tags, so differentiation is implied rather than stated.

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?

There is no guidance about when to use this tool versus alternatives. The line 'Workflow and conventions: github_get_skill("release-management")' is a procedural convention, not a comparison or exclusion. An agent must infer usage from the tool name and generic listing behavior.

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, so the description does not need to repeat that. However, the description adds no additional behavioral context such as pagination behavior, error handling, response format, or rate limits. It is consistent with annotations (no contradiction), but it provides minimal extra value beyond the annotations, which are already sufficient for a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, with the core purpose front-loaded. The workflow hint is concise and adds a useful directive without waste. No unnecessary words or repetition. It is appropriately sized for a simple list operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is straightforward and has an output schema (not shown but indicated), so return values need not be explained. The workflow hint gives some context but is cryptic—it doesn't clarify what github_get_skill returns or how it affects usage. The lack of parameter descriptions and edge-case guidance (e.g., empty repo, invalid owner) makes it only partially complete, though acceptable for a simple read-only 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 only 25% (only per_page has a description). The description text does not mention any parameters at all, leaving repo_owner, repo_name, and page without any semantic explanation in either the schema or the description. Since the description fails to compensate for the low schema coverage, this is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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

The description states a specific operation: 'Lists the labels defined in a repository.' It is clear about the resource (labels) and the action (list). It distinguishes from sibling tools like github_list_milestones and github_list_releases by the resource type, though it does not explicitly name alternatives. The purpose is unambiguous and directly maps to the tool name.

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 includes a workflow directive: 'Workflow and conventions: github_get_skill('issue-management').' This implies the tool is part of an issue-management workflow and instructs the agent to fetch a skill first, but it does not explicitly state when to use this tool vs. other list tools, nor does it provide exclusions or prerequisites beyond the skill call. The guidance is contextual but not fully 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds valuable behavioral nuance beyond those annotations: endpoint selection depends on account type, /users hides organisation private repositories, and the caller can see their own private repos. 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 first sentence is front-loaded and the endpoint-routing sentence earns its place by explaining a non-obvious behavior. However, 'See #354' and the workflow line referencing github_get_skill('user-activity') are cryptic pointers that do little to help an agent select or invoke the tool. The description is reasonably sized but not every sentence 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?

This is a simple read-only listing tool with four optional parameters, an output schema, and annotations covering safety. The description covers the main non-obvious risk—how owner account type affects endpoint and private-repo visibility. The cryptic references are minor flaws rather than missing essential invocation information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is 50%, with owner and per_page documented but page and sort left to inference. The description adds useful meaning for owner by explaining account-type-dependent endpoint behavior and private-repo visibility. However, it does not compensate for the undocumented page and sort parameters, leaving part of the parameter semantics to be guessed.

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 a clear verb and resource: 'Lists repositories for a user, an organisation, or the caller.' This distinguishes it from sibling tools that target PRs, releases, tags, or milestones. However, it does not explicitly name or contrast any sibling tool, so it stops short of full differentiation.

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 useful operational routing guidance—'the owner's account type picks the endpoint, since /orgs 404s on a person and /users hides an organisation's private repositories'—but does not explicitly say when to use this tool versus an alternative. The workflow line references github_get_skill('user-activity') rather than explaining tool-selection criteria. Usage context is mostly implied by the name and first sentence.

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, so safety is covered. The description adds valuable behavioral context: the 'truncated' field behavior and that paging cannot widen the cap, plus the entry field list. This goes beyond annotations and helps the agent handle edge cases. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the main purpose, but the cryptic '#409' reference and the workflow line about github_get_skill are tangential and may distract an agent. These additions do not clearly support tool usage and add noise without earning their place, so it is not as tight as it could be.

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 listing tool with an output schema and annotations covering safety, the description is fairly complete. It covers the main behavior, the truncation edge case, and entry contents. It omits error handling and rate limits, but those are typically not required for such a straightforward tool, and the output schema likely covers return structure.

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% (3 of 5 params have descriptions). The description reinforces the meaning of 'recursive' and 'ref' but does not add details beyond what the schema already provides. It does not clarify repo_owner or repo_name, but those are conventional and obvious from the tool name. Overall, it adds marginal value over the schema, so a 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 the tool lists a repository's tree at a given ref, with a clear one-level default and optional recursive behavior. It distinguishes itself from siblings like github_get_repository_file (which fetches a single file) and github_get_pr_diff (which returns diffs), so an agent can easily tell this is the tree-listing tool.

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 by describing what it does but does not explicitly state when to use this tool over alternatives, nor does it mention exclusions. The workflow line about github_get_skill('pr-analysis') is not directly about this tool's usage context, so it provides no alternative routing. Guidance is implied but not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that each item includes a name and URI, which gives some insight into the output structure but does not reveal any behavioral quirks (e.g., pagination, ordering). For a simple read-only listing, this is acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.