Agent Utilities Hosted

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

Beyond idempotentHint, the description discloses cost ('PAID: 800 micro-dollar service credits per successful call'), authentication requirements ('private Authorization header'), and the billing implication of a new requestId. This gives an agent the operational consequences of calling the tool, which annotations do not 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?

Five short sentences, each carrying necessary operational information, with the purpose first and no filler. Billing, prerequisites, and recovery are packed efficiently.

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 all non-schema information an agent needs to invoke correctly: preparation call, credits, auth, billing, and recovery behavior. With an output schema present, return values don't need explanation.

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?

With 67% schema coverage, the description adds important requestId semantics: 'Reuse prepared arguments for recovery; a new requestId is a new billable operation.' It also maps the overall input to 'agent configuration text.' However, it does not elaborate on maxPriceMicroUsd beyond what the schema already states, so it stops short of a 5.

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

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

The description opens with a specific verb and resource: 'Review agent configuration text with five fixed risk heuristics.' This distinguishes it from sibling audits like agents_env_template_check or agents_tool_name_conflicts by scoping to agent configuration text with a fixed heuristic set.

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 clear prerequisites and sequencing: 'First use agent_utilities_prepare for this tool,' plus 'Requires existing credits and a private Authorization header.' It also instructs on recovery vs new operations. It does not explicitly name an alternative tool or a when-not condition, so it misses the top tier.

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, destructiveHint false, and idempotentHint true. The description adds substantial behavioral context beyond that: it never returns assignment values (privacy guarantee), costs 500 micro-dollar service credits per successful call, requires existing credits and a private Authorization header, and clarifies that a new requestId is a new billable operation. This is rich, non-obvious information that annotations do not cover. No contradiction with annotations.

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

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

The description is a few sentences, front-loaded with the core purpose, then cost, prerequisites, and recovery. Every sentence adds essential information: the purpose, the privacy guarantee, the cost, the prerequisite step, and the billing behavior. There is no fluff or repetition.

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

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

Given the tool's complexity (paid, requires preparation, has an output schema), the description covers the essential operational aspects: purpose, cost, prerequisites, recovery, and a key behavioral guarantee (no value returns). The output schema presumably defines the return format, so that gap is acceptable. However, it does not specify what 'compare' returns (e.g., a diff list, a match/mismatch flag), which an agent might want to know before calling. This slight omission keeps it from being a 5.

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 67% (requestId and maxPriceMicroUsd have descriptions; the nested input object does not). The description gives the overall purpose of comparing template and actual, which helps infer what 'input' contains, but it does not elaborate on the format or semantics of the template and actual strings beyond that. It adds some value over the schema but does not fully compensate for the missing input property descriptions.

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

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

The description states a specific action ('Compare environment-variable names') on a specific resource (against a template) and immediately clarifies it never returns assignment values, which distinguishes it from any tool that might expose secrets. It also mentions the paid nature, adding uniqueness. This is clear and differentiates it from siblings like agents_config_audit or security_secret_scan.

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

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

The description explicitly instructs to first use agent_utilities_prepare, lists prerequisites (existing credits and a private Authorization header), and explains recovery behavior (reuse prepared arguments, new requestId is a new billable operation). This gives clear when-to-use and step-by-step operational guidance, including a caution about billing. It does not explicitly name alternatives but effectively routes the user through the required preparation step.

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

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

Goes well beyond annotations by disclosing exact cost per successful call, authorization requirements, and the billing implication of a new requestId. This is exactly the non-obvious behavior an agent needs to avoid surprise charges, and it complements the idempotentHint rather than relying on it.

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 dense sentences with no filler; the core purpose is front-loaded before the commercial and auth details. Slightly more structured formatting (e.g., bullet list for prerequisites) would improve scannability, but current prose is still efficient.

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 a nested input schema, output schema, and annotations, the description covers the full call path: precedent tool, prerequisites, auth, cost, recovery, and billing behavior. Nothing needed for 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 already documents requestId and maxPriceMicroUsd, and the description adds semantic weight by tying requestId to prepared arguments, recovery, and a new billable operation. The names array is self-explanatory from the tool purpose, so the 67% schema coverage is sufficiently compensated.

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

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

Description opens with a precise verb and object: find duplicate or easily confused tool names, with explicit normalization dimensions (Unicode, case, separator). This fully distinguishes it from siblings such as agents_config_audit or agent_utilities_prepare.

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

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

The description gives clear operational context: call agent_utilities_prepare first, require credits and a private Authorization header, and reuse prepared arguments for recovery. It doesn't list exclusions or equivalent alternatives, but the tool's purpose is unique enough that this is not a significant gap.

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

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

Annotations already signal read-only/idempotent/safe, and the description adds meaningful context: it uses only the Authorization header, has no financial side effects, is a point-in-time snapshot, and excludes wallet USDC. This goes well beyond the annotation hints.

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

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

Five short sentences, each adding essential information: action, auth mechanism, non-financial nature, snapshot caveat, and explicit exclusion. No filler or redundant restatement.

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?

Despite having no output schema, the description fully covers what an agent needs to invoke this safely and correctly: no arguments, auth expectations, side-effect profile, and result semantics. Nothing material is missing for a zero-parameter read 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?

With zero parameters, the empty schema already implies no arguments, but the description adds important clarity by stating 'takes no arguments or credentials' and explaining that authentication comes only from the private Authorization header.

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 ('read') and resource ('service-credit balance and live/test mode'), and clarifies what it is not ('Does not read wallet USDC'). This is distinct from sibling tools focused on config audits, preparation, and parsing utilities.

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 implies when to use: whenever the current credit balance or live/test mode is needed. It also explicitly excludes non-read use cases with 'No charge, purchase, reservation or total spending limit,' though it does not name a specific alternative sibling 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 indicate readOnly, idempotent, and non-destructive, but the description adds substantial behavioral context: it is 'FREE, no API key,' examples are 'fixed handler-generated' and 'synthetic, not customer activity,' and it cannot spend credits. These details go well beyond the structured annotations.

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

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

Three sentences, no filler, with the most attention-grabbing facts ('FREE, no API key') front-loaded. Each sentence adds distinct value: pricing, purpose, and constraints.

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

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

For a tool with one constrained enum parameter and rich annotations, the description covers the tool's purpose, input expectation, limitations, and synthetic nature of the output. No output schema exists, but the description clearly says it returns an input/output example, which is sufficient.

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?

With schema description coverage at 0%, the description compensates by clarifying that the sole parameter 'Accepts only a tool name' and is not for custom input. The enum in the schema provides the allowable tool names, and the description's framing tells the agent the parameter identifies which example to view.

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 action and resource: 'Read a fixed handler-generated input/output example for a listed non-network tool.' It also differentiates itself from execution tools by noting it 'cannot run custom input, access a wallet or spend credits,' making its purpose distinct from siblings like agent_utilities_prepare.

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

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

The description gives clear context: use this tool 'before deciding whether to pay' and for previewing examples. It also implies exclusions by stating it cannot run custom input or access a wallet, but it does not explicitly name alternative sibling tools or give a when-not-to-use condition beyond those constraints.

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 indicate read-only and idempotent behavior, but the description adds substantial non-obvious constraints: no page fetch, no JavaScript execution, no live-price verification, no orders, a maximum of 3 offers, input byte limits, and the need to inspect truncated output and warnings. These details go well 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?

Three tight sentences pack in cost, access, scope, limits, behavioral exclusions, and a routing rule without redundancy. Key selling point 'FREE, no key' is front-loaded, and the alternatives are clearly stated.

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 an output schema present, return values are already covered. The description captures all major constraints and the alternative tool, so an agent can operate safely. The only notable gap is the under-specified baseUrl, which prevents 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 0%, so the description must compensate. It explains html by emphasizing 'supplied HTML only' and the 16384-byte limit, and it clarifies maxOffers defaults to 3. However, baseUrl is not described at all, leaving its purpose (likely URL resolution) implicit.

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: 'Extract declared Product/Offer JSON-LD from supplied HTML only.' It also distinguishes itself from siblings by highlighting the free, no-key nature and the limitation to declared JSON-LD without fetching or executing JavaScript, making it clearly different from commerce_offer_extract and html_jsonld.

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 usage context: 'FREE, no key' and 'No paid fallback.' It also names the alternative route for larger inputs: 'Larger HTML uses commerce_offer_extract after separate spending approval.' This gives an agent clear guidance on when to choose this tool versus a sibling.

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

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

Beyond the read-only/idempotent annotations, it discloses that the tool performs no network fetch, requires no payment/key, and has no paid fallback, plus a 4096-byte input cap. It also clarifies the financial scope by stating exact item subtotal only and excluding shipping/tax/fees.

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 compact sentences, all information-bearing, with the main purpose and key constraints front-loaded. No filler or repeated schema 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?

The description covers scale limits, cost semantics, side-effect behavior, and the paid alternative, and the output schema covers return structure. It does not explain how to interpret the offers/requiredUnits relationship in detail, but the example schema largely fills 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?

With 0% schema description coverage, the description partially compensates by encoding limits for offers, required units, units per pack, and packs per offer, and by clarifying price meaning (exact item subtotal). However, currency and minorUnitDigits semantics still depend on the example and schema patterns, so the compensation is incomplete.

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 'custom pack planning' and adds concrete scope constraints (up to 3 offers, unit/pack limits, exact item subtotal). It distinguishes itself from the paid commerce_pack_plan, though the precise operation—selecting offers to satisfy requiredUnits—is more implied than stated.

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 positions the tool as the FREE planning path and directs larger tasks to commerce_pack_plan after separate spending approval. The limits and exclusions (no key, payment, network fetch, paid fallback) tell an agent exactly when this tool applies.

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 destructiveHint, and the description reinforces and extends this with 'FREE, no key' and 'accepts no credentials,' which are not covered by annotations. It also explicitly states 'Creates no account, checkout or payment,' giving an agent strong confidence about side-effect-free 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?

The description is two sentences, front-loaded with the most important facts ('FREE, no key') followed by the read scope and an explicit statement about no side effects. Every clause earns its place 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 zero-parameter tool with rich annotations, the description covers purpose, usage context, authentication requirements, and absence of side effects. There is no missing information an agent would need to invoke it 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 has zero parameters, so there is no parameter documentation burden. The description appropriately omits parameter details; the baseline of 4 applies because there is no semantic gap to compensate 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 description clearly states what the tool does: 'Read current credit packs, live/test configuration and the funding link.' It identifies a specific verb and resource, but it does not explicitly contrast it with sibling tools like agent_utilities_balance or agent_utilities_pack_preview, so it stops short of full sibling differentiation.

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

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

The description gives clear context for when to use the tool: 'Explains how to enable paid MCP calls after a free trial' and reading payment configuration. It does not explicitly mention alternatives or when not to use it, but the intended scenario is clear enough.

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

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

Annotations already mark it read-only and non-destructive, and the description adds meaningful behavioral detail: it is FREE, it only validates/prepares, it produces a requestId and price ceiling, and repeated preparation is discouraged. These details go well beyond the structured annotations without contradicting them.

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

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

The description is compact, front-loaded with the FREE nature, and every sentence adds value. It packs purpose, constraints, return values, and a usage warning into four short sentences with no fluff.

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

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

With no output schema, the description helpfully names the return values: requestId, price ceiling, and exact arguments. It also warns the user to save the prepared call. The main remaining gap is the lack of an explicit response shape or instructions for how to use the requestId in a subsequent paid 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%, so the description must compensate for the two parameters. It references 'input' generically and implies the prepared call is named by `name`, but it never explains that `input` must conform to the selected tool's schema or how the returned 'exact arguments' relate to the input parameter.

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 ('Validate input') and resource ('one paid call'), and clearly enumerates the return values. It reads as a distinct preparation step rather than an execution tool, so an agent can separate it from sibling operation tools.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it is FREE, should be done before execution, and must not be repeated to recover an uncertain payment. It also clarifies that it performs no execution, funding, or reservation, preventing misuse.

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

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

The description adds significant behavioral context beyond annotations: the paid nature (300 micro-dollar credits per successful call), the prerequisite of preparation, the authorization requirement, and the fact that a new requestId creates a new billable operation. This aligns with idempotentHint=true and readOnlyHint=false without contradiction.

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

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

The description is dense and front-loaded: the core purpose appears first, followed by essential billing and prerequisite information. Every sentence conveys necessary operational detail, with no filler or repetition of schema 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?

For a paid, prerequisite-gated tool, the description covers the critical operational context: cost, preparation requirement, authorization, recovery behavior, and billing semantics. Since an output schema exists, the lack of return-value explanation is not a 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 67%, with requestId and maxPriceMicroUsd already documented in the schema. The description adds general meaning by clarifying that the code parameter is a GTIN check-digit validation, but it does not elaborate on the input object structure or code format beyond what the schema provides.

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

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

The description states a specific verb and resource: validating check digits for GTIN-8, UPC/GTIN-12, EAN/GTIN-13, and GTIN-14. It also explicitly distinguishes the tool from product lookup, which differentiates it from sibling tools like commerce_offer_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?

The description gives explicit prerequisites and workflow context: use agent_utilities_prepare first, require existing credits and a private Authorization header, and reuse prepared arguments for recovery. It clearly explains the billing implications but does not name an alternative for product lookup beyond saying 'no product lookup.'

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

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

Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description discloses the cost (300 micro-dollar credits per call), the requirement for a private Authorization header, and the recovery behavior (reuse requestId to avoid new charges). It also mentions per-price errors, indicating partial success/failure granularity. This adds substantial behavioral context that annotations alone do not provide.

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

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

The description is a compact paragraph where every sentence adds value: purpose, cost, prerequisite, and recovery behavior. The key purpose is front-loaded, and the technical details are efficiently packed. No filler or 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?

Given the tool's complexity (paid service, requires a prep step, has an output schema), the description covers all critical aspects: what it does, cost, prerequisites, recovery pattern, and error granularity. It does not describe the output format, but an output schema exists, so that is not required. The description is sufficient for an agent to use the 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?

Schema coverage is 67% (requestId and maxPriceMicroUsd have descriptions, input does not). The description echoes the locale, currency, and decimal scale from the schema but adds no new parameter details. The 'up to 50' limit is already in the schema's maxItems. The description does not clarify the meaning of input fields beyond what the schema enums and types convey, so it meets the baseline but does not enhance understanding.

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

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

The description clearly states the verb 'Normalize' with a specific resource ('displayed prices') and scope constraints (up to 50, explicit locale/currency/decimal scale). It also mentions exact amounts and per-price errors, which distinguishes it from sibling tools like commerce_unit_price or commerce_price_components that handle different aspects of pricing.

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

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

The description explicitly instructs to use agent_utilities_prepare first and explains the recovery pattern (reuse requestId, new requestId = new billable operation). It also states prerequisites (existing credits, Authorization header). It does not explicitly name alternatives or say when not to use it, but the prerequisites and purpose are clear enough for an agent to decide. Lacks explicit exclusions compared to other tools, so not a 5.

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

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

Annotations only mark the operation as idempotent and non-destructive. The description adds substantial behavioral context: cost ('800 micro-dollar service credits per successful call'), authentication requirements, and billing semantics ('a new requestId is a new billable operation'). This is exactly the kind of stateful, side-effect disclosure that annotations alone 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?

Three sentences with no fluff: the first sentence front-loads the core purpose, the next states cost, and the third covers the prerequisite, auth, and recovery semantics. Every sentence carries necessary 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?

The description covers the non-obvious operational aspects: the mandatory prepare call, credits, auth header, recovery reuse, and billing tied to requestId. Since an output schema exists, return values do not need elaboration; minor gaps like the role of baseUrl are acceptable.

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

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

The schema already describes requestId and maxPriceMicroUsd, but input has no description. The description adds meaning by specifying the input as 'JSON-LD HTML' and by tying maxPriceMicroUsd to the 800 micro-dollar per-call cost, clarifying the debit cap. It does not describe baseUrl or maxOffers, but those are relatively self-evident and constrained by 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 specific verb ('Extract') and resource ('bounded Product offers from supplied JSON-LD HTML') and lists distinctive outputs (source pointers, missing-price warnings, aggregate ranges). It is clear what the tool does, but it does not explicitly contrast itself with sibling commerce/html tools, so it earns a 4 rather than a 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?

The description gives explicit prerequisites and sequencing: 'First use agent_utilities_prepare', requires existing credits and a private Authorization header, and recommends reusing prepared arguments for recovery. It does not, however, name alternative tools or state when not to use this one, so it falls short of full 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 signal idempotency and non-read-only behavior, and the description adds essential operational traits beyond that: paid service credits per successful call, the need for prepared arguments, recovery via reused requestId, and that a new requestId is a new billable operation. This meaningfully extends the annotations and matches the idempotentHint.

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

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

The description is compact and well-ordered: core behavior first, then billing, prerequisites, and recovery semantics. Every sentence earns its place, and there is no wasted wording or repetition of schema details.

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

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

For a nested, paid, externally prepared tool, the description is quite complete: it covers purpose, prerequisites, authorization, billing, and idempotent recovery. The output schema exists, so return values need not be described here; the main gap is the lack of explicit nested-parameter guidance, but the schema and purpose largely cover that.

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 67% at the top level, and the description gives conceptual context for key inputs like required count, exact prices, and pack limits. However, it does not explain nested fields such as currency, minorUnitDigits, or the relationship between offers, unitsPerPack, and maxPacks beyond the schema's structural constraints.

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

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

The description opens with a specific verb and resource: 'Choose the lowest-cost whole-pack combination for a required count.' It clearly differentiates this tool from siblings like commerce_unit_price or commerce_price_components by emphasizing whole-pack combination optimization with explicit pack limits.

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

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

The description gives clear usage context: first call agent_utilities_prepare, requires existing credits and a private Authorization header, and warns about billing per requestId. It does not explicitly state when not to use this tool versus alternatives, but the prerequisites and cost model are 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?

The description discloses billing behavior (500 micro-dollar credits per successful call), prerequisites (credits, Authorization header), and the idempotent recovery pattern (reuse requestId; new requestId is new billable operation). It also clarifies that missing costs remain unknown, which is a behavioral trait not evident from annotations. No contradiction with annotations (idempotentHint true aligns with recovery).

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

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

The description is compact, with each sentence carrying essential information: purpose, cost, prerequisites, and recovery. It is front-loaded with the core purpose. It could be slightly more structured (e.g., separating payment info from usage steps), but it's not verbose or redundant.

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 complexity (nested input object, 3 top-level parameters, output schema present), the description covers key operational aspects: payment, prerequisite steps, recovery, and the tool's core behavior. It does not explain the output schema, but that is available in the schema itself. It lacks explicit error-handling guidance, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 67% (two of three top-level parameters have descriptions). The description adds general context about the purpose of the input (reconciling amounts) but does not explain each nested parameter's semantics beyond what the schema already specifies. It adds minimal additional value for the input object, so a 3 is appropriate.

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

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

The description states a specific verb ('Reconcile') and clearly lists the resource types (item, discount, shipping, tax, fee) and the intended outcome (check declared totals). It distinguishes the tool from siblings by its focus on price component reconciliation, making its purpose unambiguous even without comparing to alternatives.

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

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

The description provides explicit usage flow: call agent_utilities_prepare first, then use the returned requestId. It also specifies prerequisites (existing credits, private Authorization header) and recovery guidance (reuse prepared arguments). However, it does not explicitly state when to avoid this tool or compare to alternative siblings, so it's slightly less than a perfect 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 only convey read/write and idempotency hints. The description adds crucial non-obvious behavior: the exact credit cost, the mandatory preparation step, the private auth requirement, and that a new requestId triggers a new billable operation. This aligns with idempotentHint=true and goes well beyond the structured annotations.

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

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

Three dense, front-loaded sentences cover purpose, cost, prerequisites, and recovery semantics with no filler. The most important scope and exclusion information appears first, and every sentence adds operational value.

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, preparation-dependent tool with a nested input schema and an output schema, the description is complete: it explains what the tool does, how much it costs, what must happen before calling it, what auth is required, and how to avoid duplicate billing. Remaining return-format details are covered by the output schema and annotations.

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

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

The schema documents requestId and maxPriceMicroUsd, but the core `input` object lacks a top-level description. The description compensates by clarifying the comparison scope (up to 50 offers), unit compatibility classes, and no-currency-conversion rule, and by linking requestId reuse to recovery. It still leaves the interpretation of the `reference` sub-object mostly to the schema, so it is not a 5.

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: compare up to 50 explicit pack prices using exact arithmetic across compatible mass, volume, or count units. The 'no currency conversion' qualifier further distinguishes this unit-price comparison from money-conversion or pricing tools.

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

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

The description gives strong operational guidance: use agent_utilities_prepare first, requires existing credits, requires a private Authorization header, and explains recovery semantics and billing consequences of new requestIds. It does not explicitly name an alternative tool or say 'use this instead of X for Y', so it stops just 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?

Beyond annotations, the description discloses key behavioral facts: each successful call debits 500 micro-dollar credits, a new requestId starts a new billable operation, and calling requires existing credits plus a private Authorization header. This is exactly the kind of non-obvious operational context an agent needs and nowhere in 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 sentences, each earning its place: purpose, cost, prerequisite, and recovery rule. Critical billing and workflow warnings are front-loaded while the recovery nuance is added last without bloat.

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 output schema already covers return shape, the description covers everything an agent needs to call the tool safely: purpose, prerequisite preparation step, authorization requirement, billing semantics, and recovery behavior. The complexity here is moderate and the description adequately addresses it.

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

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

The schema already documents requestId and maxPriceMicroUsd well, covering 67% of parameters. The description adds meaning to the undocumented 'input' object by framing its nested fields as 'requested' and 'offered' product attributes, and it reinforces the billing/recovery relevance of requestId and maxPriceMicroUsd. Still, it leaves the nested object semantics only lightly specified, so it does not fully compensate for the remaining schema 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 description opens with a specific verb and resource: it compares requested product attributes against an offered variant and reports missing or mismatched fields. This makes the tool's core function immediately clear and distinct from commerce_* siblings like commerce_offer_extract or commerce_price_components, which serve different purposes.

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

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

The description gives explicit workflow guidance: call agent_utilities_prepare first, ensure credits and a private Authorization header exist, and reuse prepared arguments for recovery within the same requestId. It does not explicitly state when to avoid this tool or name a direct alternative, but the prerequisites and payment conditions are strong enough to guide an agent.

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

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

Adds behavioral context far beyond the annotations: paid credits per call, need for existing credits and a private Authorization header, and the billing implication of a new requestId. Also warns that the JSON Schema support is a bounded subset. Nothing contradicts the idempotentHint or destructiveHint 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?

Five short, high-signal sentences. Purpose is first, followed by cost, prerequisite, and recovery. No filler or repetition of schema 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?

Covers the essential operational context: cost, auth, preparation, and idempotent recovery. An output schema exists, so return-value details are not required. Missing nuance about what the bounded subset includes or how 'input' should be assembled is the main 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 description reinforces requestId and maxPriceMicroUsd semantics via 'new requestId is a new billable operation' and the PAID credit cost, adding value over the schema. However, the 'input' object with nested 'schema' and 'data' is not described, and the exact boundaries of the 'bounded JSON Schema 2020-12 subset' are left undefined. Schema coverage is only 67%, so the description only partially compensates.

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 ('Validate'), resource ('data using a bounded JSON Schema 2020-12 subset'), and puts a clear limit on scope with 'bounded subset.' It doesn't explicitly name sibling alternatives, so it doesn't fully earn a 5, but the core purpose is unmistakable.

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

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

Gives explicit prerequisite guidance ('First use agent_utilities_prepare') and recovery strategy ('Reuse prepared arguments for recovery; a new requestId is a new billable operation'). It clearly establishes when to call this tool in sequence, though it does not mention alternative validation tools or when not to use 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?

Beyond the idempotentHint annotation, the description discloses the cost (800 micro-dollar credits per successful call), auth requirements, and the billing semantics of new requestIds. It also clarifies recovery behavior, which is not visible in the schema or annotations.

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

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

The core purpose is front-loaded in the first sentence, followed by compact billing, prerequisite, and recovery guidance. Every sentence adds essential operational 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?

The description covers cost, prerequisites, auth, and recovery semantics, and an output schema exists to define return values. It lacks an explicit comparison to sibling tools or a fuller definition of 'selected direct breaking changes,' but the essential calling context is present.

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?

With 67% schema coverage, the description adds meaning to requestId ('reuse after uncertainty') and maxPriceMicroUsd ('0 means recovery only') beyond their schema descriptions. It also ties the input to agent_utilities_prepare, though the before/after objects themselves remain semantically thin.

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 precise action and resource: detecting selected direct breaking changes between OpenAPI 3.0 documents. This clearly distinguishes the tool from siblings like contracts_openapi_lint (single-document linting) and data_json_diff (generic JSON diffing) even without naming them.

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

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

The description gives concrete usage context: must call agent_utilities_prepare first, requires credits and a private Authorization header, and should reuse prepared arguments for recovery. It does not explicitly state when not to use it or name alternatives, so it stops 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?

The description adds valuable behavioral context beyond the annotations: the paid cost (500 micro-dollar credits per successful call), prerequisites, authentication requirements, and the billing/recovery semantics tied to requestId reuse. This is especially useful given the tool has a financial side effect and aligns with idempotentHint without contradicting any annotation.

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

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

The description is compact and efficiently front-loaded: purpose first, then cost, prerequisite, auth, and recovery semantics. Every sentence adds distinct operational information 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?

Given the tool's complexity as a paid, auth-gated, idempotent operation with an output schema, the description covers purpose, cost, prerequisites, auth, and recovery. The main gap is the lack of explicit guidance on when to choose this over related contract tools, but the structured schema and output schema carry most remaining invocation details.

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 descriptions cover two of three parameters, and the description strengthens their meaning by linking requestId to prepared arguments and billable operations and by clarifying the recovery context behind maxPriceMicroUsd=0. The input.document parameter still lacks explicit schema detail, but the purpose statement partially compensates by specifying OpenAPI 3.0 JSON structure.

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 'Validate OpenAPI 3.0 JSON structure and internal references,' which names a specific action and resource and clearly identifies what the tool operates on. It is distinct enough from related siblings like contracts_openapi_diff and contracts_jsonschema_validate, though it does not explicitly name or contrast those alternatives.

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

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

The description provides clear operational context: call agent_utilities_prepare first, require existing credits and an Authorization header, and reuse prepared arguments for recovery. It does not, however, give explicit exclusions or direct comparisons with sibling tools, so the when-versus-alternatives guidance is incomplete.

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

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

Beyond idempotentHint=true and readOnlyHint=false, the description reveals pricing (300 micro-dollar credits per successful call), credential prerequisites, the mandatory prepare step, and the critical nuance that only reused requestId arguments enable recovery without a new charge. This is exactly the operational context an agent needs for a paid, stateful 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?

Every sentence earns its place: purpose, JCS caveat, pricing, prerequisites, and recovery behavior are all packed into four tight sentences. The functionality statement is front-loaded, followed by operational warnings in logical order. There is no repetition or filler, and the key cost warning is clearly highlighted.

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 tool with an output schema and a multi-step preparation requirement, the description covers the essential operational lifecycle: prepare, authorize, call, recover, and avoid duplicate billing. Combined with the output schema and input parameter descriptions, an agent has enough context to invoke the tool correctly and manage its cost implications.

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

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

The schema already describes requestId and maxPriceMicroUsd, covering 67% of parameters. The description adds important billing semantics around requestId: reusing prepared arguments is recovery, while a new requestId is a new billable operation. It does not elaborate on the open 'data' property, but the tool name and purpose make its role sufficiently clear.

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

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

The description uses a specific verb and resource: 'Serialize JSON with sorted object keys for deterministic comparison.' It also explicitly disclaims RFC 8785 certification, which prevents an agent from assuming strict JCS compliance and differentiates this tool from related JSON utilities like data_json_diff and data_json_patch.

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

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

The description gives clear procedural guidance: run agent_utilities_prepare first, require existing credits and a private Authorization header, and reuse prepared arguments for recovery. It also warns that a new requestId creates a new billable operation. It stops short of explicitly naming sibling alternatives or stating when to prefer canonicalization over diff/patch, which would have made this 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?

Beyond annotations, the description discloses the paid nature ('500 micro-dollar service credits per successful call'), the prerequisite preparation step, the auth requirement, and that a new requestId creates a new billable operation. This materially extends the idempotentHint and gives the agent important cost and recovery 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?

The description is compact and front-loaded: purpose, cost, prerequisite, auth, and recovery each get exactly one clear sentence. There is no filler, and every clause contributes operational 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?

The description covers purpose, cost, prerequisites, auth, and recovery behavior. Because an output schema exists and the input schema documents parameters, the description does not need to explain return shapes or full input details. It is complete for an agent deciding whether and how to invoke the 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 coverage is 67%, and the description augments it by explaining that requestId reuse is for recovery and that a new requestId is a new billable operation. It also ties 'bounded changes' to the maxChanges concept in the input schema, adding value beyond the raw parameter definitions.

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

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

The description opens with a specific verb and resource: 'Compare JSON structures and return bounded changes at JSON Pointer paths.' This clearly states what the tool does and its output style, and is distinct enough from siblings like data_json_patch or data_json_pointer that an agent can identify the correct operation.

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

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

The description gives concrete usage context: 'First use agent_utilities_prepare for this tool,' requires existing credits and a private Authorization header, and instructs reusing prepared arguments for recovery. It does not explicitly name alternatives or exclusions, but the preparation and recovery guidance is strong enough for an agent to call it correctly.

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?

Even with annotations present, the description adds substantial behavioral context: transactional application, 100-operation limit, strict pointer handling, safe object properties, bounded intermediate results, per-call billing, and the recovery implication that a new requestId triggers a new billable operation. This goes well beyond the annotations and aligns with idempotentHint=true without contradicting any annotation.

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

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

The description is compact and information-dense with no filler. Each sentence earns its place: the first defines what the tool does, the second announces the paid nature, the third gives the required setup, and the fourth clarifies recovery/billing semantics.

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 paid tool with a nested schema, the description covers the essential operational context: prerequisites, billing, limits, transactionality, safety constraints, and recovery behavior. An output schema is present, so the absence of return-value details is not a gap. An agent has enough information to invoke and recover from the 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 schema already documents requestId and maxPriceMicroUsd, so the baseline is 3. The description adds meaningful context by tying requestId to agent_utilities_prepare, recovery, and billable-operation semantics, and by explaining that maxPriceMicroUsd can act as a recovery-only control ('0 means recovery only' is in the schema, but the description reinforces its role in the billing flow).

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 ('Apply'), a precise standard ('RFC 6902'), a bound ('up to 100 operations'), and a clear resource ('supplied JSON'). It also states distinctive properties like transactional execution and strict pointers, making it easy to distinguish from sibling tools such as data_json_pointer, data_json_diff, and data_json_canonical.

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

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

The description gives clear context for use: it is a paid tool, it requires prior setup via agent_utilities_prepare, it needs existing credits and a private Authorization header, and it explains recovery by reusing prepared arguments. It does not explicitly name alternatives or state when not to use this tool, but the steps and preconditions are unambiguous.

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

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

Beyond the annotations, the description discloses the paid nature (300 micro-dollar credits per successful call), the dependency on agent_utilities_prepare, the authentication requirement, and important idempotency/recovery semantics (reusing requestId, new requestId is a new billable operation). This goes well beyond what the schema or annotations provide. No contradiction with annotations is 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?

Four sentences, each earning its place: function, cost, prerequisite/auth, and recovery semantics. The most important information is front-loaded, and there is no filler or redundant restatement of the schema.

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

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

For a paid tool with a prerequisite and recovery semantics, the description covers all operational essentials: what it does, how to prepare, what access is needed, what it costs, and how to avoid double billing. An output schema exists, so return-value details do not need to be in the description.

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 67%, with requestId and maxPriceMicroUsd already described in the schema. The description adds meaningful semantics for the paths parameter by identifying them as RFC 6901 pointer strings and reinforcing the 100-pointer limit. The input.data parameter remains generic, but the phrasing 'Select JSON values' implies it is the JSON document to traverse, so the description sufficiently compensates.

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 ('Select') and resource ('JSON values') using RFC 6901 pointer strings, and clearly distinguishes the tool from siblings like data_json_diff, data_json_patch, and data_json_canonical. It also adds a meaningful behavioral nuance: preserving missing versus null.

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

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

The description gives clear operational context: use agent_utilities_prepare first, existing credits and a private Authorization header are required, and prepared arguments should be reused for recovery. It does not explicitly mention alternatives or when-not-to-use scenarios, but the prerequisite and recovery guidance is strong enough for an agent to invoke this correctly.

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?

It discloses important behavioral traits beyond annotations: it is a paid operation costing 300 micro-dollar credits, requires a private Authorization header, and a new requestId creates a new billable operation. These details align with idempotentHint=true and add significant context about side effects and recovery.

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

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

The description is compact and front-loaded: purpose first, then billing, prerequisites, and recovery guidance. Every sentence adds necessary operational information with no fluff.

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

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

Given the output schema exists, the description does not need to explain return values. It covers the main operational requirements, but it leaves baseUrl semantics unexplained and does not clarify how the Authorization header is supplied, making it slightly incomplete for fully independent invocation.

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

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

Schema coverage is 67% with requestId and maxPriceMicroUsd already described. The description reinforces requestId semantics by linking it to agent_utilities_prepare and mentions recovery, but it does not explain the html input or baseUrl parameter beyond the schema. This is adequate but not exceptional.

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

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

The description clearly states the tool discovers up to 50 RSS, Atom and JSON Feed links from supplied HTML, using a specific verb and resource. This distinguishes it from sibling tools like html_links and html_metadata.

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

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

The description gives clear usage context: first call agent_utilities_prepare, requires credits and an Authorization header, and reuse prepared arguments for recovery. It does not explicitly name alternative tools or state when not to use it, but the prerequisite and billing 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?

The description discloses several behavioral traits beyond annotations: it is a paid operation (500 micro-dollar credits), requires prior preparation via agent_utilities_prepare, and has billing implications for new requestIds. It also clarifies it does not submit or return field values, which aligns with idempotentHint=true and adds context about side effects (none destructive). No contradiction with annotations.

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

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

The description is three sentences, with the core purpose front-loaded, followed by billing, prerequisites, and recovery guidance. Every sentence adds necessary operational context, with no filler or repetition. The structure is efficient and easy to parse.

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

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

The description covers the tool's scope (30 forms), prerequisites (prepare, credits, auth), billing model, and idempotency/recovery behavior. With an output schema present, return-value details are not needed. The description is complete for an agent to know how to call it correctly, including the critical 'first use prepare' instruction.

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

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

The schema already documents requestId and maxPriceMicroUsd with descriptions, and the description adds context about recovery and billing for those. However, the input object (html, baseUrl) is not described in the schema, and the description only indirectly references html by mentioning 'forms.' baseUrl is left unexplained, so the description only partially compensates for the missing schema coverage (67%).

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

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

The description clearly states the tool's function: 'Describe up to 30 forms and their controls without returning field values or submitting anything.' This gives a specific verb (describe), resource (forms and controls), a scope limit (30), and explicitly excludes actions (no field values, no submit). It also distinguishes from sibling tools like html_links or html_headings by focusing on forms.

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

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

The description provides explicit prerequisites: 'First use agent_utilities_prepare for this tool' and notes it requires existing credits and a private Authorization header. It also explains recovery behavior via requestId reuse. However, it does not contrast this tool with alternative html_* tools (e.g., when to choose forms over links), so it lacks a direct 'when-not' clause.

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

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

The description reveals paid credits, the prepare prerequisite, required authorization, and recovery semantics tied to requestId. These details go well beyond the annotations and align with idempotentHint true. No contradiction with annotations is apparent.

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 dense sentences with no filler: purpose, cost, prerequisites, and recovery behavior are each given one concise line. The most important operational details are front-loaded.

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

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

Combined with the input schema, annotations, and existing output schema, the description covers input shape, required prepare call, cost cap, credits, auth, billing behavior, and recovery. Nothing essential for 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?

requestId and maxPriceMicroUsd already have schema descriptions, while input.html only has type and maxLength. The description adds the 200-heading limit but does not explain expected HTML input semantics or error behavior, leaving the input parameter partially undercompensated.

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: extract headings from HTML, up to 200, with parent indices and skipped-level indicators. This clearly distinguishes the tool from other html_* siblings by naming its exact output and limits.

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 intended use is clear: extract headings when that structure is needed, with a clear prerequisite to call agent_utilities_prepare first. It does not explicitly compare against sibling tools or give when-not-to-use guidance, but the context is otherwise 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?

Annotations already mark idempotentHint=true and readOnlyHint=false, but the description adds significant behavioral context beyond them: the 300 micro-dollar cost, the required prepare step, the private Authorization header, and the billing distinction between reused and new requestIds. No contradiction with annotations.

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

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

The description is compact and front-loaded with the core purpose, followed by essential usage and cost details. Each sentence earns its place, and the structure allows quick scanning by an agent.

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 tool with required preparation, the description covers prerequisites, billing, authorization, recovery, and output limits. Since an output schema exists, return-value details are not needed. The description plus schema provides what an agent needs to 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?

Schema descriptions already cover requestId and maxPriceMicroUsd, and the description reinforces their recovery and billing semantics. However, the input.html and baseUrl fields are not explicitly explained; the description only implies HTML input through the extraction behavior and does not clarify baseUrl's role.

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

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

The description opens with a specific verb and resource: 'Extract up to 200 image URLs, alt text and source attributes'. It clearly states what the tool does and what it does not do ('does not fetch images'), which distinguishes it from sibling tools like html_links or web_readable_fetch.

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

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

The description gives solid when-to-use context: prerequisites (agent_utilities_prepare), credits, authorization, and recovery behavior. It does not explicitly name alternatives or state when not to use this tool, but the negative clause 'does not fetch images' partly serves that role.

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

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

The description discloses cost, prerequisites, size limits, and billing semantics: 300 micro-dollar credits per successful call, requires credits/Authorization header, up to 50 blocks, and a new requestId is a new billable operation. These details go well beyond the annotations and are consistent with idempotentHint=true because reusing a requestId enables recovery without new billing.

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

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

The description is compact and front-loaded: the core function appears in the first sentence, followed by cost, prerequisite, and recovery notes. Every sentence delivers operationally useful information without repetition or filler.

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

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

With an output schema present and three parameters documented in the schema, the description supplies the missing operational context: billing, auth prerequisites, preparation step, block limit, and recovery semantics. An agent has enough information to invoke the tool correctly and understand the consequences of doing so.

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 description adds practical meaning to requestId and maxPriceMicroUsd by framing them around recovery and billing, and the first sentence clarifies that the input is HTML to be parsed. The schema already documents requestId and maxPriceMicroUsd, while the nested input.html field's semantic role is implied by the tool's stated purpose.

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

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

The description opens with a specific verb and resource: 'Parse up to 50 JSON-LD blocks from supplied HTML.' This clearly differentiates html_jsonld from the many sibling HTML tools like html_metadata, html_tables, and html_feeds, which target other extraction tasks.

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

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

The description gives explicit operational guidance: call agent_utilities_prepare first, ensure existing credits and a private Authorization header, and reuse prepared arguments for recovery. It does not explicitly list 'when not to use' an alternative, but the unique JSON-LD extraction scope supplies enough routing context.

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

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

Annotations already indicate idempotent and non-destructive, but the description adds critical billing details (300 micro-dollar credits per successful call, new requestId is a new billable operation) and the need for credits and auth header. This goes well beyond annotations and is essential for correct usage.

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 sentences with no redundancy. The main purpose is front-loaded, followed by billing and prerequisites. Every sentence adds value; the structure is logical and easy to parse.

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

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

For a paid tool with an output schema, the description covers purpose, cost, prerequisites, and recovery. It tells the agent everything needed to call it correctly, including how to avoid extra charges by reusing requestId. No critical information 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 67% (requestId and maxPriceMicroUsd have descriptions, input does not). The description adds context about requestId reuse and billing but does not clarify the input object beyond what the schema shows. Since the schema covers most parameters, a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'extract' and the resource 'up to 200 links' plus the resolution of destinations against a URL. It distinguishes the tool from siblings like html_images or html_feeds by its specific 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?

The description gives clear prerequisites (use agent_utilities_prepare first, requires credits and Authorization header) and explains recovery behavior. It does not explicitly state when not to use this tool or name alternatives, but the purpose is distinct enough that an agent can infer appropriate usage.

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

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

Goes well beyond the annotations by disclosing the paid nature ('500 micro-dollar service credits per successful call'), the dependency on credits and auth header, and the billing behavior around requestId. This is valuable operational context not present in 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?

Every sentence earns its place: purpose, cost, prerequisite, auth, and recovery are all front-loaded and stated with minimal words. 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 a paid tool requiring preparation, the description covers the full lifecycle: what it does, how to set it up, what to expect in terms of billing, and how to recover without extra charges. The presence of an output schema also handles return-value 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 covers requestId and maxPriceMicroUsd with descriptions, but the tool description adds meaning to requestId ('Reuse prepared arguments for recovery; a new requestId is a new billable operation') and maps 'input' to the HTML being extracted. It does not explain maxPriceMicroUsd in the description, but schema coverage is already strong.

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

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

The description clearly states the action ('Extract article text') and resource ('supplied HTML'), which differentiates it from sibling tools like html_links, html_tables, or html_metadata. No ambiguity about what this tool does.

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 prerequisites: 'First use agent_utilities_prepare', requires credits and a private Authorization header. It gives recovery guidance but does not explicitly contrast this tool against siblings or state when not to use 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?

The description discloses billing costs (300 micro-USD per successful call), prerequisite preparation, and idempotent recovery behavior. These traits go beyond the annotations, which only indicate idempotency. The description aligns with idempotentHint and adds context about billing side effects, fulfilling the disclosure requirement.

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 three sentences long, front-loading the primary function then adding essential context about cost and prerequisites. Every sentence carries necessary information without redundancy, though it could be slightly more compact by merging the first two sentences.

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 tool's complexity (nested input, paid service, prerequisites) and the presence of an output schema, the description covers all critical aspects: purpose, cost, preparation, authorization, and idempotency/recovery. The only minor omission is explicit error handling, which is not required given the output schema.

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

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

The schema already describes requestId and maxPriceMicroUsd with notes about persistence and recovery. The description adds a reference to prepare and billing, but does not elaborate on html or baseUrl usage. With schema coverage at 67% and the description providing no additional parameter details, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Extract') with a clear resource ('title, description, canonical URL, language and social metadata') from supplied HTML. This clearly differentiates it from siblings like html_headings or html_jsonld, which target other specific content types.

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

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

Provides clear operational context: requires agent_utilities_prepare, existing credits, and a private Authorization header. Also explains recovery semantics and billing. However, it does not explicitly contrast with alternative html_* tools, though the purpose makes the intended use obvious.

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 behavioral disclosure beyond annotations: per-call cost (500 micro-dollar credits), the prepare-first prerequisite, credit and Authorization-header requirements, and the billing semantics of reused vs new requestId (recovery vs new billable operation). This fleshes out what idempotentHint=true means in practice and is consistent with all 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?

Five short sentences, each carrying distinct information: purpose, price, prerequisite, auth, and recovery semantics. The core purpose is front-loaded, and there is no filler or restatement of what the schema already says.

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 an output schema present and two of three parameters well documented in the schema itself, the description covers the non-obvious operational facts an agent must know: cost, prerequisite step, auth requirements, and recovery semantics. Minor gaps remain around behavior on insufficient credit and error handling beyond 'reuse prepared arguments.'

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 already documents requestId and maxPriceMicroUsd well (67% coverage); the description adds the workflow meaning — that requestId originates from agent_utilities_prepare and that reusing versus generating a new requestId controls billing. The html parameter lacks an explicit description, but its purpose is reasonably implied by 'source table cells.'

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 — 'extract source table cells' — and adds a distinguishing behavioral detail, 'without expanding spans.' This clearly separates it from sibling HTML tools (html_forms, html_headings, html_links, html_main_text) without needing to open their schemas. No ambiguity about what this tool does.

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 procedural context: first use agent_utilities_prepare, requires existing credits and a private Authorization header, and explains what counts as a new billable operation. This is actionable guidance, though it does not name alternatives or exclusion conditions relative to the sibling html_* tools.

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

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

The description discloses the paid nature ('PAID: 500 micro-dollar service credits per successful call'), prerequisites (credits, Authorization header), the preparation step, and that a new requestId is a new billable operation. It also states that cookie values are masked, which is a behavioral detail beyond the annotations (idempotentHint=true, readOnlyHint=false). No contradiction with annotations.

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

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

The description is tight and front-loaded: purpose, cost, preparation, and recovery each get exactly one clause. No redundant or filler wording. Every sentence contributes actionable information, and the most critical facts (what it does, cost) come first.

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

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

For a paid, stateful tool, the description covers all essentials: prerequisites, billing, recovery, and the preparation flow. The output schema exists, so return values are documented. The combination of description, annotations, and schema leaves no critical gap for an agent to 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 schema already provides descriptions for requestId and maxPriceMicroUsd, and setCookies has maxItems=50. The description reiterates the 50-cookie limit but adds no new parameter semantics. With schema coverage at 67%, the baseline of 3 is appropriate; the description does not compensate for the undocumented input object beyond what the schema implies.

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 ('check'), a concrete resource ('Set-Cookie headers'), a scope ('up to 50'), and what is evaluated ('security attributes and prefix rules'). It also mentions masking values, distinguishing it from sibling tools like security_header_audit or security_csp_audit. An agent can clearly tell what this tool 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?

The description gives clear procedural guidance: 'First use agent_utilities_prepare', requires credits and a private Authorization header, and explains recovery and billing. However, it never mentions when to use this tool over sibling audit tools (e.g., security_header_audit) or when not to use it. The agent must infer applicability from the stated purpose, which is less explicit than the ideal.

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 non-obvious behavior beyond annotations: the call is paid at 500 micro-dollar credits, cancellation/recovery semantics via requestId, that a new requestId is a new billable operation, and prerequisite setup steps. No contradiction with the annotations is 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?

The description is compact and front-loaded with the core function, followed by essential cost, prerequisite, and recovery details. Every sentence adds operational value 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?

Given the paid-service complexity and existing output schema, the description covers the critical operational context: cost, prerequisite call, authorization requirement, and recovery behavior. An agent has enough information to invoke it correctly and avoid surprise charges.

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 description clarifies that 'policy' is a Content Security Policy and adds billing/recovery context for requestId. Schema coverage is 67%, so this extra context helps compensate, though the nested input structure and maxPriceMicroUsd behavior rely partly on 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 names a specific verb ('Parse') and resource ('supplied Content Security Policy') and states the outcome ('flag selected risky or missing directives'). This clearly distinguishes it from sibling security tools like security_header_audit and security_cookie_audit.

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 preconditions and workflow: call agent_utilities_prepare first, requires existing credits and a private Authorization header, and reuse prepared arguments for recovery. It does not explicitly contrast with alternative security audit tools, so it falls just short of full alternative 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?

The description adds substantial behavioral context beyond annotations: it discloses the cost (500 micro-dollar service credits per successful call), prerequisites (existing credits and a private Authorization header), idempotency nuance (reusing requestId for recovery vs. new billable operation), and privacy (without echoing values). This aligns with the idempotentHint annotation and adds practical detail.

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 three sentences long, front-loading the core purpose, then addressing cost/prerequisites and recovery. It is efficient, with no redundant or vague statements, and every sentence contributes critical operational 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?

Given the tool's complexity (nested input, paid operation, prerequisite preparation, idempotency) and the presence of an output schema, the description covers all essential aspects: purpose, cost, prerequisite, auth, and recovery behavior. The output format is handled by the output schema, 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 description coverage is 67% (requestId and maxPriceMicroUsd have descriptions, input does not). The description adds some context about requestId usage ('Reuse prepared arguments for recovery') and billing implications, which clarifies parameter intent. However, it does not elaborate on the input object or maxPriceMicroUsd beyond the schema, so it only partially compensates 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 description clearly states the tool's function: 'Review supplied response headers for selected security and CORS issues without echoing values.' It specifies the verb (review), resource (response headers), and scope (security and CORS), and distinguishes itself from sibling audit tools like security_cookie_audit and security_csp_audit by focusing on headers broadly.

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

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

The description gives explicit usage guidance: 'First use agent_utilities_prepare for this tool' and 'Reuse prepared arguments for recovery; a new requestId is a new billable operation.' It does not explicitly compare to alternatives, but the name and sibling context make the differentiation clear. The lack of explicit 'when not to use' slightly reduces the score.

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

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

Beyond annotations, the description discloses the paid nature (300 micro-dollar credits), the prerequisite of agent_utilities_prepare, auth requirements, and the billing/recovery semantics of requestId. This meaningfully enriches the annotations and helps the agent anticipate side effects and required setup.

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

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

The description is compact yet information-dense, front-loading the core purpose before billing and usage warnings. Every sentence earns its place, and no wording is redundant.

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, externally-dependent tool, the description covers prerequisites, cost, authorization, idempotent recovery, and the key functional limitation. Since an output schema is present, the description does not need to explain return values, so nothing essential is missing.

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

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

Schema coverage is 67%, and the description adds semantic value by mapping 'optionally compare timestamps' to the atUnixSeconds parameter and explaining that a new requestId is a new billable operation. It also reinforces that maxPriceMicroUsd is a debit cap, which complements the schema's description.

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

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

The description opens with 'Decode untrusted JWT claims and optionally compare timestamps', which names a specific verb, resource, and action. It also clarifies what the tool does not do ('never verifies a signature'), distinguishing it from signature-focused JWT or security tools.

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

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

The description gives concrete usage context: call agent_utilities_prepare first, require existing credits and a private Authorization header, and reuse requestId for recovery. It does not explicitly name alternative tools or state when not to use it, but the 'never verifies a signature' caveat strongly implies the limitation.

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

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

Beyond annotations (idempotentHint=true, readOnlyHint=false), the description adds billing details (500 micro-dollar credits per call), the need for a private auth header, and that a new requestId is a new billable operation. This clarifies cost and idempotency implications, which the annotations only hint at.

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 concise (four sentences) and front-loaded with the primary purpose. The billing and prerequisite details are presented efficiently without redundancy. It earns a 4, not 5, because the usage notes could be slightly more compact.

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 essential operational context: paid service, preparation step, auth requirement, and recovery behavior. The output schema is provided separately, so no need to explain return values. It does not mention how the tool interacts with security_secret_scan, but that is not critical for invocation.

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

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

Schema coverage is 67% (requestId and maxPriceMicroUsd have descriptions; input does not). The description indirectly clarifies requestId (persist from prepare) and maxPriceMicroUsd (recovery only when 0), but these are already in the schema. It does not add new meaning for the input object, so it stays at the 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?

The description clearly states the action ('Replace detected credential patterns with redaction markers') with a specific verb and resource. It distinguishes from the sibling security_secret_scan (scan vs. redact) without being ambiguous.

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 prerequisites: first use agent_utilities_prepare, requires existing credits and a private Authorization header. Also explains recovery usage (reuse requestId). Does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when to invoke.

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 include idempotentHint=true but readOnlyHint=false; the description adds value by disclosing billing (500 micro-dollar credits), authentication requirements, masking of findings, and the rule that a new requestId is a new billable operation. This goes beyond annotations without contradicting them.

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 purpose, then cost, prerequisites, and recovery. Each sentence carries meaningful information without padding. Slightly dense but well-structured.

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 tool's complexity (paid, prerequisite, recovery), the description covers the essential operational details: billing, authorization, preparation step, and masking. The output schema exists so return format is covered. Minor omissions like explicit error handling or credit depletion scenarios are not critical.

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

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

Schema covers 67% of parameters with descriptions; requestId and maxPriceMicroUsd are already described. The description reinforces the meaning of requestId by linking it to agent_utilities_prepare and clarifies maxPriceMicroUsd's role in recovery. This adds marginal value but does not fully compensate for the undocumented 'input' parameter's nested structure.

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 (detect) with a clear resource (five families of credential patterns) and a distinguishing feature (fully masked findings). It is easily distinguished from the sibling security_secret_redact which implies a different operation.

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 prerequisites: call agent_utilities_prepare first, requires existing credits and a private Authorization header. Also explains recovery behavior (reuse prepared arguments). It does not explicitly name alternatives, but the context is clear enough for an agent to know the correct usage flow.

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

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

The description goes well beyond the annotations by disclosing the billing cost (300 micro-dollar service credits per successful call), the billable distinction for new requestIds, the preparation prerequisite, and the 'recovery' reuse semantics. It also adds technical behavior like preserving UTF-16 surrogate pairs, which is not present in the annotations or schema.

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

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

The description is compact and front-loaded: the core capability comes first, followed by billing and prerequisite information. Every sentence carries operational value, and the recovery note is especially important for correct repeated use.

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 tool with prerequisites and an output schema, the description is complete: it covers preparation, authentication, credits, billing behavior, idempotent recovery, and output characteristics. Nothing essential is missing for an agent to invoke and interpret 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?

Schema coverage is 67%, with requestId and maxPriceMicroUsd already described. The description adds meaningful context for the chunking behavior, such as 'overlapping,' 'at most 200,' 'offsets,' and UTF-16 safety, which helps interpret input.overlap and input.text, though it does not explicitly explain maxChars semantics beyond schema constraints.

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

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

The description opens with a specific verb and resource: 'Split text into at most 200 overlapping chunks with offsets and intact UTF-16 surrogate pairs.' This precisely defines the tool's function and its key output characteristics, and the chunking behavior clearly distinguishes it from the unrelated sibling tools.

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

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

The description clearly tells the agent to call agent_utilities_prepare first, requires existing credits and a private Authorization header, and explains the recovery pattern with reused prepared arguments. It provides strong contextual usage guidance, though it does not explicitly mention when not to use this tool or compare it to alternative tools.

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

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

Beyond annotations, the description reveals the paid nature (2000 micro-dollar credits), the need for existing credits and a private Authorization header, and the billing impact of generating a new requestId. This is non-obvious operational context that annotations alone do not provide, and it is consistent with the idempotentHint.

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 deliver the core action, cost, prerequisite, auth requirement, and recovery semantics with no filler. Critical constraints are front-loaded before secondary details.

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

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

For a paid external fetch tool, the description covers cost, prerequisite, authorization, recovery, and idempotent behavior. The output schema handles return-value documentation, so nothing essential is missing for an agent to 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 schema covers requestId and maxPrice with meaningful descriptions, but the tool description adds the 'approved public HTTPS host' constraint relevant to the url input and clarifies that reusing requestId matters for billing. It does not deeply describe the input object, but that structure is visible in 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 names a specific operation: fetching readable text from an approved public HTTPS host. It is concrete and action-oriented, and the 'approved host' and 'readable text' focus helps set it apart from web/HTML siblings, though it does not explicitly contrast itself with alternatives.

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 instructs to first use agent_utilities_prepare and to reuse prepared arguments for recovery, giving a clear prerequisite and recovery workflow. It also states that a new requestId is a new billable operation, but it does not discuss when to prefer this tool over sibling extraction tools.

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

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

The description discloses non-obvious operational behaviors beyond annotations: per-call cost ('1000 micro-dollar service credits per successful call'), dependency on agent_utilities_prepare, the Authorization header requirement, and the billing distinction between reused and new requestIds. These complement the annotations without contradicting them; idempotentHint aligns with the recovery guidance.

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?

Every sentence carries distinct, necessary information: purpose, cost, preparation dependency, credentials, and idempotent recovery behavior. The core purpose is front-loaded and the operational constraints follow compactly 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 a paid, externally-facing tool with nested input and an output schema, the description covers prerequisites, billing, auth, host restrictions, redirect limit, and recovery behavior. Sibling tools like agent_utilities_prepare and agent_utilities_balance make next steps discoverable, and the output schema handles return-value details.

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

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

The schema already documents requestId and maxPriceMicroUsd well, and the description adds recovery and billing context that makes those parameters meaningful. For the nested url parameter, the description adds the 'approved public HTTPS hosts' constraint and the redirect-tracing purpose, although it does not explicitly describe url formatting in the same 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?

Purpose is immediately clear: verb 'Trace', resource 'redirects', scope 'up to four', and constraint 'approved public HTTPS hosts'. This clearly differentiates it from siblings like web_readable_fetch or web_robots_evaluate, which do not follow redirect chains.

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

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

The description explicitly states prerequisites: 'First use agent_utilities_prepare for this tool' and 'Requires existing credits and a private Authorization header.' It also explains recovery semantics and billing ('Reuse prepared arguments for recovery; a new requestId is a new billable operation'). It stops short of naming a when-not-to-use alternative, so it earns a 4 rather than 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?

Adds substantial behavioral context beyond the annotations: the exact billing cost, the requirement to prepare first, the private Authorization header, and the crucial idempotency nuance that a new requestId means a new billable operation. This usefully qualifies the idempotentHint=true annotation and clarifies cost 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?

The description is tight and front-loaded with the core purpose, then adds necessary operational details without redundancy. Every sentence adds value: no network fetch, cost, prerequisite, auth, and idempotency/recovery behavior.

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

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

Covers the essential operational context for a paid, stateful tool: prep requirement, credits, auth, cost, and recovery semantics. Since an output schema exists, return-value details do not need to be in the description. The description is complete enough for an agent to use it 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 schema already describes requestId and maxPriceMicroUsd well, and the description reinforces their recovery and billing semantics ('Reuse prepared arguments', 'a new requestId is a new billable operation'). The nested input fields lack schema descriptions, but their meanings are evident from the tool purpose and property names.

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 ('Evaluate'), a precise resource ('supplied robots.txt'), and the dimensions of the evaluation ('for a URL and user agent'). The explicit 'no network fetch' distinguishes it from fetch-oriented siblings like web_readable_fetch and web_redirect_trace.

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

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

Provides clear prerequisites: must call agent_utilities_prepare first, needs credits and an Authorization header. It also explains recovery usage ('Reuse prepared arguments for recovery'). It does not explicitly name an alternative to use when a network fetch is needed, but the 'no network fetch' statement strongly implies this tool is only for supplied content.

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