BlockVectra Docs

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context by naming the source of truth for the numbers (/v1/plans method weights and pricing), but says nothing about accuracy, whether values are approximate, or how stale pricing affects results.

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 and calculation basis come first, the calling convention second. No filler, 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 not be explained, and the description covers both parameter modes and the pricing source. The only real gap is that it does not characterize the reliability or assumptions of the estimate.

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 already 100%, so the baseline is 3, but the description goes further by explaining the two invocation modes — a 'lines' array of {method, calls_per_day} objects versus the legacy single 'method'/'calls_per_day' pair — which is a relationship the schema alone does not spell out.

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 (estimate) and precise outputs (daily/cycle Compute Units and USD cost) plus the basis of the calculation (/v1/plans method weights and pricing). It is clearly a compute tool rather than a lookup, which implicitly separates it from get_pricing, but it never names a sibling or states the distinction explicitly.

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 the tool is useful (estimating cost from call volumes) but gives no explicit when-to-use/when-not guidance and never points to alternatives such as get_pricing for raw price data or get_method_info for validating method names. Usage must be inferred from the purpose.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns billing implications, retryability, retry delay, and a recommended agent action, which tells the agent why the call is worth making.

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, front-loaded with the action and catalog, followed by the return payload. No filler or redundancy.

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

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

The output schema covers return values, so the description need not enumerate them, and the read-only nature is annotated. The one omission is that with zero required parameters it never says whether code, reason, or http_status must be supplied (or whether multiple can be combined), which an agent needs to invoke correctly.

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

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

Schema coverage is 100% and each parameter carries its own description with examples, so the schema does the heavy lifting. The description only restates the lookup keys and adds nothing about how to combine them or that at least one is needed; 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 ('Lookup') and resource ('official error reference catalog') and names the three lookup keys (error code, reason, HTTP status), which clearly separates it from sibling doc/search/pricing tools.

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

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

Usage is implied by the keys it accepts: call it when you have an error code, reason slug, or HTTP status to interpret. However, it never states when to prefer this over search_docs or read_doc, nor any exclusions, so guidance is only inferred.

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 and openWorldHint=false, so safety is covered. The description goes beyond them by disclosing data provenance (/v1/chains, /v1/plans, documentation catalog) and the semantics of availability being governed by methods.allow and methods.deny rules, which is real behavioral context.

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, front-loaded with the substantive content and zero filler. The trailing provenance sentence is marginally useful but is the least essential part.

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 cover the read-only profile. Parameters are fully documented. The only real gap is routing guidance relative to overlapping siblings, which is minor for a simple single-method lookup.

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 both parameters are documented in the schema, including the chain-filtering behavior ('If specified, only availability for this chain is returned'). The description adds no syntax or format 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?

Specific verb ('Inspect') plus resource ('a method') and an enumeration of exactly what is returned: cross-chain availability, CU weight, price per million calls, and doc link. It is clear what the tool does, but it never differentiates itself from siblings such as get_pricing or list_chains, which return overlapping pricing/chain data.

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 per-method framing implies the use case (look up one named method), but there is no explicit when-to-use statement, no exclusion of alternatives, and no guidance on when to prefer get_pricing or read_doc instead. Usage is inferable rather than 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=true and openWorldHint=false, so the safety profile is covered. The description goes well beyond them by disclosing billing-unit semantics, method_weights resolution order, free.* units, key_defaults burst semantics, and the promo.ends_at caveat — real interpretation context not present in structured fields.

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

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

Purpose and usage lead, with unit/return semantics following, so it is well front-loaded. It is dense with semicolon-chained clauses and spends several sentences on return-value interpretation that a present output schema may already carry, so it is slightly heavier than strictly necessary for a no-argument tool.

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

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

For a zero-parameter read tool with annotations and an output schema, the description supplies exactly the missing layer — when to invoke it and how to read the units and lookup rules. Nothing needed to call or interpret it correctly is absent.

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 the baseline is 4 per the rubric. The description adds no parameter meaning because there are none to add, and the empty schema is self-explanatory.

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 resource and source endpoint ('Live prices and plan limits from GET /v1/plans'), and its scope is clearly distinguishable from siblings like estimate_usage, which it explicitly routes against by naming the cost-estimation context.

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

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

Gives explicit trigger conditions: 'Use before estimating cost or when asked about free credits, rate limits or per-method prices.' It does not name the sibling tool (estimate_usage) as an alternative or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds useful framing (live telemetry vs. static metadata) but discloses nothing further about freshness, rate limits, or error behavior; the output schema carries return-value detail, so this is adequate rather than rich.

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 with no filler, front-loaded with what the tool returns and followed by the pre-call condition and the sibling pointer. 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?

No parameters, an output schema for returns, and annotations covering the safety profile — the remaining burden on the description is when to call it and how it differs from list_chains, both of which are covered. Nothing an agent needs 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, so there is nothing for the description to disambiguate. The baseline of 4 applies; the description neither needs nor provides per-parameter guidance.

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+resource — live operational status and network health — and pins it to the concrete endpoint GET /v1/status. It explicitly contrasts itself with the sibling list_chains (static capabilities vs. live status), so an agent can distinguish it without opening either schema.

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

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

Gives explicit when-to-use ('Confirm chain status is 'ok' before calling methods') and names the alternative for a different need ('see list_chains for static chain capabilities and method policies'). This is exactly the when/when-not/alternative structure the dimension rewards.

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 and openWorldHint=false, so safety is covered. The description goes further by disclosing the concrete content of the response (sign-up paths, auth header, URL formats for both APIs), which is useful for a static-reference tool. It does not state that the content is static/versioned or how large the returned documentation is.

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 dense sentence with no filler, front-loading the verb and resource before listing the returned artifacts. 'SIWE' is unexplained jargon, but that is the only friction.

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 re-explained, and the description adequately frames what the call yields. For a zero-required-parameter reference tool, nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% with a single enumerated 'lang' parameter already documented in the schema, so the schema does the heavy lifting. The description says nothing about localization or the language option, adding no meaning beyond the structured field; 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: 'Get instructions and endpoints for obtaining a BlockVectra API key,' and enumerates the payload (auth header, URL formats for JSON-RPC and Data API). It is distinguishable from the docs-family siblings (list_docs, read_doc, search_docs) in substance, but never says so explicitly, leaving the agent to infer why this is not just a search_docs query.

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 strongly implied — an agent needing credentials or request-format details should call this — and the mention of 'preferred programmatic SIWE sign-up or browser handoff' hints at two paths. However, there is no explicit when-to-use, no when-not-to-use, and no routing against the sibling documentation tools that could plausibly cover the same ground.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: deny takes precedence over allow when matching wildcards, and a null state_window_blocks means full history is available. It does not discuss caching/freshness of this static data, which is the only notable gap.

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 compact paragraph, front-loaded with the operation and endpoint, followed by field semantics. It is efficient, though the trailing field explanations partly duplicate information an output schema already conveys.

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 parameterless, read-only lookup with an output schema, the description is sufficient: it establishes purpose, endpoint, and the interpretation of the trickier returned fields. The only missing element is guidance on when this lookup is needed relative to the other API tools.

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 input parameters, so per the rubric the baseline is 4. The description appropriately spends its space on the semantics of the returned fields instead, and the schema requires no compensating explanation.

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 concrete verb and resource ('Fetch supported blockchain networks and static parameters') and pins the exact endpoint (GET /v1/chains), so the agent knows precisely what this returns. The 'chains' resource is clearly distinct from the sibling tools, which cover pricing, status, usage estimation, and documentation.

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?

There is no statement of when to call this versus the siblings (get_pricing, get_status, estimate_usage, etc.) and no prerequisites or ordering guidance. The intended use - retrieving static per-chain configuration - must be inferred entirely from the field names.

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 safety (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds useful context: the data comes from a 'static documentation index' and requires no API key. It does not describe pagination or size limits, but for a static index that is minor.

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, zero waste, with the scope and returned fields front-loaded before the prerequisite note.

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

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

For a zero-required-param read tool with an output schema, annotations, and full param coverage, the description is nearly sufficient; it names the returned fields so the output schema need not be inspected. Routing to read_doc/search_docs for actual content would make it complete.

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 'lang' parameter is fully documented with its enum and default in the schema, so the description adds nothing beyond it. Baseline 3 applies when the 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?

States a specific verb+resource ('List all available documentation pages') plus the returned fields ('relative paths, and titles'), so an agent knows exactly what it yields. It does not explicitly differentiate itself from close siblings like read_doc or search_docs.

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 API key required' gives prerequisite context, and 'list all' implies a browse/enumerate use case. However, there is no explicit when-to-use vs alternatives guidance (e.g., 'use read_doc to fetch a page's content, search_docs to find by keyword').

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 and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: the source is static documentation build assets, and traversal attempts ('..', encoded traversal), protocol prefixes, hostnames, query strings and fragments are actively rejected rather than silently ignored.

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

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

Four sentences, front-loaded with the core action and location, then constraints. The enumeration of rejected input forms is slightly long but each item carries real information for correct invocation.

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 two-parameter read tool with full schema coverage and read-only annotations, the description covers the action, return format (raw Markdown), source, and input constraints. No output schema exists, yet the return shape is described, so an agent has what it needs.

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%, so the baseline is 3; the description goes further by revealing how 'path' resolves to a concrete asset (/md/{lang}/{path}.md) and gives path examples. It adds some meaning beyond the schema, but the lang default is already documented in the schema.

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

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

States a precise verb and resource ('Read the raw Markdown content of a documentation page') plus the exact resolution path (/md/{lang}/{path}.md). It is clearly distinguishable from search_docs by the word 'raw' and the single-path framing, though it never names that sibling explicitly.

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 specifies what inputs are valid (internal relative paths) and what is rejected, which implies usage, but it never states when to choose this tool over search_docs or how it relates to the other siblings. Guidance is inferable rather than explicit.

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 and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it searches a lightweight static index against title, relative path, and first-paragraph summary, and returns specific fields. It does not discuss rate limits or pagination, but that is not required given the annotation coverage and simple read-only nature.

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 zero waste. Purpose and search targets are front-loaded, and the return information follows immediately. Every clause contributes to selecting or invoking the tool.

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 simple three-parameter read-only search tool with 100% schema coverage, an output schema, and safety annotations, the description is largely complete. It explains what is searched and what is returned. The only notable gap is routing relative to sibling tools like list_docs and read_doc, which keeps it from being fully complete.

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 already documents query, lang, and limit fully. The description does not add syntax, defaults, or constraints beyond the schema for any parameter. Baseline 3 is appropriate when the schema carries parameter semantics.

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: search documentation pages using keywords. Names the exact search targets (title, relative path, first-paragraph summary) and return fields (titles, paths, summaries). This distinguishes it from sibling list_docs and read_doc without needing to open their schemas.

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 a keyword-search scenario but gives no explicit when-to-use guidance. It does not mention alternatives like list_docs or read_doc, nor when this tool should be preferred over browsing or reading a specific page. No exclusions or routing cues are provided.

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