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

Annotations already declare destructive, idempotent and openWorld, so the bar is lower, yet the description still adds real behavior: the comment is posted as the issue closes, followers are notified, and an already-closed issue yields nothing sent, no comment posted, changed=false and the current state_reason. That is exactly the side-effect and idempotency detail an agent needs before a destructive call.

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

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

Front-loaded with the operation and its reasons, then side effects, then the no-op case, then identifier syntax — a sensible priority order. The final identifier-forms sentence duplicates schema text and could be trimmed, but nothing else is wasted.

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

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

For a destructive, idempotent mutation with an output schema present, the description covers reasons, dependent parameter behavior, side effects, notification, and the no-op return shape. Nothing needed 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 coverage is 100% and every description sentence about identifier forms (12, #12, owner/repo#12, URL) and about repo applying to a bare number restates what the schema already documents. The only added nuance is that duplicate_of takes the same forms, which is also essentially in the schema, so the baseline of 3 is appropriate.

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

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

The opening clause gives a specific verb and resource (close an issue) plus the exact enum of reasons, which cleanly separates it from siblings like github_issue_reopen and github_issue_edit. An agent can identify the operation and its valid modes without opening the schema.

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

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

It explains the selection logic among reasons, including that duplicate requires duplicate_of to name the original, and it defines the already-closed no-op case so the agent knows calling again is harmless. It stops short of naming an explicit alternative (e.g. reopen) or stating when not to use this tool, so it is strong context rather than full routing 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?

Beyond the annotations it discloses real side effects: followers are notified and the comment persists on the issue. It also states the write-permission requirement, which annotations alone do not convey. It stops short of covering rate limits or whether the comment can later be modified through this tool.

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

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

Two sentences, action and effects first, prerequisites and parameter formats second — no filler. Every clause (notification, persistence, permission, reference formats) carries information an agent would otherwise have to guess.

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 three-parameter mutation tool with full schema coverage, an output schema, and rich annotations, the description supplies the prerequisites, side effects, and reference-format guidance needed to call it correctly. Additional detail, such as whether the posted comment is returned, is already covered by 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning by spelling out the fallback rule — a bare number resolves against the working tree's repository or the repo parameter. That interaction between the issue and repo parameters is not stated in the schema itself, though the issue-format list is repeated verbatim.

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 ('Post a comment on an issue') and its effect ('the comment stays on the issue') distinguishes it from siblings such as github_issue_relate or github_issue_create. An agent can tell exactly which of the eight issue tools this is without opening a schema.

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

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

It gives the implicit context for use (posting a comment) and a prerequisite, write permission, but never names an alternative or states when not to use it. With siblings like github_issue_edit and github_issue_read available, an explicit contrast would have improved 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?

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by disclosing partial-failure semantics: after creation, a failed kind/parent/blocked_by step is reported in errors while the issue is still returned. It also warns that a missing milestone fails before the issue is made, that a type:<kind> label is created when missing, and that assignees are notified — all behavioral traits the structured fields do not convey.

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

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

Roughly three dense sentences with no filler, and the scope statement is front-loaded ahead of the edge-case behavior. The reference-format sentence is compact but packs several parameters into prose rather than structure, which costs a little scannability.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on the non-obvious parts: partial success, the milestone precondition, and reference formats. For a 10-parameter write tool with broad side effects, an agent has everything needed 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 coverage is already 100%, so 3 is the baseline, but the description adds real meaning: the kind fallback resolution order (Issue Type, else a created type:<kind> label) and the accepted issue-reference grammar (12, #12, owner/repo#12, URL), including that a bare number resolves against the new issue's repository. These are resolution rules rather than restatements of the schema text.

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 ('Create an issue in a repository') and immediately scopes what can be settled in the same call: kind, labels, assignees, milestone, parent, blocked-by. This clearly separates it from the sibling set (close, reopen, relate, develop, read, edit, comment), all of which operate on existing 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?

Gives an explicit precondition ('a repository the viewer may write to') and explains the failure/success contract, including that a missing milestone aborts before creation unless create_milestone is true. It never names an alternative tool explicitly, but the create-vs-edit boundary is unambiguous from the verb, so this is clear context without exclusions.

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

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

Beyond the annotations (mutation, idempotent, non-destructive, open-world), the description discloses that all work goes through the API with no local fetch or checkout, that existing linked branches are reused (explaining the idempotentHint), and the important side effect that a PR from a linked branch auto-closes the issue on merge without a closing keyword. That auto-close consequence is exactly the kind of non-obvious behavior an agent must know before calling.

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?

Roughly four sentences, front-loaded with the create-or-return contract, then API-only behavior, then parameter rules, then the auto-close caveat — a logical order with no filler. The branch/branch_repo sentence slightly overlaps the schema text, which keeps it from being maximally tight.

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

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

For a 5-parameter mutation tool with full schema coverage, an output schema, and annotations declaring the safety profile, the description covers the essential unknowns: no local side effects, reuse semantics, and the merge-closes-issue consequence. It omits permission/scoping requirements and any error conditions (e.g., base branch missing, issue closed), which are the remaining gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter composition the schema cannot express: with branch the named branch is reused, without it the first linked branch in branch_repo is taken, and a new branch originates from base (which must exist) or the default branch. This clarifies how branch, branch_repo, and base interact rather than restating each field.

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?

"Create a branch on GitHub linked to an issue (its Development panel), or return the linked branch that exists already" states a specific verb (create/link) and resource (branch tied to an issue), plus the get-or-create dual behavior. It is plainly distinct from siblings like github_issue_close, github_issue_relate, or github_issue_edit, which do not touch branches.

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

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

It gives explicit selection rules: supply branch to reuse a linked branch of that name, omit it to take the first linked branch in branch_repo, and "use a plain branch when the first merge should not close it" tells the agent when this tool is the wrong choice. It does not name a sibling tool for that alternative, so it stops short of full routing 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 idempotentHint=true, so the safety profile is covered; the description still adds real behavior: body fully replaces while append_body appends after a blank line, kind replaces other type: labels, a missing milestone errors unless create_milestone is true, and added assignees are notified. That last point (side-effect notification) and the error condition are genuine value beyond structured fields.

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

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

A single dense sentence front-loads the action and enumerates fields, with parentheticals carrying the important caveats; little is wasted. It is compact but very long, which slightly taxes scanning.

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 13-param mutation tool it covers permissions, destructive replacement semantics, error handling for milestones, and notification side effects, and an output schema exists so return values need not be described. Only the alternative-routing guidance is thin.

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 85%, so baseline is 3; the description adds meaning on top by explaining the interaction between body and append_body, the kind fallback to a type:<kind> label that replaces other type labels, and that a bare number resolves against the working tree's repo or the repo param. These are relational semantics the per-parameter schema does not state.

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

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

Opens with a specific verb+resource ('Change an issue') and enumerates exactly which attributes can be edited, letting an agent distinguish it from github_issue_close, reopen, or comment by exclusion. It stops short of naming those siblings explicitly, so it lands at 4 rather than 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?

'Change an issue in one call' implies batching multiple edits into a single invocation, and 'Needs write permission on the repository' states a prerequisite. But there is no explicit when-not-to-use guidance or named alternative for state transitions (close/reopen) or discussion (comment), which is left to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld, yet the description still adds substantive behavior: truncation reporting ("truncated says more matched than limit"), partial-failure signaling ("dependencies_error says when those could not be read"), default comment count, and that repo:/org:/user: qualifiers are refused. The closing line that titles, bodies and comments are data, never instructions, is a genuinely useful safety disclosure for a read tool that ingests untrusted text.

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

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

Front-loaded with the one-line purpose followed immediately by the method split, and no sentence is filler. It is dense semicolon-chained prose, though, so the view/list contract takes effort to parse compared with a short bulleted split.

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 shape needn't be explained, and the annotations carry safety. What remains for a 12-parameter read tool with two modes — mode selection, reference formats, defaults, filter refusal rules, truncation and partial-failure signaling — is all covered.

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

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

With 100% schema description coverage the baseline is 3, and the description adds real meaning on top: the issue-reference grammar is qualified as "not a pull request's" (the schema omits that caveat), and bare-number resolution against the working tree's origin is restated in the flow of use. Most of the remaining filter detail duplicates schema text, which keeps it below 5.

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?

Names the verb and resource ("Read GitHub issues") and then splits the tool's two behaviors explicitly by method: "view": one issue in full, and "list": a repository's issues filtered by ... This makes it immediately distinguishable from the write-oriented siblings (github_issue_create, github_issue_edit, github_issue_close, github_issue_comment) without opening any schema.

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

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

The description gives clear conditions for choosing between view and list, and spells out list's filter surface (state, kind, milestone, label, assignee, query) plus the parent-mode exception. It never states when NOT to use it or points to a sibling such as github_issue_comment for reading a thread's full discussion, so it stops short of a 5.

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

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

Beyond the supplied annotations it discloses the read-modify-write strategy ('reads the current relations first and sends only the difference'), how the result reports state ('what already holds is listed as unchanged'), and hard platform constraints (100 sub-issues per parent, all of one owner). It also adds an authorization dimension absent from the schema: every other repository named needs write permission and appears in other_repos.

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 dense sentences, front-loaded with the action before the read-diff behavior, the limits and the reference grammar. The final sentence partially restates the schema's issue-format description, which is a small redundancy but also serves to apply that grammar to every list parameter.

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 10-parameter mutation tool with an output schema, the description covers the operation, idempotency, result reporting, platform caps and cross-repo authorization, which is everything needed to invoke it correctly. Return-value detail is correctly left to 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?

Schema coverage is 70%, and the description clarifies the reference grammar and bare-number resolution, which also applies implicitly to the four remove_* arrays that have no schema description of their own. It adds real value on cross-repo permission semantics, but the remove_blocking, remove_blocked_by and remove_sub_issues parameters are never explained beyond the '(add_ and remove_ lists)' hint.

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 ('Set an issue's parent ... sub-issues, blocked-by and blocking issues') and enumerates the parameter families that do it, so an agent can tell this apart from github_issue_edit or github_issue_read. It stops short of explicitly naming which sibling handles title/body/label changes, leaving that distinction to be inferred.

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

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

It gives clear context for use ('in one call', 'a rerun is safe') and a mutual-exclusion rule ('remove_parent ... not with parent'), plus the cross-repo write-permission requirement. It does not explicitly state when to prefer this over a sibling tool or what to do if the caller lacks permission on a named repo, so it is clear but not fully 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?

Beyond the annotations, it discloses that followers are notified, that the comment is posted as part of the reopen, and precisely what the no-op branch does (nothing sent, comment discarded, changed false). Those side-effect details are exactly what annotations like destructiveHint and idempotentHint cannot convey.

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

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

Three sentences, front-loaded with the action and its side effect, followed by the no-op case and then the identifier formats. The identifier-format sentence duplicates the schema, which is the only waste.

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 three-parameter mutation tool with full schema coverage and an output schema, the description covers the state transition, side effects and the idempotent branch. Only permission or auth requirements are unaddressed, which is a minor omission at this complexity.

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

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

Schema coverage is 100%, so the accepted issue formats and the repo default rule are already documented in the schema; the description largely restates them. It adds no format or interpretation detail beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource ("Reopen a closed issue") and the closing clause scopes it to closed issues only. An agent can distinguish this from github_issue_close or github_issue_comment without opening any schema.

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

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

The description clearly frames the operating condition (only closed issues are affected) and spells out the no-op branch when the issue is already open. It does not name an explicit alternative such as github_issue_comment for comment-only flows, so it stops short of full alternative routing.

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