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

No annotations are provided, so the description carries the full burden of behavioral transparency. It thoroughly discloses the user experience (a card with buttons), the result format ('I selected:'), and explicitly states that the tool blocks further agent actions until the user responds: 'After calling this tool, you MUST stop and wait for the user's response.' This is a critical behavioral trait disclosed clearly.

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-structured and front-loaded. It opens with the core purpose, then moves to usage context, then details the user interaction and the blocking requirement. Every sentence adds value, and the length is appropriate—comprehensive 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 has no output schema, but the description compensates by explaining the result flow (the user's choice appears as a message). It covers the full interaction lifecycle, including the critical post-call waiting behavior. For a tool with 3 simple parameters and no complex nesting, this description is 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 coverage is 100%, so each parameter already has a description. The tool description adds contextual nuance (e.g., options become clickable buttons) but does not significantly extend the parameter semantics beyond what the schema provides. The example of the prompt format is helpful but minor. Baseline 3 is appropriate given the schema's completeness.

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

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

The description explicitly states the tool's function: 'Present the user with a set of options to choose from.' This is a specific verb-resource pair. The sibling tools are all GitHub-focused (e.g., github_get_project_fields, github_create_issue), so this tool is clearly distinct in purpose, eliminating any ambiguity about when to call it.

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 when-to-use guidance: 'Call this tool when you need the user to make a decision between discrete alternatives.' It also advises proactive use and warns against having the user type a choice in chat. This directly addresses the decision between this tool and an alternative (chat-based input), with clear instructions.

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 write operation, but the description adds valuable behavioral context: GitHub will reject comments on unchanged lines outside hunks or on paths not in the diff, and deleted lines exist only on side LEFT. This goes beyond the structured annotation hints and helps the agent anticipate failures.

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

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

Three sentences, with the core purpose first and the critical constraints following. Every sentence contributes meaningful guidance and there is no filler or repetition of the 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 9-parameter tool, the description covers the most error-prone constraints (diff hunks, side usage, range support) and the output schema is present to handle return details. It does not enumerate every parameter, but the self-explanatory names and schema descriptions cover the rest, making the description 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?

With schema description coverage at only 33%, the description compensates partly by explaining line/range semantics and the LEFT side for deleted lines. However, it does not add semantics for path, comment_body, or the repo identifiers, though those are fairly inferable from names. The low coverage keeps this from scoring higher.

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 ('Adds an inline review comment'), a precise resource ('a line, or a range of lines, in a file within a PR'), and adds scope by explaining the diff-hunk requirement. It clearly differentiates this from sibling tools like github_add_pr_comments by emphasizing 'inline' and line/range targeting.

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 actionable preconditions: the target line must be inside a diff hunk, the path must be in the diff, and deleted lines require side LEFT. It does not explicitly name alternative tools, but the 'inline' and 'line/range' framing implies when this tool is appropriate versus general PR comment 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 convey that this is a write operation (readOnlyHint=false) and nondestructive (destructiveHint=false). The description only restates the action without adding behavioral context such as permission requirements, rate limits, or effects on existing data.

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

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

The description is a single, front-loaded sentence with no filler. It is appropriately concise for a simple action, though the brevity comes at the cost of missing useful context.

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

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

Given the simple 4-parameter schema and available annotations and output schema, the description is minimally adequate. However, it lacks usage differentiation and parameter detail, so an agent must rely on sibling names and parameter names to fully understand 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?

Schema description coverage is 0%, but the description only hints at 'comment' and 'specific pull request' without explaining repo_owner, repo_name, pr_number, or comment format constraints. It partially compensates for the schema gap but leaves most parameter semantics to inference from param names.

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

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

The description uses a specific verb ('Adds'), names the resource ('a comment'), and identifies the target ('a specific pull request'). It is clear, though it does not explicitly distinguish itself from the sibling github_add_inline_pr_comment, leaving some ambiguity about whether this is a top-level PR comment.

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

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

The description provides no guidance on when to use this tool versus alternatives such as github_add_inline_pr_comment or github_reply_to_review_comment. Usage context is only implied by the tool name and the one-line description, with no exclusions or 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?

The description adds meaningful behavioral context beyond the idempotentHint annotation by explaining that a retry 'adds nothing and overwrites nothing' and that an already-present item returns its existing card. This clarifies the idempotency semantics concretely. There is no contradiction with 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 concise and front-loaded with the core action in the first sentence. The second sentence earns its place by explaining retry behavior. A minor grammatical awkwardness in 'One the board already holds' prevents 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?

With annotations covering idempotency and non-destructiveness, and an output schema covering return values, the description is adequate for a basic invocation. However, the lack of parameter-level detail and alternative guidance leaves meaningful gaps for an agent deciding exactly how to populate all five required arguments.

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%, so the description should compensate for the undocumented parameters, but it does not explain project_owner, project_number, repo_owner, or repo_name. It adds only marginal context by saying the issue_number can be an issue or pull request on a project board, which mostly repeats the one schema description already present.

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 action and resource: 'Puts an issue or pull request on a project board.' This is not a tautology of the name, and it clearly differentiates the tool from siblings like github_remove_from_project and github_set_project_field by identifying the exact operation and target.

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 first sentence implies the use case: when an issue or pull request should be placed on a project board. However, it does not explicitly state when to prefer this tool over alternatives such as creating a new issue, setting a field, or removing an item, nor does it provide any when-not-to-use guidance.

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

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

The description discloses a non-obvious behavior: the 'mcp' tracking label is appended by default unless mcp_label is disabled, and update tools do not re-add it. This adds value beyond the annotations (readOnly=false, idempotent=false, openWorld=true). It does not contradict the annotations, and the label nuance is exactly the kind of hidden trait that agents need.

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 filler. It front-loads the core purpose in the first sentence and packs the important label nuance into the second. The second sentence is slightly dense and could be more readable, but every word earns its place.

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

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

For a create operation with an output schema, the description provides the essential purpose and a critical caveat about label handling. The required parameters are clear from the schema. It could have explicitly named github_update_issue as the alternative, but the main context an agent needs to call this tool correctly is present.

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 43% (labels, mcp_label, milestone have descriptions; body, title, repo_owner, repo_name do not). The description mentions the mcp_label append behavior, which partially overlaps with the schema, but it does not compensate for the low coverage by explaining the meaning of the four undocumented parameters. Their names are suggestive, but the description itself adds no parameter semantics beyond what the schema already says.

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

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

The description opens with 'Creates a new issue,' a clear verb+resource statement that identifies exactly what the tool does. It also distinguishes itself from update tools by contrasting their label-handling behavior, giving an agent a clear way to separate create from update operations.

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

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

The description provides explicit behavioral guidance: update tools replace the label set and never re-add 'mcp', while only create tools append it when mcp_label is enabled. This gives context on when this tool's behavior differs from update_issue, though it doesn't name the sibling explicitly or state 'use for new issues only'.

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 only mark readOnlyHint false, idempotentHint false, and destructiveHint false. The description adds a useful failure mode: duplicate titles fail due to per-repository uniqueness. However, it does not clearly state that this is a write operation creating a remote object, nor does it mention permissions or other 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 only two sentences with no filler, and it front-loads the uniqueness constraint and the alternative tool. The wording 'Opens a milestone' is slightly imprecise, but structurally the description is efficient.

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

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

With 6 parameters, low schema coverage, and an output schema present, the description still fails to explain the core creation behavior clearly. It adds the duplicate-title rule and update alternative, but leaves state, due_on, description, and general behavior under-specified.

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%, with only due_on described. The tool description adds meaning for title uniqueness, but state, description, and the repo fields receive no semantic explanation. Given the low coverage, the description should have compensated 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 says 'Opens a milestone', which is ambiguous and does not clearly say 'creates a new milestone'. The uniqueness caveat and pointer to github_update_milestone help identify the intent, but the tool is not clearly differentiated from related siblings like github_list_milestones or 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?

The description explicitly states that duplicate titles fail and that the correct action for an existing milestone is github_update_milestone. This gives a clear when-to-create vs when-to-update rule, though it does not cover broader alternative selection.

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

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

Annotations already indicate readOnlyHint=false, so the agent knows this is a write. The description adds valuable behavioral context about label handling: labels are not applied atomically, they are applied in a second call, and the token's write limitations are visible in the response. This goes beyond annotations and helps set expectations.

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, reasonably short, but the second sentence is convoluted ('they come back under labels so a set the token could not write is visible') and could be clearer. It is front-loaded with the primary action, but the phrasing hurts readability.

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?

There is an output schema, so return values are partially covered, but the description doesn't mention what the PR creation returns or any authentication prerequisites. The label quirk is covered, but for a 9-parameter mutation tool with low schema coverage, more context would be helpful.

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

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

Schema description coverage is only 22%, and the description does not compensate. It mentions labels and the label-appending behavior, but does not explain required parameters like repo_owner, repo_name, title, body, head, base. The schema's descriptions for labels and mcp_label are decent, but the rest are bare, and the description adds no parameter-level meaning.

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?

Clearly states it creates a pull request, with a specific verb and resource. The mention of label handling distinguishes it from update operations, but it does not explicitly name alternatives, so it doesn't fully separate from siblings like github_update_pr.

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

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

No explicit when-to-use guidance or alternatives are given. The description notes that labels are applied in a second call, which is a behavioral detail rather than usage context. It does not state when to choose this over github_create_issue or github_update_pr.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false) and do not reveal irreversibility or the update behavior. The description discloses that overwriting published notes cannot be undone, and explains exactly what the update path does (drops make_latest, generate_release_notes, replaces changelog with body). This adds significant context beyond annotations, with no contradiction.

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

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

The description is two paragraphs, with the primary action and warning front-loaded. The reference to '#401' is cryptic and adds noise, and the second paragraph is somewhat dense but still focused. It is appropriately sized for the complexity of the tool and does not waste 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?

The tool has an output schema (not shown), so return values are likely covered there. The description covers the key behavioral nuances: failure on existing tag, update semantics, and parameter behavior in the update path. It does not mention how the response indicates which path occurred, but the output schema likely provides that. Overall, it is complete for the tool's purpose.

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% (only if_exists has a description). The description compensates by explaining if_exists behavior and the impact on make_latest and generate_release_notes in the update path. However, other parameters like body, draft, prerelease, repo_owner, etc. are not elaborated, though their meaning is fairly obvious from names. The description adds value for the tricky parameters, but not complete 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 verb ('Publishes') and resource ('a release for a tag'). It clearly differentiates from siblings like github_update_release and github_delete_release by focusing on the publish action and the special update behavior. The scope is unambiguous.

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

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

The description explicitly warns that a tag already carrying a release fails and advises passing if_exists='update' to deliberately overwrite. It also details the consequences of the update path (dropping make_latest and generate_release_notes), giving clear when-to-use and when-to-avoid guidance. No alternative tools are named, but the context is sufficient for the agent to decide between fail and update.

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, indicating a write operation. The description adds the annotated vs lightweight distinction, which is a meaningful behavioral nuance. However, it does not mention side effects, failure conditions (e.g., tag already exists), or permission requirements. Given annotations cover the mutation aspect, the extra value is limited but real.

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?

A single sentence that is front-loaded with the core action ('Creates a new tag') and then explains the key behavioral distinction. No fluff, every word earns its place.

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

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

The tool is simple, has an output schema (so return format is documented), and annotations cover the mutation nature. The description captures the essential tag behavior (annotated vs lightweight). It does not mention prerequisites like repo existence or tag uniqueness, but for a straightforward creation tool, this is adequate.

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% (only sha has a description). The description explains the message parameter's effect (annotated vs lightweight), adding meaning beyond the bare type. It does not explain repo_owner, repo_name, or tag_name, but those are self-evident from their names. It partially compensates for the low schema coverage but leaves room for more.

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: 'Creates a new tag.' It distinguishes from sibling tools like github_list_tags (listing) and github_delete_tag (deletion), and from github_create_release (release vs tag). The scope is clear.

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

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

No guidance is given on when to use this tool versus alternatives. It does not mention that creating a release (github_create_release) might be more appropriate for distributable artifacts, or that a lightweight tag is for simple refs. The agent gets no decision support.

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

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

Annotations already mark destructiveHint=true, and the description adds meaningful nuance: the tag survives unless delete_tag is set, and the release is always removed before the tag, avoiding the dangling-release state the guard protects against. It also explains why no force flag is needed. This goes beyond what 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 not bloated, but the second and third sentences are dense and jargon-laden, referencing 'the delete_tag tool refuses to touch' and a cryptic 'See #404.' The core purpose is front-loaded, but the extra behavioral rationale could be stated more plainly and compactly.

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

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

The description covers the key destructive behavior and tag interplay, and an output schema exists so return details need not be explained. However, it relies on internal references like '#404' and the unnamed 'delete_tag tool,' which may confuse an agent. Explicitly naming github_delete_tag and stating when to use it would make this more 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 carries some burden. It adds real value for delete_tag, explaining that it removes the tag without the force check, and clarifies that tag_name is the tag the release was published from. However, repo_owner and repo_name receive no explanatory treatment, and their semantics are left entirely to naming convention.

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 object: 'Deletes a release.' It also clarifies the relationship to the release's tag, which distinguishes it from sibling github_delete_tag and github_update_release. The purpose is unambiguous and the resource is named explicitly.

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

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

The description gives clear context on when the optional delete_tag parameter matters and references the delete_tag tool's guard behavior. It does not explicitly say 'use github_delete_tag when you only want to delete a tag,' but the tag-survival explanation strongly implies the division of labor between this tool and the tag-deletion 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?

Besides the destructiveHint annotation, the description reveals a specific non-obvious behavior: deleting a tag that a release points at will be refused unless force=true, and it explains the rationale. This adds meaningful behavioral context beyond the annotation. It does not contradict the annotation and is honest about the deletion risk.

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 action is front-loaded and the safety caveat follows. The slightly awkward second sentence does not hurt clarity or compactness.

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 annotations marking it destructive and an output schema present, the description covers the key operational nuance (force requirement). Missing parameter explanations are the main gap, but self-evident names and schema reduce the need. Overall adequate for an agent to invoke 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?

Only 1 of 4 parameters (force) has schema documentation, and the description partially re-explains it with the release-refusal semantics; it does not add descriptions for repo_owner, repo_name, or tag_name. The parameter names are intuitive, but with only 25% schema coverage the description bears more responsibility and does not fully compensate.

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+object: 'Deletes a tag.' It further distinguishes itself from sibling delete tools such as github_delete_release and from github_create_tag by focusing on tags and explaining the release-point interaction. This is enough for an agent to identify what resource this tool acts 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 gives no guidance about when to select this tool over github_delete_release or github_create_tag. It states the force/refusal condition, which is operational context rather than tool-selection guidance. There are no explicit when-to-use or alternative references.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it reads from the canonical issue store rather than the search index, making it strongly consistent and able to see a write immediately. This is useful and does not contradict the annotations.

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

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

The first two sentences are efficient and front-loaded, but 'See #358' is cryptic and provides no actionable value to an AI agent. It is likely an internal reference, making the description slightly less clean than 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 single-issue GET with a rich output schema and safety annotations, the description is nearly complete: it identifies the target, key behavior, and freshness semantics. It could be improved by explicitly noting the alternative search tool, but nothing essential for a correct call 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 schema has 0% description coverage, so the description must compensate. It only meaningfully clarifies issue_number by saying 'by number'; repo_owner and repo_name are left to their self-evident names. The listed body/labels/assignees/milestone are output fields rather than parameter semantics, so compensation is partial.

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

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

States a specific verb and resource: 'Fetches a single issue by number' and enumerates the included fields (body, labels, assignees, milestone). It also distinguishes itself from search-index-based tools by noting it reads straight from the issue, which differentiates it from siblings 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?

Provides clear context for when this tool is preferable: when a write must be immediately visible, since it reads directly from the issue rather than the search index. It does not explicitly name the alternative tool or state exclusions, so it falls short of full explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavior: it returns None for empty repositories and warns that the value is a reading, not a pin, so a later push can change it. These details align with idempotentHint=false and destructiveHint=false with no contradiction.

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

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

Three short sentences deliver the core action, the default-branch behavior, the empty-repo edge case, and the mutability caveat. There is no filler or redundancy.

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

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

The description fully covers how the tool behaves, including ref resolution, default branch usage, no-commit handling, and read semantics. Given the output schema and annotations, nothing essential is missing 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?

The schema already documents the ref parameter, and the description mostly restates its default behavior. repo_owner and repo_name are self-explanatory from their names, but schema description coverage is low and the description does not add much beyond the schema for these 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 names a specific verb ('Fetches'), a specific resource ('SHA of the newest commit'), and the ref handling. It is clearly distinguishable from sibling tools such as github_get_release or github_get_repository_file, so an agent can select it without ambiguity.

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

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

The description clearly implies when to use the tool: to get the latest commit SHA for a ref or the default branch. It does not name alternatives or state explicit when-not-to-use cases, but the narrow resource and default-branch behavior give enough context for correct use.

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 declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. However, the description adds no additional behavioral context such as what the 'content/details' include, authentication requirements, or any limitations. Since it adds nothing beyond the annotations, a score of 2 is warranted.

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, short sentence with no redundancy. It is concise and front-loaded with the action. However, its brevity is also its weakness, as it lacks necessary detail. For conciseness alone, it earns a 4, but the lack of substance limits its value.

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

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

Given the tool's simplicity (3 parameters) and the existence of an output schema, the description doesn't need to explain return values. However, it fails to clarify what 'content/details' encompasses, making it ambiguous compared to sibling tools that fetch specific aspects like diffs or status checks. Without this context, the agent cannot reliably choose this tool. Thus score 2.

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

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

The input schema has zero description coverage for its three parameters (repo_owner, repo_name, pr_number). The description fails to explain any parameter semantics, such as how to identify the pull request or any format expectations. With 0% schema coverage, the description must compensate but does not, so score 1.

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 'Fetches' with a specific resource 'content/details of a specific pull request'. It is clear what the tool does, but it does not explicitly differentiate from sibling tools like github_get_pr_diff or github_get_pr_linked_issues. Thus a score of 4 is appropriate.

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

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

No guidance is provided on when to use this tool versus alternatives such as github_get_pr_diff or github_get_pr_status_checks. The description only states what it does, leaving the agent to infer usage. With many sibling tools that fetch PR-related data, this is a significant gap, so score 2.

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 valuable behavioral context about truncation: it explains that bytes_total reflects the full patch size even when the response is truncated, and that max_bytes caps the output. This goes beyond the annotations and helps the agent interpret 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?

Two concise sentences with the main action and key nuance front-loaded. Every word earns its place, except perhaps the cryptic 'See #314', which is a minor reference but doesn't detract from clarity. The description 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?

The tool has an output schema (not shown), so return values are documented elsewhere. The description covers the essential behavioral nuance (truncation and bytes_total) and the capping mechanism. However, it lacks usage context—when to choose this over similar PR-related tools—which would make it more complete. Given its simplicity and the presence of an output schema, the coverage is adequate but not exhaustive.

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 max_bytes has a description). The description mentions max_bytes and its capping behavior, but the schema already says 'Cap on the patch returned. Pass 0 to learn the size without reading the patch'. It adds no new meaning for repo_owner, repo_name, or pr_number, which are trivial. The mention of 'bytes_total' pertains to output, not parameters. Baseline 3 is appropriate because the key parameter is already documented and the others are 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 clearly states the verb ('Fetches') and the resource ('diff/patch of a specific pull request'), and specifies the key constraint ('capped at max_bytes'). This is specific enough to distinguish it from sibling tools like github_get_pr_content, though it doesn't explicitly name them.

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

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

The description provides no guidance on when to use this tool versus alternatives such as github_get_pr_content or github_get_pr_status_checks. The cryptic 'See #314' is not actionable for an agent. There is no mention of exclusions, prerequisites, or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific behavior of returning auto-close issues, which is useful. However, it does not disclose details like whether the list is empty if no linked issues exist, or whether it only returns issues linked via keywords. With annotations covering safety, 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 a single sentence that is concise and front-loaded with the core purpose. There is no wasted wording, and it clearly states what the tool does without unnecessary elaboration.

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

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

The tool has a simple input schema (3 self-explanatory parameters) and an output schema exists, so the description need not explain return values. The description is complete enough for an agent to understand the tool's purpose and invoke it correctly. A small gap is the lack of any mention of edge cases (e.g., no linked issues), but this is minor given the 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 carries the burden of explaining parameters. The description does not mention repo_owner, repo_name, or pr_number at all. However, the parameter names are self-explanatory (repo owner, repo name, PR number), and the schema provides types and required status. The description adds no extra meaning beyond 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 states a specific verb ('Return') and resource ('issues that will be auto-closed when a pull request is merged'). It clearly distinguishes this from sibling tools like github_get_pr_content or github_get_pr_diff, which fetch different PR-related data. The title and description align well.

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 the tool is for retrieving linked issues that will be auto-closed, which is a clear context. However, it does not explicitly state when to use this tool versus alternatives like github_get_issue or github_search_issues_prs, nor does it mention any exclusions or prerequisites. The usage context is implied but not fully articulated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns field names and single-select options, which is useful. It doesn't mention pagination or whether all fields are returned, but for a read-only list tool 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?

One sentence, front-loaded with the action and resource, and ends with a purposeful connection to the sibling tool. No wasted 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 list tool with full schema coverage and an output schema, the description is nearly complete. It could mention that the output is meant to be consumed by github_set_project_field, which it does. Minor gap: no mention of whether the result includes all field types or just single-select ones, but the description already clarifies single-select options are included.

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 both parameters are already documented. The description doesn't add parameter-level detail beyond the schema, but it does clarify the purpose of the output in relation to the setter tool. 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 project's fields and the options for single-select fields, and explicitly connects it to what github_set_project_field expects. This distinguishes it from sibling tools like github_list_project_items and github_set_project_field.

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

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

The description implies when to use this tool: before calling github_set_project_field, to discover valid field names/options. It doesn't explicitly state when not to use it or name alternatives, but the connection to the setter tool provides clear 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?

The description discloses detailed pagination behavior, hard caps, the truncated=True flag, and the downgrade from 'passing' to 'unknown' on partial results. This goes well beyond the readOnly/openWorld annotations and tells the agent how to interpret potentially incomplete data.

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 front-loads the core purpose, and the following two sentences provide necessary edge-case behavior with no filler. The internal constant names make the middle sentence dense, but it remains appropriately sized for a tool with non-obvious truncation semantics.

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 simple required parameters, safety annotations, and an output schema, the description covers the non-obvious pagination/truncation semantics well. It omits general usage context and error/permission notes, but those are less critical for this read-only tool with an 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?

With 0% schema description coverage, the description does not explicitly map repo_owner/repo_name/pr_number to their roles beyond the 'pull request' context. However, the parameter names are conventional and the first sentence implies that pr_number identifies the PR whose HEAD commit is inspected, so a capable agent can infer the required values.

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 clause uses a specific verb ('Return') and a precise resource ('CI check runs and commit status for a pull request's HEAD commit'), which clearly separates it from PR-content siblings like github_get_pr_content or github_get_pr_diff. Even without naming an alternative, the resource is distinctive enough for an agent to identify it.

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

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

No when-to-use context or alternatives are provided; it explains mechanics rather than when to choose this over other GitHub tools. The only usage-related remark is the caution about not acting on a truncated result, which is a caveat, not selection 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 and destructiveHint=false, so the read-only nature is covered. The description adds no extra behavioral context beyond restating the schema's tag_name description (by tag or latest). It does not mention error behavior, rate limits, or authentication, which are not critical for a simple read but are not disclosed either. With annotations covering safety, 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 a single, front-loaded sentence with zero wasted words. It immediately states the action and scope, and the tag/latest distinction is compactly conveyed.

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 tool with an output schema and read-only annotations, the description covers the essential purpose and mode selection. It does not detail error handling or return format, but the output schema presumably covers that, so this is adequate. A 4 is justified because nothing critical is missing for an agent 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 33% (only tag_name has a description). The description's 'by tag or the latest' duplicates the schema's tag_name description and adds nothing new for repo_owner or repo_name, though those are self-explanatory from their names. Since the schema already explains tag_name, the description adds marginal value but does not fully compensate for the two 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?

The description states a specific verb ('Fetches') and a precise resource ('one release'), and clarifies the two modes: by tag or latest. This clearly differentiates it from siblings like github_list_releases (which fetches many) and github_create_release (which writes).

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

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

The description implies when to use it (when you need a single release) but does not explicitly name alternatives or state when not to use it. For instance, it doesn't say 'use github_list_releases for all releases.' The usage is inferred from the wording 'one release' but lacks explicit routing.

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

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

The description goes beyond the readOnly annotation by explaining windowing semantics: 'windowed to limit bytes from offset,' and crucially clarifies that 'bytes_total is the whole file either way and next_offset says where to carry on, so a partial read never passes for the lot.' This prevents a common misreading of truncated responses.

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

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

The description is three sentences with no filler: the action is first, behavior follows, and the boundary to a sibling is last. Every sentence earns its place and the structure is 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?

With a rich output schema and readOnly annotations, the description covers the key behavioral nuance (partial reads) and the main usage boundary (directory vs. file). It doesn't mention error handling or encoding, but those are lower-stakes for a well-schematized read 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 67%, but the description adds meaning for the limit and offset parameters by framing them as a byte window and introducing bytes_total and next_offset as continuation semantics. It doesn't repeat schema fields, adding real value beyond the structured data.

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: 'Reads one file from a repository at ref,' and clearly differentiates from a sibling by noting that 'A directory belongs to github_list_repository_tree.' An agent can immediately tell this tool reads file content, not directory listings.

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

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

The description gives a clear when-not by routing directory operations to github_list_repository_tree. It lacks explicit alternatives for other file-related tools, but the unique 'at ref' and windowed-read behavior makes the context sufficiently clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: counts are based on weekly star history and resolve to whole UTC days, cost scales with page counts and window length, and truncated can be true under two distinct conditions. This is exactly the kind of operational nuance an agent needs.

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

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

The description is front-loaded with the core purpose and example prompt, then adds operational details. All sentences contribute useful information, though the cost explanation is dense and could be tightened. It remains appropriately concise for the complexity of the tool.

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, the description does not need to describe return values, and it covers the important behavioral aspects: input format, defaults, cost, and truncation caveats. An agent can correctly invoke the tool without major gaps. Slightly more explicit mapping of top_n and max_repos to the described behavior would make it fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning. It explicitly documents the since format and default, clarifies username as the repo owner, and explains truncation as it relates to max_repos/listing limits. It does not explicitly walk through top_n or max_repos by name, but their roles are reasonably inferable from the description and schema defaults.

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

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

The description opens with a specific verb and resource: 'Return the repos owned by username that received the most new stars since a given date.' It clearly distinguishes itself from sibling tools like github_list_repos by describing the star-ranking behavior and example prompts. The purpose is unambiguous and immediately actionable.

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

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

The description provides clear context for when to use it: 'Answers prompts like which repos gained the most stars in the last 30 days.' It also gives the default since value and cost behavior, which helps an agent decide. However, it does not explicitly mention alternatives or state when not to use this tool, so it stops short of full exclusion 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=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=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable behavioral nuance by explaining that repo_stars is cumulative, not period-specific, and clarifies date format acceptance. It does not disclose rate limits or pagination, but these are minor given the output schema 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: the first sentence states the purpose, the second covers date formats, and the final sentence adds a critical caveat and alternative. Every sentence earns its place with 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?

Given the output schema exists and annotations cover read-only behavior, the description covers most essential aspects: purpose, filters, date formats, and a notable caveat. However, it omits explanation of max_results semantics and any pagination behavior, which an agent might need. It is still fairly complete for its 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 all parameters. It only explains since/until formats; org, repo, username, and max_results are left undefined. While org and repo are somewhat self-explanatory, max_results and the exact meaning of 'activities' are not clarified. This is a significant gap for a tool with six 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 clearly states the tool's purpose: getting user activities with optional filters. It names the GraphQL API and explicitly contrasts with a sibling tool (github_get_repo_stars_since) for star deltas, which distinguishes it from 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?

Provides explicit guidance on when not to use this tool for star deltas and directs to an alternative. The date format requirements are also clearly stated, giving concrete usage instructions.

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 the useful behavioral detail that each milestone includes an issue count, which is not obvious from the schema. It does not disclose pagination behavior or that the default state is 'open', but these are partially visible in the schema.

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

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

A single sentence that is front-loaded with the action and resource, and adds the distinguishing issue-count detail without any filler. Every word earns its place.

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

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

For a simple read-only list tool with an output schema and readOnlyHint annotation, the description is mostly adequate. However, it does not mention pagination defaults, the state filter, or how the issue count is represented, leaving an agent to infer those from the schema or discover them at runtime.

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 'state' and 'per_page' having descriptions. The tool description does not compensate for the undocumented 'repo_owner', 'repo_name', or 'page' parameters, though their names are fairly self-explanatory. The description adds the issue-count context but no parameter-level detail beyond the schema.

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

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

The description states a specific verb ('Lists') and resource ('a repository's milestones') and adds a distinguishing detail ('with the count of issues in each'). It is clear enough to differentiate from github_list_releases and github_list_tags, though it does not explicitly name a sibling.

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 reading milestone data, and the readOnlyHint annotation reinforces that it is a safe read operation. However, it does not explicitly state when to prefer this over alternatives like github_list_open_issues_prs or github_get_issue, nor does it mention pagination or state filtering as usage considerations.

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 meaningful behavior beyond that: the fixed is:open qualifier and the exclusion of closed/merged items. It does not mention pagination or return format, but the output schema exists and annotations cover the safety aspects, so the added value is solid.

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 waste. It front-loads the core purpose, then immediately states the limitation and routes to the alternative. 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 list tool with a fully self-documenting schema and an output schema present, the description covers the essential context: what it returns (open items only), when to use a different tool, and the fixed qualifier. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema itself. The description adds no new parameter-level details beyond noting that some qualifiers are not exposed, which is more about usage guidance than semantics. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool 'Lists open pull requests or issues', giving a specific verb and resource. It explicitly contrasts with the sibling tool 'github_search_issues_prs' by noting the fixed is:open scope and naming the alternative for closed/merged items, so an agent can distinguish them without inspecting schemas.

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 explicit when-to-use and when-not-to-use guidance: 'The search is fixed to is:open, so closed and merged items are out of reach here' and directs 'Call github_search_issues_prs for those, and for any qualifier this tool does not expose.' This leaves no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about inline comments carrying file/line info, which is behavioral detail beyond the schema. However, it doesn't disclose pagination behavior, default kind, or what the response structure looks like, though the output schema exists. 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 sentences with no filler, and the key differentiator (inline comments carry file/line) is front-loaded. The description is appropriately sized for the tool's complexity. It could arguably be more explicit about usage, but it 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 list tool with an output schema and annotations covering safety, the description is mostly complete. It explains the distinction between comment kinds, which is the main contextual nuance. It doesn't mention pagination defaults or rate limits, but those are minor given the schema and output schema. The sibling list shows related tools, and the description helps distinguish from review-listing tools.

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. The description does clarify the meaning of 'inline' vs 'conversation' comments, which adds value beyond the schema's enum. However, it doesn't explain repo_owner, repo_name, pr_number, page, or per_page semantics beyond what the schema already provides. The baseline is 3 given partial coverage, and the description adds some but not full compensation.

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

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

The description clearly states the tool lists comments on a pull request, with a specific verb and resource. It distinguishes inline comments from conversation comments by noting inline comments carry file/line context, which helps differentiate from sibling tools like github_list_pr_reviews and github_add_pr_comments. However, it doesn't explicitly name sibling alternatives, so it falls short of a 5.

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

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

The description implies usage for reviewing prior comments on a PR ('so a second review can tell what it already said'), which gives some context. It does not explicitly state when to use this vs alternatives like github_list_pr_reviews or github_get_pr_content, nor does it mention exclusions. The kind parameter in the schema adds some guidance, but the description itself lacks explicit routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral detail about GraphQL cursor-based pagination and the need to loop with `after`, which goes beyond what annotations and schema provide.

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

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

The description is two sentences with no filler. It front-loads the purpose and then gives the essential pagination guidance, making every clause informative.

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 safety, the description adequately explains the tricky pagination contract. A small gap remains: `project_owner` and `project_number` are not semantically described, though their names and required status make their role inferable.

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 clarifies the `after` parameter by explaining the cursor loop pattern. However, `project_owner` and `project_number` remain undocumented in both schema and description, so it only partially compensates for the 50% schema description coverage.

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

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

The description clearly identifies the resource ('project board') and action ('Lists what is on a project board with each card's field values'). It differentiates from sibling tools by framing the use as reading a backlog by Status rather than fetching individual issues.

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

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

The description provides a concrete use case and explicit pagination instructions: 'pass next_cursor back as after until has_more comes back false.' It does not explicitly name alternatives or exclusion conditions, but the context is sufficiently 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 cover readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: ordering ('oldest first'), scope ('submitted on a pull request'), and a clear definition of what a review is (as opposed to a comment). It does not mention pagination or empty-result behavior, but given the annotations, this is a minor 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 three sentences, with the primary purpose front-loaded. The second sentence removes ambiguity with a sibling tool, and the third offers a useful usage tip. The trailing 'See #408' is slightly cryptic but not distracting. Overall, each sentence earns its place with no wasted 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?

Given the tool's low complexity, an output schema exists, and annotations cover safety, the description is largely complete: it tells what is returned (reviews with author and verdict), the ordering, and distinguishes from comments. It lacks explicit pagination behavior, but the page/per_page params and output schema likely cover that. The only notable omission is guidance on what happens when no reviews exist, but this is minor.

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% (only page and per_page have descriptions, while repo_owner, repo_name, pr_number do not). The description adds no parameter meaning, failing to compensate for the low coverage. Although these are standard GitHub identifiers, the rubric mandates that low coverage requires description compensation, which is absent here.

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

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

The description states a specific action ('Lists the reviews submitted on a pull request'), a clear resource (reviews), and adds ordering ('oldest first') and content ('author and verdict'). It also explicitly distinguishes from github_list_pr_comments, preventing confusion with a sibling tool. This is a precise, unambiguous 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 an explicit exclusion: 'A review is not a comment… github_list_pr_comments returns what was said on lines and in the thread, not whether anyone approved.' It also directs the agent to github_get_pr_content for requested_reviewers, offering a concrete alternative for a related need. This fully guides when to use this tool versus others.

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 the ordering behavior ('newest first') but does not mention pagination behavior or other operational details. This is similar to the calibration example that received a 3.

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 no wasted words. It front-loads the core action and immediately provides the ordering detail. Every word earns its place.

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

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

Given the tool's simplicity, the presence of an output schema, and annotations that cover the read-only/destructive profile, the description is complete enough for an agent to invoke it correctly. The only missing details (pagination defaults) are already present in the input 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?

Schema description coverage is only 25% (only per_page has a description). The tool description does not compensate for the undocumented repo_owner, repo_name, or page parameters, nor does it explain pagination semantics. With low coverage, the description should add this meaning 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 uses a specific verb ('Lists') and resource ('a repository's releases'), and adds ordering ('newest first'). This clearly distinguishes it from sibling tools like github_get_release (singular) and create/update/delete release tools.

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

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

The description implies the use case (listing releases) but provides no explicit guidance about when to use alternatives such as github_get_release for a single release, or when to avoid this tool. No exclusions or alternative conditions are 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 declare readOnlyHint=true and destructiveHint=false, and the description's 'Lists' claim is consistent with that safety profile. However, the description adds little behavioral context beyond the annotations: it does not mention pagination behavior, whether default labels are included, or any other operational characteristics.

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 no redundant words, and the core verb and resource are front-loaded. This is appropriately sized for a simple read-only list tool.

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 and the output schema plus read-only annotations reduce the need for extensive description. However, usage guidance and pagination semantics are absent, so the description is adequate but not complete on its own.

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 is described), and the description does not compensate by explaining repo_owner, repo_name, or page. While repo_owner and repo_name are fairly self-explanatory from context, the pagination parameters receive no semantic help from the description, leaving a notable 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 verb ('Lists') and resource ('labels defined in a repository'), making the tool's purpose immediately clear. Among sibling list tools such as github_list_milestones, github_list_tags, and github_list_releases, naming 'labels' unambiguously differentiates this 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 gives no guidance on when to prefer this tool over alternatives, nor does it mention exclusions or prerequisites. While the name implies its use case, the description itself does not provide any usage direction beyond the basic action.

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

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

Beyond the annotations' read-only and non-destructive hints, the description discloses the account-type-dependent endpoint behavior and the 404/private-repo caveats for /orgs and /users. This is exactly the kind of hidden behavior an agent needs before selecting an owner value.

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

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

Three sentences deliver the core function and the key endpoint caveat with no redundant wording. The trailing 'See #354' is an internal reference that an agent cannot act on, so the text is not completely waste-free.

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 no required parameters, an output schema, and annotations already covering safety, the description covers the non-obvious endpoint behavior that could otherwise cause failures. Nothing essential is missing for invoking 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 enriches the owner parameter by explaining that account type determines the endpoint, but it does not add meaning for page or sort beyond the schema's type/enum/default conventions. Schema description coverage is only 50%, so some extra parameter explanation would be welcome, though the existing defaults mitigate 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 opening clause 'Lists repositories for a user, an organisation, or the caller' gives a specific verb, resource, and the accepted scopes. This makes it immediately distinct from sibling tools that list releases, tags, milestones, or files.

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

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

The description clearly frames the usage context: listing repositories by user, organisation, or caller. It does not name an alternative, but there is no direct sibling for plain repository listing, so the lack of an explicit 'instead of' is not a material gap.

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 readOnlyHint annotation, the description discloses meaningful behavior: the default is one-level deep, recursive changes that, each entry contains specific fields, and the truncated flag indicates GitHub's cap cannot be widened by paging. This is exactly the kind of non-obvious behavior an agent needs to know.

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 tightly packed sentences lead with the core action, then describe the entry shape and the truncation caveat. Every sentence carries useful information and there is no filler or repetition of schema fields.

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 listing tool with an output schema and annotations, the description is complete. It covers default depth, recursion, entry fields, and the truncation limitation, so an agent can call it correctly without additional context.

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

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

The input schema already documents ref, path, and recursive with clear descriptions, covering 60% of parameters. The description reinforces ref and recursive but adds little beyond what schema descriptions already say; repo_owner and repo_name are self-evident from names.

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

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

The description opens with a specific verb and resource: 'Lists a repository's tree at ref'. It clearly distinguishes this from sibling tools like github_get_repository_file, github_list_releases, and github_list_tags by naming the exact object being listed and the default depth 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 operational context—list a tree at a ref, one level deep unless recursive—but does not explicitly state when to prefer this tool over alternatives such as github_get_repository_file. There are no exclusions or 'use X instead' guidance, leaving the choice mostly implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, 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 and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that each tag entry includes the commit it points to, which is useful context beyond the input schema, but no additional traits like pagination behavior or rate limits are 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 a single front-loaded sentence with no filler. It conveys the essential scope and the key output detail while remaining compact and easy to parse.

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

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

For a simple read-only list operation with an output schema and safety annotations, the description is mostly adequate, but it does not address pagination or when this tool is preferred over related list tools. These are clear gaps given the minimal parameter documentation and the large sibling tool set.

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

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

Schema description coverage is only 25%, so the description carries a heavy burden for explaining parameters, but it does not mention repo_owner, repo_name, page, or per_page. While repo_owner and repo_name are inferable from the resource wording, pagination fields are left undocumented beyond the schema's default values.

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 adds a useful detail about the commit each tag points to. It is clear and immediately recognizable, though it does not explicitly differentiate itself from sibling tools like github_list_releases.

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

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

No guidance is given about when to use this tool versus alternatives such as github_list_releases or github_create_tag. The description implies a read-only listing operation, but there are no explicit conditions, exclusions, or alternative tool mentions.

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, and openWorldHint=true. The description adds no behavioral context beyond 'merges', which is already implied by the name. It doesn't disclose side effects like closing the PR, creating a merge commit, or triggering deployments. However, since annotations cover the safety profile (not read-only, not idempotent, not destructive), the description doesn't contradict them and adds minimal value. A 3 is appropriate because the description is consistent but doesn't enrich the annotation-provided behavior.

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

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

The description is a single concise sentence with no wasted words. It is front-loaded with the action. However, it is so brief that it misses opportunities to add value, but for what it contains, it is efficient.

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

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

Given the tool has 6 parameters, 0% schema description coverage, and an output schema, the description is too thin. It doesn't explain the merge method options, the effect of commit_title/commit_message, or any preconditions. The output schema exists but the description doesn't clarify what the response represents (e.g., merged PR details). For a mutation tool with no parameter documentation, this is inadequate.

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 parameter meaning. It does not. The description only mentions 'a specific pull request' but doesn't explain that repo_owner, repo_name, and pr_number identify the target, nor does it clarify merge_method options (merge/squash/rebase) or commit_title/commit_message overrides. The enum for merge_method is self-explanatory, but the optional parameters' semantics are left entirely to the schema, which lacks descriptions.

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

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

The description 'Merges a specific pull request' clearly states the verb (merges) and resource (a specific pull request). It distinguishes from siblings like github_create_pr and github_update_pr, though it doesn't explicitly name them. The title is redundant but the description is clear enough.

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

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

No guidance on when to use this tool versus alternatives like github_update_pr_branch or github_submit_review. The description implies usage for merging but doesn't state prerequisites (e.g., PR must be open, mergeable, or have required reviews) or when not to use it. Sibling tools exist for related PR operations, but no 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?

With no annotations provided, the description carries the full behavioral burden and mostly delivers: it discloses the Pyodide WASM sandbox, full Python support, streaming enabled by PrefabApp, data injected as globals, and per-call sandbox creation. Gaps remain — no error/exception behavior, no return/output format — and the Args section documents a 'sandbox' parameter missing from the actual schema, which slightly undermines transparency.

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

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

It is long, but for a tool that executes arbitrary user code, the length earns its place: the core purpose is front-loaded, followed by two working examples, the pipe list, a chart snippet, and bulleted layout rules — every section carries actionable guidance an agent needs to produce correct code. It could be trimmed (pipe list and chart example overlap with the components search tool), but the clear sectioning keeps it navigable.

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

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

For a complex arbitrary-code tool with no output schema and no annotations, the description is remarkably complete on usage: syntax, state management, charts, and layout gotchas are all covered. Remaining gaps are the absent return/output format, unclear error semantics, and no explanation of how this tool serves the GitHub PR/issue analysis purpose its name claims.

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 0% (bare 'code' and 'data' properties with no descriptions), so the description must compensate — and it does extensively: 'code' is fleshed out with complete examples, imports, and layout rules, and 'data' gains real semantics ('Values passed via data are available as global variables'). However, it documents a third arg, 'sandbox', that the schema (additionalProperties: false) would reject, which could mislead an agent into passing an invalid parameter.

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

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

The first line states a specific verb+resource ('Execute Prefab Python code in a sandbox and render the result'), and the mechanism is clearly distinct from the github_* CRUD siblings. However, the description never connects to the tool's own name — github_pr_issue_analyser_ui implies GitHub PR/issue analysis, yet there is zero mention of GitHub, PRs, issues, or analysis anywhere. An agent selecting by purpose cannot confirm this is the right tool for the workflow the name advertises.

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 is rich in how-to-write-code guidance (layout patterns, reactive bindings, examples) but never says when to use this tool versus any of the ~50 GitHub siblings or the 'choose' alternative. There is no when/when-not guidance and no exclusions, and it never positions itself within a PR-issue analysis workflow. The pointer to a 'components' tool for lookups is the only nod to an alternative, and it's not framed as selection 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 destructiveHint=true and readOnlyHint=false. The description adds context beyond that: it clarifies that the issue itself stays open and that the card's field values are removed. This disambiguates the extent of destruction, which is valuable.

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 main action front-loaded in the first sentence. It includes only essential information and has no redundant words. It is concise and well-structured.

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

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

An output schema exists, so return values are covered externally. The description explains the side effect on field values and the fact that the issue remains open. It does not mention permissions or reversibility, but for a removal tool this is acceptable. It is fairly complete for a simple operation.

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

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

The schema has 5 required parameters with no descriptions (0% coverage). The description does not explain any of them, failing to compensate for the low coverage. However, the parameter names (project_owner, issue_number, etc.) are self-explanatory, providing minimal inherent clarity, so a score of 2 is warranted.

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: 'Takes an issue or pull request off a project board.' It clearly identifies the resource (project board) and the object (issue/PR), and distinguishes from the sibling github_add_to_project. It also adds nuance about the issue remaining untouched, so it is not a tautology.

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 provide when-to-use versus alternatives. It implies the purpose of removing from a project board, and the sibling add_to_project is the obvious inverse, but no explicit exclusion or condition is given. An agent can infer usage from the action, but guidance is minimal.

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 indicate this is a write operation (readOnlyHint=false) and not destructive, but the description adds little beyond the 'reply' action. It does not disclose permission requirements, the effect on the thread, or response behavior. Given the annotations are sparse, the description should provide more behavioral context but does not.

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

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

The description is a single, clear sentence with no redundancy. It is efficiently written, though it may be too terse to be fully helpful. The front-loading of the key distinction is effective.

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 five required parameters and low schema coverage, the description omits essential context such as how to obtain the comment_id, any prerequisites, or what the expected outcome is. The output schema exists, so return values are not required, but parameter guidance and operational context are missing.

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

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

Schema description coverage is only 20% (only comment_id has a description), and the tool description mentions no parameters at all. It does nothing to compensate for the missing schema documentation, leaving four of five parameters unexplained.

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 'replies' and the resource 'existing review thread', and distinguishes from 'starting a new one'. However, it does not name specific sibling tools like github_add_inline_pr_comment or github_add_pr_comments, so it lacks explicit sibling 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 phrase 'rather than starting a new one' implies when to use this tool, but it does not explicitly name alternatives or provide exclusion criteria. The guidance is present but minimal and relies on inference rather than direct instruction.

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 read-only nature is clear. The description adds the behavioral detail that the tool accepts arbitrary GitHub search qualifiers, providing more flexibility than a simple list. While it does not mention pagination quirks or response format, that is minor given the annotations and output schema.

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

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

Two sentences, no fluff. The main purpose and differentiator are front-loaded in the first sentencewif the alternative is named in the second. Every word adds value.

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

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

Given the annotations and output schema, the description covers the core usage: it targets search of any state (open/closed/merged) and accepts all GitHub qualifiers. It does not mention rate limits or that the query must be URL-encoded, but an agent with GitHub API knowledge should infer that. Overall sufficient for a search 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 covers the 'query' parameter with an example, and query is requiredERSONEN. The description does not add extra semantics for 'page' or 'per_page', but schema already describes per_page (1-100) and defaults. With 67% coverage, the description's mention of qualifiers supplements the query schema, but overall the schema does most of the work.

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

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

Describes a specific verb ('Searches') and resource ('issues and pull requests') with a clear scope (caller-supplied query, qualifiers). Explicitly differentiates from sibling github_list_open_issues_prs by noting that closed and merged items are reachable. Purpose is 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 states the key alternative (github_list_open_issues_prs) and implies why to use this tool (when you need closed/merged items or custom qualifiers). However, it does not explicitly say when NOT to use it or mention potential limitations such as GitHub search API quotas or the need for exact qualifier syntax.

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 provided, the description carries the full burden of behavioral disclosure. It clearly explains the search matching behavior (space-separated terms OR-matched), the automatic detail vs. compact mode based on match count, and the ability to override with 'detail'. It also explains the limit parameter's effect. However, it does not disclose behavior for the 'components' parameter, which is a notable omission for full transparency.

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

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

The description is well-structured, starting with a clear purpose, then usage guidance, then behavior explanation, and ending with parameter details. It is front-loaded with the primary action and efficiently uses paragraphs and bullet points. Every sentence adds value, with 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?

The tool has an output schema (not shown but indicated), so return format explanation is not required. The description covers the search behavior, parameter semantics for most parameters, and provides usage context. However, the 'components' parameter is completely undocumented, which is a gap in completeness for a 4-parameter tool. Otherwise, the description is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 75% (3 of 4 parameters are described in the schema). The description adds extra meaning for query (OR-matching and example), detail (automatic threshold), and limit (context). However, the 'components' parameter has no schema description and is not mentioned in the description, leaving a significant gap. The description adds value for the documented parameters but does not compensate for the undocumented one, 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's function: 'Search the Prefab component library.' It uses a specific verb (search) and a clear resource (Prefab component library), and distinguishes itself from siblings by noting that 'The skill covers patterns and layout; this tool has the API details.' This effectively differentiates it from the skill-related sibling 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 provides explicit guidance on when to use this tool: 'Use this tool to look up exact argument names, accepted values, and usage examples before writing component code.' It contrasts with 'the skill' as an alternative, indicating this tool is for API details. However, it doesn't explicitly state when not to use it or name a specific sibling tool as an alternative, but the context is clear enough.

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

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

The annotations already cover the safety profile (read-only and non-destructive), but the description adds no behavioral detail beyond the implementation note 'using GraphQL API'. It does not mention exact vs partial match semantics, error or no-result behavior, rate limits, or authentication requirements.

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 one concise, front-loaded sentence with the verb and resource clear. The 'using GraphQL API' clause is unnecessary implementation detail, but it does not significantly harm 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?

For a one-parameter, read-only lookup with an output schema present, the description is nearly sufficient. It lacks a brief scoping note such as whether this searches public users or requires authentication, but the annotations and output schema carry most of the remaining burden.

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 0% schema description coverage, the phrase 'by username' is the only explanatory text for the single parameter. It confirms the username string is the search key, but it adds no format details, exact-match expectation, or edge-case behavior.

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 ('Search'), a concrete resource ('GitHub user'), and the lookup key ('username'), so an agent can immediately tell what this tool does. It is distinct from sibling search tools like github_search_issues_prs and getters like github_get_user_activities.

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 intended use is implied: call this when looking up a GitHub user by username. However, the description gives no explicit when-to-use or when-not-to-use guidance and does not compare against any sibling tools, so an agent must infer the selection from 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 convey mutability, idempotence, and non-destructiveness, so the description only needs to add behavioral context. It correctly says 'Updates' but does not disclose whether the assignee list replaces existing assignees, appends to them, or how an empty array behaves.

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

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

The description is a single sentence with no filler or redundant information. It is front-loaded with the action and target, making it easy for an agent to process quickly.

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

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

For a relatively simple tool with an output schema and annotations covering safety, the description is minimally viable. However, because the schema has no parameter descriptions and the description adds little detail, an agent may not know key semantics like replacing assignees or expected username format.

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 by explaining parameters. It only references 'assignees' and 'issue or pull request' generically, leaving repo_owner, repo_name, issue_number, and the expected format of assignees (e.g., GitHub usernames) 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 uses a specific verb ('Updates') and names the exact resource ('assignees for a specific issue or pull request'). It clearly distinguishes this tool 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 intended use is implied: use this tool when assignees need to be changed on a GitHub issue or pull request. However, it does not explicitly mention alternatives or state when not to use it, such as using github_update_issue for other issue fields.

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 states the mutation explicitly ('files', 'takes it off', 'clears the milestone') and adds the implementation detail that the tool looks up the title rather than taking GitHub's numeric ID. Annotations already mark readOnlyHint=false including idempotentHint=true, and the description is consistent with those.

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 concise sentences with no filler. The core behavior is front-loaded, the distinguishing lookup behavior comes second, and the clearing instruction closes it out. Every sentence adds necessary information.

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

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

For a simple four-parameter mutation with an output schema and annotations covering idempotence and destructive intent, the description covers the key behavioral and semantic needs. It does not describe what happens if the milestone title is not found, but the output schema and sibling tools fill most remaining 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 25%, so the description must compensate. It does explain that the milestone parameter is a title and that omitting it clears the milestone, which is critical. However, repo_owner, repo_name, and issue_number rely entirely on their names, which are fairly self-explanatory but not elaborated.

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 action and resource: 'Files an issue under a milestone, or takes it off one.' It also explicitly distinguishes this tool from github_update_issue by explaining the title-lookup behavior, so an agent can tell them apart immediately.

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 explains the key usage nuance: pass a milestone title to set it, omit it to clear the milestone. It also references github_update_issue as the tool this lookup work is kept out of, giving useful context, though it doesn't fully spell out the exact conditions for choosing one over the other.

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 mutation, idempotency, and non-destructive behavior, lowering the burden on the description. The description adds a useful implementation detail—this goes through GraphQL because REST only accepts draft at creation—but it does not disclose side effects, permissions, or 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?

The description is two sentences with no filler. The core action is front-loaded, and the second sentence earns its place by explaining the GraphQL route rather than repeating the action.

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

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

For a simple four-parameter toggle operation with an output schema and annotations covering idempotency and mutation, the description is nearly complete. The only notable gap is the lack of explicit guidance to prefer sibling update_pr for non-draft PR edits, which is minor.

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%, and the description does not compensate for the undocumented repo_owner, repo_name, or pr_number parameters. The draft parameter's meaning is already fully captured in the schema, so the description adds no meaningful parameter information 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 states a specific action ('Moves a pull request between draft and ready for review') and clearly identifies the resource and the two possible states. However, it does not explicitly contrast with sibling tools like github_update_pr, so it lacks direct sibling 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 intended use is implied: call this tool when you need to toggle an existing pull request's draft status. It does not name alternatives or state when not to use it, and the REST/GraphQL note explains the implementation path rather than how to choose between sibling 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?

The annotations already mark this as a non-read-only, non-destructive, idempotent mutation. The description adds genuinely valuable behavior beyond that: it states that an issue not yet on the board is added first and explains why. It does not cover permission requirements or failure modes, but the side effect that matters most is 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?

Two sentences, no filler, and the primary action is front-loaded. The second sentence earns its place by disclosing an important side effect and its rationale.

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 supplies the essential operational context for a 7-parameter write tool: what it sets, how parameters are expressed, and the auto-add behavior. Since an output schema exists and the annotations cover read-only/destructive/idempotence, the missing minute details (permissions, invalid-option errors) do not prevent a competent agent from invoking 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?

With schema coverage at 29%, only field and option have schema descriptions, so the description must compensate. It does clarify the key ambiguity—field and option are human-readable names rather than node IDs—but the other five parameters (project_owner, project_number, repo_owner, repo_name, issue_number) receive no added explanation beyond their conventional identifiers.

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 clause names a specific verb and resource: 'Sets a single-select field on an issue's card.' It also clarifies the input style (names instead of node IDs) and distinguishes the operation from nearby siblings like github_add_to_project and github_get_project_fields, so the agent can identify what this tool does at a glance.

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 this is the tool to use when a single-select project field needs to be set, and it warns that an issue missing from the board will be added. It does not explicitly name alternatives such as github_add_to_project or state when to use that flow instead, so the usage guidance is implied rather than 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 indicate a state-changing operation (readOnlyHint=false), but the description does not add any behavioral context such as authentication requirements, potential conflicts with existing reviews, or that it is a one-time action. It simply restates the basic action without depth.

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

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

The description is a single, front-loaded sentence with no wasted words, but it is too thin to be effective. It is appropriately concise in length but sacrifices necessary detail, earning a middle 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?

For a tool with five parameters, one required enum, and no parameter descriptions, the description is insufficient. An agent cannot determine appropriate usage context, event meanings, or return behavior from this definition alone.

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