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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is largely covered; the description adds the valuable detail that the result warns if the pause extends past a deadline, and that the change is reversible via resume. It does not explain permission requirements or what happens to a queued nudge already in flight, which keeps it below 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?

Three short lines: behavior first, then when-to-use, then when-not-to-use. No filler, and the most decision-relevant fact (what it stops and how to undo it) is front-loaded.

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?

With no output schema, the description compensates by noting the deadline warning in the result, and it covers both pause and resume paths for a 4-parameter mutation tool. Minor gaps remain around permissions and the effect on already-scheduled nudges, but nothing an agent needs to call it correctly is missing.

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 75% and the YYYY-MM-DD format is already in the schema, but the description supplies the meaning of resume:true (restarts the nudges), which the schema leaves as an undescribed boolean with a default. That is genuine added semantics beyond the structured fields, though 'until' and idempotency_key get no extra depth.

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 ('Stops all Nudges to one Client') plus the two modes: a dated pause and a resume via resume:true. It also names the boundaries against siblings (archive_client, mark_chase), so an agent can distinguish it from set_nudge_plan or send_nudges_now without opening a 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?

Gives an explicit 'Use this when' trigger (client ill, away, or asked for no reminders) and an explicit 'Not for' with the correct alternatives for each exclusion. This is the when/when-not/alternatives pattern at full strength.

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