handoff_read

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' is redundant. However, it adds non-obvious behavioral details: the tool returns {error: not_party_to_dispatch} when app_id is not a party to the dispatch, and it ties this to a specific issue/ticket (B-54, #242) and to the same check in dispatch_read. It also clarifies the tool reads two distinct artifacts. This is meaningful disclosure beyond the annotations.

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?

The description is front-loaded with the core purpose, then usage, then an error condition. It is three sentences with minimal fluff. The inclusion of the issue reference 'B-54, issue #242' is somewhat noisy but provides traceability. Overall it is efficient and avoids redundancy, though it could be tightened by dropping the redundant 'Read-only' given the annotation.

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 read-only tool with two parameters and no output schema, the description covers the main purpose, usage context, and a key error case. However, it leaves out essential details: it does not describe the structure of the return value (beyond the error), does not explain dispatch_id at all, and does not mention any pagination or content format of handoff.json. The annotations cover safety, but the agent still lacks enough to fully anticipate the tool's behavior without external context.

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 compensate for the undocumented parameters. It provides only a partial hint about app_id—its role in the party check as 'from_app, to_app, reply_to, or orchestrator'—but never defines what either parameter means, their expected formats, or how dispatch_id is used. An agent cannot infer from the description alone what values to supply for dispatch_id or how app_id should be structured, which is a significant gap given zero schema help.

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 opens with a precise verb and resource: 'Read the closeout of a completed dispatch: the structured handoff.json findings plus the closeout.md narrative.' It names the exact artifacts read, and immediately distinguishes its role from siblings by noting it is what the orchestrator reads before verify_handoff and what a successor agent reads. It also contrasts with dispatch_read via the shared party-check reference, so the agent can tell them apart.

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 explicitly states two usage scenarios: 'What the orchestrator reads before verify_handoff, and what a successor agent reads to pick up the thread.' This gives clear context for when to invoke it. It does not explicitly list exclusions or when not to use it, but the phrase 'same packet-party check as dispatch_read' hints at a sibling that behaves similarly, implying a selection criterion. The lack of an explicit 'use X instead when...' is a minor gap.

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