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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable extra context by stating it 'does not fetch prices, charge a wallet, or submit payment,' which clarifies side effects beyond the basic read-only hint. It also discloses expected return contents (method, URL, service notes, pricing docs, next steps), exceeding the annotation baseline.

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 primary purpose and followed by a concise statement of return values and non-actions. Every word earns its place with 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?

The tool has only 2 parameters and an output schema, and the description fully covers what it does, what it returns, and what it avoids. It is complete for an AI agent to decide when and how to invoke it, without needing additional context about x402 or usage steps.

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% parameter description coverage, with detailed descriptions for 'symbol' and 'service' including examples and enum meanings. The tool description does not add parameter-specific details beyond the schema, so the baseline of 3 is appropriate; it neither hinders nor enhances the schema's clarity.

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 'Build' with a clear resource: 'the exact x402-protected HTTP URL for one live market-data request.' It clearly distinguishes from siblings like 'fetch' and 'get_pricing_info' by stating it does not fetch prices. This makes the tool's purpose unambiguous.

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: use this tool to construct a URL for a live market-data request, and it explicitly states it 'does not fetch prices, charge a wallet, or submit payment.' However, it does not name specific alternative tools (e.g., 'use fetch for actual prices'), so it falls short of explicit when/when-not 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 declare readOnly, idempotent, and non-destructive behavior. The description adds beyond that by noting it is 'free' and explicitly that it 'does not initiate payment,' which is critical context for a pricing tool that could otherwise be mistaken as a purchasing action.

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, each earning its place: the first front-loads the exact scope (prices, tiers, networks), the second adds critical safety/usage context ('free', 'read-only', 'does not initiate payment'). There is no unnecessary verbiage.

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 zero parameters, a clear output schema, and a description that enumerates the covered domains, the tool is fully contextualized for an agent to decide whether to call it. The output schema makes return-value explanation unnecessary.

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 semantics to convey. The schema description coverage is effectively complete, and the baseline for 0-parameter tools is 4; the description adds no missing parameter info because none exists.

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 'Inspect' and names concrete data: per-call prices, bulk credit tiers, and supported settlement networks. This clearly distinguishes it from sibling tools like get_product_catalog or get_market_data_endpoint, which concern different data domains.

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 frames its context as 'free and read-only planning metadata' and states it 'does not initiate payment,' making it clear when to use it in a planning workflow. It does not explicitly name alternative tools, but the context is unambiguous 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.

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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful context by stating that the operation is free, returns catalog metadata, and explicitly excludes live pricing, account creation, and payment initiation. This goes beyond the annotations to clarify side effects and boundaries.

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 primary purpose in the first sentence and a clarifying boundary statement in the second. Every word contributes to understanding the tool's function and limitations, 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 single-parameter, read-only list operation with a well-documented schema, comprehensive annotations, and an output schema, the description is fully complete. It tells the agent what the tool does, what it does not do, and the parameter is fully explained 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 fully documents the single 'service' parameter with a detailed description and enum values, achieving 100% schema coverage. The description's mention of 'one Blocksize service' adds no additional semantic detail beyond the schema, so a baseline score 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 uses the specific verb 'List' with a clear resource, 'supported instruments for one Blocksize service,' and immediately distinguishes itself from sibling tools like get_pricing_info or fetch by noting it does not fetch live prices. The scope is precise and unambiguous.

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 (to list supported instruments) and explicitly states what it does not do (fetch live prices, create accounts, or start x402 payment), which guides against misuse. However, it stops short of naming specific alternative tools for those purposes, so it lacks full alternative 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 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds meaningful behavioral disclosures: the tool is 'free, read-only, and never returns live prices or starts payment.' It also mentions a hard limit of 'up to 50 catalog matches'. This is valuable context that annotations alone do not provide, and there is 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 two sentences, front-loaded with the main purpose, and every sentence adds value. It covers purpose, output, limitations, and cost/behavior without redundancy or 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 tool has an output schema (which covers return values), the description provides all necessary context: what it searches (symbols), what it returns (up to 50 matches), key constraints (free, read-only, no live prices/payment), and its role in the workflow (pre-paid API discovery). No critical information is missing for an agent to select and 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?

Schema description coverage is 100% for both parameters (query and asset_class), so the schema already explains their meaning and allowed values. The tool description adds no additional parameter semantics beyond restating that it searches for symbols. Per the baseline rule for >80% coverage, a score 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's purpose: 'Discover supported crypto, equity, FX, and metal symbols' and specifies what it returns ('up to 50 catalog matches with asset class, available services, and pricing tier'). It is specific about the resource (symbols/catalog) and the verb (discover/search). However, it does not explicitly differentiate from sibling tools like 'search' or 'list_instruments', so it misses the top distinction criterion.

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 usage: 'before using the paid HTTP API' and emphasizes it is free, read-only, and never returns live prices or starts payment. This implies when to use it (for pre-API discovery). However, it does not explicitly state when NOT to use it or mention alternative tools, so it lacks explicit exclusions.

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