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

Annotations already declare readOnly/closed-world/non-destructive, so the bar is lower, and the description still adds useful semantics: the full status enum in prose, the notion of permanently failed checks versus transient ones, 'budget pause', waitingToStart, and that estimate methodology is delivered in a howToRead field. It doesn't discuss polling cost or rate limits, which is the remaining gap.

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, front-loaded with the payoff (what progress data you get), followed by input provenance. The long field enumeration is dense but each item is a distinct returned value, so it earns its space; slightly list-heavy.

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?

No output schema exists, so the description correctly carries the return-shape burden and does so by naming each field plus the howToRead explainer. Safety is covered by annotations. Missing only operational detail such as whether repeated polling is expected or what an absent jobId yields.

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 100%, so the schema already documents all three params, and the description largely restates them (jobId from run_scan). It does add one thing the schema doesn't state clearly — that projectId/clientId resolve to the most recent scan — but the added meaning is modest.

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?

Opens with a specific resource and intent ('Progress of an AI-visibility scan') and then enumerates exactly what the caller receives: status values, finished/failed check counts, timestamps, error or budget pause, waitingToStart, estimatedMinutesLeft. It is unambiguously a status-reader and is clearly distinguished from its sibling run_scan, which it names as the source of jobId.

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?

Tells the agent how to obtain the key input ('jobId comes from run_scan') and how the selector params behave ('projectId or clientId selects that project's most recent scan'), which is real routing guidance. It stops short of saying when to prefer projectId over clientId or how often to poll, so no explicit exclusions.

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