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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuine context beyond them: pause/stop take effect only after in-flight batches, a queued batch is cancelled and refunded, and resume continues from where it left off. This is useful mutation semantics. It still omits whether stop is irreversible and what state the search ends in.

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?

A single sentence with a parenthetical, zero waste, but the most important element — the primary statement of what the tool does — is absent, so it is under-specified rather than well-structured. The action semantics are front-loaded, but the reader must reconstruct the purpose.

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 an output schema and rich annotations, the description needn't explain returns or safety. However, for a destructive control tool it should state valid preconditions (which search states each action accepts) and whether stop is final; those gaps leave an agent guessing about error cases.

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 50%: campaign_id is documented in the schema, but the action enum has no per-value descriptions. The description compensates by explaining what pause, stop (queued batch cancelled and refunded) and resume actually do, which is meaning an agent cannot get from the bare enum. It says nothing extra about campaign_id beyond the schema's own pointer.

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?

The description never states the primary action ('pause, resume or stop an advanced search'); it only explains the timing semantics of those actions, leaving the title and name to convey purpose. An agent can infer the verb+resource, but the description itself is close to a restatement of the action enum. No differentiation from siblings like run_advanced_search or get_advanced_search.

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?

There is no explicit when-to-use guidance, no prerequisites (e.g. the search must be running to pause, or paused to resume), and no routing against alternatives such as run_advanced_search or get_advanced_search. Only the action enum and the phrase 'resume carries on' imply usage.

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