BlockRun MCP

Official

by BlockRunAI

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.40.2
Disambiguation4/5
Most tools target distinct domains (AI generation, search, crypto data, trading, phone), but there is some overlap: blockrun_search and blockrun_exa both offer web search, and blockrun_markets, blockrun_surf, blockrun_dex, and blockrun_price all provide market data. The descriptions are detailed and cross-reference alternatives, which mitigates confusion.
Naming Consistency5/5
All tools follow a consistent blockrun_<service> pattern in lowercase snake_case. The only deviation is blockrun_polymarket_read vs blockrun_polymarket, but the _read suffix is a clear and consistent modifier indicating read-only access, so the naming remains predictable.
Tool Count4/5
20 tools is on the heavier side, but the server spans a wide range of capabilities—AI generation, search, financial data, trading, phone services, sandboxing, and wallet management—so each tool earns its place. No tool feels redundant or unnecessary given the platform's broad scope.
Completeness5/5
The toolkit provides full lifecycle coverage for its domains: wallet and budget management, Polymarket read and write operations, the complete RealFace enrollment flow, multi-model AI generation, and multiple complementary data query paths. There are no obvious dead ends or missing critical operations for the platform's purpose.
Average 4.6/5 across 20 of 20 tools scored. Lowest: 3.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 18 of 18 community issues answered or closed in the last 6 months
- 158 commits in the last 12 weeks
- Last stable release on August 19, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: cost per call ($0.012 for search/answer, $0.002 per URL for contents), supported categories for search, and endpoint-specific body shapes. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a purpose sentence, followed by a bulleted list of endpoints with body shapes and costs, then categories and a reference to further details. Every sentence adds value; no redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 endpoints, no output schema) and the richness of annotations and input schema, the description is mostly complete but lacks details on return values, error handling, or pagination. It references the 'exa-research' skill for full shapes, which may not be directly accessible to the agent, leaving a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all three parameters described. The description enhances understanding by providing example body shapes for each endpoint and clarifying that body is required for all endpoints, and agent_id is for budget tracking. This adds meaning beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a neural web search via Exa, understands meaning, and is great for research. It lists four specific endpoints (search, answer, contents, find-similar) with distinct purposes, distinguishing it from sibling tools like blockrun_search which likely offers a different search capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for research but does not explicitly state when to use this tool versus alternatives such as blockrun_search. No direct comparison or exclusion criteria are provided, leaving the agent to infer usage context from the 'great for research' hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds that the tool lists models with pricing but does not disclose further behavior like pagination or result format, which is acceptable for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the action ('List available AI models with pricing'), and every word serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and usage, but lacks explicit mention of what the output contains (e.g., model IDs, pricing details). However, for a listing tool with no output schema, this minor omission is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions fully cover both parameters (category and provider) with clear filtering instructions. The description does not add additional parameter meaning beyond the schema, but no further explanation is needed due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('available AI models with pricing'), clearly distinguishing it from sibling tools like blockrun_chat or blockrun_image which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use to discover models and compare costs,' providing clear context for when to use the tool. It does not explicitly exclude alternatives, but the distinction from siblings is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, covering safety. The description adds that it's free and from DexScreener, but does not disclose rate limits, data freshness, or any additional behavioral traits. With annotations covering the main points, this is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with bullet points for use cases and examples. It is front-loaded with the main purpose and free status. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but for a search/query tool, the description covers usage, examples, and data source adequately. It may lack details on response format or pagination, but given the complexity, it's nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-described in the schema. The description adds value by providing usage examples (e.g., blockrun_dex({ query: 'SOL' })) that show how parameters interact, which goes beyond the schema definitions. This aids agent understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets real-time DEX data from DexScreener, lists specific use cases (token prices, liquidity, volume), and distinguishes from sibling tools like blockrun_markets or blockrun_defi by focusing on DEX data. Verb+resource is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (e.g., 'Token prices and liquidity across chains') and example queries. It does not explicitly state when not to use or name alternatives, but the context of siblings is present. For a data retrieval tool, this is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant behavioral traits beyond the annotations: it is async and client-polled, takes 1-3 minutes, charges only on success, and returns a permanent URL. This adds transparency about side effects and failure modes that the annotations (readOnlyHint=false, destructiveHint=false) do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, front-loading the core purpose and then adding essential operational details (duration, polling, payment, model, return type). Every sentence contributes value without redundancy or excessive length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async, money-related, time-consuming), the description is remarkably complete. It explains the asynchronous flow, payment settlement policy, time estimate, and return format (permanent URL). No output schema exists, so the description adequately fills the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter description coverage, so the baseline is 3. The tool description adds minimal parameter-specific meaning (e.g., model cost) but mostly relies on the schema. It does not need to compensate for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates music tracks, specifically full-length ~3 minute MP3s, via BlockRun x402. It identifies the distinct resource (music) and differentiates from sibling tools like blockrun_image and blockrun_speech by naming the output type and model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context such as async processing, polling behavior, and payment terms, but does not explicitly state when to use this tool over alternatives or when not to use it. Usage is implied by the tool name and purpose rather than directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond annotations: it discloses the data source (Pyth-backed), pricing model (free vs paid), and action constraints (market required for stocks). It does not contradict any annotations. The behavior is fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points for actions, pricing, and markets, plus explicit examples. It is moderately concise but contains some redundancy (e.g., restating action options). Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters and no output schema, the description should describe return structures. It mentions 'realtime quote' and 'OHLC bars' but lacks detail on the exact fields returned. The completeness is adequate but not thorough for a data-heavy tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so baseline is 3. The description adds value by showcasing parameter combinations in examples, clarifying resolution defaults, and explaining the market parameter's conditional requirement. This goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 multiple asset classes (crypto, FX, commodities, stocks). It specifies three distinct actions (price, history, list) and lists supported markets. This distinguishes it from sibling tools like blockrun_markets or blockrun_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use each action and notes pricing differences. It explains that market is required for stocks and provides usage examples. However, it does not explicitly state when not to use this tool compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the sparse annotations by disclosing cost implications ('Pays with USDC on the ACTIVE chain'), multi-image behavior, mask constraints, and the inline preview behavior ('Return a small inline image preview ... in addition to the full-resolution URL'). It also explains that source images can be base64, URLs, or file paths, which is valuable operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections for actions, models, and edit specifics. Every sentence adds useful detail, and the first line front-loads the core purpose. While it is dense, the complexity of the tool justifies the length; a shorter version would lose critical model and pricing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description provides substantial context: return behavior is hinted via 'full-resolution URL' and 'inline preview', and payment, model options, and input formats are all covered. However, it never explicitly describes the full return structure (e.g., a JSON object with URL and metadata), and error cases or rate limits are not mentioned. This leaves a minor gap for a tool with 9 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 89% schema coverage, the schema already documents most parameters. The description adds meaningful value by explaining model pricing, model strengths (e.g., 'gpt-image-2 renders on-image text best'), and the exact semantics of multi-image editing ('pass an array of 2–4 source images ... to fuse them in one render'). This enriches parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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', using a specific verb and resource. It further distinguishes itself with actions (generate/edit) and clearly separates from sibling tools like blockrun_video, blockrun_music, and blockrun_speech by focusing solely on image generation and editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the tool is for image generation/editing and provides model selection guidance (e.g., 'gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts'). It also references blockrun_wallet for payment context, but does not explicitly mention when not to use this tool relative to other siblings beyond the inherent scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint, destructiveHint) are already strong, but the description adds value by noting that paths are GET only, costs in USDC, and no API key needed. However, it omits details like response format or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: first sentence summarizes purpose, then lists paths with costs, gives examples, and ends with sibling tool guidance. No redundant sentences; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all critical aspects: data types, costs, examples, and sibling differentiation. However, missing explicit mention of return format (JSON) and error handling, which are minor gaps given the endpoint nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description provides concrete examples ('protocol/aave-v3', 'prices/coingecko:ethereum') and clarifies path formatting, adding meaning beyond the schema's generic endpoint description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides DeFi fundamentals via DefiLlama, listing protocol TVL, chain TVL, yield pools, and token prices. It distinguishes from siblings blockrun_price, blockrun_dex, and blockrun_surf by specifying that this tool is for protocol/TVL/yield fundamentals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use alternatives: 'Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pairs, blockrun_surf for labeled on-chain data — this tool is for protocol/TVL/yield fundamentals.' Also mentions cost per call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false; the description confirms write operations (buy/release) and discloses state changes, costs, and polling behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and clear sections, but somewhat lengthy. It front-loads the purpose and each sentence adds value, though minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multiple endpoints, stateful operations, voice presets, E.164 format), the description is comprehensive, covering required dependencies, pricing, and data formats. References the 'phone skill' for further details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds significant meaning: explains path options, body usage (omit for GET), and provides examples (e.g., body shapes for voice/call). This goes well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Phone-number intelligence, US/CA number provisioning, and outbound AI voice calls' and lists detailed paths with actions, making it clear and specific, differentiating 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit prerequisites (e.g., 'from must be a number your wallet owns' and 'Provision one with phone/numbers/buy first'), and details each path's purpose and cost, though it does not explicitly contrast with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses cost ($0.002 per call), batch behavior, and behavior for unknown network slugs (pass through to Tatum gateway). Annotations already indicate destructiveHint=true, and the description aligns by not restricting operations. Could be improved by explicitly noting that some RPC methods can modify state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise and well-structured. Uses bullet points and examples to convey information efficiently. Every sentence adds value, and the description is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters (full coverage), no output schema, and existing annotations, the description is comprehensive. It covers usage guidelines, examples, cost, alternative tools, and even notes the full network list is in the rpc skill. No gaps given the tool's nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: explains relationship between 'body' and 'method'/'params', provides usage examples showing parameter combinations, and describes behavior of 'body' for batch calls. Adds value without repeating schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a raw JSON-RPC interface for 40+ blockchains, with specific verb 'Raw JSON-RPC' and resource '40+ blockchains'. Distinguishes from siblings by saying it is for data not covered by higher-level tools, and provides examples of use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when you need data the higher-level tools don't cover') and when to prefer alternatives (blockrun_price, blockrun_dex, blockrun_surf). Provides concrete usage examples for different chains and methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) are consistent. The description adds significant behavioral detail: pricing formula, default cost, the effect of max_results on spend, source subset behavior, and default values. This fully informs the agent of the tool's cost and operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first paragraph gives purpose and cost warning, second explains common shape, third details sources and max_results. It is concise yet complete, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input thoroughly and hints at output (summarized results with citations). It references an external file for full examples, which is acceptable. However, a brief summary of the return structure would improve completeness, especially since no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial context: the body structure example, default values, effect of max_results on cost, and the reserved nature of path. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it performs 'Grok Live Search' across web, X/Twitter, and news with AI-summarized results and citations. It distinguishes itself from sibling tools like blockrun_markets or blockrun_chat by specifying the search domain and output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool (real-time search) and how to control cost (max_results). It does not directly compare to siblings, but the sibling names are sufficiently distinct that no confusion arises. The pricing warning and source selection advice help the agent decide parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature (consistent with annotations), pricing, pre-validation, and no charge on 400 errors. Adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, but includes pricing and catalog link that could be considered extraneous. Still efficient for the information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects: scope, examples, behavior, parameter usage, and error handling. No output schema, but sufficient for a data-fetching tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description greatly expands meaning with examples, routing rules, pre-validation behavior. Makes parameters actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a unified API for 83 Surf endpoints, listing specific coverage areas and common paths. It distinguishes from siblings by being the meta-tool for crypto data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (for various crypto data types) and method auto-routing. Does not explicitly compare to siblings but is clear enough for a broad tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), but the description adds substantial behavioral nuance: it discloses that mode:'free' is NVIDIA-only and ignored if a model is specified, that thinking is only honored for anthropic/claude-* models, that image inputs work on the native Claude path, and that mixing system param with a role:'system' message causes duplicates. It also explains agent_id budget enforcement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized: it front-loads the purpose, uses a clear 'Notable modes' bullet list, and each clause adds information (model mappings, budget, caveats). It avoids repeating schema definitions. Some redundancy exists between the description and the mode parameter's schema description, but the additional model lists justify the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, nested multimodal messages, no output schema), the description covers the key decision points: mode routing, direct model selection, thinking behavior, image support, system-prompt duplication, and budget enforcement. It intentionally defers full pricing/availability to blockrun_models, which is acceptable for a chat tool. It does not describe the response format, but that's implicit for a chat endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all parameters (100% coverage), so the baseline is 3. The description adds value by enumerating concrete model names for each mode (e.g., powerful → Opus 5, GPT-5.6-sol) and giving direct model ID examples, which the schema enum does not fully specify. It also clarifies free-mode behavior relative to the model parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase 'Get a second opinion from another AI model, or use a specialized model for a specific task,' clearly identifying this as a multi-model chat tool. It distinguishes itself from siblings like blockrun_image, blockrun_speech, and blockrun_models by focusing on conversational AI access and pointing to blockrun_models only for model listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use context ('Get a second opinion... for a specific task') and provides mode-specific guidance (coding, cheap, free, etc.). It also names an alternative tool ('Run blockrun_models to see all available models with pricing'), making the decision boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, non-destructive read-only operation. The description goes further by revealing pricing per call, HTTP method conventions (GET via params, POST via body), and constraints like the smart-money criterion requirement and mandatory time ranges for orderbooks/candlesticks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with a one-line summary and pricing, then organized into headers and bullet lists. Every endpoint entry is concise and adds actionable information, so nothing feels wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-endpoint read-only API, the description covers input semantics comprehensively, including pagination, filters, and required combinations. It even provides output hints like 'volume w/ YES/NO split' and 'full smart-wallet profile'. No output schema exists, but the description still equips an agent to select and invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides basic field types, but the description enriches this with a full catalog of valid path values (including dynamic IDs), query filter names, and examples such as { q: 'Bitcoin', status: 'open' }. It also clarifies the distinction between params and body, which is absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a data provider for prediction markets and derivatives via Predexon, with a comprehensive endpoint listing that distinguishes it from venue-specific siblings like blockrun_polymarket. The scope and aggregator role are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers extensive endpoint-specific guidance, including a recommended workflow (markets/search → keyset) and explicit disclaimers (e.g., 'order'/'ascending' are not supported). However, it never explicitly contrasts this tool with siblings like blockrun_polymarket_read, so it lacks an explicit 'when-not' or alternative recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds critical behavioral context beyond annotations: billing model (timeout is billed lifetime, no refunds), pricing tables for different time ranges and GPUs, and common endpoint patterns. No contradiction with annotations (destructiveHint=true is supported by running untrusted code).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and sections, front-loaded purpose. Every sentence adds value. However, it is somewhat lengthy; could be slightly more concise without losing key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (pricing, multiple endpoints, destructive nature), the description is highly complete. It covers purpose, usage, billing, and endpoints. References external 'modal skill' for full tables, which is acceptable. No output schema needed as description explains return implications (prices, sandbox_id).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: lists common paths (sandbox/create, exec, etc.) with example request bodies, and clarifies pricing implications for timeout and GPU parameters. This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run isolated code in a BlockRun-hosted Modal sandbox' — a specific verb (run) and resource (Modal sandbox). It distinguishes from sibling tools (e.g., markets, wallet) by focusing on ephemeral code execution with GPU options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'when you need: a clean ephemeral environment, GPU access... or a safer place for untrusted code.' And when not to: 'Prefer local tools for normal repo work.' This provides clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotated as destructive and open-world; description richly expands with details like real money, non-custodial, gasless, BlockRun pays gas for some actions, region check, dry-run mode, and compliance responsibility. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is long but well-structured with sections per action and critical notes front-loaded. Every sentence provides essential information; no wasted words. Could be slightly more concise, but comprehensiveness justifies length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 15-parameter tool with 9 actions, the description covers all actions, their parameters, important constraints (gas, limits, region), and return behavior (dry-run vs confirm). Even without output schema, it explains what to expect, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. Description adds value beyond schema by explaining price as probability 0-1 on tick grid, token_id source from blockrun_markets, and usage of amount_usd in different actions. Marginally improves understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's for trading on Polymarket prediction markets, listing specific actions (setup, fund, buy, sell, etc.) and distinguishing from sibling tools like blockrun_markets (for discovery) and blockrun_polymarket_read (likely read-only). It uses specific verbs and resource references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to run 'setup' first and again after funding, and to use blockrun_markets for market discovery. Provides clear guidance on when to use each action, when to set confirm:true vs omit for dry-run, and mentions per-order caps and region handling. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true. The description adds valuable context: 'without signing or changing anything', and for preview specifically 'never accepts confirm and never signs or submits an order.' No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose, then organized into bullet-point actions. Some redundancy in preview action details but overall well-structured and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects: tool purpose, usage guidelines, behavior, parameter usage rules, and sibling tool differentiation. No output schema but not required for a read-only tool. Complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage with clear parameter descriptions. The description adds context for preview action (e.g., market buys use amount_usd; limit orders use price+size), which helps agents understand parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads or previews Polymarket state without signing or changing anything, and lists three specific actions (positions, orders, preview) with brief explanations. It distinguishes itself from the sibling tool blockrun_polymarket for write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: use this tool for read-only operations; use blockrun_polymarket for setup and funds-affecting operations. The preview action is also clearly described as never accepting confirm or submitting an order.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, offering minimal safety info. The description adds rich behavioral detail: pricing structure ('$0.05/1k chars', 'min $0.001, quoted before payment'), model constraints ('max 3k chars in / 120s out'), prompt-directed behavior ('voice parameter is ignored'), and persistence guidance ('download immediately if you need to keep the file'). This goes far beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficiently structured: intro line, bullet-style action list, model breakdown, voice aliases, and a crucial note about hosted URL expiration. Every sentence carries actionable information (pricing, constraints, defaults, exclusions) with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple actions, models, pricing, voice aliases, prompt-directed behavior), the description covers all critical aspects for selection and invocation: how to use each action, which model to choose, billing implications, input length limits, and output format. No output schema exists, but the description explains the return value (hosted audio URL) sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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: pricing per character for each model, voice alias list (sarah, george, etc.), default model and speed, sound effect pricing and duration limits, and the key nuance that seed-audio-1.0 uses input text for voice/emotion/staging. This enhances the schema for every parameter, not just repeating existing descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, multi-action statement: 'speak text aloud (ElevenLabs or ByteDance Seed Audio), generate sound effects, list voices.' This clearly distinguishes the tool from sibling tools (e.g., blockrun_music, blockrun_image) and states the exact resources it acts upon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for each action (speak, sound_effect, voices) and model usage (e.g., 'multilingual-v2 for narration', 'v3 most expressive', 'seed-audio-1.0 is prompt-directed'). It does not, however, state explicit exclusions or compare with sibling tools (e.g., 'for music use blockrun_music'), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details behaviors beyond annotations (readOnlyHint=false, destructiveHint=false): it explains the two-wallet system, active chain switching, each action's effect, budget controls, and delegation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections and bullet points. It is front-loaded with the primary purpose and then provides detailed breakdowns. Could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return values (e.g., status shows addresses, balances, active chain) and outcomes of actions (e.g., deposit opens a link). It provides a complete guide for wallet management.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds substantial meaning: it explains each action's purpose, how budget and delegate actions work, and the role of agent_id and agent_limit. Provides context not captured by enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'manage the BlockRun payment wallet and control agent spending budgets.' It distinguishes itself from sibling tools by explicitly stating not to call it for AI queries and to use blockrun_chat instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Call this FIRST if any other blockrun_* tool returns a payment/balance error,' 'Call this to check your current USDC balance before expensive operations,' and 'Call this to set spending limits before spawning child agents.' It also clarifies when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the sparse annotations (all false) by disclosing costs (FREE vs. paid $0.01 USDC), the mandatory liveness check, the H5 link expiration (~120s), the multi-step enrollment process, and a privacy statement. It also explains that enrollment is not a single step and that group_id can be reused to refresh an expired link. This fully compensates for the lack of annotation detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured: a clear introductory sentence, an explanatory paragraph about RealFace assets, a bulleted list of actions with costs and requirements, a numbered typical flow, and a privacy note. Every section delivers essential information, and the front-loading makes the purpose immediately clear. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five actions, no output schema, and minimal annotation signals, the description is remarkably complete. It covers return values (ta_xxxx ids), prerequisites (liveness, public image URL), expiration behavior, model compatibility constraints, cost implications, and a concrete usage example. It leaves no major gaps for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already provides per-parameter descriptions (100% coverage), the description adds critical semantics: it explains that group_id must come from init, that image_url must be a clear front-facing photo, that name is required for init/enroll/portrait, and that agent_id is for budget tracking on enroll. It also clarifies that group_id is not used by portrait, which is not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's core function with a specific verb ('Enroll') and resource ('a real person's face as a BytePlus RealFace asset'), and explicitly distinguishes it from sibling blockrun_video by explaining that the asset is later consumed by that tool. It also differentiates between real-face enrollment (init/status/enroll) and AI character enrollment (portrait), leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: which models accept ta_ assets, when to use portrait vs. the liveness flow, and the exact sequence of actions in a typical flow. It also names the alternative (blockrun_video) and clarifies that this tool is for creating the asset, not generating video.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses async client-polling, a 5-minute hard cap, and payment-only-on-success behavior, adding context beyond the annotations. It also reveals the occasional audio moderation failure and explains the permanent URL guarantee, giving the agent a rich understanding of runtime behavior and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with a clear purpose prefix, a 'Models' section, and concise bullet-like flow. Every sentence carries unique operational or pricing information, and the length is justified given 10 parameters and 7 models; nothing feels redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully specifies the return value ('permanent blockrun-hosted MP4 URL') and covers all critical aspects: models, pricing, resolution multipliers, aspect ratio handling, audio, duration limits, RealFace integration, and payment semantics. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 100% coverage, the description adds substantial semantic meaning by detailing per-model constraints, pricing (e.g., $0.105/sec for Sora), mutual exclusions (real_face_asset_id vs image_url), and nuanced behaviors like 'Sora uses it only to pick portrait vs landscape.' This goes far beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line states 'Generate short AI videos via BlockRun x402' with a specific verb and resource, immediately clarifying the tool's function. It further defines the output as 'a short MP4 clip' and distinguishes it from sibling tools like blockrun_image by focusing on video generation and polling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive when-to-use guidance, including per-model breakdowns with pricing, durations, and capabilities, as well as explicit alternatives like 'Use 2.0 for 1080p/4K or real-person video.' It also cross-references blockrun_realface for enrolling RealFace assets, clearly scoping when this tool is appropriate relative to its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![blockrun-mcp MCP server](https://glama.ai/mcp/servers/BlockRunAI/blockrun-mcp/badges/card.svg)](https://glama.ai/mcp/servers/BlockRunAI/blockrun-mcp)

Score Badge

Copy to your README.md:

[![blockrun-mcp MCP server](https://glama.ai/mcp/servers/BlockRunAI/blockrun-mcp/badges/score.svg)](https://glama.ai/mcp/servers/BlockRunAI/blockrun-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BlockRunAI/blockrun-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server