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?

It discloses key non-obvious behavior: GitHub rejects comments on non-hunk lines or non-diff paths, and deleted lines exist only on side LEFT. These constraints go beyond the annotations (readOnly=false, destructive=false, idempotent=false) and help the agent predict failure modes.

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 short sentences, each carrying essential information: the action, the diff-hunk validation constraint, and the workflow pointer. It is front-loaded and has no filler, making it easy for an agent to skim and retain.

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 core call constraints are covered, and an output schema exists so return-value explanation is unnecessary. The only gaps are minor: no explicit handling of start_line/start_side edge cases or a clear alternative routing, but the description plus schema and annotations are otherwise sufficient for correct 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?

With only 33% schema description coverage, the description compensates by explaining the line/range relationship and the LEFT side for deleted lines. It also clarifies that the path and line must be part of the diff. Obvious parameters like repo_owner, repo_name, pr_number, and comment_body are self-explanatory and need little extra prose.

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 identifies the action ('Adds an inline review comment') and object ('to a line, or to a range of lines, in a file within a PR'), so an agent can tell what it does. It does not explicitly call out how it differs from github_add_pr_comments or github_reply_to_review_comment, but the 'inline' and line/range scoping is enough to infer the distinction.

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

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

The description gives strong contextual guidance: comments are only valid inside PR diff hunks, unchanged lines outside hunks are rejected, and deleted lines must use LEFT. It stops short of naming alternatives or stating when not to use the tool, and the github_get_skill('pr-review') reference is indirect workflow guidance.

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

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

Annotations already 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 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, 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?

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 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 and destructiveHint=false, so the 'Fetches' wording is consistent and the safety profile is covered. The description adds minimal behavioral context beyond that, such as the scope being a single specified pull request, but it does not disclose additional traits like authentication requirements or rate limits.

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 purpose. The workflow line is a bit cryptic but not padded; overall it is efficient and easy to scan.

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?

Output schema and annotations carry some contextual weight, so the description does not need to explain return values or read-only behavior. However, it lacks sufficient parameter guidance and sibling differentiation, making it minimally viable but not fully complete for correct tool selection and invocation.

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

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

Schema description coverage is 0%, and the description does not explain repo_owner, repo_name, or pr_number semantics beyond the generic phrase 'a specific pull request'. The parameter names are self-explanatory, but the description fails to compensate for the missing schema-level documentation.

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

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

The description states a clear verb ('Fetches') and resource ('content/details of a specific pull request'), making the basic purpose obvious. However, it does not differentiate from sibling tools like github_get_pr_diff or github_get_pr_linked_issues, so the agent must infer the exact distinction from 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 only usage-related content is the terse instruction 'Workflow and conventions: github_get_skill("pr-analysis")', which tells the agent to load a skill but not when to prefer this tool over alternatives. There are no conditions, exclusions, or explicit comparisons with sibling PR-related 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 mark the tool as read-only and non-destructive. The description adds valuable behavioral detail beyond that: the patch is capped at max_bytes, bytes_total reports the full patch size even when truncated, and a truncated reply indicates content was left behind. This helps the agent handle partial results correctly.

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, which is good. However, 'See #314' is cryptic and provides no actionable context for the agent, and the workflow reference is terse. The message is structured but contains a vague reference that reduces overall clarity.

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

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

The output schema exists, so return shape is covered. Annotations cover safety. The description handles the key edge case (truncation) but leaves the required parameters undocumented and refers to an external issue number and a skill for additional context. For a simple read tool this is adequate, but not fully complete.

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

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

Schema description coverage is only 25%, so the description must compensate for undocumented parameters. It explains the max_bytes cap and truncation behavior, which adds value, but repo_owner, repo_name, and pr_number are not described at all. The required parameters are conventional, but the description does not clarify them or their relationships.

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: 'Fetches the diff/patch of a specific pull request'. This clearly identifies the tool's function. It does not explicitly name sibling tools to differentiate from, but the diff/patch target is distinct enough to be recognizable among similar PR-related tools.

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

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

The description points to a skill ('github_get_skill(pr-analysis)') as a workflow convention, but it does not say when to use this tool versus alternatives like github_get_pr_content or github_get_pr_status_checks. There is no when-to-use or when-not-to-use guidance, and no mention of alternatives.

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

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

Annotations already 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?

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds significant behavioral context beyond that: pagination caps, the supplemental query drain, and the critical truncation semantics (truncated=True and downgrading 'passing' to 'unknown'). This prevents an agent from acting on an incomplete view.

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 first sentence states the core purpose, the second covers pagination, and the third covers truncation. The workflow pointer is a minor tangent but useful. No filler, though the unexpanded MAX_* constants could be considered mild jargon.

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, return-value details are covered elsewhere. Annotations cover the safety profile. The description fills the remaining operational gaps: pagination limits, the supplemental drain, and the truncation downgrade behavior. An agent has everything needed to invoke this correctly and interpret partial results.

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 the tool operates on a PR's HEAD commit and implicitly maps repo_owner, repo_name, and pr_number to identifying the PR. The three parameters are self-descriptive names, so the description adds enough meaning without needing explicit per-parameter docs.

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: 'Return the CI check runs and commit status for a pull request's HEAD commit.' This clearly distinguishes it from sibling tools like github_get_pr_content (which fetches content) and github_get_pr_diff (which fetches diffs).

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' sentence points the agent to github_get_skill('pr-analysis'), which provides when/where to use this tool. It does not explicitly name alternatives or give negative usage guidance, but the workflow pointer is clear and actionable context.

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 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 and destructiveHint, so the bar for additional disclosure is lower. The description adds the key behavioral constraint that the search is fixed to is:open, and clarifies that closed/merged items are not retrievable. It does not contradict annotations and adds meaningful context about the tool's fixed filtering behavior.

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

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

The description is compact, with the primary action stated first, followed by the constraint and the alternative, then a workflow pointer. Every sentence earns its place and there is no redundancy or fluff.

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

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

Given the presence of a full input schema and an output schema, the description adequately covers the tool's purpose, its main limitation, the appropriate alternative, and a recommended workflow. Nothing essential for 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?

The input schema already describes all 6 parameters with 100% coverage, including enums and defaults. The description adds minimal parameter-related semantics beyond noting that certain qualifiers are not exposed, which is more about usage than parameter meaning. The baseline of 3 applies because the schema carries the weight, and the description does not introduce new parameter-level details.

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 open pull requests or issues, and explicitly contrasts it with the sibling tool github_search_issues_prs by noting the fixed is:open filter and that closed/merged items are out of scope. This distinguishes it from alternatives without needing to inspect 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 provides explicit usage guidance: it tells the agent to use github_search_issues_prs for closed/merged items and for any qualifiers this tool does not expose, and it points to a workflow convention via github_get_skill('issue-management'). This fully addresses when and when not to use this tool.

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

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.

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

The description is two sentences long, front-loading the main action ('Lists the workflow guidance') and then providing a key relationship to github_get_skill. The mention of '#414' is cryptic but does not add unnecessary length. 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?

Given the tool's simplicity (no parameters, read-only) and the existence of an output schema, the description sufficiently explains what it does and how to use it. It mentions the skill name and URI, which are likely covered in the output schema. It does not mention pagination or filtering, but these are not critical for a list-all tool and are likely in the output schema.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to explain parameters since there are none, and the schema is empty. No additional parameter semantics are required.

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

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

The description clearly states the tool's purpose: to list the workflow guidance bundled with the server. It also connects to the sibling tool github_get_skill by mentioning the name that tool takes and the skill:// URI, effectively distinguishing itself from that retrieval tool. The verb 'lists' is specific and the resource (workflow guidance) is well-defined.

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 explicit usage direction: 'Read the one covering the task before starting it.' This implies the tool should be used to discover which skill to fetch via github_get_skill, providing clear context for when to use it. It does not explicitly name alternatives or state when not to use it, but the guidance is actionable.

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 the useful detail that each tag is paired with the commit it points at, but it does not describe pagination behavior or other API nuances. 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?

Two short sentences, with the core action front-loaded and no redundant filler. The workflow line adds a distinct piece of guidance, making every sentence 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 simple paginated list tool with an output schema and strong annotations, the description is nearly complete. The only mild gap is that the workflow instruction is cryptic—it tells the agent to fetch a skill but doesn't explain whether that step is mandatory before calling this 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%, with only per_page documented. The description does not compensate by explaining repo_owner, repo_name, or page; it relies on their self-evident names. Parameter meaning is mostly left to the schema and naming conventions.

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 tags and the commit each points at.' This clearly distinguishes it from siblings like github_list_releases or github_get_release by emphasizing tags and their associated commits.

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 pointer 'github_get_skill('release-management')' gives useful context that this tool belongs to a release-management skill, but it does not explicitly say when to choose list_tags over alternatives like list_releases, or when not to use it. Usage is implied rather than stated.

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 readOnly=false and destructive=false; the description only restates the action and adds no side effects such as branch cleanup, CI triggers, or required permissions. It does not contradict the annotations.

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

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

Two short sentences with no filler. The action is front-loaded and the skill pointer is a compact way to route the agent to conventions.

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 six parameters, no param descriptions, and a mutating operation, the description is thin; however, the workflow pointer and existing output schema/annotations mitigate the gap. It leaves behavioral and parameter details to be fetched from the skill.

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 merge_method, commit_title, commit_message, or repo fields. It only adds 'specific' to indicate pr_number selection, which leaves most parameter meaning 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 states a specific verb ('Merges') and resource ('a specific pull request'), and no sibling tool claims the merge operation, so the agent can immediately distinguish it from create/update PR tools.

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

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

It provides a workflow pointer to github_get_skill('pr-management'), which implies the correct usage context, but it does not say when to use this tool instead of update_pr or other PR 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?

With no annotations, the description carries the full burden. It thoroughly explains the sandboxed execution, streaming behavior, reactive state, and layout patterns. It also discloses the need to import all dependencies and use PrefabApp as the outermost context. While it does not explicitly state side effects or safety, the sandbox context implies a safe, read-only execution environment. This is substantial transparency for a complex tool.

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

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

The description is lengthy but well-structured with clear sections and code examples. It front-loads the core purpose and then provides necessary syntax, layout patterns, and pipe filters. Each section adds value, though the length could be trimmed for simpler contexts. Overall, it is appropriately sized for the complexity of the Prefab UI system.

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 tool's functionality comprehensively: execution model, syntax, reactive bindings, charts, layout patterns, and parameter usage. It lacks a connection to the specific PR issue analysis domain implied by the tool name, but it fully covers the mechanics of the tool itself. Since there is no output schema, the description does not need to explain return values beyond 'render the result'. It is complete for calling and using the tool correctly.

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

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

The description includes an 'Args' section that explicitly defines both parameters: 'code' as Python code building a Prefab component tree and 'data' as injected variables. This fully compensates for the 0% schema coverage. The description also provides multiple examples demonstrating how these parameters are used, adding rich meaning beyond the raw schema.

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

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

The description clearly states the tool executes Prefab Python code in a sandbox and renders the result, which is a specific verb+resource. It distinguishes itself from sibling GitHub operation tools by being a UI rendering tool. However, the tool name suggests a PR issue analysis focus, but the description omits that domain context, making the purpose slightly ambiguous in this GitHub context.

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

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

The description does not explicitly state when to use this tool versus alternatives. It mentions a workflow convention to call github_get_skill('interactive-ui'), but this is a pointer to a skill, not an explicit usage guideline. No guidance on when not to use this tool or how it compares to other UI-related tools 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 destructiveHint=true, so the agent knows it is destructive. The description adds valuable nuance: the issue remains open but its card's field values are lost. This goes beyond the annotation and helps set expectations. It does not contradict any annotation.

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

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

The description is two sentences with no waste. It front-loads the core action and effect, then points to a skill for conventions. Every sentence earns its place, and the structure is easy to parse.

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

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

Given that an output schema exists (though not shown), the description does not need to explain return values. It covers the critical behavioral nuance (issue stays open, field values lost) and points to a skill for workflow conventions. It lacks explicit parameter explanations, but the parameter names are fairly obvious. Overall, it is reasonably complete for a destructive board operation, though it could mention idempotency or reversibility.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any parameter. The parameter names are self-explanatory (repo_owner, issue_number, etc.), but the description gives no guidance on how they relate to the project board or any special constraints. This is a significant gap given five required 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?

The description uses a clear verb and resource ('Takes an issue or pull request off a project board') and explicitly states the effect on the issue (untouched, stays open). It also distinguishes itself from the sibling 'github_add_to_project' by its opposite action. This makes the tool's purpose unmistakable.

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

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

The description clearly implies when to use the tool (when removing an item from a project board) and explains that the issue itself is not deleted, which helps an agent decide between this and other board-related tools. It does not explicitly name alternatives or exclusions, but the context is strong. The pointer to a skill for conventions adds a workflow cue, though it is not direct guidance.

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

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

Annotations already indicate readOnlyHint=false (mutation), so the description's 'replies' aligns. It adds the nuance that it operates on an existing thread, which is not explicit in the schema. However, it lacks details on authentication requirements or response behavior, but given the annotations, a baseline of 3 is appropriate.

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

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

The description is short (two sentences) and front-loads the core behavior: 'Replies on an existing review thread rather than starting a new one.' The reference to the workflow is extra but useful. 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 mutation tool with an output schema, the description covers the main differentiation (reply vs new thread) and points to a skill for broader context. It does not detail all parameters or effects beyond the schema, but given the output schema and annotations, it is adequate for an agent to select and invoke correctly in most cases.

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

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

The schema has only 20% description coverage, with only comment_id described as 'the review comment being replied to, which sets the thread.' The description does not elaborate on the other parameters like body or repo_name, but these are relatively self-explanatory. Given low coverage, the description could have done more, but the essential purpose of comment_id is covered in the schema. Baseline 3 is defensible.

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 (reply on an existing review thread) and explicitly contrasts it with starting a new one, which distinguishes it from sibling tools like github_add_inline_pr_comment and github_submit_review. It also references the workflow convention via github_get_skill('pr-review').

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

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

The description makes clear that this tool is for replying to an existing thread, implying when not to use it (when starting a new thread). However, it does not explicitly name alternative tools for the opposite case or provide conditions like 'if you need to start a new thread, use X'. Despite that, the context is strong.

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. The description adds behavioral context beyond annotations: it clarifies that the tool accepts any GitHub search qualifier and that closed/merged items are reachable, which is important for setting agent expectations. It doesn't mention pagination or rate limits, but the output schema and annotations cover the core behavior.

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

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

The description is compact and front-loaded: the first sentence states the action and scope, the second sentence differentiates from the sibling, and the third gives a workflow pointer. No wasted words; 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?

For a read-only search tool with an output schema and clear annotations, the description is nearly complete. It covers the key differentiator (caller's query, closed/merged reachable) and points to a skill for workflow conventions. It doesn't describe the return format, but the output schema exists, so that's not required. A small gap is not mentioning pagination behavior, but that's minor given the schema has page/per_page 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?

Schema description coverage is 67%: the query parameter has a helpful example ('rate limit repo:owner/name is:closed label:bug'), and per_page has a range description. The description itself doesn't add much parameter-level detail beyond what the schema already provides, but the schema is adequate. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Searches') and resource ('issues and pull requests'), and immediately distinguishes itself from the sibling github_list_open_issues_prs by noting the query is the caller's, so closed and merged items are reachable. This is a clear, specific purpose that an agent can act on.

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 names the alternative tool (github_list_open_issues_prs) and explains the key difference: this tool uses the caller's query and can reach closed/merged items, while the sibling presumably lists only open items. It also directs the agent to github_get_skill('issue-management') for workflow conventions, which is concrete usage 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?

With no annotations, the description carries full burden and does an excellent job: it explains the OR-matching behavior, the automatic detail/compact mode based on match count (≤5), and how the 'detail' parameter overrides this. It also discloses the limit behavior difference between modes. These are precisely the behavioral traits an agent needs to predict the tool's response.

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 well-organized and front-loaded with the main purpose, then presents usage context, matching behavior, parameters, and a workflow reference. While it's longer than necessary, every sentence contributes meaning and the structure supports quick scanning. It could be tightened, but it's 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 covers the core search behavior, detail override, and limit semantics thoroughly, and mentions the workflow with github_get_skill. However, it omits the 'components' parameter entirely, leaving it unexplained. Given four parameters, one undocumented is a real gap that impacts an agent's ability to call the tool correctly in all cases. The output schema exists, so return format is covered, but the missing parameter drags completeness down.

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 three parameters (query, detail, limit) with clear descriptions that largely match the text. The description adds little beyond the schema for these. More critically, the fourth parameter 'components' has no description in either the schema or the tool description, leaving it undefined. Since schema coverage is 75% (above the low threshold but not >80%), the description should have compensated but instead omits it entirely.

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 line 'Search the Prefab component library' states a clear verb and resource. It then distinguishes this tool from the sibling github_get_skill by specifying that the skill covers patterns/layout while this tool provides API details. The purpose is unambiguous and distinct from all sibling github tools.

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

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

The description explicitly states when to use this tool ('before writing component code') and contrasts it with the skill ('The skill covers patterns and layout; this tool has the API details'). It also names the specific alternative github_get_skill and references a workflow. This is direct and actionable usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that it uses the GraphQL API, which is a minor behavioral detail, but it does not disclose things like rate limits, result shape, or whether partial username matches are supported. With annotations carrying the main safety burden, a 3 is appropriate.

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

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

The description is very short and front-loaded with the core purpose. The workflow note is a single extra sentence that adds a convention, though it is somewhat cryptic. No wasted words, but the workflow reference 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?

For a simple one-parameter read-only search tool with an output schema present, the description is nearly sufficient. However, the workflow note is vague and the description does not clarify what the search returns or how to interpret the result. The presence of an output schema reduces the need to explain return values, but the missing usage guidance and parameter semantics keep it from being 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 undocumented 'username' parameter. The description says 'Search for a GitHub user by username,' which confirms the parameter's role, but it does not add details like case sensitivity, exact-match requirements, or whether the username can include special characters. The description adds minimal value beyond the schema's bare parameter 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 specific verb and resource: 'Search for a GitHub user by username using GraphQL API.' This clearly distinguishes it from issue/PR search tools like github_search_issues_prs, though it doesn't explicitly name a sibling alternative. The mention of GraphQL API adds a small implementation detail but doesn't confuse the core purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions a workflow convention ('github_get_skill('user-activity')') but that is a follow-up action, not a usage condition or exclusion. There is no explicit context for when this tool is preferred over other search or user-related 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=false, destructiveHint=false, and idempotentHint=true, so the description does not need to repeat those. However, the description adds no further behavioral context such as whether setting an empty array clears assignees, whether existing assignees are replaced or appended, or what permissions are required. Given this is a mutation tool, the lack of added behavioral detail is a noticeable gap.

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

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

The description is brief with the core purpose front-loaded in the first sentence. The second sentence is a concise pointer to a skill for workflow, adding some utility without excessive verbosity. It earns its place, though it could be more self-contained.

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 4 required parameters, no schema descriptions, and only a sparse description, an agent lacks critical context for correct invocation: valid values for assignees (e.g., GitHub usernames), whether the array replaces all assignees, and the exact meaning of issue_number. Although an output schema exists, the description is incomplete for a mutation tool with 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 0%, so the description must compensate for the undocumented parameters. It mentions 'assignees' and 'issue or pull request' but does not explain the meaning or format of repo_owner, repo_name, issue_number, or the assignees array contents. The description adds minimal value beyond the parameter names already present in 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 clear verb and resource: 'Updates the assignees for a specific issue or pull request.' It identifies the target resource as an issue or PR, which is unambiguous. However, it does not explicitly differentiate itself from sibling tools like github_set_issue_milestone or github_set_pr_draft.

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

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

The description implies when to use it: whenever assignees need to be updated on an issue or PR. It references a skill 'pr-management' for workflow, but gives no explicit guidance on when not to use this tool or what alternatives exist. This is minimal but not misleading.

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

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

The description adds valuable behavioral detail beyond the annotations: it takes the title rather than the number and performs a lookup, and explains the clearing behavior via 'Omit the title to clear the milestone.' This does not contradict the annotations (readOnlyHint=false, idempotentHint=true) and enriches the agent's understanding of side effects.

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

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

The description is two concise sentences plus a workflow reference, with the core purpose front-loaded. Every sentence adds information and there is no redundancy or fluff.

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

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

It covers the primary action and the unique title-lookup behavior, and points to a skill for workflow. However, it leaves the required parameters unexplained and does not address error conditions or prerequisites like milestone existence. Given the tool's simplicity, this is a moderate gap but not severe.

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 milestone has a description). The description adds context that milestone is a title, but provides no elaboration on repo_owner, repo_name, or issue_number, which remain undocumented in both schema and description. With such low coverage, the description should compensate but does not.

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

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

The description clearly states the tool's function: 'Files an issue under a milestone, or takes it off one.' It also distinguishes itself from the sibling github_update_issue by noting it handles the title lookup, making the purpose unambiguous and differentiated.

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 references github_update_issue as an alternative and clarifies that this tool handles the milestone work, implying when to use it. It also points to github_get_skill('issue-management') for workflow conventions, but it does not enumerate all alternatives or state explicit when-not-to-use conditions.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it explains the REST limitation and the GraphQL workaround, which is beyond what annotations provide. It doesn't detail side effects, but the idempotentHint covers the main concern.

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

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

Two sentences with no filler. The core behavior is front-loaded, the technical constraint is explained in one clause, and the workflow reference is a single line. 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?

For a simple 4-parameter boolean toggle, the description is nearly complete. The output schema exists, so return values are covered. The only minor gap is that it doesn't explicitly state prerequisites (e.g., the PR must exist), but that is implied by the resource naming and the workflow reference.

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 only the 'draft' parameter documented. The description clarifies the boolean semantics ('True puts the pull request back into draft, False marks it ready for review'), which adds value. However, repo_owner, repo_name, and pr_number are left undocumented in both schema and description, though their names are self-explanatory in context.

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 ('Moves') and resource ('a pull request between draft and ready for review'), which clearly distinguishes it from siblings like github_update_pr or github_create_pr. It also explains the REST/GraphQL distinction, adding precision about what the tool actually does.

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 use this tool: when you need to toggle draft status, and it notes that REST cannot do this after creation, so GraphQL is used. It doesn't explicitly name alternatives or exclusions, but the workflow reference to github_get_skill('pr-management') provides additional guidance for the agent.

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