quanticdata-mcp

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds meaningful behavior beyond that: the asynchronous execution, the returned job id, the polling obligation, and the summary-mode payload distinction. No contradictions with 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?

Two sentences with no filler; the core action and async model are front-loaded, and the mode guidance is a meaningful second sentence. Every clause earns its place.

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?

Covers the essential invocation model: async batch, job id, polling via batch_status, and the main mode decision. The schema handles parameter syntax, though the description could briefly mention default-mode results or result shaping, which is a minor gap for an async tool with no output schema.

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?

The schema already has 100% parameter coverage with descriptive enum and field text. The description still adds semantic value by explaining the 'shared options' concept and detailing what summary mode returns (title, description, canonical, contentLength) versus full page content.

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 pair ('Scrape many URLs asynchronously') and clearly signals an async job model. The 'many URLs' framing separates it from single-URL siblings like scrape, and the mention of batch_status immediately ties the batch API to its status companion.

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 a concrete use condition ('For SEO/status audits over many pages set mode 'summary'') and implies batch is for multi-URL workloads while polling is done via batch_status. It stops short of explicitly naming alternatives or saying when not to use batch, but the async/many-URL framing is enough contextual guidance.

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 already mark the tool as read-only and idempotent; the description adds crucial behavioral context that annotations do not cover: results are incremental and cursor-based, and page content is omitted by default. This is exactly the kind of stateful behavior an agent needs to know before calling the 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 short sentences, front-loaded with purpose, then usage mechanics, then a default-behavior warning. Every sentence earns its place and there is no fluff.

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 tells the agent it will receive progress and per-URL results, and it explains the cursor loop and the content flag. It stops short of specifying completion conditions or the exact response envelope, but it is sufficient for correct invocation.

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 baseline is 3; the description adds value by tying `since` to the previous `nextCursor` and advising `include_content` only when content is needed. It reinforces the schema's meaning without merely repeating 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?

The description opens with a specific verb and resource ('Poll a batch job') and clarifies the result scope ('for progress and per-URL results'). This separates it from creation tools like batch and other status tools by naming the resource type and the polling behavior.

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 clear operational guidance: pass the previous response's `nextCursor` as `since` for incremental polls, and enable `include_content` only when page text is actually needed. It does not explicitly name alternative tools or state when not to use this tool, so it falls slightly short of the top score.

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 already declare readOnlyHint and idempotentHint, so the description only needs to add async/status context. It does: 'Use after run_collector returned 202/async' plus the list of status values and the partial flag, which tells the agent this is a polling/read operation returning progress information. No contradiction.

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 tightly written sentences put the core action first, list the return fields compactly, and add only the workflow trigger and format option. No filler or unnecessary repetition.

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?

Covered: when to call, statuses, result fields, format switch, and safety profile via annotations. Without an output schema, it could say a bit more about the meaning of the partial flag and failure/not-found behavior, but for a simple async status fetch it is nearly complete.

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?

The schema describes both parameters at 100% coverage, so the description need not re-document them. It does clarify the csv format behavior, but that mostly mirrors the schema's 'Return rows as JSON (default) or CSV text' 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?

Description starts with a specific verb and resource: 'Fetch a Collector run by run_id', then enumerates exactly what is returned: status, result count, cost, partial flag, and result rows. This distinguishes it from run_collector, which launches the run, and from other status tools by naming the Collector-specific resource.

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 says to use this tool 'after run_collector returned 202/async', tying it to the run_collector workflow. It doesn't name exclusions or alternatives, but the async handoff condition is clear enough for an agent to choose this over launch tools.

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 already provide readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: the crawl is asynchronous, returns a job id, converts pages to Markdown, and requires polling via crawl_status. No contradiction with 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?

Two efficient sentences capture the core action, the async nature, the output format, and the follow-up polling step. Every phrase earns its place, and the most important information 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?

The description is complete for correct invocation: it names the required resource (seed URL), explains what will happen asynchronously, and tells the agent how to track progress via crawl_status. With the schema covering parameters and annotations covering read-only/open-world semantics, nothing critical 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 description coverage is 100%, so all seven parameters are already documented in the schema. The description adds general context (seed URL, BFS crawl) but does not need to explain individual parameters further.

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 clearly states the verb ('crawl'), the resource ('a site from a seed URL'), and the key behavior (asynchronous BFS, converting pages to Markdown). It also differentiates itself from siblings by describing a site-wide crawl while referencing crawl_status for polling.

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?

The description establishes clear usage context: start an asynchronous BFS crawl from a seed URL, then poll with crawl_status. It does not explicitly name alternatives like scrape or map, but the intended use case is clear enough for an agent to select this tool over single-page tools.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behaviors: incremental polling with a cursor, pages omitting content by default, and a concrete size warning for include_content. This is valuable operational context an agent needs before invoking the 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?

The description is two sentences: the first defines the tool's purpose and core polling behavior, the second covers the cursor contract and the content-size caveat. Every sentence earns its place, with no filler or repetition of schema details.

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?

There is no output schema, but the description references nextCursor, pages crawled so far, and metadata-only default, which tells the agent what to expect from responses. Combined with full parameter coverage and clear behavioral notes, nothing essential is missing for correct invocation.

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 baseline is 3, but the description adds meaning beyond the schema: it explains how since relates to nextCursor from a previous poll and when include_content is worth the cost. This materially improves parameter understanding.

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 and resource: 'Poll a crawl job for progress and the pages crawled so far.' This clearly identifies the tool's function and scope, and the resource 'crawl job' differentiates it from sibling status tools like batch_status or collector_run_status.

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?

The description gives clear context for use: polling is incremental and should build on a previous response's nextCursor. It does not explicitly name alternatives or state when not to use it, but the polling mechanics and incremental contract make the intended usage evident.

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 signal readOnlyHint=false and openWorldHint=true, but the description discloses key runtime behavior: it performs live web searches, scrapes external sites, returns an async job id, requires polling via dataset_status, and has a billing model with a hard cost cap and refund. This is substantial 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 tight sentences: purpose, pipeline, async/polling behavior, and cost model. It is front-loaded with the core purpose and every sentence adds necessary operational information without fluff or repetition.

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 complex async, billed, web-scraping tool with no output schema, the description covers the critical operational points: job id, polling endpoint, cost model, and budget safety. It relies on the input schema for parametric details, which is reasonable given 83% schema coverage, though it does not explain the final dataset delivery format or webhook behavior beyond the schema.

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 high (83%), so the baseline is 3, and the description adds extra meaning for the cost-related parameters: email/phone fields are premium and billed only when found, and limits.max_cost_usd is a hard cap with refunds for unspent budget. This clarifies semantics that the bare schema descriptions ('Budget cap for the run') do not fully convey.

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 names a specific verb ('Build') and resource ('structured dataset') and describes the full pipeline: planning queries, searching multiple engines, mapping sites, and scraping validated rows. This clearly distinguishes it from sibling tools like search, scrape, crawl, or map, since it is end-to-end dataset construction from a plain-language prompt.

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 clear context: use this tool when you want a structured dataset from a natural-language prompt, and it explains that the tool itself handles search and scraping. However, it does not explicitly name alternatives or state when NOT to use it, leaving some inference to the agent.

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 already declare readOnlyHint and idempotentHint, and the description adds useful behavior beyond that: polls are incremental, summary mode reduces payload, and completed jobs return signed CSV/JSON download URLs. This gives the agent a solid behavioral model without contradicting 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?

Three dense sentences each carry essential information: what the tool returns, how incremental polling works, how to lighten the poll, and what completion yields. There is no filler or repetition of annotation data.

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?

The description covers the key outputs an agent needs to know: progress, steps, rows, `nextCursor`, and signed download URLs. There is no output schema, so a bit more detail on status values or pagination edge cases could be helpful, but this is complete enough for correct invocation and basic handling of responses.

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 description does not need to compensate for missing parameter docs. It does add a small amount of context, such as calling summary mode a 'light poll' and tying `since` to the prior response's `nextCursor`, but this largely mirrors the schema. Baseline 3 is appropriate.

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 uses a specific verb and resource: 'Poll a dataset job' for progress, collection trace, and rows. This clearly distinguishes dataset_status from sibling status tools like batch_status, crawl_status, and collector_run_status by naming the exact job type it targets.

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?

The description provides clear usage context: incremental polling with `since`, the `summary` mode for lighter polls, and download URLs on completion. It does not explicitly name alternatives or say when not to use this tool, but the dataset job framing makes the intended context unambiguous.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: the LLM runs only once, later extraction is deterministic and free, selectors are validated against the page before being returned, and report/coverage indicate field reliability. No contradiction with 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?

Three sentences, each earning its place: how it works, when to use it, and what reliability signals to expect. The core action is front-loaded, and there is no fluff or repetition of schema details.

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 tool with no output schema, the description explains what is returned (CSS selectors), how to use it, and how to judge reliability via report/coverage. It could describe the report/coverage value shapes more precisely, but the essential invocation information is present and well integrated with the schema.

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 six parameters thoroughly. The description adds general context about the returned parser being used as an `extract` argument, but it does not need to add parameter-level semantics; baseline 3 is appropriate.

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 states a specific verb and resource ('Look at a page ONCE with an LLM and get back CSS selectors') and explains the tool's output and lifecycle. It also distinguishes it from ai_prompt by describing when each is appropriate, so an agent can separate it from the alternative without opening 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?

Provides explicit when-to-use guidance: 'Use this instead of ai_prompt whenever you will scrape more than a couple of pages of the same shape.' It also implies the exclusion case (one-off scrapes) and tells the agent how to use the result on later scrapes via the `extract` argument.

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 already signal readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context: generated strings include credentials, are ready-to-use, and 'plug straight into any HTTP client, e.g. curl -x'. It does not mention potential side effects like quota consumption, but it does not contradict 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 focused sentences: purpose, supported capabilities, prerequisites, and output usability. Every sentence earns its place, with the most important action and resource stated first. No filler or repetition of schema details.

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 tool with 15 parameters and no output schema, the description covers the essential context: what it produces, which sibling tools supply required inputs, supported modes, and how the output can be consumed. It does not explicitly state that the result is an array, but the quantity parameter and 'proxy endpoint strings' phrasing make that inferable.

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 baseline is 3. The description adds value beyond the schema by mapping orderId to list_proxies and targeting codes to proxy_locations, which helps an agent know where parameter values come from. It also usefully summarizes geo targeting and output format capabilities, though the schema already documents individual fields.

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 and resource: 'Generate ready-to-use proxy endpoint strings (credentials included) from one of the account's active proxy services'. It also lists the covered proxy types and clearly separates this tool from sibling tools like list_proxies and proxy_locations by focusing on generation of endpoint strings.

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 says 'Use list_proxies first to get the orderId, and proxy_locations for valid targeting codes,' giving clear sequencing and prerequisite guidance. It does not enumerate when to avoid this tool, but the prerequisite direction is clear enough to prevent improper use.

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?

The description goes well beyond the annotations by disclosing that the tool refetches the source page, only adopts new selectors if they extract more than current ones, leaves the preset untouched otherwise, and is not billed in that case. This is meaningful behavioral context that the annotations (readOnlyHint false, destructiveHint false, openWorldHint true) do not provide.

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?

The description is a single, well-structured sentence that front-loads the action and then packs in the key behavioral, conditional, and billing details. Every clause earns its place with no repetition or filler.

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 mutation tool with full schema coverage, the description explains the trigger, the refetch behavior, the acceptance condition, and the billing consequence. No output schema exists, but the description sufficiently conveys what will happen for an agent to decide and invoke 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 description coverage is 100%, so both `preset_id` and `force` are already documented in the input schema. The description does not add anything about parameter meanings beyond the schema, so it does not need to compensate. Baseline 3 is appropriate.

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 starts with a specific verb and resource: 'Regenerate a preset's selectors now'. It clarifies this is the manual trigger for the automatic repair, which distinguishes it from any automatic repair process and from sibling tools like save_parser_preset or generate_parser. The `heal` framing and the condition about adopting selectors only if they extract more makes the tool's unique role unmistakable.

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?

The description implies usage context by calling this 'the manual trigger for the automatic repair', so an agent can infer it is for manually forcing a repair that would otherwise happen automatically. However, it does not explicitly state when to prefer this over alternatives, nor does it mention any conditions or exclusions beyond the improvement check.

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 already declare read-only, idempotent, and non-open-world behavior. The description adds the return fields (slug, input/output schema, example input, price, health) and the pay-per-success billing model, which are not conveyed by 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?

The description is a single unwieldy paragraph with dozens of example collector names, which buries the key facts. While the examples provide useful context, the length hurts scannability and the structure is not front-loaded beyond the first sentence.

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 simple list tool with one optional filter and no output schema, the description adequately covers what is returned, the billing model, and the nature of the collectors. A formal return type or pagination behavior would be nice but is not essential here.

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?

The schema fully documents the optional category parameter with examples (100% coverage). The description adds nothing about the parameter itself, so 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?

The description opens with a specific verb and resource ('List the ready-made Collectors') and then defines what Collectors are with concrete examples. This clearly distinguishes it from siblings like run_collector, scrape, or list_parser_presets.

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?

The description explains that Collectors are run with a semantic input instead of URLs, which implies when this tool is useful for discovering them. However, it does not explicitly state when to use this over alternatives or mention exclusions, leaving some inference to the agent.

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 already declare readOnlyHint and idempotentHint, and the description is consistent with those. It adds some useful context about the response contents (version, health stats, changelog), but does not mention pagination, ordering, or any operational quirks. No contradiction with 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?

The description is a single efficient sentence with no filler. The action and key output details are front-loaded, making it easy for an agent to parse quickly.

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 zero-parameter, read-only, idempotent list tool with no output schema, the description gives enough to invoke it correctly: what is listed and what fields are returned. There are no serious gaps for this level of complexity.

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?

The input schema has zero parameters, so there are no parameter semantics to document. The description focuses on the output instead, which is appropriate for a parameterless list operation. This aligns with the baseline for 0-param tools.

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 uses a specific verb ('List'), names the exact resource ('your stored parser presets'), and states the included fields (version, health stats, changelog). This makes the tool's purpose immediately clear and distinguishes it from other parser-related siblings.

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?

The description implies this tool should be used for getting an inventory/overview of stored presets, but it does not explicitly state when it should be used over alternatives like parser_preset_stats or save_parser_preset. This is acceptable but leaves routing to inference.

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 already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by specifying the breadth of the list and the key output fields, including the orderId needed downstream. It does not cover pagination behavior, but the schema documents the relevant parameters.

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 with no filler. The core action and scope are front-loaded, followed by the useful downstream pointer. Every clause earns its place.

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 read-only listing tool with no output schema, the description compensates well by naming the returned fields, enumerating proxy types, and explaining why an agent should call it first. Combined with the fully documented optional parameters and safe annotations, nothing essential 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 description coverage is 100%, with all four parameters already clearly explained and the planType enum fully listed. The description adds no additional parameter-level meaning beyond contextualizing the orderId in the output, so the baseline score of 3 is appropriate.

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 uses a specific verb ('List') with a precise resource ('the account's proxy services'), enumerates all covered types, and lists the returned fields. It clearly differentiates itself from siblings like generate_proxies by explicitly naming that tool as the follow-up consumer of the returned orderId.

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?

The description gives clear context with 'Call this first to see which proxy plans are available' and ties directly to generate_proxies. It does not mention exclusions or alternative tools for proxy locations, but the intended sequencing is explicit enough for an agent.

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 already mark readOnlyHint and openWorldHint as true, and the description adds valuable behavioral context: the URL discovery sources, default limit, return of `total` and `summary`, and the `group_by` path-tree mode. It goes beyond annotations by describing the output shape and narrowing semantics.

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?

The description is front-loaded with the core purpose and uses three focused sentences. It packs return-shape details and parameter guidance without redundancy, though it is slightly dense in the middle.

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?

Given no output schema, the description adequately explains what the tool returns (limit, total, summary, path tree). It covers the main behaviors and parameter semantics, but does not mention any rate limits or auth needs; for a read-only mapping tool this is a minor 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%, so the baseline is 3. The description adds meaningful semantic detail beyond the schema, particularly for `search` ('substring filter — the primary way to find specific pages') and `group_by` ('path tree with counts instead of URLs').

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: 'Discover a site's URLs fast' using robots.txt/sitemaps/homepage links. Explicitly differentiates from a full crawl, which distinguishes it from the sibling crawl tool.

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?

Offers clear guidance: use map for fast URL discovery without a full crawl. It also explains when to use the `search` parameter as the primary way to find specific pages, giving the agent actionable routing criteria.

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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral detail beyond that: it computes success rate, mean coverage, and a decayed flag, and even explains the practical meaning of decayed ('the site probably changed'). This goes beyond the structured 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?

A single, well-structured sentence that opens with the core purpose and then lists the specific metrics after a colon. There is no filler, repetition, or unnecessary detail.

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 simple one-parameter read-only tool, the description conveys the essential output semantics: success rate per field, mean coverage, and decayed status. It does not specify exact return field names or the exact window for 'recent runs', but overall it gives an agent enough context to call the tool and interpret the result.

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?

The input schema is fully documented at 100% coverage, with preset_id described as 'The preset id returned by save_parser_preset'. The tool description itself does not expand on the parameter, but because the schema already covers it, the baseline of 3 is appropriate.

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 clearly identifies the resource (a stored parser preset) and the purpose (assessing how well it is still working). It names the specific output concepts—success rate per field, mean coverage, and decayed status—which distinguishes it from action-oriented siblings like heal_parser_preset and save_parser_preset.

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?

The description provides clear context for when this tool is relevant: checking whether a stored parser is still reliable or has decayed. It does not explicitly name alternatives or state when not to use it, but the health/status framing is sufficient for an agent to infer its role among sibling tools.

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 already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuine behavioral context beyond annotations: the tree returns a hierarchy (countries → regions → cities → ISPs), is tied to specific plan categories, and can be large. This helps the agent anticipate response size and structure.

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?

The description is two sentences, front-loads the core purpose, and every clause earns its place: the value categories, the generate_proxies relationship, the tree-level guidance, and the size warning. No redundancy or filler.

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?

Given the rich schema, helpful annotations, and the tool's read-only lookup nature, the description is largely complete. It states what the tool returns, when to call it, and calls out the large-tree caveat. The absence of an output schema is partially mitigated by the description naming the returned value categories.

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 parameters. The description adds useful high-level context about level values and the tree's purpose, but it does not materially deepen parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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 uses a specific verb ('Discover') and a clear resource ('valid geo-targeting values for a proxy plan type'), and explicitly ties the tool to a downstream sibling ('before calling generate_proxies'). It also enumerates the exact kinds of values returned, which distinguishes it from proxy-generation and proxy-listing siblings.

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?

The description tells the agent when to use the tool ('before calling generate_proxies') and gives concrete sub-guidance on when to choose level 'tree' for specific plan types and for the datacenter gateway list. It does not explicitly name excluded cases or alternative sibling tools, but the usage context is clear enough.

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?

Adds substantial behavior beyond annotations: short runs return rows inline, long runs return 202 with run_id and statusUrl, results are billed per delivered row (never for failures), and async forces background execution. This complements the openWorldHint and readOnlyHint annotations effectively.

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 tightly written sentences with no filler. The action is front-loaded, followed by behavior, billing, and async guidance—each sentence earns its place.

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 tool with no output schema, the description explains the return contract (inline rows vs 202 + run_id/statusUrl), the polling path, billing, and async behavior. An agent has everything needed to call and follow up on the run.

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 baseline is 3. The description adds a concrete input example, references list_collectors for per-collector inputSchema, and explains the async parameter's behavioral effect, going beyond the schema descriptions.

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: 'Run a Collector by slug with a semantic input.' It names the related tools list_collectors and collector_run_status, which clarifies its distinct role in the workflow.

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?

Provides clear context: consult list_collectors for the inputSchema and example, poll with collector_run_status after long runs, and set async true to force background execution. It does not explicitly contrast against alternative run/execute tools, but the collector-specific workflow is well defined.

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?

Beyond the annotations, the description discloses a notable behavioral trait: every preset is scored per field, and on decay it automatically regenerates from `source_url` and bumps a version. It also warns that without `source_url` the preset can never self-heal. This adds genuinely useful runtime behavior context beyond the simple read/write hints.

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, each earning its place: what the tool does, how it is used later, and the key self-healing caveat. The most actionable information (store, reuse, source_url) is front-loaded, with no filler or redundant restatement of the name or schema.

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 tool with six parameters and nested objects, the description covers the important behavioral consequences (self-healing, version bumps, inability to heal without source_url) while the schema covers parameter details. The only minor gap is that the return value is not explicitly described, but 'reused by id' strongly implies a preset id is returned, so the description remains adequately complete.

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 baseline is 3; the schema already documents `name`, `parser`, `fields`, `render`, `auto_heal`, and `source_url`. The description adds emphasis on `source_url` for self-healing, but that is already reflected in the schema. No significant new parameter meaning is introduced beyond the schema.

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 and resource: 'Store a generated parser under a name so it can be reused by id.' This clearly distinguishes saving a preset from sibling tools like generate_parser, heal_parser_preset, and list_parser_presets. It also immediately conveys the post-condition (future reuse via preset_id).

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?

The description gives clear practical context: save a parser if you want to reuse it in scrape via `preset_id` instead of repeating selectors. It also advises providing `source_url` to enable self-healing. It does not explicitly contrast with heal_parser_preset, but the intended workflow is evident enough that no exclusions are needed.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description reveals useful behavioral details: residential proxy use, Chrome TLS fingerprint default, browser escalation only when bot-challenged, the smart content_mode default, and the raw no-JS/SEO fallback via format 'html'. This gives an agent a genuine model of how the tool behaves at runtime.

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?

The description is dense but not bloated, front-loading the core action and output first. Each sentence adds meaningful context about defaults, render behavior, extraction, or format nuances, though the final sentence is a bit long.

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 tool with 31 mostly-optional parameters and no output schema, the description provides a strong high-level mental model while the schema supplies detailed parameter semantics. It does not enumerate every output payload, but the parameter descriptions compensate well, so the overall context is sufficient for correct invocation.

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?

Input schema coverage is 100%, so the schema carries most parameter meaning. The description still adds value beyond the schema, particularly by explaining that format 'html' is the raw no-JS/SEO fallback and by framing content_mode 'smart' as the default page-preserving behavior.

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 and resource: 'Scrape a single web page' and states the primary output ('clean Markdown (or HTML/text)'). It clearly distinguishes itself from site-level siblings like crawl and batch by emphasizing 'single' page.

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?

The description gives a clear context: scraping a single page with proxy, TLS fingerprinting, and optional extraction. However, it does not explicitly say when to choose scrape over crawl, search, or map, or when not to use it, so the routing guidance is mostly implied rather than stated.

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?

Given readOnlyHint and openWorldHint already declare safety, the description adds meaningful behavioral context: residential proxy use, Bing's HTTP-only verticals, Copilot answers/citations, and Google's direct parsing of rich blocks. This gives an agent a realistic model of how results are obtained without contradicting 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?

The description is compact and front-loaded with the core action. The Bing vertical enumeration in sentence 2 partly duplicates what the search_type parameter description already states, which prevents a perfect conciseness score, but the overall length is still reasonable and free of filler.

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 38-parameter tool with no output schema, the description plus the extremely detailed input schema provides enough orientation to select engines and verticals correctly. It does not describe the overall response envelope, but the rich schema carries most of the burden and mentions pagination metadata in parameter docs.

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?

The input schema provides 100% description coverage for all 38 parameters, including detailed semantics for num, page, search_type, and vertical-specific fields. The main description largely restates engine/vertical support already present in the search_type parameter description, adding no new parameter-level meaning, so the schema-covered baseline of 3 is appropriate.

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 clear verb and resource: 'Run structured Google, Bing or DuckDuckGo searches through a residential proxy.' It conveys a specific, multi-engine search capability, but it does not explicitly differentiate this tool from the sibling search_bulk or search_and_read tools, so it stops short of full sibling disambiguation.

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?

The main description provides context about engine-specific verticals and HTTP vs rendered behavior, implying when the tool is appropriate. Parameter descriptions add explicit routing guidance, e.g. num says 'Use page to address one specific page, or search_bulk for many queries.' No explicit when-not-to-use exclusions are given, so not a 5.

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 already mark readOnlyHint=true and openWorldHint=true. The description adds meaningful behavioral context: live-web freshness, Markdown conversion, numbered citations, and token-bounded context assembly. It doesn't disclose all edge behaviors (e.g., fetch failures or citation formatting nuances), but for a read-only search tool this is sufficient and does not contradict 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?

The description is two sentences, front-loaded with the core operation and output shape, followed by the usage distinction. Every sentence earns its place, and there is no redundant fluff.

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 clearly explains what the caller receives: numbered sources and one token-bounded context string. It could add more detail on the exact format or behavior on sparse results, but the fully documented input schema, read-only annotation, and precise sibling comparison make this definition largely complete.

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 input schema already documents all seven parameters with defaults, ranges, and enums. The description indirectly reinforces top_n and max_tokens through 'top organic pages' and 'token-bounded context,' but it does not add substantial parameter-level meaning beyond what the schema provides.

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 names a specific verb and resource: 'Search the live web, fetch the top organic pages as clean Markdown, and return citation-ready numbered sources plus one token-bounded context string.' It clearly distinguishes itself from the sibling 'search' by contrasting raw SERP needs, so an agent can tell them apart immediately.

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 explicitly states when to use the tool: 'Use this when the goal is answering/researching.' It also gives a clear exclusion: 'use `search` when raw SERP structure or a specialized vertical is needed.' This gives the agent both positive and negative usage guidance.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses asynchronous execution, deduplication, retention of page-one enrichments, the render requirement for JS blocks, and per-page billing with refunds for unavailable pages. These are meaningful behavioral details an agent could not infer from the annotations alone.

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 the core operation, then enrichment behavior, then billing. Every sentence adds distinct value; no filler or restatement of the schema.

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?

The description covers the operation, billing, and enrichment behavior well, which is strong for an asynchronous tool. However, since there is no output schema, it does not mention what the actual response contains, such as a job handle or status reference, which is a relevant missing piece for an async flow.

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 baseline is 3, but the description adds extra meaning by explaining that render:true is needed for Google JS enrichments and that billing is per actually fetched page. This semantic context goes beyond the parameter names and schema comments.

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 leads with a specific verb and resource: 'Paginate ONE search query asynchronously'. It also defines the output behavior ('merge deduplicated organic results') and names retained SERP enrichments, making it distinct from synchronous or single-page search siblings without needing to open the 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?

The first sentence makes the intended use case clear: asynchronous pagination of a single query. The description also gives conditional guidance for render:true, but it does not explicitly name alternatives or state when not to use this tool versus search or search_and_read.

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 already establish readOnly and idempotent behavior. The description adds useful behavioral context beyond that: polling is incremental, `since` yields only new organic results, and the response merges results since the last poll. This tells the agent how repeated calls behave.

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 tight sentences with no filler. The core purpose comes first, and the incremental polling nuance is explained immediately after, making it easy for an agent to parse.

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 simple two-parameter, read-only tool, the description covers how to initiate polling and how to continue polling incrementally. It omits terminal/error state details, but the annotations and schema provide enough safety and parameter context for correct invocation.

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 parameter meaning is already fully documented in the schema. The description adds a minor framing by tying `since` to the previous response's `nextCursor`, but this largely restates the schema description rather than introducing new semantic detail.

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 names an explicit action ('Poll'), a specific resource ('a bulk search job'), and what is returned ('progress and merged organic results'). This clearly distinguishes it from sibling status tools such as batch_status or crawl_status by focusing on bulk 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?

The description gives a concrete usage pattern: poll an existing bulk search job and advance incrementally by passing the previous `nextCursor` as `since`. It does not explicitly name when-not-to-use alternatives, but the schema's jobId provenance and the incremental polling instructions supply enough context.

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?

The description discloses the dual-fetch behavior (pure HTTP and fully rendered), the exact return elements (title, description, canonical, h1, word count, diff, bot-facing meta), and the effect of the no_render parameter. This goes well beyond the readOnlyHint annotation and gives a precise mental model.

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?

The description is succinct but information-dense. It leads with the core purpose, then lists the outputs and diff, and ends with a usage hint. It avoids redundancy and each sentence adds value, though it could be slightly more streamlined by omitting parentheticals.

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?

Given there is no output schema, the description thoroughly covers what the tool returns (both views and diff) and the filtering options. It explains the dual-fetch logic and the bot-facing meta, providing enough context for an agent to decide when and how to call it. No critical aspects are 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?

The schema already fully documents all three parameters with descriptions (url, country, no_render). The tool description adds no additional meaning—e.g., it does not clarify the purpose of the country parameter or explain default behavior beyond what the schema states. Since coverage is 100%, baseline is 3 and no extra value is added.

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 clearly states the tool audits a URL's SEO in one call, specifying the resource (URL) and the action (audit). It distinguishes from manual scraping by offering a comprehensive alternative, making the purpose immediately obvious.

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 explicitly recommends using this tool instead of manual scraping when checking how a page indexes, providing a clear scenario. However, it does not compare against other sibling tools like 'scrape' or 'crawl', leaving some ambiguity about when to prefer this over those.

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 already declare destructiveHint=true. The description adds context that whitelisted machines use proxies without credentials and that it's required for Mobile V2 IP-auth list, which clarifies the impact. No contradiction with 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?

Two sentences, front-loaded with the purpose, then the auth context. No unnecessary words.

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?

The description gives enough high-level context: what the tool does, when to use it, and which auth methods it applies to. The schema covers parameter details. It lacks explicit prerequisites like needing an existing order, but this is implied by orderId from list_proxies.

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 covers 100% of parameters with descriptions, so the description adds little beyond the schema. It provides context about the auth method that relates to orderId, but no new parameter-specific details.

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 states a clear verb (manage) and resource (IP-auth whitelisting) and specifies the actions (add, remove, list). It distinguishes from sibling proxy tools by focusing on whitelisting specifically.

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?

Provides explicit guidance on when to use (for IP-auth proxy types, required for Mobile V2) and when not (Residential Premium/Private with user:pass auth). This gives agents a clear decision rule.

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