prepare_handoff

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

The description frames the tool as a "Preview" that "sends nothing," which reads as a side-effect-free read, while annotations declare readOnlyHint=false and destructiveHint=true with idempotentHint=false. It does add genuine behavioral context the schema lacks (no arbitrary text, location or sensitive context accepted), but the preview framing materially understates the mutation and non-idempotency the annotations promise.

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?

Two short sentences with the no-side-effect constraint front-loaded and zero filler. The sizing is appropriate; the problem is thinness of content rather than verbosity.

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 non-idempotent, destructive-hinted mutation tool with no output schema and 0% schema coverage, the description says almost nothing about what the preview produces, whether anything is persisted, or what happens on repeat calls. An agent cannot predict the result or the state change from this text.

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 carries the full burden for the two parameters and largely fails it: contact_id is never mentioned, and the template enum (check_in, hi, tea) is only obliquely gestured at by "one plain check-in." No format, UUID requirement, or effect of template choice is conveyed.

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?

"Preview one plain check-in" gives a verb and an object, but the tool is named prepare_handoff and the description never says what a handoff is or how the preview relates to it. The sibling prepare_poke and send_trusted_message are not distinguished, so an agent cannot tell which preparation path to pick from the text alone.

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?

"sends nothing" implies this is a safe pre-flight step before send_trusted_message, but the guidance is only implied. There is no explicit when-to-use, no exclusion against prepare_poke or cancel_handoff, and no statement of what an agent should do with the preview result.

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