Blocksize Agentic Market Intelligence

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

Description goes beyond the annotations by explicitly stating there are 'no account, credential, payment, or live-price side effects' and that it is 'free, read-only content retrieval.' This adds valuable behavioral context that readOnlyHint and destructiveHint alone do not convey, such as the absence of hidden costs or authentication requirements.

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 only two sentences, front-loaded with the primary purpose, and contains no redundancy. Every word adds value, making it highly 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 tool is simple (single parameter), has rich annotations and schema descriptions, and also has an output schema available. The description covers purpose, usage context, and side-effect transparency, which is complete for this tool's complexity. No additional details are necessary.

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

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

Schema description coverage is 100%, and the parameter 'id' is well-documented with examples in the schema. The description adds no additional parameter semantics, but it does not need to since the schema already explains the expected value format. 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 a specific action ('Fetch one document or instrument guide') and identifies the source ('returned by search'), distinguishing it from sibling tools like search, list_instruments, and get_pricing_info. It uses a specific verb and resource, leaving no ambiguity about what the 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?

The description implies this tool is for retrieving a specific result after using the search tool ('returned by search'), which is a clear usage context. It does not explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to choose this over search or other getter 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?

Annotations already provide readOnlyHint and idempotentHint, so the bar is lower. The description adds value beyond annotations by stating it does not fetch prices, charge a wallet, or submit payment, and by outlining the response structure (method, URL, service notes, etc.). 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?

A single, information-dense sentence that front-loads the core action and includes return items and constraints. No filler; every clause 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?

The description explains the return contents and safety profile, and the output schema exists. It could add an explicit pointer to when to use this versus fetch or get_pricing_info, but the core purpose and limitations are covered sufficiently 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?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The tool description does not add any parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Build') and a specific resource ('exact x402-protected HTTP URL for one live market-data request'), and distinguishes itself from data-fetching tools by explicitly noting it does not fetch prices or charge a wallet. It also lists its return contents, making it unmistakable from siblings like fetch 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?

The description implies when to use this tool (when you need to construct a URL for a paid request) by clarifying it does not execute the request, but it does not explicitly name alternatives or say 'use X instead'. The purpose is clear enough that an agent can infer the distinction, but explicit routing to a sibling would earn a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond those annotations: it explicitly states the operation is free and 'does not initiate payment,' which is especially meaningful for a payment-adjacent tool. 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?

Two sentences with no filler: the first sentence front-loads the exact data topics, and the second adds a crucial safety clarification. Every part 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?

The tool is simple (zero parameters), annotations are rich, and an output schema exists. The description covers the main behavioral caveat and lists the specific metadata categories an agent can expect, 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?

The tool takes zero parameters and the schema coverage is fully represented by an empty properties object. The baseline of 4 applies because there are no parameters requiring explanation, and the description appropriately focuses on the output content rather than inputs.

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 clear verb ('Inspect') and a specific resource: current direct x402 per-call prices, starter-credit costs, USDC settlement networks, and the account-plan contact path. This fully distinguishes the tool from its sibling data-access 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 use case is clearly implied and well-scoped: use this tool when you need current pricing-related metadata such as per-call costs, connector credits, or settlement networks. It does not name alternative tools or exclusions, but the context is clear enough for an agent to select 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description needs to add value beyond these. It contributes 'free' (cost context) and enumerates the scope of the catalog (e.g., 'starter-credit positioning, credit costs, suggested paid prices'), which goes beyond the structured annotations. No hidden behaviors like rate limits are disclosed, but the description adds enough context given the strong annotation coverage.

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: one that lists the catalog contents and one that notes it's free/read-only. Every word contributes to defining the scope and safety, with no redundant or irrelevant information. The front-loaded verb 'Inspect' gives immediate 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 has no parameters, a strong set of annotations, and an output schema (not shown but indicated), the description successfully communicates what the catalog contains and the fact that it's safe and free. It falls slightly short of a 5 because it doesn't explicitly frame when to choose this over sibling tools, but the overall context is sufficient for an agent to invoke it appropriately.

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

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

The input schema has zero parameters, so the baseline is 4 per the rubric. The description adds no parameter-specific details because there are none to describe. It does clarify that the tool is a catalog inspection, indirectly confirming the absence of required inputs.

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 with the verb 'Inspect' and lists a specific set of catalog contents (raw data, ticker bid/ask, workflow products, pricing, endpoints, upgrade paths). This distinguishes it from sibling tools like get_pricing_info or get_workflow_endpoint by positioning it as the overarching product catalog.

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 this is a general catalog tool but does not explicitly say when to use it versus alternative endpoints. It notes the tool is 'free and read-only,' which encourages safe exploration, but lacks direct exclusions or alternative naming. Usage context is clear but not explicitly differentiated.

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 beyond the annotations by specifying the output content (endpoint, method, cost, example body) and clarifying it does not fetch live data or charge credits. This adds meaningful behavioral context not covered by readOnlyHint or idempotentHint alone.

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

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

Two sentences, front-loaded with the primary action, and followed by a succinct clarification. No wasted words, and the structure makes the purpose immediately clear.

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 one-parameter tool with a rich output schema and extensive annotations, the description fully covers what is needed. It explains what is built and what is not done, making it complete for its simple complexity.

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 100% coverage with a clear enum description for 'product'. The description does not add significant parameter-level detail, but the schema is sufficient, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Build' with a clear resource ('exact paid HTTP endpoint, method, starter-credit cost, and example body') for premium Blocksize workflows. It distinguishes itself by stating it does not fetch live data or charge credits, which separates it from sibling data 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?

Provides clear when-not guidance by stating it is free, read-only, does not fetch live data, charge credits, or start x402. This signals it is for preparing an endpoint rather than executing. However, it does not explicitly name alternative sibling tools like get_market_data_endpoint, so it lacks full alternative 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, idempotentHint, and destructiveHint=false. The description adds behavioral context by clarifying that this operation is free, is catalog-only, and does not trigger live price fetching, account creation, or x402 payment. This goes beyond the annotations and reduces surprise.

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 concise sentences with no filler. The main action is front-loaded, and the second sentence earns its place by spelling out important non-behaviors that help with tool selection and safety expectations.

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 tool is simple, all three parameters are optional and well-documented in the schema, an output schema exists, and strong annotations cover safety, idempotency, and read-only behavior. The description supplies the remaining context about scope and side-effect boundaries, 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 100%, and the schema already explains limit, offset, and service with examples for the enum values. The description does not add significant new parameter-level detail beyond repeating the 'one Blocksize service' concept, so a 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 states a specific verb and resource: 'List the supported instruments for one Blocksize service.' It also differentiates from pricing/payment tools by noting it 'does not fetch live prices, create accounts, or start x402 payment,' which helps an agent distinguish it from the 'get_pricing_info' and similar siblings.

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: this is free, read-only catalog metadata and explicitly lists what it does not do. It does not name alternatives or explicitly say 'use this when you need the instrument catalog,' but the negative scope is strong enough to guide an agent toward the right use case.

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 safety (read-only, idempotent). Description adds 'free', 'returns ids for fetch', and explicitly excludes live data/payment actions, providing useful behavioral context 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?

Two efficient sentences, front-loads purpose, then clarifies exclusions. No wasted words.

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 a single parameter, output schema present, and annotations covering safety, the description sufficiently covers usage context. It explains the tool's role in the larger workflow (returning ids for fetch) and its 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 schema fully describes the single 'query' parameter with length constraints and example queries, achieving 100% coverage. The description adds no additional parameter-level detail, so baseline 3 applies.

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

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

Clearly states it searches Blocksize documentation and catalog metadata by keyword. Distinguishes itself from sibling tools by specifying it returns document/instrument ids for fetch and explicitly excludes live prices and payments.

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 context that this is the appropriate tool for keyword searches of docs/catalog, and explicitly states it does not return live prices or start payment, signaling when not to use it. Does not name alternative tools by name but gives enough guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructiveness. The description adds valuable behavioral detail beyond the annotations: a 50-match limit, the kinds of data returned (asset class, services, pricing tier), and the guarantees that it is free, read-only, and does not trigger payment or provide live prices.

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 filler. It front-loads the main purpose, then packs the crucial constraints (free, read-only, no live prices, no payment) into a compact second sentence. Every clause adds useful 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 rich annotations, a fully described input schema, and an output schema, the description provides everything an agent needs to decide whether and how to call it. It covers the catalog scope, result-size cap, and safety guarantees, so no critical context is missing.

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

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

Schema description coverage is 100%, so the input schema fully describes both the query parameter and the asset_class filter. The description does not add new parameter-level meaning beyond the schema, so it earns the baseline score for schema-documented parameters.

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 the specific verb 'Discover' with a clearly defined resource: supported crypto, equity, FX, and metal symbols. It also states what the tool returns (catalog matches with asset class, services, pricing tier) and distinguishes itself from live market data and payment-triggering tools by explicitly saying it never returns live prices or starts payment.

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 when-to-use context: 'before using the paid HTTP API.' It also gives exclusions by noting the tool is free, read-only, and never returns live prices or starts payment. It does not name sibling tools or explicitly contrast list_instruments/search, but the usage context is strong enough to guide selection.

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