BlockRun MCP

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

Annotations only signal non-read-only, non-destructive, non-open-world behavior, leaving room for the description to explain side effects. The description hints at cost via 'free models (no cost)' and budget enforcement is mentioned in the agent_id schema param, but it never explicitly states that non-free models incur charges, that calls are external and may be slow, or that responses are non-deterministic. It does convey the core behavior: sending a message to an AI and getting a response.

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 front-loaded with the purpose, then uses compact bullet lists for modes and direct model picks, ending with a pointer to blockrun_models. Every sentence earns its place; there is no filler or repetition of schema content.

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 tool with 11 parameters and nested objects, the description covers the most decision-heavy aspects (mode selection, model IDs, model capabilities) thoroughly. It leaves out response format and cost details, but the schema documents parameters well and the chat response nature is implicit. A brief note on expected latency or output structure could push it to 5.

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 baseline is 3, but the description adds substantial value beyond the schema. It maps each enum mode to concrete model IDs and describes qualitative distinctions (frontier, 1M context, strong at coding, no cost). It also gives direct model pick examples and clarifies that 'free' is ignored when a model is specified, details not present in the schema alone.

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 opens with a specific verb and resource: 'Get a second opinion from another AI model, or use a specialized model for a specific task.' It clearly identifies this as a text-chat/completion tool and differentiates it from sibling media tools (video, image, music, speech). The listed modes further cement what the tool does without ambiguity.

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 clear context for when to use the tool: second opinions or specialized tasks. It provides mode-by-mode guidance (powerful, reasoning, coding, cheap, glm, free) with concrete model mappings, and directs the agent to run blockrun_models for the full catalog with pricing. It stops short of explicitly stating exclusions versus siblings, but the specialized modes and direct model picks imply the selection logic.

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 destructiveHint=false, so the read-only nature is covered. The description adds valuable operational context: per-call payment in USDC, the base+flat fee structure ($0.001 today, $0.002 reserved), the 402 header for exact charge, GET-only paths, and the note that yields is large and should be filtered client-side. This goes beyond what annotations alone provide.

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 moderately long but well-structured: it opens with purpose, then covers cost, then lists paths with base prices, then examples, then alternatives. Every sentence carries useful information; nothing is redundant. While it could be slightly more compact, the density is justified given the multiple endpoints and the pricing detail.

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 data-retrieval tool with no output schema, the description covers the essential operational details: endpoints, cost model, examples, and filtering advice. It does not specify response shapes, but for a GET-only data fetch, that is typically not critical for invocation. The inclusion of payment semantics and alternative routing makes it sufficiently 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 baseline is high. The description adds further meaning with concrete examples (e.g., 'protocol/aave-v3', 'prices/coingecko:bitcoin,coingecko:ethereum') and clarifies the path format (endpoint under /v1/defillama/). This enhances the agent's ability to construct valid paths without guessing.

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 ('fetches' implied by 'DeFi fundamentals via DefiLlama') and resource with clear scope: protocol TVL, chain TVL, yield pools, token prices. It explicitly distinguishes itself from siblings blockrun_price and blockrun_dex, so an agent can immediately infer what this tool is for and what it is not.

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 explicit when-to-use guidance: 'Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pairs — this tool is for protocol/TVL/yield fundamentals.' This directly names alternative tools and the conditions that select them, leaving no inference required.

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 mark the tool as read-only and non-destructive, so the description does not need to cover safety. It adds useful context about being real-time and free, but does not disclose response format, pagination, rate limits, or external API dependencies. This is acceptable given the annotations but not 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?

The description is well-organized with a purpose statement, bulleted use cases, and examples that are easy to parse. The 'FREE - no payment required' line is somewhat extraneous but does not hurt, and the examples justify their place.

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

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

Given the simple read-only nature, optional parameters, and full schema coverage, the description covers the main usage scenarios and gives enough example invocations for an agent to call the tool. It lacks output-shape guidance, but that is less critical for a data query tool with no output 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?

Schema description coverage is 100%, so the schema already documents chain, query, token, and symbol. The examples add small usage clarity but mostly restate what the schema already says, so the description adds little semantic value beyond the structured fields.

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 gets real-time DEX data from DexScreener and lists specific use cases like token prices, liquidity, volume, and finding pairs. It does not explicitly contrast with siblings like blockrun_defi or blockrun_price, so it is clear but not fully differentiated.

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 for' section gives concrete contexts for when the tool applies, and the examples show typical invocation patterns. It does not explicitly say when not to use it or name alternative sibling tools, so it stops short of full 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?

The annotations already cover read-only and non-destructive behavior, so the description appropriately focuses on adding value: pricing, per-URL limits, 402 header handling, and allowed category values. These behavioral details go beyond the annotations but do not exhaustively describe every edge case.

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 bulleted list for endpoints and pricing is easy to scan, the essence (semantic search) is front-loaded, and the final pointer to the skill compresses unnecessary detail. Every line carries concrete reference information; there is no 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?

Because the output schema is absent, the description delegates full request/response shapes to the exa-research skill, which is an acceptable pointer given the tool's complexity. It covers request shapes and costs, but an agent expecting a self-contained answer would still need to consult the skill.

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 description gives the exact body shape for each path, marks optional fields with '?', lists category values, and provides cost figures. This is far richer than the input schema's property descriptions, which only say 'endpoint name' and 'JSON body for the call'.

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 explicitly states 'Neural web search via Exa — understands meaning, not just content,' which gives a concrete verb and resource. It enumerates four endpoints (search, answer, contents, find-similar), making it clearly distinct from generic search siblings like blockrun_search.

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

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

It provides clear context: 'Great for research' and emphasizes semantic meaning over keywords. However, it does not explicitly name which sibling tools are alternatives or state when not to use this tool. Still, the context is sufficient for an agent to gauge when to choose it.

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 sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses payment mechanics (USDC on active chain), per-model pricing, multi-image and mask constraints, source input formats, and the inline preview behavior (full-resolution URL plus optional thumbnail). This gives the agent a rich behavioral model of what happens when the tool is invoked.

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 long but earns every word. It is structured with clear sections: purpose/payment, actions, model list with pricing and capabilities, edit specifics, multi-image rules, source formats, and mask constraints. Critical info (purpose, payment) is front-loaded, and the bulletized model list aids scannability despite the density.

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 8 parameters, no output schema, and multiple model-specific behaviors, the description covers all necessary invocation details: required prompt, defaults, pricing, chain/payment, image sources, action variations, inline output preview, and constraints. An agent can make a confident, correct call using only the description and 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?

Even though schema coverage is 100%, the description adds substantial semantics: it maps each model to its specific use case and cost, explains default model behavior per action, clarifies multi-image array limits per provider, and details mask compatibility rules. This goes far beyond the schema's short field descriptions.

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 opens with 'Generate or edit images via BlockRun', a specific verb and resource, and clearly distinguishes itself from media siblings like blockrun_video or blockrun_music. The generate/edit action split further clarifies the two main operational modes, leaving no ambiguity about the tool's scope.

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 explicit guidance for selecting actions (generate vs edit) and models, including cost/quality trade-offs and defaults ('gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts'). It also directs the agent to blockrun_wallet for payment context retain full clarity. While it does not name other sibling tools as exclusions, the tool name and media-type focus make when to use it unmistakable.

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 readOnlyHint and non-destructive annotations, the description discloses pricing and 402-charge behavior, upstream 500 failures releasing payment, '?' in path being refused before payment, POST 404s, time-unit requirements, and optional/default behavior for candlestick intervals. This is rich behavioral context the annotations do not provide.

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 well organized with section headers and compact endpoint bullets, and almost every sentence carries useful operational information. It is long, and a few instructions like the markets/search 'q' parameter are repeated, but the length is largely justified by the large endpoint surface.

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 complex, multi-endpoint data tool, the description is exceptionally complete on request contracts, degraded routes, and failure modes. However, there is no output schema and the description does not specify return-value shapes, so an agent must infer response structure mostly from endpoint labels.

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 already documents all parameters, but the description adds substantial meaning: q vs search field names, keyset pagination, Unix seconds vs milliseconds, body only for POST endpoints, and endpoint path rules. It also gives concrete examples for path and params, making correct invocation much clearer.

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 resource and scope: prediction-market and derivatives data via the Predexon aggregator, then enumerates exact endpoint families (Polymarket, Kalshi, sports, Binance futures, cross-platform). This clearly differentiates it from Polymarket-only siblings by emphasizing cross-venue coverage and 'search every venue in one call'.

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 explicit endpoint-level usage rules and alternatives, such as warning that sports/* is degraded and directing the agent to markets/search or polymarket/events instead. However, it does not compare against sibling tools like blockrun_polymarket or blockrun_polymarket_read, so cross-tool selection guidance is incomplete.

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 this is a mutating, open-world, destructive tool. The description adds crucial behavioral context beyond annotations: timeout is the billed lifetime, charged upfront with no refunds, sandboxes terminate on timeout/budget reset, and GPU access is capped at H100. This is fully consistent with readOnlyHint=false and destructiveHint=true.

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?

Despite being long, the description is front-loaded with purpose and usage guidance, then uses compact bullet lists for pricing and endpoint schemas. Every sentence earns its place, espacially the billing warning, which is essential for correct invocaation and cost awareness.

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 multi-endpoint, high-stakes billing tool with no output schema, the description is nearly complete: it covers paths, request bodies, pricing, GPU limitations, termination behavior, and budget replan. The main gap is that it never explicitly states what responses look like, e.g., that sandbox/create returns a sandbox_id needed for subsequent calls, though the endpoint list implies this chaining.

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 only describes 'body' as a JSON POST body, so the description adds real semantic value by specifying per-endpoint body shapes such as { image?, timeout, cpu?, memory?, gpu?, setup_commands? } for sandbox/create and { sandbox_id, command, timeout? } for sandbox/exec. It also clarifies path examples and the billing meaning of timeout, going well beyond the thin schema descriptions.

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 opens with a specific verb and resource: 'Run isolated code in a BlockRun-hosted Modal sandbox — disposable remote container, optional GPU.' It then lists concrete endpoints under /v1/modal/, making the tool's scope unmistakable and clearly distinct from sibling tools like blockrun_image or blockrun_chat.

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 explicitly states when to use the tool ('clean ephemeral environment', 'GPU access', 'safer place for untrusted code') and when not to ('Prefer local tools for normal repo work'). It also enumerates the available POST paths, helping the agent choose the right operation within the tool.

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 with readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds the pricing angle and implies a read-only listing, but it does not disclose output shape, pagination, or how 'available' is determined under the open-world hint.

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 with no wasted words. The core purpose is front-loaded, and the usage guidance follows immediately.

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 read-only list tool with optional filters and full schema documentation, the description provides enough context for an agent to invoke it correctly. It could mention filtering by category/provider, but the schema already documents those options.

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 parameters are already fully documented. The description does not add parameter-level detail, which is acceptable because the schema carries that burden.

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 ('List'), a clear resource ('available AI models'), and a key attribute ('with pricing'). It is clearly distinct from the sibling tools, which target media, finance, and search 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?

It gives clear usage context: 'Use to discover models and compare costs.' It does not explicitly state when not to use it or name alternatives, but no sibling is a close substitute for listing models, so the guidance is sufficient.

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?

The description goes far beyond the sparse annotations (readOnlyHint false, destructiveHint false) by offering rich behavioral detail: async client-polled execution, 1-3 minute duration, per-rail billing differences (Base vs Solana/account), failure charge policies, job claimability for ~48h, and a permanent URL return. This is exactly the type of context that helps an agent anticipate side effects and cost implications.

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 front-loaded with the core purpose and then provides critical operational details. While the billing paragraph is long, every sentence carries information the agent needs (e.g., charge timing, failure handling, job recovery). It is structured into clear sections and avoids fluff, though it could be slightly tightened by moving pricing into a single line.

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 moderately complex (async, polling, multiple payment rails) and has no output schema, so the description carries full responsibility for return values and behavior. It covers the output (permanent URL), duration, cost, failure modes, and post-hoc job claimability. Nothing an agent needs to decide whether to call this tool or interpret its results 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 every parameter already has meaningful documentation. The tool description adds only the model default and pricing context ('minimax/music-2.5+ ($0.1575/track)'), which is somewhat useful but not essential for parameter understanding. It does not clarify any parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with 'Generate music tracks via BlockRun x402' – a specific verb and resource. It clearly distinguishes from sibling content tools (blockrun_video, blockrun_image, blockrun_speech) by naming the output type (music tracks) and specifying 'full-length ~3 minute MP3 track'. An agent can immediately understand what this tool does without opening the 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?

Usage context is implied rather than explicit. The description states it generates music tracks and details billing/polling behavior, but it never says 'use this when you need music, use blockrun_speech for speech' or provides any alternative guidance. There are no exclusions or conditions for choosing this over siblings, leaving the agent to infer when this tool is appropriate.

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 declare destructiveHint=true and readOnlyHint=false; the description goes further by disclosing costs, 30-day leases, release-to-pool side effects, and the wallet-ownership requirement. It also marks which operations are free, which are paid, and what the flat call rate 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?

The description is dense but well structured: a one-line summary, a compact bulleted endpoint list with pricing, and short requirement/format sections. Every line carries actionable information with no filler. The critical requirement about wallet-owned numbers 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?

The definition covers all main endpoints, prerequisites, costs, number format, and voice presets, which is strong for a multi-endpoint tool. However, it defers 'full body shapes' for voice/call to an external `phone` skill and leaves the semantics of `task` undefined, so an agent may need additional information to construct a fully valid voice call request.

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 only describes path generically and body as a JSON object, but the description maps specific path strings to endpoints, lists exact body key shapes, marks `from` as required for voice/call, and gives E.164 formatting. This is far more semantically useful than the schema alone.

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 opens with a precise summary: 'Phone-number intelligence, US/CA number provisioning, and outbound AI voice calls.' It then enumerates eight distinct endpoints with method, body, and purpose, making its scope and resource clear and separating it from sibling 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 explicit endpoint routing under 'Common paths', states the prerequisite that voice/call 'from' must be a wallet-owned number provisioned via phone/numbers/buy, and explains when to use the free GET poll instead of a POST. This gives clear when-to-use and prerequisite 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?

The description openly warns 'REAL MONEY — orders spend pUSD held in your Polymarket deposit wallet, signed locally by your BlockRun key'. It explains the dry-run preview when confirm is omitted, the per-order cap, the geoblock handling, and states 'Complying with Polymarket's terms for the user's jurisdiction is the user's responsibility'. This adds significant context beyond the annotations (readOnlyHint=false, destructiveHint=true).

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 long but well-structured with action sections and bullet-style lines. It front-loads the critical money warning and the setup requirement. While it could be more condensed, every sentence adds value given the tool's complexity (9 actions, 16 parameters). It is not excessively verbose.

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?

Covers all actions (setup, fund, buy, sell, orders, cancel, positions, redeem, withdraw), pricing, token ID sourcing, confirmations, caps, geoblock, and compliance. It also mentions the free tool aspect and the non-custodial funding path. No critical information is missing for an agent to call 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?

The description explains parameter meaning in context: 'Prices are probabilities 0–1 on the market's tick grid', 'token_id comes from blockrun_markets Polymarket data', and the detailed max_fill_price behavior ('Defaults to the worst fill of this session's last preview...'). It also clarifies how condition_id+outcome resolve to token_id, which is not in the schema. This is far beyond the schema's own descriptions.

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 opens with 'Trade on Polymarket prediction markets (CLOB V2, Polygon)', which is a specific verb-resource pairing. It also references 'discover markets/prices/token IDs with blockrun_markets first', implicitly distinguishing it from the read-only sibling tool blockrun_polymarket_read. The purpose is unmistakable.

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 instructs to run action:'setup' FIRST and after funding, and directs users to blockrun_markets for discovery. It lists each action with its prerequisites and conditions (e.g., 'confirm:true REQUIRED to place', 'amount_usd required' for fund). This gives clear when-to-use and workflow 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 mark readOnlyHint and destructiveHint false, and the description reinforces them with concrete commitments: 'This action never accepts confirm and never signs or submits an order.' It also discloses the data sources, CLOB book and Data API, and clarifies that previews are live but non-mutating.

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 concise, bulleted by action, and front-loaded with the all-important safety statement. Every sentence adds functional value, and sibling routing is compressed into one clear sentence.

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 output schema exists, but the action bullets summarize what each call returns: Holdings, value, PnL, and redeemable status; open CLOB orders; and live order previews. Combined with a l00% schema-described parameters, the description gives the agent enough context to select and invoke the tool 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%, but the description adds critical combination logic beyond the schema: preview requires side plus token_id or condition_id+outcome, market buys use amount_usd, limit orders use price+size, and condition_id filters orders. These cross-parameter requirements are not inferable from the individual parameter descriptions alone.

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 opening line specifies a read-only verb and resource with a clear safety boundary: 'Read or preview Polymarket state without signing or changing anything.' The action list explicitly names positions, orders, and preview, making the tool's scope unambiguous and distinct from the funds-affecting sibling.

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 final sentence gives explicit routing guidance: 'Use blockrun_polymarket only for setup and funds-affecting operations' and enumerates confirmed buy/sell, cancel, redeem, fund, or withdraw. This directly tells the agent when to use this tool versus its sibling.

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 read-only and non-destructive behavior, so the description doesn't need to repeat that. It adds valuable context about pricing and the 501 gateway error for certain markets, which is a behavioral trait beyond the annotations. However, it could mention what the response format looks like (e.g., exact price data returned), so it doesn't fully cover the agent's behavioral expectations.

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 well-structured with clear sections for actions, pricing, markets, and examples. It uses bullet points and a simple format that is easy to scan. Slightly verbose with the pricing details, but all of it is relevant to avoid unnecessary calls. The examples at the end are a nice touch but could be trimmed if needed.

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

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

Given the tool's complexity (11 params, 5 enums, multiple actions), the description covers the essential usage patterns and limitations. It lacks an output schema, but the description's examples imply the return types. It could be more complete by specifying response formats for each action, but it's sufficient for an agent to make correct calls.

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 all parameters are documented with their types and descriptions. The description adds extra context by explaining how parameters relate to actions (e.g., 'symbol' required for price/history, 'market' required for stocks category) and provides example values like 'BTC-USD' and 'EUR-USD', which enhances the agent's understanding beyond the bare 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?

The description clearly states the tool provides realtime quotes and OHLC history for crypto, FX, and commodities, plus ticker catalogs. It explicitly outlines three distinct actions (price, history, list) with examples, effectively distinguishing it from siblings like blockrun_markets and blockrun_dex. While it doesn't explicitly name siblings, the resource and action specificity make its 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 explicit guidance on when to use each action and which categories are supportedcli. It clearly states that stocks/usstock price/history are not served, advising the agent not to retry. It also gives concrete examples of how to structure requests, making usage conditions highly 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 are sparse (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the full burden and delivers. It discloses the multi-step liveness requirement, the ~120s H5 link expiry with re-init instruction, per-action costs ($0.01), settlement mechanisms (Solana/Base wallet or account key), wallet-mode-only for list, and a privacy statement (no face/liveness data stored). Rich and complete.

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?

Front-loaded with the core purpose, but the description is long and partially redundant. The action list, the typical-flow example, and the model-compatibility paragraph overlap; the flow example restates what the action bullets already say. For a 5-action tool some length is warranted, but trimming the redundant step-by-step example would tighten it.

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?

Comprehensive for a complex multi-step tool with no output schema and sparse annotations. It covers the full lifecycle (init→status→enroll/portrait→list), cost, payment routes, timing/liveness constraints, model compatibility, and privacy. An agent has everything needed to sequence calls 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%, so baseline is 3. The description adds value beyond the schema: group_id can refresh an expired H5 link or is unused by portrait; image_url must be the SAME person as the liveness check for enroll; agent_id is budget-tracking for enroll only. These constraints are not fully apparent from schema alone, earning a 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?

Opens with a precise verb+resource statement: enroll a real person's face as a BytePlus RealFace asset, then drive Seedance 2.0 video with it. It clearly distinguishes this tool from its consumer blockrun_video (which takes real_face_asset_id) and differentiates portrait (AI characters, no liveness) from enroll (real person, liveness).

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?

Exceptional routing guidance. Each of the five actions has explicit when-to-use context (FREE vs PAID, liveness vs no-liveness, wallet-only for list). It names the model constraint explicitly — seedance-2.5 is numerically newer but does NOT accept ta_ assets — and gives a step-by-step typical flow. Nothing 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?

Adds meaningful behavior beyond annotations: no node required, no API key, per-call cost, flat fee, batch pricing, and network slug pass-through. The destructiveHint annotation already covers mutation risk, so the description needn't restate it.

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?

Well structured with a clear opening, usage guidance, network overview, examples, and priority note. The pricing details and example list are useful but slightly longer than strictly necessary; each section 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?

Complete enough for a raw JSON-RPC tool: covers purpose, when to use, cost, network list, and example calls including batches. Lacks explicit note about output/error shape and broader write-method safety, but the standard JSON-RPC response format is inferable.

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 schema already documents method, params, body, network, and agent_id. The description adds examples and clarifies body/method override behavior, but doesn't substantially extend the parameter semantics beyond what's structured.

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 action and resource: raw JSON-RPC access across 40+ chains. It differentiates itself from the higher-level tools and provides concrete examples, making the tool's purpose immediately 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?

Explicitly says to use this tool when higher-level tools don't cover the need, and names alternatives (blockrun_price, blockrun_dex) to prefer when they do. Also gives practical guidance on when to use batch requests.

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 destructiveHint=false, so the agent knows it's a safe read operation. The description adds significant behavioral context: the pricing model, cost estimation formula, that 'sources' defaults to web only, and that requesting an unavailable source is refused before payment. It also refers to a skill for full shape. This adds value beyond annotations, but falls short of flawless because it doesn't detail return format or pagination, though that's 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?

The description is moderately long but front-loads the most critical information: the cost warning and how to control it. It uses structured sections (e.g., 'Common shape') to improve readability. Some repetition exists (e.g., cost details repeated in the first paragraph and again for max_results), but overall it's efficient and scannable. It's not as concise as ideal but appropriate given the complexity of pricing logic.

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 tool with a complex pricing model and parameter behavior, the description covers essential usage constraints: price calculation, default values, parameter ranges, and even refers to a skill for full request shape. It doesn't explain the return value shape (no output schema), but given that it references a skill file with worked examples, it's reasonably complete. The only gap is that it doesn't explicitly state when to choose this over other search-like siblings, but the domain-specifics (news, cost) are clear enough.

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 explains each parameter (body, path, agent_id). The description adds further detail on the body structure, including example fields and defaults for 'sources' and 'max_results', which is useful but not strictly necessary. The description also clarifies that 'path' is reserved for future surfaces, which is beyond schema, but the schema already has a description, so the added value is moderate. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs a live web and news search with AI-summarized results and citations. It specifies the endpoint path and distinguishes it from the sibling list (e.g., blockrun_exa for AI search, blockrun_polymarket for prediction markets). However, it doesn't explicitly contrast with siblings, and the name 'blockrun_search' is generic, but the description provides specific details like the price model that helps identify the tool's purpose.

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

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

The description explains when to use the tool (for real-time web and news queries) and provides explicit guidance on parameter usage, including defaults and how to cap spend by reducing max_results. It also notes the absence of an X/Twitter source, which is a useful exclusion. However, it doesn't explicitly discuss when NOT to use this tool versus alternatives like blockrun_exa for AI search; it only mentions that asking for X is refused.

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 only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It goes far beyond annotations by specifying pricing, per-model latency and characteristics, the prompt-directed behavior of bytedance/seed-audio-1.0 (voice parameter ignored), and that the returned hosted URL requires immediate download. This is rich, non-obvious 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?

The description is long but every sentence delivers useful information: purpose, actions, pricing, models, aliases, behavioral caveats, and return-value guidance. It is logically organized with line breaks and no filler, making it dense yet easy to scan.

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 9 parameters, 3 enums, no output schema, and minimal annotations, the description is remarkably complete. It covers return value behavior, pricing, model selection, voice handling, parameter constraints, and action differences—everything an agent needs to invoke the tool 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?

Although schema description coverage is 100%, the description adds substantial meaning: it expands the voice aliases, explains when the voice param is ignored, gives model-specific billing details, clarifies action-specific parameter usage, and describes the output as a hosted audio URL. This far exceeds the baseline for fully covered schemas.

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 core purpose: 'AI voice via BlockRun x402 — speak text aloud (ElevenLabs or ByteDance Seed Audio), generate sound effects, list voices.' It enumerates distinct actions, models, and voice aliases, giving agents a concrete understanding of what the tool does and how it differs from non-speech siblings like image, music, or video tools.

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

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

The description provides clear action-level guidance: use 'speak' for text-to-speech, 'sound_effect' for cinematic effects, and 'voices' to list voices. It does not explicitly name sibling tools to contrast with, so while the usage context is strong, it lacks the explicit when-not-to-use-alternative statements that 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?

The description fully covers operational behavior: async submission and polling, typical wall-time and hard caps, wallet-rail vs account-rail billing consequences on failure, upstream audio moderation quirks, and the permanent GCS-mirrored MP4 URL. This goes well beyond the minimal annotations and does not contradict them.

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 top-loaded with purpose, execution flow, billing, and model options, and the bullet list makes dense information scannable. It is long and repeats some per-model constraints already present in parameter descriptions, but the complexity of seven models and pricing justifies most of the length.

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 complex paid async tool with no output schema and only minimal annotations, the description covers invocation, polling, billing, model compatibility, RealFace prerequisites, and the returned artifact. Nothing needed to call the tool correctly appears to be 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 coverage is 100%, but the description adds substantial meaning per parameter: per-model charge rates, default durations, resolution price multipliers, mutual exclusions among image_url, last_frame_url, and real_face_asset_id, and which models ignore which parameters. This materially helps an agent choose correct values.

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 specific action ('Generate short AI videos via BlockRun x402') and a concrete result ('short MP4 clip'), which clearly separates it from image, music, and speech sibling tools. It also enumerates the available model options, so an agent understands the tool's scope immediately.

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 rich conditional guidance: when to use RealFace, when Sora is not available on Solana, which Seedance model to prefer for 4K or real-person video, and how to avoid audio moderation failures. It does not explicitly say 'use blockrun_image for stills' or list when not to use the video tool, so sibling-tool exclusion guidance is implied 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?

Discloses substantial behavior beyond annotations: API-key mode has no wallet, wallet mode holds two wallets with one active chain, chain switching requires no restart, BLOCKRUN_BUDGET_LIMIT acts as a ceiling, and deposit opens a Coinbase Onramp link in the browser. No contradiction with readOnly/destructive hints is present.

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?

Long but justified: a nine-action tool with two modes and an env-var ceiling needs this level of detail. Sections are clearly labeled, critical call-this-first guidance is front-loaded, and the closing exclusion prevents misuse. Almost every sentence carries operational value.

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

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

Complete for a high-complexity tool with no output schema: it describes what each action returns or does, covers both server modes, budget clamping, per-agent delegation, chain switching, and where to manage credits outside wallet mode. An agent has enough to invoke any action 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?

Although schema coverage is 100%, the description adds critical semantics: the default action is 'status', budget_action defaults to a read-only 'check', agent_limit is required for delegate, and omitting chain displays the current chain. It also maps action values to their wallet-mode effects.

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 opens with a specific verb+resource: 'manage the BlockRun payment wallet and control agent spending budgets.' It clearly distinguishes this tool from content-generation siblings and closes with an explicit exclusion: 'Do NOT call this for actual AI queries — use blockrun_chat.'

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 explicit when-to-use guidance: call first on payment/balance errors, before expensive operations, and before spawning child agents. It names the alternative tool (blockrun_chat) for queries and even gives a three-step usage pattern for multi-agent orchestration.

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