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

Annotations declare readOnlyHint=false and destructiveHint=true, and the description adds genuinely useful context that the change is only a proposal pending user confirmation, which softens how the agent should treat the destructive flag. It does not disclose what happens to a pending proposal, whether it expires, or whether multiple proposals can stack, so the added context is partial rather than rich.

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?

Two short sentences with the propose-only constraint and the required agent behavior front-loaded; nothing superfluous. The only defect is accuracy of the status list, not verbosity.

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 destructive, nested-object, conditional-parameter mutation with 25% schema coverage and no output schema, the description omits too much — notably the conditional relationship between new_status and waiting_on, and the fate of additional_information. An agent could invoke it correctly only by reading the schema closely.

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 only 25% and the description does not compensate: it says nothing about when 'waiting_on' must be supplied or that 'additional_information' is stored verbatim. Worse, its status enumeration conflicts with the schema enum, risking an invalid value like 'not-today' being attempted.

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 ('Propose a task status change') and clarifies the write is a proposal, which distinguishes it from a direct mutation like update_task. However, the parenthetical status list ('done/not-today/waiting/blocked/waiting_on_other') does not match the schema enum, which includes open, in_progress, and dropped but has no 'not-today', leaving the agent with a misleading picture of valid targets.

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 clear post-call workflow guidance ('tell the user it is awaiting confirmation'), implying a confirm_change/discard_change follow-up exists. It never names those alternatives or states when a proposal is preferable to a direct update, so the routing decision is only implied.

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