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

Goes well beyond the annotations by disclosing that follow_up dispatches the builder against the mission's open pull request and overrides cached review and QA verdicts, that note dispatches nothing, that a receipt is returned, and that it requires the missions:write token scope against the external SHIP API. These are consequential side effects an agent cannot infer from readOnlyHint=false / idempotentHint=false alone.

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 core action, then branches cleanly by kind, with the restart disambiguation placed after the primary modes. Slightly dense and the trailing doc-link and token-scope sentences could be woven more tightly, but no sentence is filler.

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 3-parameter mutation tool with no output schema, the description covers the missing pieces itself: what it returns ('a receipt saying what was recorded and what it will cause'), the auth requirement, and the external API reference. Nothing needed to call it correctly is absent.

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 real meaning to kind by explaining the downstream consequences of each value (builder dispatch + verdict override vs. pure context recording) rather than restating the schema's enum text. body and issueId are already fully documented in the schema and get no extra treatment.

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+resource ('Tell a mission what to change') and immediately disambiguates the two operating modes (follow_up vs note) plus the confusingly similar 'restart' action. An agent can distinguish this from siblings like start_mission or pause_mission 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?

Explicitly says when to use each mode: follow_up 'to ask for a change' (dispatches the builder), note 'to record context for whatever runs next without starting any work'. It also names a nearby alternative concept (a restart) and states why it is different ('re-evaluates an unchanged pull request ... changes nothing').

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