Verant

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description goes further by disclosing polling behavior, the concise-vs-full detail modes, the fields of each finding, and the meaning of hidden and reportUrl — genuine behavioral context beyond the annotations.

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?

Four tightly packed sentences, front-loaded with purpose then usage then parameter semantics then output hints. No filler, and the most decision-relevant information (what it is, when to call it) comes first.

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 two-parameter read tool with an output schema, this is complete: it covers purpose, polling loop, parameter modes, and finding shape. Nothing an agent needs in order 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 only 50% (detail has no schema description), but the description compensates by explaining 'concise' as counts plus the first 25 findings and 'full' as everything, including the default. That adds real meaning beyond the enum alone, though scanId gets no elaboration beyond its schema description.

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 opens with a specific verb+resource ('Read the progress and findings of a scan') and ties the scan back to its producers, proofread_url or proofread_site. An agent can immediately distinguish this polling/read tool from the two sibling proofread tools.

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?

It gives an explicit invocation cadence ('every 10 seconds') and termination condition ('stop when done is true (status is not processing)'), plus the required key (scanId). This is exactly the operational guidance needed and there is nothing left to infer.

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

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

Annotations only declare the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds substantial behavior the annotations cannot convey: asynchronous execution (returns a scanId immediately rather than results), the required polling cadence and termination condition, plan gating, and a real cost model ('each checked page uses 1 page of the monthly allowance').

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 sentences, front-loaded with what it does, then eligibility/routing, then the async follow-up and cost. Every clause carries operational information — no filler or restated title.

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?

An output schema exists, yet the description still supplies the one thing an agent needs to act on the result: that the response is a scanId requiring polling via get_scan with a 10-second interval. Plan restrictions and quota consumption complete the picture for a long-running, allowance-consuming operation.

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% and both parameters are documented in the schema, so the baseline is 3. The description restates the same clamp semantics already present in maxPages' schema description ('clamped by the account allowance and page limit') and adds no format, syntax, or default information beyond it.

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 ('crawl a public website from its root URL and proofread every page found') with explicit scope limits (maxPages, plan page limit). It also names the sibling it is not — 'for one page, use proofread_url' — so an agent can distinguish it from proofread_url and get_scan without reading schemas.

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 eligibility ('Pro and Ultra plans only'), an explicit alternative-selection rule ('for one page, use proofread_url'), and the follow-up workflow ('call get_scan with it every 10 seconds and stop when done is true'). When-to-use, when-to-use-something-else, and what-to-do-next are all covered.

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

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

Goes well past the annotations by disclosing the async contract (returns a scanId at once, poll get_scan every 10 seconds, stop when done is true) and the billing consequence (consumes 1 page of the monthly allowance, free accounts limited to 2 pages/month). That is exactly the operational and cost context an agent needs before invoking a non-idempotent, open-world tool.

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 sentences, zero filler, and ordered by importance: what it checks, when to use it, then the mechanics and cost. Every sentence earns its place and nothing is front-loaded incorrectly.

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?

An output schema exists so return values needn't be explained, yet the description still supplies the one thing the schema cannot: how the async result is retrieved and what the call costs. For a one-parameter, fully-described tool this leaves no practical gap.

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% and the single url parameter is already fully documented there ('The public page URL to proofread'). The description only adds the indirect hint that the page must be published/live; it offers no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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 precise verb+resource+scope: 'Check one published web page for spelling, grammar, punctuation, and leftover placeholder text.' The scope word 'one published web page' cleanly separates it from the sibling proofread_site, and the check categories tell the agent exactly what the tool produces.

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 clear trigger conditions ('when the user gives a page URL or asks to proofread, spell-check, or find typos on a live page') and describes the follow-up workflow with get_scan. It never explicitly says when NOT to use it or names proofread_site as the alternative for multi-page jobs, so sibling routing is left to inference.

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