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

Annotations already mark the tool as destructive, but the description goes well beyond that by specifying exactly what gets affected: 'can EDIT OR HARD-DELETE the task rows it generated earlier,' explains the deletion mechanism ('the machine patch-tasks endpoint deletes them outright'), warns 'treat this as destructive,' and adds a limit ('up to five refinements per thread each carry that power'). It also discloses the state transition ('Moves the thread to refine_pending') and the re-planning side effect. This is substantial behavioral disclosure that annotations alone do not provide, and it is consistent with destructiveHint=true.

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 about 80 words, front-loads the purpose in the first sentence, and then packs in only high-value information: the status precondition, feedback length, state transition, follow-up polling, side effects (re-planning, editing/deleting tasks), destructive warning, and limit. Every sentence earns its place; the technical aside about the patch-tasks endpoint explains the mechanism without redundancy.

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

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

For a tool with an output schema and destructive side effects, the description covers the essential operating context: when it can be used (status done), the input constraint (feedback length), what happens to the thread state, how to observe results (poll get_request_status), the scope of side effects (re-plans roadmap, edits/deletes tasks), and the limit of five refinements. There is no requirement to explain return values because an output schema exists, so the description is complete for correct invocation and expectation-setting.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for feedback_md by specifying the character range ('1..2000 chars') and the status precondition, but it does not explain project_id or thread_id beyond their names. These are standard identifiers and likely self-evident, but with zero schema descriptions, a full compensation would require at least a sentence clarifying their role. The description partially fills the gap, earning a 3.

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-resource pair: 'Say what is wrong with what a request produced, and have it reworked.' This clearly distinguishes refine_request from siblings like submit_request (initial submission) and answer_request (responding), and the later mention of polling get_request_status differentiates its purpose from status-checking tools. The phrase 'have it reworked' plus the detailed mechanics make the purpose unambiguous and distinct.

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

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

The description gives an explicit precondition: 'Status must be "done".' It also tells the agent what to do after invocation: 'poll get_request_status to see the revised items,' implicitly naming the alternative for checking status. It does not explicitly say 'use this only when status is done and avoid manual editing tools,' but the condition and outcome guidance are clear enough to route the agent correctly.

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