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

Annotations only say write, destructive, idempotent; the description adds real substance beyond them: state-gated editability, the monotonic constraint on attempts, the SCHEDULED audience exclusion, partial-update semantics ("Send only what changes"), and the side-effect disclaimer ("never sets consent and places no call"). It does not explain the destructiveHint flag or what happens to fields omitted in a given state, so it stops just short of a 5.

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 core action, then state rules in ascending restrictiveness, then exclusions. Telegraphic but every clause carries a rule an agent must obey; nothing is redundant.

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 14-parameter nested mutation with no output schema, the description covers the hard parts: state gating, partial updates, and sibling boundaries. The only gap is the response shape after a successful update, which nothing else documents since there is no output schema.

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 coverage is 86%, so the baseline is 3, but the description adds state-conditional meaning the schema cannot express (audience not editable while SCHEDULED, attempts can only increase, PAUSED allows only a named subset). That is genuinely useful routing information for choosing parameters, though individual field formats are left to the schema.

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 resource ("Change the settings of a voice campaign") and immediately differentiates itself from the campaign-lifecycle siblings by scoping exactly what part of the campaign is mutable. The state-by-state breakdown lets an agent tell instantly whether its intent belongs here rather than in launch/pause/delete.

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 explicit when-to-use rules keyed on campaign state (DRAFT/PAUSED/SCHEDULED/running) and names the blocking alternative for the excluded case ("a running campaign cannot be edited: pause it first"). It also routes contact membership to add_voice_campaign_contacts and remove_voice_campaign_contacts and excludes consent changes, so the agent knows which sibling to pick for each sub-intent.

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