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

Annotations already declare readOnlyHint and non-destructive, but the description adds real behavioral texture: the link carries per-step receipts, an in-browser hash check, which AI ran each step, and an explicit 'what was not checked' surface. It does not mention that the handover is published (visibility defaults to public) or that a Zambo access capability may be required, which matters for a tool whose output leaves the machine.

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 sentences, zero filler, with the artifact definition front-loaded before the invocation trigger. The middle clause stacks a long list of package contents, but every item adds a distinct capability the agent would otherwise miss.

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 return values need not be described, and the description covers the trigger plus the shape of the deliverable. For a 21-parameter tool with nested redaction, payment, branding and deliverable objects, though, the absent explanation of the safety- and disclosure-relevant parameters (redact, shield, visibility, dry_run, acknowledge_warnings) leaves the definition short of what an agent needs to invoke it correctly.

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 24% across 21 parameters, so the schema is doing very little work and the description must compensate — yet it names no parameter at all. High-impact inputs such as redact mode/auto_pii, shield, dry_run, visibility, payment, not_run/not_checked, and acknowledge_warnings are left entirely to the agent's inference from bare property names.

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 artifact — 'Package the work from this session ... into one client-ready link' — and enumerates what the package contains (receipts, hash check, AI attribution, unchecked items, Accept/Flag buttons). That is far more than the title 'Handover' conveys. It stops short of differentiating itself from siblings handover_list and handover_status, so the agent must infer that this is the create action and those are the query actions.

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 an explicit trigger: 'Use when the user says "Use zambo to hand this over to <client>"', which is unambiguous context for invocation. It offers no when-not guidance and does not point to handover_list/handover_status for inspecting or re-checking an existing handover, so the alternative-selection half of the rule set is absent.

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