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

The description goes well beyond the annotations: it explains that decision_md is appended as an audit trail, that resolving a project_pause/orphan_pause resumes the project, that the acknowledgement is replay-guarded but the call is not idempotent end to end, and that queued refinement can DELETE tasks. This materially enriches the destructiveHint and idempotentHint flags without contradicting them.

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?

Every sentence earns its place: the opening states the primary guard, the middle covers parameter semantics and side effects, and the closing defines accepted ID formats. The description is dense but not padded, and critical warnings are front-loaded.

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?

Given the tool's destructive, non-idempotent, and conditional behavior, the description covers the key decision criteria, parameter usage, side effects, alternatives, and valid ID forms. It is complete enough for an agent to know when to call it, how to fill the arguments, and what consequences to expect.

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 carry parameter meaning, and it does. It defines decision_md as a required short note explaining why/how it was resolved and where it goes (detail_md). It defines escalation_id by its accepted forms: a real escalation UUID or a synthetic 'orphan:<project_id>'. Both parameters receive meaning the schema alone does not provide.

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 names a specific action ('Acknowledge a handled ask') on a specific resource (an escalation) and states the precise condition under which it applies ('only when no blocked task becomes invisible'). It also differentiates from siblings by explicitly saying a blocked task's final task_block/operator_action must be handled via retry, platform-policy resolution, replan, close, or supersede operations instead.

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 when-to-use gate ('only when no blocked task becomes invisible') and spelling out alternatives by operation type, which map to sibling tools like retry_blocked_task, resolve_platform_policy_conflict, replan_task, and close_task. It also clarifies when not to acknowledge and what side effects to expect for paused projects.

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