Check the status of a handoff by ID to view its state, checkpoints, owner, and result, enabling monitoring of durable agent execution.
Status of a handoff: state, checkpoints, owner, result if completed.
| Name | Required | Description | Default |
|---|---|---|---|
| handoff_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It implicitly discloses the read-only nature by describing a pure status read and lists the fields returned, which is useful. However it says nothing about what happens with an unknown or expired handoff_id, whether results are cached, or any permissions required for a completed handoff's result.
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?
A single tight sentence with no filler, front-loading the resource and then the returned facets. It is a noun fragment rather than a clause, which slightly weakens the lead, but nothing is wasted.
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?
An output schema exists, so enumerating state/checkpoints/owner/result in the description is partly redundant. With no annotations and an undocumented parameter, the definition leaves the agent to infer error behavior and handoff_id provenance; for a simple one-param read tool this is adequate but not fully rounded out.
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 0% with one required parameter, and the description never mentions handoff_id — no format (UUID? opaque token?), no source (returned by dhp_dispatch or dhp_claim), no existence requirement. The parameter name is self-explanatory, which is the only thing keeping this above a 1, but the description adds nothing.
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?
It names a specific resource (a handoff) and the read operation (fetching status), and enumerates the facets returned: state, checkpoints, owner, result. That distinguishes it from dhp_last_checkpoint (checkpoint-only) and dhp_health (system-level), though it never names a sibling explicitly. The fragmentary phrasing 'Status of a handoff' lacks a verb but is unambiguous.
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?
There is no when-to-use guidance, no condition selecting this over dhp_last_checkpoint, dhp_health, or dhp_approval_status, and no stated prerequisites (e.g. the handoff must exist). Usage is only implied by the tool name and the returned-fields list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.