Blocksize Agentic Market Intelligence

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context beyond that: no account, credential, payment, or live-price side effects, which tells the agent this is an unauthenticated, non-metered read. It does not cover error behavior for unknown or stale ids.

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 short sentences, front-loaded with what is fetched before the side-effect disclaimer. Nothing is redundant or padded.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, cost, and side effects for a single-parameter read. It stops short of noting id validity/error handling or whether fetched content is cached or snapshotted.

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 id parameter already documents its role with concrete examples (doc:pricing, instrument:crypto:BTCUSD). The description only restates that ids come from search, adding no format or constraint detail beyond the schema, so the 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?

States a specific verb (fetch) and resource (one document or instrument guide), and ties the retrieval to ids produced by the search tool. It differentiates from 'search' by being single-item retrieval, though it does not clarify how it relates to overlapping siblings like get_product_catalog 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?

'Returned by search' establishes the workflow context: use this after a search to pull a specific result by id. The free/read-only framing also signals it is safe to call liberally, but no explicit when-not conditions or named alternatives are given.

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, so the safety profile is covered. The description adds real value by drawing explicit boundaries: it does not fetch prices, charge a wallet, or submit payment, which is exactly the confusion an agent would have for an 'endpoint builder' 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?

Two sentences, zero waste. The core action leads, and the negative-scope clause follows immediately where it matters most.

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 need not be enumerated, and annotations cover the safety profile. The description completes the picture by clarifying this is a URL-construction step rather than an execution step, though it leaves the handoff to fetch unstated.

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 service enum is fully documented with per-value meanings, so the schema carries the load. The description adds no parameter-level detail such as symbol format or service selection guidance beyond what the schema already says.

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: 'Build the exact x402-protected HTTP URL for one live market-data request.' It also clarifies the output shape (method, URL, service notes, pricing docs, next steps). It doesn't name a sibling explicitly, but the negation 'does not fetch prices, charge a wallet, or submit payment' implicitly separates it from 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?

Usage is only implied: build the URL, then presumably use fetch to execute it. The description never states when to prefer this over get_workflow_endpoint or get_pricing_info, and the useful 'use search_pairs first' hint lives in the schema rather than the description.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: that the call is free, that it does not initiate a payment, and that there are two distinct pricing models (direct x402 per-call vs authenticated connector starter credits).

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, both earning their place, with the verb front-loaded before the content enumeration. The list of four content categories is dense but each item conveys distinct return content; nothing is redundant, though it reads as a laundry list rather than structured guidance.

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?

An output schema exists, so return-value explanation is unnecessary, and the annotations carry the behavioral profile. For a zero-parameter read-only metadata tool, the description covers purpose, content categories, cost model, and the no-payment boundary — nothing an agent needs in order to invoke it correctly 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 is empty with additionalProperties=false, so there is nothing for the description to disambiguate. The baseline for a zero-parameter tool is 4.

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 specific verb 'Inspect' is paired with a precise enumeration of the resource contents: direct x402 per-call prices, connector starter-credit costs, USDC settlement networks, and the account-plan contact path. This makes it clearly distinct from siblings like get_market_data_endpoint or get_product_catalog, though the 'account-plan contact path' element slightly overlaps the concern of recommend_account_plan without resolving that relationship.

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 line 'it does not initiate payment' establishes one useful boundary condition, and 'free read-only metadata' signals low-cost invocation. However, there is no explicit guidance on when to call this versus recommend_account_plan (a plausible alternative for plan/pricing questions), and no prerequisites are stated.

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, destructiveHint=false, and openWorldHint, so the safety profile needs no restating. The description's notable addition is 'This is free', a cost/credit-consumption trait not expressible in annotations, which is genuinely useful for a credit-based product. It still says nothing about whether calls are rate-limited or cached.

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 action and contents before the operational note. The middle enumeration is dense and slightly list-like, but every item names something the catalog actually contains, so it earns its space.

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?

An output schema exists, so the description is not obligated to explain return values, and with no input parameters there is nothing else required for correct invocation. Enumerating the catalog's contents gives the agent enough to judge whether this is the right starting point.

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, so there is nothing for the description to disambiguate and the baseline for a no-arg tool applies. The discussion of credits and pricing relates to returned content rather than inputs, so no compensation is required.

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 clear verb (Inspect) plus the resource and enumerates the concrete contents (raw data, equity bid/ask, workflow products, credit costs, endpoint templates, upgrade path). It does not, however, differentiate itself from siblings like get_pricing_info, get_workflow_endpoint, or get_market_data_endpoint, whose subject matter it partly overlaps.

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 line 'This is free and read-only' implies the tool is safe to call liberally, and the enumeration implies it is an overview/discovery entry point. But there is no explicit when-to-use guidance and no named alternative for the overlapping pricing, market-data, or workflow lookups.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered structurally. The description adds genuinely useful non-structural context — that the call is free, does not charge credits, and does not initiate x402 payment — which prevents the agent from mistaking it for a billable or state-changing operation.

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, both earning their place: the first delivers purpose and outputs, the second forecloses the most likely misreading (billing/execution). No filler, and the core purpose is 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?

For a one-parameter read-only builder with an output schema present, the description need not explain return values and instead covers what an agent must know before calling: cost, side effects, and the x402 boundary. Nothing material 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 single enum parameter is fully documented, so the baseline is 3. The description adds no extra meaning about the product enum or how the choice affects the returned endpoint, leaving the schema to carry the load.

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 ("Build") and enumerates the concrete artifacts produced (endpoint, method, starter-credit cost, example body) for a named resource (premium Blocksize workflow). It is clearly distinguishable from execution-style siblings, though it never names or contrasts with the adjacent get_market_data_endpoint tool that covers a superficially similar need.

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 frames when-not to use it: "does not fetch live data, charge credits, or start x402," which tells the agent this is a preparation/metadata step rather than an execution step. It gives clear context but does not name an alternative tool for actually invoking the built endpoint or for the market-data variant.

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, so the safety profile is covered. The description adds genuinely new context beyond the annotations: the call is free and neither triggers account creation nor x402 payment, which is meaningful behavioral information for an agent weighing cost/side effects.

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 tight sentences: the purpose is front-loaded and the negative-scoping sentence is compact and earns its place by ruling out costly side effects. 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?

With annotations covering the safety profile, a full parameter schema, and an output schema, the description only needs to frame purpose and side effects, which it does. The one gap is the absence of sibling routing (catalog alternatives vs. live-data tools), which slightly limits 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 100% and the service enum, limit, and offset are all fully documented in the schema itself, including the traversal guidance. The description contributes nothing about parameters, so the 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?

States a specific verb and resource ('List the supported instruments') scoped to 'one Blocksize service', which is unambiguous. It does not name a sibling it competes with (e.g. get_product_catalog, search_pairs), so an agent must infer differentiation, but the purpose itself is clear.

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 negative scoping ('does not fetch live prices, create accounts, or start x402 payment'), which implicitly tells the agent this is catalog metadata rather than a data-fetch call. However, it never names the alternative tool an agent should use for live prices or for the other catalog-style calls, so routing is left to inference.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant context beyond that: it is free, collects no contact details, creates no entitlement, and does not start a purchase — exactly the side-effect concerns an agent would otherwise have to guess 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?

Two tight sentences: the first front-loads what the tool produces and from what inputs, the second immediately disambiguates cost and side effects. No filler and no repetition of the title.

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?

An output schema exists, so return values need no explanation, and annotations carry the read-only/idempotent profile. The description covers purpose and non-effects well, but omits any statement of when this tool should be preferred over the pricing or catalog siblings, which is the one remaining gap for a four-parameter 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 75% schema description coverage, the schema already documents three of the four parameters. Naming the inputs in prose ('live-call volume, team size, recurring use, SLA needs') maps loosely onto expected_monthly_live_calls, team_seats, recurring_days_per_month, and needs_sla, but adds no units, ranges, or format detail 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 ('recommend') and resource ('sales-assisted Blocksize account plan') and enumerates the four inputs that drive the recommendation, so the agent knows exactly what this produces. It does not explicitly distinguish itself from the nearest-sounding sibling, get_pricing_info, leaving a small ambiguity an agent must resolve on its own.

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?

Usage is only implied: the phrase 'from expected live-call volume, team size, recurring use, and SLA needs' hints at the scenario (plan sizing before purchase), but there is no explicit when-to-use, when-not-to-use, or comparison against get_pricing_info or get_product_catalog. An agent can infer the context but gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context: that the call is free, that it returns ids rather than content, and that it will not perform payment or return live prices. It does not cover pagination or result limits, which keeps it out of the top band.

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, zero filler, front-loaded with the action and resource before the caveats. Both the return shape and the exclusion are stated in the fewest possible 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 an output schema present, return formatting needn't be described, and annotations carry the safety profile; the description still usefully names the id-based return contract and the payment/price exclusions. What is missing is any hint about result volume or how to page/refine, which a search tool would benefit from.

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?

There is a single parameter with 100% schema description coverage, and the schema already supplies constraints (1-120 chars) and example queries. The description adds only the word 'keyword', which conveys little beyond the schema's own examples, so this sits at the schema-driven 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?

States a specific verb (search) and resource (Blocksize documentation and catalog metadata) with the scope qualifier 'by keyword'. It also draws a boundary around what it returns ('document and instrument ids for fetch') and what it does not ('live prices'), which lets an agent separate it from get_pricing_info and get_market_data_endpoint.

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 says the results are ids 'for fetch', effectively routing the agent to the fetch sibling as the next step, and rules out live-price/payment use cases. It stops short of naming the alternative tools explicitly (e.g. use get_pricing_info for prices), so the when-not guidance is implied rather than spelled out.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint), but the description adds real value beyond them: the 50-match result cap, that it returns asset class/services/pricing tier, and explicitly that it never returns live prices or initiates payment. The payment/live-price caveat is exactly the kind of behavioral boundary an agent needs.

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 dense sentences with the free/read-only reassurance front-loaded alongside the action, and 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?

With an output schema present and annotations carrying the safety hints, the description only needs to frame purpose and key behavioral boundaries, which it does; the result cap, free/paid distinction, and no-payment guarantee round it out.

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 query and the asset_class enum with examples. The description's mention of asset classes loosely mirrors the enum but adds no syntax, format, or matching-behavior detail (e.g., how partial or ambiguous queries resolve), so the 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?

The description states a specific verb and resource: discover supported crypto, equity, FX, and metal symbols, with the result shape (up to 50 catalog matches). It is clearly distinguishable from data-fetching siblings like fetch or get_market_data_endpoint, though it never explicitly contrasts itself with list_instruments or get_product_catalog, which overlap in resource.

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

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

It gives clear usage context: run this before hitting the paid HTTP API, and it is free, so an agent knows this is the cheap discovery step. It stops short of exclusions or naming alternatives, which keeps it from a 5.

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