update_issue_description_patch

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

The description discloses the critical behavioral facts: it modifies the issue description when not dry-running, requires issue-edit permission, and returns either a patch result or a mismatch/validation/permission error. It also explains dry_run's preview behavior. Since annotations carry only openWorldHint (with no readOnly or destructive hints), the description correctly assumes the burden of disclosure. It could add details about reversibility, but the main side effects are covered.

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

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

The description is front-loaded with the core verb and resource, then moves to purpose, usage guidance, and finally behavioral notes. Every sentence serves a distinct purpose without redundancy. It's a compact paragraph that an agent can parse quickly and without ambiguity.

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?

Because there is no output schema, the description dutifully explains the return value ('patch result or a mismatch/validation/permission error'). It covers the primary use case, key options, and permission requirements. It could explicitly name update_issue as the alternative for full updates and elaborate on when to use each patch_type, but the core information an agent needs to call it 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 coverage is 100%, so the parameters are already documented, giving a baseline of 3. The description adds value by explaining the role of dry_run and create_note, and how patch_type maps to 'search/replace or unified diff'. It also mentions token reduction, which contextualizes the tool's purpose. The allow_multiple parameter is not highlighted, but the schema explains it; overall the description goes 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 opens with a precise verb 'Apply' and resource 'patch to an issue description', and explicitly names the two patch formats (search/replace, unified diff). It also states the intended benefit (token reduction) and clearly differentiates this from full-description replacement tools like update_issue. This is far from a tautology and gives an agent an unambiguous understanding of the tool's core function.

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 strategical guidance: use dry_run for uncertain patches, create_note when an audit summary is wanted, and positions the tool for targeted changes. Though it doesn't explicitly mention update_issue as an alternative, the phrase 'targeted' implies that larger or full changes are handled elsewhere. This is sufficient to route an agent to the right action.

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