agentic-payments

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context that it is free, read-only, and has no side effects like requiring account or credentials, reinforcing and expanding on annotations. No contradictions.

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

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

Two sentences that concisely convey purpose and constraints with no superfluous words. Every sentence earns its place.

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

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

Given the tool's simplicity (one param), existence of output schema, and rich annotations, the description is fully complete, covering what it fetches, that it's read-only, and its relation to search.

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

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

Input schema has one parameter with 100% coverage and clear description including examples. The description does not add semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'fetch' and identifies the resource as 'one document or instrument guide returned by search', clearly distinguishing it from sibling tools like search (which returns results) and list_instruments (which lists).

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

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

The description implies usage after search by stating 'returned by search', providing clear context. However, it does not explicitly state when not to use or compare to alternatives, but the sibling list makes the context clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by stating it does not fetch prices, charge a wallet, or submit payment, and clarifies it is read-only, reinforcing and expanding on the annotations.

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

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

The description is two sentences: first states purpose, second states return values and what it does not do. No waste, front-loaded with key 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 simple parameters and existing output schema and annotations, the description covers purpose, behavior, and next steps. It could explicitly mention using the resulting URL with the 'fetch' tool for completeness, but it is mostly 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?

Schema description coverage is 100%, so parameters are well-documented. The description adds no new details about parameters beyond what the schema provides, hitting the baseline of 3.

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

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

The description uses specific verb 'build' and resource 'x402-protected HTTP URL' for live market-data request. It clearly distinguishes from sibling tools like 'fetch' by stating it does not fetch prices.

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 indicates it is for building a URL for a live request and returns next steps, implying the workflow. However, it does not explicitly mention when not to use it or name alternative tools like 'fetch' for actual data retrieval.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it is free, read-only, and does not initiate payment. It also specifies the exact data returned (prices, tiers, networks). No contradictions with annotations.

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

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

The description consists of two short sentences, each adding essential information. The first sentence lists the data contents, and the second provides usage context. No wasted words 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?

The description fully captures the tool's functionality and purpose. Given zero parameters and the presence of an output schema (which the description does not need to detail), the description is complete. It tells the agent exactly what the tool provides and that it is safe to use.

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 description does not need to add parameter details. The schema coverage is 100% trivially, and the description does not repeat anything from the schema. Baseline 4 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 tool's purpose: inspecting per-call prices, bulk credit tiers, and supported settlement networks. It explicitly distinguishes itself from sibling tools by highlighting that it is for planning only and does not initiate payment, which differentiates it from any payment-related 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 provides clear context for when to use this tool—for read-only planning and obtaining pricing metadata. It explicitly states that it does not initiate payment, implying it should be used before any payment operations. However, it does not explicitly exclude other sibling tools or provide direct alternatives, so it is not 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that the tool is 'free and read-only', which is consistent and adds a cost-related behavioral trait. No contradictions.

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

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

The description is a single sentence with a clear list of items, followed by a brief note on cost and safety. It is concise and front-loaded, though the list could be slightly more 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 no input parameters and an existing output schema, the description adequately covers the tool's scope. It lists major components and notes the tool is free and read-only. However, it lacks specifics on the output format or limitations.

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

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

The input schema has no parameters, so the description cannot add parameter semantics. The baseline for 0 parameters is 4, and the description explains the tool's output content, which is valuable context.

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 inspects Blocksize raw data, equity ticker bid/ask, and premium agent-native workflow products, which aligns with the tool name 'get_product_catalog'. However, it does not explicitly differentiate from sibling tools like get_market_data_endpoint or get_pricing_info.

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

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

No explicit guidance on when to use this tool versus alternatives. The description only mentions it is free and read-only, but does not specify conditions or contexts. Sibling tools like fetch, get_market_data_endpoint are not referenced.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context: 'free and read-only; it does not fetch live data, charge credits, or start x402,' which reinforces and elaborates on the annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose and follows with behavioral modifiers. Every sentence adds 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?

Given the tool has a single parameter and an output schema, the description covers the key behavioral aspects and purpose. It mentions the output components (endpoint, method, cost, example body) but does not detail prerequisites or use cases, though the output schema likely fills in structural 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 description coverage is 100% because the 'product' parameter includes a description. The tool description does not add further semantics beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states the tool builds a specific HTTP endpoint for a premium Blocksize workflow, using the verb 'Build'. It distinguishes itself from sibling tools like 'get_market_data_endpoint' or 'fetch' by focusing on endpoint construction rather than data retrieval.

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

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

The description implies usage for preparing a paid HTTP endpoint but does not explicitly state when to use it versus alternatives or when not to use it. The phrase 'free and read-only' provides some context but no exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying the tool is free and does not fetch live prices, create accounts, or start payment, which are behavioral traits 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?

The description is minimal yet complete: two sentences, no fluff. The first sentence states the action and resource, the second clarifies non-behaviors. Every sentence serves a purpose.

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 low complexity (one parameter with enum, output schema exists), the description is fully adequate. It covers what the tool does, what it doesn't do, and the parameter is thoroughly documented in the schema.

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

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

The input schema covers all parameter details with 100% description coverage, including enum values and documentation. The tool description adds no additional parameter semantics beyond summarizing, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists supported instruments for one Blocksize service, using the verb 'list' and specifying the resource. It distinguishes from other tools by clarifying it does not fetch live prices, create accounts, or start payment, and implicitly sets it apart from sibling tools like 'fetch' and 'search'.

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

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

The description explains when to use the tool by stating it is for listing catalog metadata and what it does not do. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, though the context signals and sibling list offer some differentiation.

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, openWorldHint, idempotentHint. Description adds value by specifying 'free read-only search', 'does not return live prices', and confirms it returns IDs. No contradiction.

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

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

Two sentences, no wasted words. Front-loaded with purpose, followed by key constraints and return type. 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 single parameter and existing output schema, description captures core purpose, usage bounds, and return type. Sufficient for a search 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 100% with a detailed description for 'query'. The description adds only 'by keyword', which is redundant; baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states it searches 'Blocksize documentation and catalog metadata by keyword', with specific verb and resource. It distinguishes from siblings by noting it returns document/instrument IDs for fetch, not live prices.

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

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

Explicitly states it is a read-only search and does not return live prices, implying use for documentation/catalog metadata. However, it lacks explicit when-not-to-use or direct alternatives, though context hints at fetch for full documents.

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, so the tool's safety profile is clear. The description adds valuable context: it is free, never returns live prices, never starts payment, and returns up to 50 matches. This aligns perfectly 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 two sentences with no wasted words. It front-loads the purpose and immediately follows with key behavioral details. Every sentence adds 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?

Given the tool has only two well-documented parameters, an output schema, and clear annotations, the description is complete. It states the result limit, the nature of results, and explicitly what it does not do (live prices, payment). No gaps remain for an agent to misinterpret.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description does not add significant meaning beyond the schema; it briefly mentions output fields (asset class, services, pricing tier) but does not elaborate on parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool discovers supported symbols across asset classes, using the verb 'Discover' and specifying the resource. It distinguishes from sibling tools like 'search' and 'list_instruments' by emphasizing it is free and read-only, for use before the paid API.

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

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

The description implies when to use ('before using the paid HTTP API') and states it never returns live prices, indicating when not to use it. However, it does not explicitly name alternative tools or provide 'when-not-to-use' guidance, though sibling tools are listed.

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