shadowgraph_ack_review

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

The description goes well beyond the annotations by disclosing that the operation overwrites status and acknowledgedAt in place, writes no journal entry, cannot be reconstructed by a rebuild, and that a repeat call restamps it. This is valuable destructive-behavior context that an agent could not infer from the annotations 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?

Three short sentences each serve a distinct purpose: main operation, id source and alternative routing, and side effects. It is front-loaded with the core function and contains no filler or redundant restatement of the tool name.

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?

The definition provides everything needed to invoke the tool correctly: the input id semantics, what operation is performed, how it differs from sibling tools, and the important destructive and non-reconstructible side effects. With the output schema present and the single parameter fully documented, no critical context is missing.

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?

The input schema already covers the id parameter fully at 100% coverage, including its provenance and the warning that it is a signal id rather than a decisionId. The description reinforces that provenance but does not add meaning that the schema does not already provide, so it stays at the baseline for high schema coverage.

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 states a specific action, 'Acknowledge one persisted review signal by id, closing it as open work,' and clearly identifies the resource and scope. It also names sibling tools that handle different operations on decisions, so the agent can distinguish it from shadowgraph_update_status and shadowgraph_supersede.

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?

It explicitly says when to use this tool: to acknowledge a persisted review signal by id and close it as open work. It also gives the alternative routing, 'use shadowgraph_update_status or shadowgraph_supersede to act on the decision,' which clearly communicates the boundary between acknowledging the signal and acting on the decision.

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