write_coach_resolve

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds genuine context beyond them, namely that the tool clears the proposal, that 'dismissed: true' throws it away, and that no plan changes occur. It omits any auth/permission requirements or confirmation behavior for a destructive operation.

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?

Tight and front-loaded, with the primary action first and the argument shapes after. The telegraphic fragments are efficient but slightly at the expense of 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?

For a three-parameter, no-output-schema mutation tool, the description covers the main ambiguity an agent faces (what to put in 'accepted' per proposal type) and points to read_coach for the apply-then-resolve workflow. It does not describe the return value or confirm success semantics.

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%, so the description carries the burden and does so: 'accepted' and 'rejected' hold change ids for a review, 'accepted' holds ['plan'] for a plan and ['debrief'] for a debrief, and 'dismissed' is a boolean discard flag. This is real meaning beyond the bare array/boolean types, though the mapping could be spelled out more explicitly.

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 ('Record the decision on the waiting Coach proposal and clear it'), which is clearly distinct from the adjacent write_coach_request/share and delete_coach_data siblings. The sentence-fragment examples ('A review: accepted and rejected change ids') make the core action slightly harder to parse than it needs to be, so it stops 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?

Gives real sequencing guidance: this does not change the plan, so apply accepted items with leap write tools first, deferring detail to howToApply in read_coach. It does not state when this tool should NOT be used relative to the alternatives, so it is not a full 5.

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