datawebot

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

Annotations cover only readOnlyHint and openWorldHint; the description adds substantive behavioral context beyond them — cost ('Free'), auth requirement ('no account needed'), that the result enumerates which tools need sign-in and how, and the catalog_version staleness/refresh rule. This is exactly the extra context annotations cannot 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?

Three sentences, no waste, and the most important instruction ('Start here') is front-loaded. Every clause earns its place: purpose, refresh trigger, return contents, and the free/no-account note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must explain the return payload — and it does: tool list, input schemas, sign-in requirements, sign-in instructions. Combined with the annotations, an agent has everything needed to call and re-call this tool 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to compensate for. Schema coverage is 100% and no parameter semantics are needed; the 4 reflects a clean, unparameterized contract without any added or missing parameter 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?

States a concrete verb and resource: it returns every datawebot tool available now, along with each tool's input schema, sign-in requirements, and sign-in instructions. It also distinguishes itself from run_tool, naming that sibling as the channel for tools added after the session started.

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?

Explicit when-to-call guidance: 'Start here' and 'call again whenever a result's meta.catalog_version differs from the one you saw first,' plus the alternative path (run_tool) for newly added tools. Nothing about invocation timing 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 already supply readOnlyHint and openWorldHint, and the description adds useful context beyond them: 'Allowlisted, unbilled' (no auth, no cost) and ETA-based polling behavior. These are genuine behavioral disclosures, though the phrasing 'scraping preview' and 'discovery reports blueprint maintenance' is garbled and adds noise rather than clarity.

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 core purpose is front-loaded in the first sentence, which is good. The second sentence is a confusing semicolon-joined bundle of jargon ('Allowlisted, unbilled scraping preview; discovery reports blueprint maintenance') that obscures rather than informs.

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 single undocumented parameter, the description carries real burden. It partially covers the tool's nature (read-only metadata), cost/auth status, and polling cadence, but omits what metadata is returned, the meaning of the ETA, and failure 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?

There is one required parameter (job_id as a uuid) and schema description coverage is 0%, so the schema documents nothing about it. The description never mentions job_id, its format, or how to obtain it, leaving a coverage gap it should have compensated for.

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 first sentence gives a clear verb+resource+scope: 'Read Job metadata only,' which distinguishes it from the sibling get_results by explicitly limiting the return to metadata. However, the remaining fragments ('discovery reports blueprint maintenance') are cryptic domain jargon and don't sharpen the purpose further.

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?

'Follow the ETA before polling again' gives an actionable polling cadence, implying this is a poll-until-complete tool. But it never names alternatives (get_results, submit_job) or when NOT to use it, so the guidance is implied 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 openWorldHint=true, so safety is covered. The description adds meaningful non-annotation context: "Best-effort" (results may be incomplete or fail) and "Needs sign-in" (authentication requirement), which an agent must know before invoking.

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 purpose, then the payload list, then two short imperatives and two terse caveats. It is dense but every clause carries information; only the long enumeration makes it slightly run-on.

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 describes the return payload (prices, shipping, discounts, seller ratings, links, images, reviews). Combined with the sign-in and best-effort caveats and readOnly annotations, an agent has everything needed to call it correctly 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?

Schema description coverage is 100% and the schema already states that query and product_id come from search_products and that country must match. The description reinforces the same constraint but adds no new syntax, format, or fallback semantics, 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 exactly what it does for a single product from search_products and enumerates the returned data (per-seller price, total with shipping, discount, stock/delivery, seller rating, direct link, plus images, rating breakdown, features, reviews). An agent can instantly distinguish it from the sibling search_products, which searches across products rather than detailing 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?

"For one product from search_products" and "Use the same query and country as the search" give a clear precondition and the tool that must run first. It does not, however, state what to do if the product is missing from results or name any alternative tool for a different need.

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 genuinely useful traits beyond that: 'unbilled' (cost behavior) and 'never starts another extraction' (no side effects). The trailing 'discovery reports blueprint maintenance' is opaque jargon that adds confusion rather than clarity.

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 core action and the no-extraction guarantee are front-loaded and earn their place. The final clause ('Allowlisted, unbilled scraping preview; discovery reports blueprint maintenance') is dense internal jargon that an external agent cannot decode, which dilutes an otherwise brief statement.

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 does helpfully distinguish two return states (pending metadata vs. an authorized completed result page). But with three parameters at 0% schema coverage and a multi-step job workflow implied by siblings, an agent still lacks enough to call this correctly on the first try.

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 0% across three parameters (job_id, cursor, page_size), so the description is the only place meaning could be added — and it says nothing about any of them. The phrase 'result page' loosely hints at pagination but never explains cursor or page_size semantics, so it fails to compensate for the coverage gap.

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 gives a specific verb (read) and resource (pending metadata / a completed result page), so the agent knows this fetches job output rather than triggering work. The 'Never starts another extraction' clause reinforces scope. However, it does not differentiate itself from the sibling get_job, leaving ambiguity about which retrieval tool to pick.

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?

'Never starts another extraction' functions as a when-not hint, implying this is a read-only polling/retrieval path. But there is no explicit guidance on when to use get_results versus get_job or discover, and no prerequisites (e.g., that a submit_job must have run first) are stated. Usage is only implied.

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 genuinely non-annotated traits: the operation is 'unbilled', gated by an allowlist, and functions as a 'preview' rather than a real submission — meaningful context for an agent deciding whether cost or side effects apply.

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 short, front-loaded sentences with no padding. The tradeoff is that the brevity comes at the cost of clarity, since the fragments ('discovery reports blueprint maintenance') read as jargon rather than plain intent.

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-param, no-output-schema discovery tool this is roughly adequate, but the cryptic 'one-URL Job' and 'blueprint maintenance' phrasing leaves the agent unsure what a blueprint is or how this relates to 'discover' and 'get_job' in the same family.

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?

Zero parameters with 100% schema coverage, so the baseline is 4. The description has no parametric content to add and none is needed.

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 resource ('one-URL Job contracts and limits') but the terminology mismatches the tool name ('blueprints' vs 'contracts'), leaving the agent to guess whether these are the same thing. It does not distinguish itself from the nearby sibling 'discover', whose name suggests a very similar function.

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 guidance on when to call this versus siblings like 'discover', 'get_job', or 'submit_job'. The 'allowlisted, unbilled scraping preview' fragment hints at context but never states the condition or timing for using this tool.

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=false and openWorldHint=true, so the agent knows this is an unconstrained dispatcher, and the description usefully explains why the world is open (dynamically added tools). However, it says nothing about failure modes for an invalid tool name, permission requirements, or that arbitrary side effects may result from the dispatched tool, which matters for a readOnlyHint=false router.

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 the action, followed by the use case and the exclusion. Every sentence carries distinct information with no redundancy.

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 meta-dispatch tool with no output schema, the description covers purpose, routing, and the reason the target tool set is unknown. It is nearly complete; only error/failure behavior for a bad tool name is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both 'tool' and 'arguments' including the cross-reference to discover's input_schema. The description only restates that pattern ('by name, with its arguments') without adding format or validation detail, so the baseline of 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 and resource (run any tool listed by discover) and explains the mechanism (by name, with its arguments). This clearly separates it from the concrete siblings like search_products or submit_job, which it dispatches to rather than duplicates.

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 states when to use it (tools not in your tool list, added after your session started) and when not to (tools already in your list can be called directly). Both the condition and the alternative path are named, 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 already cover read-only and open-world semantics, but the description adds genuinely new behavior: best-effort results with possibly stale prices and an explicit sign-in/auth requirement, plus instructions to warn the user about price accuracy. It doesn't cover pagination or the meaning of limit, so it falls short of full disclosure.

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, each load-bearing: what it returns, how results chain to the sibling, and the best-effort/auth caveats. Front-loaded with the core purpose and 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 compensates by enumerating the result fields, and it adds the chaining path, accuracy caveat and auth requirement. An agent has everything needed to call it correctly and set user expectations.

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 75%, with sites and country well documented in the schema itself; the description adds no additional parameter meaning and says nothing about limit or result-count behavior. Baseline 3 is appropriate since the schema largely carries parameter semantics.

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 ('Find products for sale across online shops') and enumerates the returned fields, so an agent knows exactly what comes back. It also names the sibling get_product_offers and the chaining pattern, cleanly separating this search tool from the per-seller offer lookup.

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 pass product_id to get_product_offers to get every seller's price and shop link, which is real routing guidance against a sibling. It also flags operational context (best-effort, needs sign-in), though it never states when not to use this tool or which sibling handles non-product discovery.

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 cover readOnlyHint=false and openWorldHint=true, so the description carries most of the burden and delivers real value: asynchronous execution, idempotency-key retry semantics, allowlist-gated access, and unbilled preview status. It does not disclose the return shape or polling requirement, which keeps 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?

The three clauses are compact and the core action is front-loaded, which is good. The trailing fragment "discovery reports blueprint maintenance" is cryptic and reads as an unrelated note, costing a point on structure and clarity.

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?

This is an asynchronous mutation with no output schema and a nested, wholly undocumented parameters object. The description omits the critical follow-up workflow (what identifier comes back, that the agent should poll get_job) and the blueprint allowlist specifics, leaving the agent under-equipped to complete the task beyond the initial call.

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 0% across 5 parameters, so the description must compensate and largely fails: it mentions only the URL and idempotency key, and gestures at blueprints via "allowlisted." It says nothing about the blueprint_id enum values, the nested `parameters` object (a nested object with no documentation anywhere), or `blueprint_version`.

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 first sentence gives a specific verb and resource ("Submit one URL asynchronously"), which is clearly distinct from read-side siblings like get_job, get_results, and search_products. It stops short of explicitly differentiating itself from run_tool, the closest sibling, so it lands at 4 rather than 5.

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 one concrete operational rule ("Keep the same idempotency key on retries") and flags the access/price context ("allowlisted, unbilled ... preview"), which does imply when this tool is usable. However, it never states when to choose submit_job over run_tool, nor what to do after submitting (poll with get_job), so usage is only partially covered.

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