quanticdata-mcp

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description consistently describes a read/audit (not a mutation). It adds valuable behavioral context beyond annotations: the GPTBot-identifying fetch to catch WAFs, the no-JS nature of AI Overview/Copilot SERPs being mentions-only, the retrievability-first blocker semantics, and per-(query×engine) billing. These are non-obvious operating characteristics.

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?

Front-loaded with the single-sentence purpose and the seo_audit routing, which is strong. But the middle is a very long run-on enumeration of every check (robots.txt, JSON-LD, headings, readability, paywall tokens, etc.) that reads as a spec dump rather than earning each phrase; it inflates the description well past what an agent needs to select and invoke the tool.

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 12-parameter, open-world audit tool with no output schema, the description covers the pillars returned, blocker semantics, the citation panel behavior, and the distinction from seo_audit. Nothing essential to invoking it correctly (or interpreting that a not-indexed page caps the score) 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 baseline is 3; the description goes well beyond by explaining the semantics of key optional params: `queries` triggers the citation panel and is billed per (query×engine), `offsite` adds a pillar and costs 5 SERP calls, `engines` values are explained (aio/copilot/API approximations/deepseek), and `no_retrieval` is described as the strongest predictor that is on by default. This meaningfully supplements 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?

States a specific verb (audit) and resource (AI assistants' ability to read/cite a page), lists the actual engines, and enumerates the pillars measured. It explicitly distinguishes itself from the sibling seo_audit ('Use this instead of seo_audit when the question is AI answers rather than Google rankings'), so an agent can route correctly without opening 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?

Gives clear context and the key branch: on-page only when `queries` is omitted, citation panel when `queries` is set, and it names the alternative (seo_audit) with the distinguishing condition. However, no explicit when-NOT-to-use beyond the seo_audit contrast, and no guidance on whether to pre-fetch the URL.

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 cover safety (readOnlyHint, openWorldHint), and the description adds meaningful behavior beyond them: this is asynchronous, returns a job id that must be polled via batch_status, and summary mode yields metadata only rather than full content. It does not address job lifetime, concurrency, or failure 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?

Three tightly written sentences with the core action front-loaded, followed by the polling contract and the mode guidance. No redundant or filler content.

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 present, the description supplies the essential return contract (a job id plus the batch_status polling path) and the key mode trade-off. All eight parameters are described in the schema, including the 5000-item cap, so 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what mode='summary' actually returns (title, description, canonical, contentLength) instead of full page content, adding concrete meaning beyond the enum label.

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 ('Scrape many URLs'), plus the async execution model and that it returns a job id, which distinguishes it from a synchronous single-URL scrape. It routes the agent to batch_status for polling. It does not, however, explicitly differentiate itself from siblings like crawl, map, or search_bulk.

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 a clear when-to-use signal: 'For SEO/status audits over many pages set mode summary.' It also names the follow-up tool (batch_status) for retrieving results. There is no explicit when-not-to-use or comparison against crawl/map alternatives.

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, and the description adds non-obvious behavior beyond them: polling is incremental via `since`, and page content is omitted by default. This is exactly the kind of context an agent needs before calling.

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 front-loading a distinct behavior (purpose, incremental polling, content omission), with zero waste. The most consequential detail (the `since` cursor) is stated early.

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 purpose, incremental polling, and the content default without needing an output schema. It doesn't mention completion/failure states or terminal conditions of a batch job, which would be helpful for an agent deciding whether to keep polling, but it is otherwise 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 coverage is 100%, so all five parameters are already documented in the schema. The description reinforces the `since` cursor and `include_content` default but adds no syntax or format details beyond the schema, 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?

States a specific verb (poll) and resource (a batch job) with its scope (progress and per-URL results). An agent can distinguish it from sibling status tools like crawl_status and search_bulk_status because of the batch-job-specific cursor semantics described.

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 clear usage pattern: poll incrementally, pass the previous response's nextCursor as `since`, and set include_content true only when the text is needed. It lacks explicit routing against sibling *_status tools, but the conditional guidance is strong.

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?

No annotations would leave this as a read-only fetch anyway, and the description discloses the full returned status enum (queued|running|done|failed), the partial flag, and cost — the async/polling nature is the key behavioral trait an agent needs. It does not mention pagination or how the result rows are bounded, which keeps it short of a 5.

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 compact sentences, each earning its place: purpose, return fields, usage trigger, and the one runtime param hint. It is front-loaded with the verb and resource.

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 polling status tool with no output schema, the description covers the return shape, the usage trigger, and the single behavioral option. Nothing an agent needs 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 100%, so the baseline is 3; the description adds meaning by naming format 'csv' as the mechanism to get rows as CSV text, which is the only param behavior not obvious from the enum alone. The two analytics-only params (context, llm_model) are left to the schema, which 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 ('Fetch a Collector run by run_id') and enumerates exactly what is returned (status, result count, cost, partial flag, result rows). It is clearly distinguishable from the sibling run_collector, which creates the run.

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 when-to-use condition: 'Use after run_collector returned 202/async.' It also notes the format 'csv' option. The polling relationship to run_collector is stated outright, leaving nothing 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 cover read-only and open-world safety, and the description adds meaningful non-safety behavior: it is asynchronous, uses BFS traversal, converts pages to Markdown, and returns a job id requiring polling. That async/poll workflow is context the annotations do not convey. It does not mention rate limits or failure behavior, keeping it short of a 5.

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 the core action front-loaded and the follow-up workflow (poll with crawl_status) immediately after. No 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?

There is no output schema, and the description compensates by stating the return value (a job id) and the polling path. With 9 parameters at full schema coverage, the only gap is that it doesn't surface scope defaults (depth, page limit) at the description level, though the schema handles those.

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 every parameter (depth, limit, include, exclude, country, content_mode, context, llm_model) is already documented in the schema. The description adds no additional parameter meaning beyond what the schema provides, so the 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?

States a specific verb (start), resource (BFS crawl of a site), and mechanism (seed URL, pages to Markdown). It also implicitly distinguishes itself from crawl_status by naming it as the polling follower and from scrape (single page). An agent can tell what it does without opening 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?

Clearly frames this as an asynchronous job that must be paired with crawl_status for results, which is the key usage context. It does not explicitly state when to prefer this over scrape or map, but the async multi-page crawl framing implies the selection condition.

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 safety is covered. The description adds genuinely non-obvious behavior beyond that: polls are incremental via a cursor contract, content is omitted by default, and full content can be hundreds of KB. It stops short of describing terminal job states or error behavior.

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 action, then the incremental-polling rule, then the payload-size caveat. Every sentence carries distinct, actionable information with no restatement of the tool name 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?

With no output schema and a fully described input schema, the description supplies the missing polling workflow and payload-control context an agent needs. It omits what job states/progress fields look like and whether polling after completion is meaningful, which keeps it from being fully 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 coverage is 100%, so the baseline is 3 and the schema already explains jobId, since, and include_content. The description reinforces the `since`/nextCursor relationship and adds a size rationale for include_content, but contributes little semantic detail beyond the schema, and never mentions the analytics-only `context`/`llm_model` params.

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 (poll) and resource (crawl job) plus what the response contains: progress and pages crawled so far. The separation from the sibling `crawl` (which starts the job) is implicit in 'poll a crawl job', and the `*_status` siblings are clearly differentiated.

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 clear condition for the incremental mode ('pass the previous response's nextCursor as since') and a conditional rule for the expensive option ('set include_content true only when you actually need the text'). It does not explicitly name alternatives such as `crawl` to start a job or sibling status tools, so it falls short of an explicit when/when-not/alternative statement.

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 provide openWorldHint/readOnlyHint/destructiveHint, so the description carries the billing model, budget cap enforcement (limits.max_cost_usd), refund behavior, and premium field costs — valuable context beyond annotations. Missing mention of run duration or failure modes.

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?

Front-loads purpose then pipeline then billing concisely in three sentences. Every clause earns its place, though the billing sentence is dense.

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 8 parameters, nested objects, no output schema, and minimal annotations, the description covers the async workflow, cost semantics, and output format. Could add more on row validation or error handling, but is suitably 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 coverage is 88%, so the schema already documents most parameters including the billing note on column types and context guidance. The description adds the budget-refund behavior tied to max_cost_usd but little else 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?

States a specific verb 'Build a structured dataset' and resource, and describes the full pipeline (plans queries, searches engines, maps sites, scrapes into validated rows). Distinguishes itself from siblings like scrape/search by being an end-to-end dataset builder.

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 poll with dataset_status after getting a job id, which is clear usage context for the async flow. Does not name when to use this vs scrape/crawl directly, but the dataset-building framing implies intent.

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, idempotent, closed-world behavior, so the bar is lower; the description adds real value by disclosing the incremental polling contract, the row-omitting summary mode, and that completed jobs return signed CSV/JSON download URLs. It omits details like terminal error states or how long URLs stay valid.

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, front-loaded with the core purpose and then the incremental-poll mechanics and completion behavior. Every sentence carries information an agent needs; no 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?

With no output schema, the description carries the full burden of explaining return values and does so: progress, steps, rows, and download URLs on completion, plus how to poll incrementally. Nothing essential for calling 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 description coverage is 100%, so baseline is 3. The description explains `since` and `mode` in narrative form, but that meaning is largely already present in the schema descriptions of those same fields, so it adds little beyond the structured data.

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 (poll) and resource (dataset job) plus exactly what is returned: progress, collection steps, and rows. The jobId description ties it back to create_dataset, making the lifecycle clear, though it never contrasts itself against the other *_status siblings (batch_status, crawl_status, 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?

Gives concrete usage instructions: poll incrementally by passing the prior response's nextCursor as `since`, and use mode 'summary' for light polls. It does not state when this tool is inappropriate versus sibling status tools, so it stops short of explicit exclusions.

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 readOnly/openWorld, so the description adds real behavioral value: it discloses that an LLM runs once, that selectors are validated against the page before being returned, and that report/coverage indicate field reliability. It does not cover cost, rate limits, or failure modes, keeping it below a 5.

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 one-shot mechanism, then the reuse payoff, then the validation guarantee. No filler 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 an 8-parameter tool with no output schema, the description covers the mechanism, the reuse path, and the meaning of the returned `parser`/`report`/`coverage`. Remaining gaps (proxy/country behavior, cost implications) are minor and partly covered by 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 8 parameters; the description only gestures at 'fields you asked for' and the fields-vs-prompt choice. It adds cross-tool semantics (pass the returned `parser` as `extract`), but nothing that meaningfully extends the parameter docs themselves, matching the baseline 3.

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 (generate) and resource (a CSS-selector parser) plus the exact mechanism: 'Look at a page ONCE with an LLM and get back CSS selectors that extract the fields you asked for.' It names the conceptual alternative (ai_prompt), so an agent can tell it apart without opening 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?

Gives an explicit when-to-use rule ('whenever you will scrape more than a couple of pages of the same shape') and names the alternative it replaces (ai_prompt). Nothing about selection 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.

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, indicating a non-destructive generation operation. The description adds useful context about credentials being included and output plugging into HTTP clients, but doesn't disclose rate limits, whether generation consumes plan quota, or credential security implications.

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?

Dense but front-loaded: purpose first, then capabilities, then prerequisite routing, then output example. One sentence is long but each clause earns its place. Slightly packed for a single description.

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 17-parameter, no-output-schema generation tool, the description covers purpose, prerequisites, targeting capabilities, and output format. Missing only output shape details (e.g., returned as a list of strings) and quota/rate implications, which are secondary given the rich 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 100%, so every parameter already has a rich description in the schema. The description only summarizes the categories (geo targeting, rotation, protocol, formats) without adding syntax or constraints beyond the schema. Baseline 3 when schema does the heavy lifting.

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 ('Generate ready-to-use proxy endpoint strings') and enumerates the proxy types supported. Clearly distinguishes itself from siblings like list_proxies and proxy_locations by naming them as prerequisites.

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 tells the agent to use list_proxies first to get orderId and proxy_locations for targeting codes. This is exactly the when-to-use and prerequisite sequencing an agent needs.

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 the annotations: it refetches the source page, adopts new selectors ONLY if they extract more, leaves the preset untouched on a failed heal, and is not billed in that case. That conditional-write and cost disclosure is exactly what annotations cannot convey.

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 front-loaded sentences with no waste; the core action leads and the conditional behavior plus billing consequence follow compactly.

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 mutating, no-output-schema tool the description covers the essential outcome and cost semantics, though it does not describe what the response reports when a heal succeeds or fails.

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 parameters (including 'force' bypassing the cooldown and the analytics-only context/llm_model) are fully documented by the schema; the description adds nothing parameter-specific, making 3 the correct baseline.

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 ('Regenerate a preset's selectors') and frames it as the manual counterpart to the automatic repair, which cleanly separates it from generate_parser or 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 parenthetical 'the manual trigger for the automatic repair' tells the agent when this tool is relevant versus the automatic path, but it names no explicit alternative tool and gives no when-not condition.

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, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond that: the return payload (slug, input/output schema, example input, price per result, health) and the billing model (pay-per-success, only delivered rows charged). Useful disclosure that the schema and annotations 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 first clause front-loads the purpose well, but the ~70-name enumeration is disproportionately long and pushes the genuinely useful information (return shape, billing) to the end. The list borders on data that belongs in the response rather than the definition, though it does aid discovery.

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 correctly compensates by describing the returned fields (slug, schemas, example input, price, health). Combined with annotations covering the safety profile and 100% schema coverage on inputs, an agent has enough to call it correctly; only pagination/format details are absent.

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 category, context, and llm_model are already fully documented in the schema. The description adds no parameter-level detail (e.g. what category values exist) beyond what is structured. Baseline 3 is correct.

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 ('List the ready-made Collectors') and defines the concept precisely as paid, versioned scrapers driven by semantic input rather than URLs. This distinguishes it cleanly from the URL-crawl siblings (crawl, scrape, map) even without naming them. An agent immediately knows this enumerates available collectors, not runs one.

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 phrase 'instead of URLs' implies the discovery-vs-scraping distinction, but the description never says when to call this versus run_collector, e.g. 'call this first to find a collector slug, then invoke run_collector'. Usage is implied rather than stated, leaving the sequencing 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=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful return-content context (version, health stats, changelog) but says nothing about auth, rate limits, or result scope, so it goes only modestly 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?

A single front-loaded sentence that names the action, the resource, and the returned data with zero filler. Nothing to trim.

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 read-only list tool with no output schema, the description usefully names the returned fields, which compensates for the missing output schema. Minor gaps remain around ordering, filtering, and pagination behavior.

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 (context, llm_model) are analytics-only fields fully documented in the schema. The description adds no parameter meaning, 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 specific verb (List) and resource (parser presets) and enumerates what is returned (version, health stats, changelog). This distinguishes it from save_parser_preset and heal_parser_preset, though it overlaps conceptually with the parser_preset_stats sibling without addressing the difference.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as parser_preset_stats. Usage is only implied by the verb 'List'.

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, idempotentHint=true and openWorldHint=false, so safety is covered. The description adds genuine value beyond that: it discloses the returned fields (plan type, bandwidth left, expiry, whitelisted IPs, orderId) and explains that orderId feeds generate_proxies.

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 verb and the resource. The plan-type enumeration is somewhat long but earns its place by clarifying scope; the second sentence is a crisp directive.

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 and rich annotations, the description carries its share by describing the returned payload and the role of orderId. Nothing an agent needs to call this read-only listing correctly appears to be 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 the schema already documents limit, active, offset, planType, context and llm_model. The description reinforces plan coverage by naming plan types but adds no filtering syntax or format detail beyond what the schema provides; 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 specific verb ("List") and resource ("the account's proxy services") and enumerates the exact plan types covered. It clearly distinguishes itself from siblings like generate_proxies, which it names as the downstream 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?

"Call this first to see which proxy plans are available" gives an explicit when-to-use and sequencing directive relative to generate_proxies. It lacks an explicit when-not/alternative exclusion, but the usage context is 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?

Annotations declare readOnlyHint and openWorldHint, so safety is covered. The description adds value beyond that: the discovery sources used, and the behavioral nuance that `total`/`summary` always cover the whole site regardless of `limit`. It omits any mention of rate limits or how subclass/path derivation works, keeping it from a 5.

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?

Dense but well front-loaded: the core purpose leads, then return shape, then narrowing options. It is a single tight block with no filler, though the parenthetical mechanism list and example make it slightly heavier than a 5 would warrant.

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 correctly carries the return-value burden — it explains the `limit`-bounded URL list, the site-wide `total`, and the per-section `summary` with a concrete example, so the agent knows exactly what comes back. Nothing an agent needs 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 100%, so the baseline is 3, but the description goes further by adding prioritization the schema lacks — `search` as the recommended narrowing mechanism, the default-100 limit, and the full-site scope of `total`/`summary`. It enriches parameter meaning rather than restating 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 ('Discover a site's URLs') with the exact mechanism (robots.txt sitemaps, /sitemap.xml, homepage links) and explicitly contrasts with a full crawl, separating it from the sibling `crawl` tool. An agent can immediately tell what this does and how it differs from crawling.

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 operational guidance: narrow with `search` (framed as 'the primary way to find specific pages') before raising `limit`, and use group_by 'path' for the tree view. The 'without a full crawl' phrasing implies when to prefer this over `crawl`, but the alternative tool is never named explicitly, so it falls short of 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 declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description adds value by explaining what the result contains (per-field success rate, mean coverage, decay verdict) and, critically, what 'decayed' means ('the site probably changed') — useful interpretation context with no output schema present.

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-formed sentence with a colon-delimited list; the core concept ('how well a stored parser is still working') is front-loaded. Tight and free of filler, though the parenthetical definition slightly lengthens it.

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 appropriately explains the returned metrics, and the annotations cover safety semantics. Parameters are fully documented in the schema. Adequate for correct invocation, with only the sibling-routing guidance left implicit.

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%, documenting preset_id, context, and llm_model, so the schema does the heavy lifting. The description adds no parameter-level detail, which is the correct baseline when the schema is fully annotated.

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 the exact outputs (success rate per field, mean coverage over recent runs, decayed flag), so an agent knows precisely what this returns. It is clearly a diagnostic/stats tool, distinguishable from mutation siblings like save_parser_preset or heal_parser_preset by implication. However it never explicitly names those siblings to disambiguate.

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?

Usage is implied — the 'still working'/'decayed' framing signals a health-check used before deciding to heal. But there is no explicit when-to-use statement or reference to alternatives such as heal_parser_preset or list_parser_presets, so the agent must infer the routing.

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 readOnly, idempotent, and closed-world, so safety is covered. The description adds genuinely new operational context beyond that: the 'tree' level can be large, and it maps tree contents to specific plan types and ISP codes, which helps the agent anticipate response size.

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 dense sentences, front-loaded with purpose and the generate_proxies dependency, then the level-routing guidance. Every clause carries information; the size caveat and tree contents are tightly packed rather than padded.

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, 100%-covered schema with no output schema, the description supplies the missing pieces an agent needs: what the tool yields, when to call it, and the size caveat. It stops short of describing result shape or pagination, but nothing essential to correct invocation 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 100%, so the baseline is 3, but the description adds interpretation beyond the schema by explaining that 'tree' returns the full countries→regions→cities→ISPs hierarchy and that it is the level needed for specific slugs and ISP codes, giving the 'level' enum real decision meaning.

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 (discover) and resource (valid geo-targeting values) and enumerates the value categories (countries, states, cities, ASNs, tree). It also names the downstream sibling generate_proxies, so an agent can place it in the workflow without opening other 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?

Explicitly ties usage to a moment ('before calling generate_proxies') and routes the agent to the right level value for specific plan types (tree for Residential Premium / Mobile V2 slugs and ISP codes, or the static datacenter gateway list). It lacks a when-not-to-use statement or a clear default, keeping it short of 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 declare non-read-only, open-world, non-destructive, but the description adds substantial behavior beyond them: billing is per delivered row and never for failures, short runs return rows inline while long runs return 202 with run_id + statusUrl, and async forces background execution. This is exactly the extra context annotations can't carry.

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?

Front-loaded with the core action, then efficient sentences covering return modes, billing, and the async override. No filler; every clause carries operational meaning.

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 carries the return-value burden and does so: inline rows or a 202 with run_id/statusUrl, plus the polling tool and billing caveat. Nothing an agent needs to invoke and follow up 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 description coverage is 100%, so the schema already documents slug, async, input, context, and llm_model. The description reinforces the input semantics (matches the collector's inputSchema) and the async flag, but adds little the schema doesn't already say, so the baseline 3 holds.

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 (Run) and resource (a Collector by slug) with the input semantics called out. It explicitly differentiates from siblings by pointing to list_collectors for the inputSchema and collector_run_status for polling, so an agent can place it without opening either 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?

Gives clear routing context: fetch the collector's inputSchema via list_collectors, poll long runs with collector_run_status, and force background with async=true. It does not state explicit exclusions or when not to use it, but the when/how guidance is strong and actionable.

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 establish that this is a non-read-only, non-destructive write. The description goes well beyond: it discloses version bumping, per-field scoring on every run, automatic regeneration on decay, and the crucial constraint that without a source_url self-healing is impossible. This is rich behavioral context an agent could not infer from 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?

Three tight sentences, front-loaded with the core action and reuse path, then self-heal behavior, then the standout operational advice. No sentence is filler; each adds a distinct fact.

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 purpose, persistence model, self-heal mechanics, and the key source_url recommendation for a complex 8-parameter tool with no output schema. The one minor gap is that it says the preset is reused 'by id' but does not state that the tool returns that id, which the agent needs to chain calls.

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 8 parameters, including source_url's role. The description reinforces source_url's importance ('without one it can never self-heal') and ties auto_heal to it, but adds little syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Store a generated parser under a name') plus the reason ('so it can be reused by id'). This clearly separates it from the sibling generate_parser (which produces a parser) and list_parser_presets (which reads them). An agent can pick this tool without opening 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?

Explicitly routes the agent to scrape's `preset_id` for later reuse, giving a concrete when-to-use context. It also advises passing source_url whenever possible. It stops short of naming the alternative tools (e.g., generate_parser to create, heal_parser_preset to fix manually), so there are no explicit exclusions.

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 declare only readOnlyHint and openWorldHint, but the description adds substantial behavioral context: residential proxy routing, a real Chrome TLS fingerprint by default, browser escalation only on bot challenges, and exactly what 'smart' Markdown includes (nav/footer/cookie chrome stripped, GFM tables, absolutized links). This goes well beyond the structured fields.

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?

It is a dense but front-loaded paragraph: the primary action and default output lead, followed by extraction and format caveats. Every sentence carries information despite covering a 33-parameter tool, though it could be tightened.

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 33-parameter tool with no output schema, the description covers the core fetch/parse/extract behavior and key mode switches well. It does not describe the payload/return shape (payload.chunks, payload.data, etc.), which only appears in schema property descriptions, leaving 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 description coverage is 100%, so every parameter is already documented in the schema; the baseline of 3 applies. The description restates the key defaults (content_mode 'smart', markdown format) that are already defined on the parameters, adding framing but little 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 opening sentence names a specific verb (Scrape), a scoped resource (a single web page), and the mechanism (residential proxy), returning 'clean Markdown (or HTML/text)'. The 'single' qualifier and the description of optional structured/AI extraction distinguish it from crawling/batch siblings without needing their 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?

It gives clear context for specific modes — use format 'html' to inspect a no-JS/SEO fallback, use xhr/fetch_resource to discover an SPA's API, use 'tls' for SEO checks — which is strong in-tool guidance. However, it never explicitly routes the agent away from siblings like crawl, batch, or search_and_read, so the when-not condition is left implicit.

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 openWorldHint, so safety is covered. The description adds genuinely useful behavioral context: it runs through a residential proxy (relevant for blocking/rate-limit expectations) and parses rich blocks over HTTP rather than rendering. It stops short of describing output shape or pagination behavior.

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, front-loaded with the core action and proxy/scraping behavior. Every sentence carries information; the engine/vertical sentence is long but justified given 18 search_type values.

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 search tool with a 40-parameter, fully described schema and no output schema, the description covers purpose and engine/vertical scope adequately. But it omits any return-shape or pagination narrative and gives no sibling routing, which matters given search_bulk/search_and_read live in the same namespace.

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 baseline is 3. The description goes slightly beyond by clarifying which engines and verticals are supported (Bing's set, Google's extra set, Copilot citations when returned), giving the agent engine/vertical selection context the per-param schema does not consolidate. It does not restate parameter syntax, appropriately leaving that to 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 states a clear verb+resource ('Run structured Google, Bing or DuckDuckGo searches') and details engine-specific verticals. However, it does not distinguish this tool from the closely named siblings search_bulk and search_and_read, which an agent could easily confuse for the same or adjacent capability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance: nothing states when to pick this tool over search_bulk (many queries/pages) or search_and_read. The schema mentions those siblings in passing for pagination, but the description itself offers no 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 declare readOnlyHint and openWorldHint, so safety profile is covered. The description adds valuable behavioral context: pages are fetched as clean Markdown, output includes citation-ready numbered sources and a token-bounded context string, and fetch_content=false skips page fetching. Doesn't mention rate limits or auth, but the operational shape is well disclosed.

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 dense sentences, no filler. The purpose and output are front-loaded before the routing directive. Every clause carries information.

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 9-parameter tool with no output schema, the description covers the main behavioral output (Markdown, numbered sources, context string) and routing. It doesn't explain return structure beyond naming the fields, but the schema documents all params and annotations cover the safety profile. Slightly short of full completeness.

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 9 parameters are documented in the schema. The description adds no parameter-level syntax or format details 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?

States a specific compound verb chain (search, fetch, return) and the resource (live web, organic pages, numbered sources, token-bounded context). It explicitly distinguishes itself from the sibling `search` by contrasting the goal types (answering/researching vs raw SERP structure/verticals).

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 when the goal is answering/researching, and use `search` when raw SERP structure or a specialized vertical is needed.' Names the alternative tool and the precise condition that selects it.

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 cover safety (readOnlyHint, openWorldHint) and the description adds substantial behavior beyond them: asynchronous execution, deduplication of merged results, retention of page-one AI Overview/PAA/Knowledge Graph enrichments, the render:true trigger for JS blocks, and a per-page billing model with refunds for unavailable pages. The cost and refund disclosure is unusually valuable. It stops short of explaining how the async job's results are ultimately retrieved.

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, front-loaded with the core behavior (paginate one query, merge deduped results), followed by enrichment/render semantics and then billing. Every sentence carries distinct information with no 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 an 18-parameter async tool with no output schema, the description covers purpose, enrichment, rendering, and billing well but omits the critical retrieval path: there is no mention of polling search_bulk_status or using the webhook parameter, so an agent knows it starts a job but not how to collect its output.

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 18 parameters, including render and max_pages. The description explains the effect of render:true and indirectly the cost of max_pages, but adds no syntax or format guidance beyond 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?

States specific verbs ("paginate", "merge deduplicated organic results") and clarifies the scope as "ONE search query," which usefully distinguishes it from multi-query siblings like batch. The async nature further differentiates it, though it never names the specific sibling (search, search_bulk_status) it replaces.

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?

Implies usage context (deep paging of a single query, async execution, page-based billing) but never states when to choose this over search or batch, nor the prerequisite of retrieving results later. Usage is inferable rather than explicit.

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 safety and repeatability are covered structurally. The description adds genuinely useful behavioral context: polling is incremental and the previous response's nextCursor drives the since parameter. It doesn't describe what 'progress' fields or completion signals look like, but that's partly expected from the (future) response.

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 incremental polling rule. Efficient and specific, though not maximally trimmed.

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 status poller with fully-documented params and annotations covering safety/idempotency, the description covers the essential mechanics (incremental cursoring). Missing is termination/refresh guidance and any signal of what 'progress' contains, which would require an output schema to fully cover.

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 four parameters. The description reinforces the since semantics (previous poll's nextCursor, returns only newer results) which slightly exceeds the schema, but with full coverage 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 specific verb (poll), resource (bulk search job), and what is returned (progress and merged organic results). Clearly distinguishes this status-polling tool from the sibling search_bulk that initiates the job.

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?

Implicitly tells the agent to call this after search_bulk and to poll repeatedly, and explains the incremental polling mechanic. It does not explicitly state when to stop polling (e.g., terminal state) or how it relates to search_bulk's jobId beyond the schema, but the context is clear.

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 openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that — two fetch passes (bot vs rendered), the diff computation, and the cost implication of no_render — though it doesn't mention latency or rate limits.

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?

One dense sentence with the core action and the routing hint front-loaded. Every clause adds value (dual-fetch, returned fields, diff, meta, when-to-use), though the enumerated list makes it heavier than strictly necessary.

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 fully carries the burden and does so: it enumerates the returned fields, the diff contents, and the meta categories, so an agent knows what to expect. Complete for a read-only audit tool.

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 url, context, country, llm_model, and no_render in detail. The description adds no parameter-level syntax or format guidance, so 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?

States a specific verb (audit) and resource (a URL's SEO) and spells out exactly what the tool does: two fetches, the fields returned, the diff, and bot-facing meta. It also distinguishes itself from the nearest sibling by saying to use it 'instead of scraping manually'.

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 clear use case ('checking how a page indexes') and explicitly positions it against manual scraping. It implies the cheaper no_render path but stops short of naming when-not-to-use or the alternative sibling tools like scrape/crawl.

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 and readOnlyHint=false, so the mutating nature of add/remove is covered. The description adds real value beyond that by explaining the auth-mode consequence (whitelisted machine bypasses username/password), but it is silent on the port-allocation behavior implied by the many 'Mobile add' parameters (ttl, sticky, ports_count, geo) and on reversibility of removal.

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, front-loaded with the core verb set, followed by the operational consequence and the exclusion. No filler 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?

Given 13 params, four required, and no output schema, the description supplies the essential framing (which services, what add/remove/list mean, why whitelisting matters). Its main gap is not flagging that add behaves differently for Mobile (allocating ports with TTL/sticky/geo), which matters 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 description coverage is 100%, so the schema already documents all 13 parameters, including which apply to add vs. remove. The description adds no field-level detail beyond schema; baseline 3 applies when the schema does the heavy lifting.

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 set (add/remove/list) against a specific resource (IP-auth whitelisting on a proxy service) and enumerates the exact service tiers affected. An agent can distinguish this from siblings like list_proxies or generate_proxies without opening 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?

It states both when to use it (IP-auth services: Residential Basic, Datacenter, ISP, IPv6, Mobile, and required for Mobile V2) and when not to (Residential Premium/Private use user:pass and don't need this). That is an explicit positive condition plus an exclusion, which is the top of the scale.

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