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

Goes well beyond the annotations: it explains the mechanism behind idempotentHint=true ("Stable requestKey and item keys; never change them on retry") rather than merely restating it, declares the wave immutable, states that no provider call or send occurs despite being a write, and names the required authorization (tenant Marketing Owner/write authority). It also flags that missing addresses/lawful basis must be supplied rather than inferred, which is a data-integrity constraint no annotation conveys.

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?

Front-loaded with the action and its explicit-request gate, then layered with idempotency, scope exclusion, parameter hints, ordering and authorization — dense but with no filler. The telegraphic, fragment-heavy style ("No provider call or send.") borders on terse for a reader unfamiliar with the domain.

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 an 8-parameter write tool with nested item/recipient/address objects and no output schema, the description covers purpose, safety profile, idempotency contract, authorization, and the surrounding workflow. Remaining gaps are the meaning of mode/color/dispatchDate and any hint about what the persisted wave returns for the follow-up quote step.

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 whole burden; it does explain requestKey and item keys (stability across retries), campaignKey (groups waves) and profileId (links an imported contact), which are the highest-risk fields. However, it says nothing about mode (simplex/duplex), color, dispatchDate, or the title/campaignTitle distinction, leaving four of eight parameters defined only by their names and enums.

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?

"Persist a tenant-bound campaign and immutable letter wave" gives a specific verb (persist/create) and two specific resources, with the payload scope spelled out (per-recipient texts, postal addresses, language, lawful basis). The clarifier "No provider call or send" separates it from the send-oriented siblings (request_letter_wave_send, confirm_letter_wave_send) without the agent needing to open any schema.

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?

"On explicit request" sets a pre-condition, and the description prescribes an explicit sequence: read get_letter_wave, then quote_letter_wave after explicit price-read permission, which names real siblings. The separation from the send tools is only implied by the scope line rather than stated as routing, so the when-not case is slightly less explicit than it could be.

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