Relate GitHub issues

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.