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

Goes far beyond the annotations (readOnly=false, openWorld=true, destructive=false), disclosing AI spend accounting, premium-engine 3x weighting, overage caps, own-key billing, the two required write/spend permissions, and a 20-per-day-per-workspace rate limit. It also describes background execution, queue-vs-replace semantics, and that a second queued call updates settings.

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?

Purpose and the spend warning are front-loaded, and nearly every sentence carries distinct operational information. However, it is a dense wall-of-text paragraph where the queue/replace rules could be broken out for faster scanning.

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 no-output-schema, side-effecting, cost-incurring operation, it covers permissions, cost model, rate limit, async execution, follow-up tool, and queue/replace behavior. An agent has everything needed to invoke it safely and correctly.

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 100%, so the schema already documents all four parameters and the baseline is 3. The description adds the surrounding workflow semantics — preview is returned until confirm:true, and get_usage should be consulted first — which gives the confirm/previewToken pair operational meaning beyond the schema text.

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+resource ('Start an AI-visibility scan of a project now') and defines the exact scope — every active tracked prompt, on each engine with a key, for the project's passes per prompt. It clearly separates itself from siblings like get_scan_status, update_scan_settings and refresh_rankings by describing what actually gets scanned.

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?

Explicitly routes the agent: call get_usage first and show the user the cost preview, follow execution with get_scan_status, and pass confirm:true plus previewToken only after previewing. It also states the queuing rule when a scan is already running, so the agent knows what happens on repeat invocation.

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