dhp_effect_done

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

With no annotations, the description carries the burden and does disclose the null-vs-recorded-result semantics and the intended idempotency-check role. It says nothing about permission requirements, whether the check mutates state, or any rate/locking behavior in a concurrent recovery workflow, leaving meaningful gaps.

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, purpose first, return behavior second, usage condition last. No filler and nothing repetitive.

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 output schema covers the returned value so the description need not expand on return format, and it sensibly notes the null case. However, with no annotations and zero parameter documentation, the definition leaves the agent without enough to invoke it confidently on unfamiliar identifiers.

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% and neither parameter is described in the schema, yet the description never mentions handoff_id or step_id. It conveys only that the check is scoped to a step, so the two required identifiers remain semantically unexplained.

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: checks whether a side effect already happened, and contrasts implicitly with the recording side of the pattern (dhp_record_effect). An agent can tell it is an idempotency lookup rather than a mutation, though no sibling is named explicitly.

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 a concrete trigger condition: 'Call before re-executing a side effect after recovery.' That is actionable context with a clear lifecycle placement, but it does not state when not to use it or name a specific alternative tool such as dhp_record_effect.

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