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

Annotations already declare idempotentHint=true, readOnlyHint=false, openWorldHint=true. The description adds real behavioral context beyond that: a replay returns the original receipt rather than current state, the topic must be re-read after recovery, and request text cannot grant external authorization. These are meaningful operational and security disclosures the annotations do not carry.

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?

Four dense sentences, front-loaded with the core action, then idempotency handling, replay behavior, and the auth caveat. No filler, though the auth caveat is somewhat tangential to selecting/calling the tool.

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 mutation tool with no output schema, the description supplies idempotency semantics, replay behavior, recovery steps, and an authorization caveat, which is substantial. It falls short only in not describing the action variants or expected_revision/conflict handling.

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 100%, including a detailed idempotency_key description, so the schema already carries the parameter burden. The description only reiterates the idempotency_key requirement and adds no format, enum, or revision-handling detail beyond the schema. Baseline 3 is appropriate.

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 specific verb+resource: 'Change an authenticated participant's handoff state.' It is clear this mutates a participant's state, but it never enumerates the action variants (agree, decline, pause, accept, etc.) that the schema's oneOf defines, and it does not name a sibling to contrast with. Clear purpose, weak sibling differentiation.

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 operational guidance for calling ('Save the exact body and required idempotency_key before sending', 're-read the topic after recovery') but never states when to use this tool versus peerlookup_set_outcome, peerlookup_reply, or other siblings. Implied usage only, no explicit when/when-not routing.

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