Tollkit Extract

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses headless-browser rendering, that images are never invented, that missing fields return null rather than guesses, redirect refusal behavior, caching semantics with cached:true and fetchedAt, failed extractions not being charged, and the two-call payment flow. This is exceptional transparency for a paid tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: purpose, when to use, exclusions, return shape, rendering behavior, cost/payment, redirect edge case, caching, and preview recommendation. Each paragraph is front-loaded with a clear signal (USE THIS, DO NOT USE, RETURNS, HOW, COST) and there is 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 a paid, multi-step tool with payment requirements and edge cases, the description covers everything an agent needs: input constraints, output shape (referencing the output schema), cost and auth model, failure behavior, caching, redirects, and a preview path. Nothing material is left to inference.

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 meaningful context beyond the schema: the detailed x402 two-call payment protocol for `payment`, the cost implication of redirects for `allow_redirect`, and the cached-render behavior tied to repeated URLs. It enriches parameter understanding without being redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Turn a product page URL into structured schema.org/Product data.' It clearly distinguishes from the plural sibling by stating it returns one product, not a list, and explicitly names preview_extract for trial usage. An agent can immediately tell this is the single-product extraction tool.

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

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

It provides explicit 'USE THIS WHEN' conditions with typical jobs, and explicit 'DO NOT USE FOR' exclusions (search/category pages, login/paywall, non-product pages, private addresses). It also routes to preview_extract when the agent wants to see output before paying. This is model usage guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses batch semantics, per-URL ok/error results, duplicate removal, flat billing even on partial success, and no charge when all URLs fail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but well structured with clear sections. Each section adds relevant operational or billing context, though a few technical details like EIP-3009 could be trimmed without losing core 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?

The description covers the important edge cases: partial failure, full failure, duplicate URLs, billing behavior, and return shape. Even with an output schema present, it provides enough behavioral context for an agent to invoke the tool correctly and know what to expect.

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 explains urls, payment, and allow_redirect. The description adds minor value by noting output order follows input order, but it mostly reinforces what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it extracts up to 5 product pages in one call and one payment, with a specific verb, resource, and batch size. It also differentiates itself from extract_product by emphasizing the multi-URL batch use case.

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

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

It explicitly says to use this whenever there is more than one URL, gives concrete example use cases, and directly contrasts with extract_product. It even advises using extract_product when there is a single uncertain URL, which is strong routing guidance.

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

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

The readOnlyHint annotation already covers safety, so the description adds useful context by stating the tool is 'Free' and outlining what information it exposes. It does not discuss rate limits or auth, but with zero parameters and read-only behavior, those omissions are minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loads the most important facts in the first sentence. The opening fragments are terse to the point of being slightly awkward, but every phrase earns its place and the sibling pointer is neatly included.

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

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

For a zero-parameter, read-only info tool, the description is almost complete: it states cost, content, and points to preview_extract for actual output samples. It does not enumerate the exact response fields, but the preview alternative compensates for that 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?

The tool has zero parameters and the schema coverage is 100%, so the description has no parameter burden. The baseline of 4 applies because there is nothing for the description to add beyond the schema, and it does not try to invent parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource as service info and states the key content areas: 'Free. Price, network, and what this service returns.' It does not use an explicit verb like 'get' or 'returns', but the tool name and title fill that in, and it clearly distinguishes itself from preview_extract.

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 routing rule: 'For a sample of the actual output rather than a description of it, call preview_extract instead.' This tells the agent when to choose the sibling and implies that this tool is for the descriptive summary, price, and network information.

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?

Discloses important behavioral details beyond the annotations: it is free, costs nothing, takes no arguments, runs real code rather than a hand-written example, returns the identical shape as extract_product, and is limited to one fixed sample page. This gives the agent a clear and honest picture of what will happen, especially useful since openWorldHint means results are not predetermined.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized, front-loaded with the core value proposition ('Free. Run a real extraction...'), and every sentence earns its place by explaining purpose, behavior, or limitation. It is concise yet complete, with no redundant phrases.

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

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

Given the zero-parameter schema, the presence of annotations, an output schema, and a simple non-nested return shape, the description covers everything an agent needs: what the tool does, when to use it, what it returns, what it cannot do, and how it differs from the paid alternative. No important gaps remain.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds meaningful context by explicitly stating 'It takes no arguments and costs nothing' and explaining why a URL parameter is intentionally absent ('You cannot choose the page'). This goes beyond the empty schema by clarifying the design rationale.

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 action ('Run a real extraction against one fixed sample product page and return the result'), names the exact resource, and distinguishes itself from extract_product by emphasizing the fixed sample page and free nature. It is immediately clear this is a trial/demo version, not the real paid extraction tool.

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

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

Explicitly says when to use this tool ('to decide whether extract_product is worth paying for') and when not to ('Use extract_product for the URL you actually care about'). It also explains the design limitation (cannot choose the page) and why that limitation exists, which removes ambiguity for the agent.

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