Token API by The Graph

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

The description discloses the response format (text/markdown) and provides an example, which adds value beyond the absent annotations. However, it does not cover potential error responses, authentication requirements, or rate limits. Since no annotations exist, the description carries the full burden, and it is only partially transparent.

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 relatively concise and front-loaded with the main purpose. It includes a list of response details and an example. Minor redundancy (e.g., 'Successful Response' could be omitted) but overall well-structured and efficient.

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 description adequately conveys the tool's purpose and response format, but it does not fully explain the content of the llms.txt file beyond a truncated example. Since an output schema exists (though not provided), the description need not detail return values, but additional context about the file's structure or use cases would improve completeness.

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

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

The input schema is empty with no parameters, so schema description coverage is 100%. According to guidelines, zero parameters warrant a baseline of 4. The description does not need to add parameter information, and it correctly avoids superfluous details.

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 that the tool returns the public llms.txt documentation index for AI tools discovering the Token API. It uses a specific verb and resource, making it easy to understand. However, it does not explicitly differentiate from sibling documentation tools like getOpenapiSpec or getSkillsMarkdown, which weakens its distinctiveness.

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

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

The description implies the tool is for retrieving the llms.txt file for AI tool discovery, but it provides no explicit guidance on when to use this tool versus alternatives. Given the presence of sibling documentation tools, some usage context would be beneficial. The description lacks exclusions or alternative recommendations.

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?

With no annotations, the description carries the full burden. It includes a response example and structure, clearly indicating it's a read-only operation. No destructive behavior is suggested.

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 short, front-loaded with purpose, and includes a structured response example. Every part adds value without redundancy.

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

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

Given no parameters and an output schema, the description provides a full response example and explains the return type. Complete for a spec retrieval tool.

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

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

Input schema has zero parameters, so baseline is 4. Description does not need to add parameter info.

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 it returns the public OpenAPI specification for the Token API, which is a specific verb and resource. It distinguishes from sibling tools that are data endpoints.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. However, the purpose is self-explanatory and siblings are data-focused, so usage is implied.

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?

No annotations are provided. The description discloses that the tool returns Markdown content with a 200 response example, which is transparent for a read-only, no-parameter operation. It does not mention side effects or auth needs, but the simplicity of the tool reduces the need.

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, front-loaded with the core purpose, and includes relevant response details in a structured manner. Every sentence adds 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?

Given no parameters and the existence of an output schema, the description is complete for understanding the tool's behavior. It provides the purpose, response format, and an example.

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?

No parameters exist in the input schema (100% coverage). According to guidelines, baseline is 4 for zero parameters. The description does not add parameter details, which 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 it returns the public Markdown reference for AI agents integrating with Token API, which distinguishes it from sibling tools like getOpenapiSpec (returns OpenAPI spec) and getLlmsText (likely LLMs text).

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

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

The description implies usage for retrieving the Markdown reference, but does not explicitly state when to use this tool versus siblings or provide any exclusions. The context is clear but guidance is minimal.

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?

No annotations provided, so description carries full burden. Includes valuable pagination signaling ('Empty data array signifies end of results') and plan restriction notices. However, lacks auth requirements, rate limits, or data freshness details despite documenting extensive response schemas.

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?

Extremely verbose with massive redundancy. Includes full JSON example blocks for 6 HTTP status codes despite structured output schema existing. While front-loaded with purpose statement, the bulk is wasteful duplication of structured data, making it inefficient for agent consumption.

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?

Documents all parameters and response fields comprehensively, but fails to address critical context: sibling differentiation among the 4+ balance-related tools. Given the tool family complexity (EVM vs SVM, Current vs Historical, Native vs ERC-20), the description should explain positioning but instead focuses on redundant field documentation.

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 structured fields already document parameters fully. The description text largely duplicates schema content (e.g., 'Page number to fetch') without adding syntax details, format constraints, or usage examples beyond what the schema provides. Baseline 3 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?

States 'Returns ERC-20 token balances for a wallet address' - specific verb (Returns), resource (ERC-20 token balances), and scope (wallet address). Distinguishes from 'Native' siblings by specifying ERC-20, but does not explicitly contrast with 'Historical' variants.

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

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

No guidance on when to use this vs alternatives. With siblings like getV1EvmBalancesHistorical and getV1EvmBalancesNative, the description should explicitly state this retrieves current/token balances vs historical data or native currency, but it does not.

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?

With no annotations provided, the description carries the full burden. It successfully discloses plan restrictions ('OHLCV historical depth is subject to plan restrictions'), pagination behavior ('Empty `data` array signifies end of results'), and HTTP error scenarios (400, 401, 403, 404, 500) with example responses. However, it omits mention of caching, rate limits, or idempotency characteristics.

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?

While front-loaded with the purpose statement, the description is excessively verbose, replicating entire Query Parameters and Responses sections with extensive JSON examples. This duplicates structured fields (input schema and output schema) and consumes significant context window, violating the principle that every sentence should earn its place beyond structured data.

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 (8 parameters, no annotations), the description provides comprehensive coverage of parameters, response structure, pagination signals, and plan restrictions. It correctly identifies the ERC-20 scope, distinguishing from native token siblings. The only gap is explicit differentiation from pool OHLCV endpoints (getV1EvmPoolsOhlc).

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%, establishing a baseline of 3. The description adds value by specifying comma-separated formatting for the contract parameter and providing date string format examples for temporal parameters. However, it largely duplicates schema content rather than adding rich semantic context or validation constraints not captured in the schema.

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

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

The opening sentence clearly states the tool 'Returns wallet ERC-20 token balance changes over time in OHLCV format,' specifying the verb (Returns), resource (ERC-20 token balance changes), format (OHLCV), and temporal nature (over time). This implicitly distinguishes it from sibling tools like getV1EvmBalances (current balances) and getV1EvmBalancesHistoricalNative (native tokens).

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

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

The description implies historical analysis use cases through 'over time' and 'OHLCV,' and mentions 'plan restrictions' for certain parameters. However, it lacks explicit guidance on when to use this versus alternatives like getV1EvmPoolsOhlc or getV1EvmBalancesHistoricalNative, and does not state prerequisites or when-not-to-use conditions.

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?

With no annotations provided, the description carries the full burden and discloses plan restrictions, pagination termination signals, and detailed HTTP error responses (400, 401, 403, etc.). It clarifies that results are aggregated OHLCV data rather than raw balance snapshots.

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?

Extremely verbose due to inclusion of full JSON response examples for six HTTP status codes, which dilutes the essential tool purpose. While structured with clear headers (Query Parameters, Responses), the massive JSON blocks do not earn their place in an MCP tool description meant for selection 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?

Comprehensive coverage of response structure, pagination behavior, and plan restrictions compensates for lack of annotations. The verbose response documentation, while inefficient, ensures completeness for a 7-parameter tool with complex output formatting.

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?

Input schema has 100% description coverage, establishing baseline 3. The description duplicates parameter definitions from the schema (including examples and plan restriction notes) without adding significant new semantic meaning beyond what the schema already provides.

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

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

Clearly states the tool returns 'wallet Native balance changes over time in OHLCV format,' specifying the unique output format (OHLCV) that distinguishes it from sibling historical balance tools. However, it lacks explicit comparison to alternatives like getV1EvmBalancesHistorical.

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?

Notes that 'OHLCV historical depth is subject to plan restrictions' and documents pagination behavior ('Empty data array signifies end of results'), providing usage constraints. Missing explicit guidance on when to prefer this over getV1EvmBalancesHistorical.

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?

No annotations provided, so description carries full burden. It documents response structure including pagination fields and statistics, and notes the 'Plan restricted' limitation for array inputs. However, it omits rate limits, caching behavior, authentication requirements (despite listing 401/403 errors), and whether balances are real-time or cached.

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

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

Extremely verbose due to inclusion of complete HTTP status code documentation (200, 400, 401, 403, 404, 500) with full JSON examples. While the first sentence is appropriately front-loaded, the subsequent content is boilerplate API documentation that an AI agent doesn't need for tool selection. Every sentence does not earn 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?

The description documents the complete output schema structure including pagination and statistics objects, satisfying the output richness requirement. However, given the complexity of blockchain data querying, it lacks operational context about network availability, plan restrictions comprehensibility, and the distinction between native and token balances that would be necessary for robust agent operation.

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%, establishing baseline 3. The description repeats schema definitions for 'network' and 'address' parameters without adding semantic depth (e.g., no explanation of Graph Network IDs beyond the URL, no examples of valid comma-separated addresses). The extensive response examples provide data context but don't enhance parameter understanding.

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 first sentence clearly states the tool 'Returns EVM native balances for wallet addresses' with specific verb and resource. The term 'native' distinguishes from sibling getV1EvmBalances (likely ERC20), but fails to differentiate from getV1EvmBalancesHistoricalNative or clarify what 'native' means (ETH, MATIC, etc.).

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

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

No explicit guidance on when to use this versus siblings like getV1EvmBalances (tokens) or getV1EvmBalancesHistoricalNative. Only implicit guidance is the 'Plan restricted' note for multiple addresses, which hints at usage limitations but lacks clear when/when-not instructions.

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?

Without annotations, the description carries the full disclosure burden. It provides some useful behavioral context: 'Plan restricted' note on the limit parameter and pagination behavior ('Empty data array signifies end of results'). However, it lacks details on authentication requirements, rate limits, or what the DEX data fields (factory, uaw, etc.) actually represent.

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?

Severely bloated with ~100 lines of JSON examples for standard HTTP error codes (400, 401, 403, 404, 500) that belong in the output schema, not the description. The signal-to-noise ratio is extremely low; an agent must wade through extensive boilerplate to find the single sentence of actual purpose description.

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?

While the description is voluminous, it redundantly documents response structures that already exist in the output schema (per context signals), while under-documenting crucial context like sibling differentiation (EVM vs SVM/TVM) and data semantics. It meets basic completeness for a 3-parameter tool but wastes space on the wrong details.

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%, establishing a baseline of 3. The description text duplicates the schema descriptions verbatim ('The Graph Network ID...', 'Number of items*...') without adding syntax clarification, example values beyond the schema's 'example' field, or semantic context about how parameters interact.

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 first sentence 'Returns all supported EVM DEXs' is clear with a specific verb and resource, but the description fails to distinguish from sibling tools like getV1SvmDexes (Solana) and getV1TvmDexes (Tron). An agent cannot determine from this description which chain type (EVM vs SVM vs TVM) requires this specific tool.

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

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

No explicit guidance on when to use this tool versus alternatives. The description does not mention that this is specifically for EVM chains versus other chain types available in the sibling tools, nor does it explain prerequisites like authentication despite listing 401/403 error codes.

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?

Without annotations, the description carries the burden well: it discloses 'Plan restricted' rate limiting on the limit parameter, explains pagination termination signals, and documents authentication requirements (401/403 errors) and other failure modes. It does not, however, explicitly confirm idempotency or safety.

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?

While well-structured with clear headings, the description is excessively verbose due to massive JSON response examples that duplicate the existing output schema (context signals confirm has_output_schema: true). These examples waste tokens without adding value for an AI agent.

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 coverage of parameters (100% schema coverage), clear resource identification (ERC-20 holders), and documented error cases. The inclusion of response examples is redundant given the output schema, but the tool definition is functionally 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%, establishing a baseline of 3. The description adds minimal semantic value beyond the schema—primarily organizing parameters into a readable list and noting the plan restriction constraint, but not explaining formats or relationships beyond the schema's existing 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 opening sentence 'Returns top token holders ranked by ERC-20 balance' provides a specific verb (Returns), resource (token holders), and scope (ERC-20 balance), clearly distinguishing it from sibling getV1EvmHoldersNative (likely for native tokens) and getV1SvmHolders (Solana VM).

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

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

The description implies usage by specifying 'ERC-20' (distinguishing from native holders) and documents pagination behavior ('Empty data array signifies end of results'), but lacks explicit guidance on when to choose this over siblings like getV1EvmHoldersNative or getV1EvmBalances.

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?

With no annotations provided, the description carries the full burden. It usefully notes that 'Empty `data` array signifies end of results' and mentions plan restrictions. However, it lacks explanation of sorting criteria ('top' is undefined), data freshness, rate limits, or the distinction between native and token balances that would help an agent predict behavior.

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?

Extremely bloated due to including full JSON response examples for every HTTP status code (200, 400, 401, 403, 404, 500). Since an output schema exists, these lengthy examples represent noise rather than signal. The actual purpose statement is front-loaded, but the overall description is not appropriately sized for an AI context.

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?

Technically comprehensive regarding execution (parameters, response structure, error codes), but misses crucial conceptual context. Given the existence of output schema, the extensive response examples are redundant. Missing: differentiation from getV1EvmHolders, definition of 'Native' balances, and ranking methodology.

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%, establishing baseline 3. The description text duplicates the schema descriptions verbatim in a 'Query Parameters' section without adding semantic value, syntax clarification, or cross-parameter relationships. No additional meaning is provided beyond the structured 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 opening sentence clearly states the tool 'Returns top token holders ranked by Native balance' with a specific verb and resource. However, it fails to explain what 'Native' means (blockchain native currency vs. ERC-20 tokens) or distinguish this from sibling tool getV1EvmHolders, which is critical given the similar naming.

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 no guidance on when to use this tool versus getV1EvmHolders or other balance-related siblings. The only contextual hint is 'Plan restricted' under the limit parameter, but there are no explicit prerequisites, workflows, or decision criteria provided.

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?

With no annotations provided, the description carries the full burden and delivers substantial behavioral context: it documents pagination termination ('Empty `data` array signifies end of results'), rate limiting hints ('Plan restricted'), and comprehensive HTTP error codes (400, 401, 403, 404, 500) with response structures. It omits explicit read-only declaration though 'Returns' implies 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?

The description is severely bloated, containing full JSON examples for 6 different HTTP response codes despite the presence of a structured output schema (per context signals). While the parameter section is well-structured, the extensive response examples violate 'every sentence earns its place'—this is API documentation bloat, not concise MCP tool guidance.

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

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

Given the 4 parameters with 100% schema coverage and existing output schema, the description is functionally complete. It covers all input parameters with examples, explains pagination behavior, and documents error cases. The only gap is the lack of sibling differentiation, but the operational context is thoroughly covered.

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%, establishing a baseline of 3. The description adds value by noting the plan restriction on limit and explaining the pagination termination signal ('Empty `data` array'), which adds semantic meaning beyond the schema's type definitions. It also provides the networks URL reference.

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 sentence clearly states it 'Returns NFT collection metadata, supply stats, owner count, and transfer history'—specific verb and resource. It distinguishes from siblings like getV1EvmNftItems (individual tokens) and getV1EvmNftTransfers (transaction history) by focusing on collection-level aggregate data, though it could explicitly emphasize 'collection-level overview' to prevent confusion with the transfer-specific 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 description extensively documents WHAT the tool returns but provides no guidance on WHEN to use it versus siblings like getV1EvmNftHolders or getV1EvmNftTransfers. No mention of prerequisites, typical use cases, or selection criteria among the 5 NFT-related tools available.

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?

No annotations are provided, so the description carries the full burden. It discloses the response structure through extensive JSON examples and mentions the 'Plan restricted' limitation on the limit parameter. However, it lacks operational details like rate limits, caching behavior, or authentication requirements—information that would be crucial given the complex nested response structure.

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 excessively verbose due to embedding complete HTTP response example blocks for six different status codes (200, 400, 401, 403, 404, 500). While front-loaded with the purpose statement, the sheer volume of redundant JSON examples makes it difficult to quickly scan and violates conciseness principles for an MCP tool definition.

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?

Despite the verbosity, the description is comprehensive. It covers all input parameters (4/4 with 100% coverage), provides detailed response schema documentation through examples, and explains pagination behavior. Given the complexity of the nested return object (data, statistics, pagination), the extensive response documentation ensures the agent understands the output structure.

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

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

With 100% schema description coverage, the baseline is 3. The description's parameter section largely mirrors the schema descriptions verbatim (e.g., 'The Graph Network ID for EVM networks') without adding additional semantic context, validation rules, or format guidance beyond what the structured schema already provides.

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

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

The description opens with a specific verb ('Returns') and clearly identifies the resource (wallet addresses holding NFT collection tokens) along with what data is returned (quantity and percentage distribution). It implicitly distinguishes from siblings like getV1EvmHolders (fungible tokens) by specifying 'NFT collection tokens', though it could explicitly clarify the distinction from getV1EvmNftOwnerships.

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 no guidance on when to select this tool versus siblings like getV1EvmNftOwnerships or getV1EvmHolders. While it includes pagination hints ('Empty data array signifies end of results'), it lacks explicit when-to-use/when-not-to-use recommendations or mentions of prerequisites like authentication requirements.

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?

With no annotations provided, the description carries the full disclosure burden. It successfully documents pagination behavior ('Empty `data` array signifies end of results') and tier restrictions ('Plan restricted'), but fails to explicitly declare that this is a read-only operation or detail authentication requirements despite listing 401/403 error codes.

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 headers and front-loaded purpose, but suffers from excessive verbosity. It duplicates parameter documentation already present in the schema and includes extensive JSON response examples that mirror the structured output schema, reducing information 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?

Given the presence of a complete output schema, the description comprehensively covers query parameters, pagination logic, and error responses (400-500). However, given the absence of annotations, it should explicitly state behavioral traits like read-only status rather than relying solely on error code documentation.

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

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

Schema description coverage is 100%, with complete documentation for all 5 parameters including enums, examples, and constraints. The description largely mirrors this information without adding significant semantic value beyond repetition, warranting the baseline score of 3.

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 sentence explicitly states the tool 'Returns NFT token metadata, attributes, current owner, and media URIs'—a specific verb plus detailed resource scope. This clearly distinguishes it from siblings like getV1EvmNftCollections (aggregate data) or getV1EvmNftTransfers (event logs) by focusing on individual token-level metadata retrieval.

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 thoroughly documents parameters and responses but provides no guidance on when to use this tool versus closely related siblings like getV1EvmNftOwnerships or getV1EvmNftHolders. There are no prerequisites, filtering recommendations, or explicit exclusions mentioned.

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?

Without annotations, the description carries the burden of disclosure. It successfully notes 'Plan restricted' limitations on certain parameters and explains pagination termination ('Empty data array signifies end of results'). However, it fails to explicitly state whether the operation is read-only, safe, or idempotent, though 'Returns' implies a read operation.

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

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

The description is excessively verbose due to including complete HTTP response documentation (JSON examples for 200, 400, 401, etc.) which belongs in the output schema field rather than the description. While structured with headers, the content is largely boilerplate API documentation not optimized for an AI agent's selection task.

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?

Despite the verbosity, the description is technically complete regarding parameter functionality and pagination behavior. However, given the existence of an output schema, the extensive response documentation is redundant, and the description misses critical context for distinguishing this tool from its many NFT-related siblings (getV1EvmNftHolders, getV1EvmNftItems, etc.).

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

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

With 100% schema description coverage, the baseline is 3. The description provides extensive parameter documentation including examples and array syntax explanations, but this largely duplicates the structured schema rather than adding semantic meaning beyond it.

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 'Returns NFT tokens owned by a wallet address with metadata and ownership information,' providing a specific verb and resource. However, it lacks explicit differentiation from sibling tools like getV1EvmNftHolders or getV1EvmNftItems, which may also relate to NFT ownership data.

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

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

No guidance is provided on when to use this tool versus alternatives such as getV1EvmNftHolders (likely the inverse lookup) or getV1EvmNftItems. There are no prerequisites, exclusion criteria, or workflow recommendations mentioned.

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?

Provides substantial behavioral context despite no annotations: notes 'Plan restricted' limitations on multiple parameters (indicating tier/rate limits), documents pagination behavior ('Empty `data` array signifies end of results'), and catalogs error responses (400, 401, 403, 404, 500). Could improve by explicitly stating read-only nature and authentication requirements.

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

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

Severely oversized due to extensive duplication of structured data. The description includes complete query parameter tables and response schemas that mirror the input schema and output schema (which exists per context signals). The critical information (first sentence) is buried under verbose API documentation that an agent must parse.

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

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

Over-compensates on response documentation (unnecessary given output schema exists) while under-explaining domain concepts. Fails to clarify what constitutes a 'sale' versus a generic transfer, which is critical given sibling tool getV1EvmNftTransfers exists. Parameter coverage is complete due to 100% schema coverage.

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

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

With 100% schema description coverage, the baseline is 3. The description largely mirrors schema content without adding significant semantic value beyond what's in the structured parameters. Date format examples (e.g., '2025-01-01T00:00:00Z') provide useful clarifications but are also present in 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 opening sentence 'Returns NFT marketplace sales with price, buyer, seller, and transaction data' provides specific verb (Returns), resource (NFT marketplace sales), and distinguishing scope (sales-specific data vs transfers/holdings). It clearly differentiates from sibling tools like getV1EvmNftTransfers by emphasizing marketplace sales with pricing info.

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

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

No explicit when-to-use or alternatives are named, but the description implies usage through the sales-specific framing. Lacks guidance on when to prefer this over getV1EvmNftTransfers (which may include non-sale transfers) or getV1EvmNftOwnerships. Agents must infer applicability from the name and first sentence alone.

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?

Without annotations, the description carries the full burden. It successfully documents pagination behavior ('Empty `data` array signifies end of results') and plan restrictions on certain parameters. However, it lacks explicit statements about safety (read-only implied but not stated), rate limits, or authentication requirements despite listing 401/403 error codes.

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 severely bloated, containing full JSON response examples and HTTP status code documentation that likely duplicates the output schema. This obscures the actual purpose statement and forces agents to parse through hundreds of lines of structured data to find semantic meaning.

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 14 parameters and complex filtering capabilities, the description documents individual parameters adequately. However, it lacks sibling differentiation critical for the NFT tool cluster (transfers vs sales vs ownerships) and buries the pagination semantics within parameter lists rather than highlighting them as key behavioral constraints.

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?

Input schema has 100% description coverage, establishing a baseline of 3. The description largely repeats parameter documentation already present in the schema (type, network descriptions) without adding usage guidance (e.g., no explanation of how start_block and end_block interact with time filters, or when to use address vs from_address/to_address).

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 sentence clearly states it 'Returns NFT transfer events including mints, burns, and ownership changes,' providing specific verb and resource identification. However, it fails to distinguish from close siblings like getV1EvmNftSales or getV1EvmTransfers (fungible), leaving agents to guess which NFT-related tool is appropriate.

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

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

No guidance is provided on when to use this tool versus alternatives like getV1EvmNftSales (for marketplace sales) or getV1EvmNftHolders (for current ownership). The description consists entirely of API reference documentation (parameters and response codes) without selection criteria or use-case examples.

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?

No annotations provided, but description carries substantial weight: documents pagination behavior ('Empty data array signifies end of results'), plan restrictions on certain parameters, and comprehensive HTTP error codes (400-500) with response schemas. Missing only explicit read-only/safety statements.

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 clear headers, but excessively verbose due to extensive JSON examples for every HTTP error code (400-500). These examples don't aid invocation decisions; could be condensed to status code descriptions without full JSON payloads.

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 an 8-parameter filtering endpoint: covers all query options, explains array value formatting, documents pagination logic, and includes response structure examples. Suitable complexity coverage despite missing explicit rate limit numbers.

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 has 100% coverage (baseline 3), but description adds crucial invocation context: comma-separated array syntax, plan restriction warnings (*Plan restricted), external reference URL for network enums, and pagination end conditions. Elevates beyond raw 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?

Excellent specificity: states it 'Returns DEX pool metadata' with specific fields (tokens, fees, protocol), distinguishing it from sibling getV1EvmPoolsOhlc (likely price history) by content type, and from getV1SvmPools via the 'EVM networks' reference in the network parameter description.

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 implied usage through specificity ('metadata' vs other data types), but lacks explicit guidance on when to choose this over getV1EvmPoolsOhlc or getV1EvmDexes. No prerequisites or exclusions 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?

With no annotations provided, the description carries the full burden. It discloses plan restrictions, pagination behavior ('Empty data array signifies end of results'), and provides extensive response examples including error codes (400, 401, 403, etc.), though it omits explicit rate limit or authentication requirement descriptions.

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 clear markdown sections (Query Parameters, Responses). The upfront summary is concise, though the response examples are lengthy. Information is logically ordered with purpose first, parameters second, and responses third.

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 rich input schema (100% coverage), output schema examples provided in the description, and 7 parameters, the description is substantially complete. It covers plan restrictions, pagination logic, and response structure, though minor gaps remain regarding authentication requirements and rate limiting.

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%, establishing a baseline of 3. The description accurately lists all 7 parameters with identical descriptions to the schema, but adds no additional semantic context, syntax clarification, or usage examples beyond the schema definitions.

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 specific action ('Returns') and resource ('OHLCV price data for liquidity pools'), distinguishing it from siblings like getV1EvmPools (likely current state) and cross-chain variants (getV1SvmPoolsOhlc) by specifying the financial data type.

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?

Mentions 'OHLCV historical depth is subject to plan restrictions' indicating usage constraints, but lacks explicit guidance on when to use this versus getV1EvmPools or other data endpoints, and doesn't clarify the historical vs. current data distinction.

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?

Without annotations, the description carries the full burden. It successfully discloses pagination behavior ('Empty `data` array signifies end of results') and plan restrictions ('*Plan restricted' on multiple parameters). However, it doesn't explicitly state that this is a read-only operation, though implied by 'Returns'.

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 Query Parameters and Responses sections, but severely bloated by duplicating the input schema and including massive JSON response examples despite the presence of an output schema. Every section contains information, but the redundancy with structured fields wastes tokens.

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 complexity (18 parameters) and rich output schema, the description covers all necessary aspects: parameter purposes (via duplication), response structure with examples, error codes, and pagination logic. It adequately supports agent invocation despite inefficiencies, though it could omit redundant JSON examples since an output schema exists.

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

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

With 100% schema description coverage including examples and enums, the schema already fully documents parameters. The description duplicates this information (including HTML formatting and 'Plan restricted' notes) but adds minimal semantic value beyond the structured schema, meeting the baseline for high-coverage 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 opening sentence 'Returns DEX swaps events with input & output token amounts' provides a specific verb (Returns), resource (DEX swaps events), and scope. The EVM-specific nature distinguishes it clearly from siblings like getV1SvmSwaps and getV1TvmSwaps, while 'swaps' distinguishes from getV1EvmPools or getV1EvmTransfers.

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 defines what the tool returns (DEX swaps), providing implied usage context. However, it lacks explicit guidance on when to use this versus getV1EvmTransfers (for general transfers) or getV1SvmSwaps (for Solana), and doesn't state prerequisites like authentication requirements despite listing 401/403 responses.

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?

With no annotations provided, the description carries the full burden. It discloses the 'Plan restricted' constraint for multiple contract addresses and documents the response structure. However, it omits auth requirements, rate limits, caching behavior, and whether the operation is idempotent or safe (though 'Returns' implies read-only).

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?

While the first sentence is efficient, the description is extremely bloated with extensive HTTP status code documentation (400, 401, 403, 404, 500) and full JSON response examples that replicate what should be in the structured output schema. This content is not useful for an MCP tool selector and buries the actual tool purpose.

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

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

Despite having a structured output schema available, the description redundantly documents response formats extensively but fails to address the relationship between this tool and its many siblings (e.g., EVM vs SVM variants, Token vs Holder queries). For a 2-parameter tool, it is complete on data formats but incomplete on usage context.

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

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

Schema description coverage is 100% for the 2 parameters, establishing a baseline of 3. The description text largely repeats the schema definitions for 'network' and 'contract' (including the comma-separated format), adding no additional semantic context about parameter interactions or data formats beyond what's already in the schema.

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

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

The first sentence clearly states the tool 'Returns ERC-20 token metadata including supply and holder count,' specifying the verb (Returns), resource (ERC-20 tokens), and specific data points. It implicitly distinguishes from sibling getV1EvmTokensNative by specifying 'ERC-20' (vs native), but lacks explicit differentiation guidance from other related tools like getV1EvmHolders.

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 documents the 'network' and 'contract' parameters and notes '*Plan restricted' for array values, but provides no explicit guidance on when to use this tool versus siblings (e.g., getV1EvmTokensNative for native tokens, getV1EvmHolders for holder-specific queries) or preconditions for usage.

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?

With no annotations provided, the description carries the full burden. It documents HTTP error cases (400, 401, 403, 404, 500) and response structure via embedded JSON examples. However, it fails to explain what 'Native' specifically means (native currency vs. other tokens) or describe pagination behavior evident in the example 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?

While front-loaded with the core purpose, the description is severely bloated by extensive OpenAPI-style response documentation (JSON examples for 200, 400, 401, etc.) that duplicates what should be in the structured output schema. This verbosity reduces readability for an LLM agent.

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 description documents parameters, success responses, and error codes, but wastefully duplicates structured output schema data. Given the simple single-parameter input, it is technically complete but lacks critical domain context—specifically clarifying that 'Native' refers to the chain's gas token and how this differs from generic token endpoints.

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

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

The input schema has 100% description coverage for its single 'network' parameter. The description repeats this information in a 'Query Parameters' section without adding additional semantic context (e.g., explaining the Graph Network ID format or providing usage examples), meeting the baseline for high-coverage 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 first sentence clearly states the action ('Returns') and specific resource ('Native metadata') along with key data fields ('supply and holder count'). However, it assumes domain knowledge that 'Native' refers to the blockchain's native currency (vs ERC-20 tokens) and does not explicitly distinguish this from the sibling 'getV1EvmTokens' tool.

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

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

No guidance is provided on when to use this tool versus alternatives like 'getV1EvmTokens' (likely for ERC-20 tokens) or other sibling tools. There are no prerequisites, filtering tips, or error-handling instructions beyond the raw HTTP status codes.

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?

Without annotations, the description must carry the full behavioral burden. It adds valuable context like 'Plan restricted' notes on certain parameters and explains pagination termination ('Empty `data` array signifies end of results'). However, it fails to explicitly state this is a read-only operation, doesn't mention rate limits, and doesn't indicate data freshness or latency.

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 extremely verbose with excessive repetition. It includes full JSON examples for five different error codes (400, 401, 403, 404, 500) that are nearly identical, consuming significant context window without adding distinct value. While it uses headers like 'Query Parameters' and 'Responses', the sheer length and redundancy make it difficult to scan efficiently.

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 parameters, rich output structure), the description is comprehensive. It documents all possible response codes with examples and explains the pagination mechanism. While the output schema exists, the inclusion of response examples provides helpful concrete context, though it borders on excessive.

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

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

With 100% schema description coverage, the baseline score is 3. The description largely duplicates parameter information already present in the schema (e.g., descriptions for network, contract, and date filters). It does not add semantic meaning, syntax clarification, or usage examples beyond what the schema already provides.

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

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

The description opens with a clear, specific statement: 'Returns ERC-20 transfers with transaction and block data.' This identifies the resource (ERC-20 transfers), the operation (returns), and the included data scope. It implicitly distinguishes the tool from siblings like getV1EvmTransfersNative (native currency) and getV1EvmNftTransfers (NFTs) by specifying 'ERC-20', though it doesn't explicitly compare against these alternatives.

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 extensive parameter documentation but offers no guidance on when to use this tool versus its siblings (e.g., when to use getV1EvmTransfers vs getV1EvmTransfersNative or getV1SvmTransfers). There are no 'when to use' or 'when not to use' clauses, nor does it mention prerequisites like authentication requirements despite listing 401/403 error codes.

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?

No annotations provided, so description carries full burden. It documents HTTP error codes (400, 401, 403, 404, 500) and mentions 'Plan restricted' constraints on certain parameters, hinting at rate limiting. However, it lacks explicit statements about read-only safety, idempotency, or specific rate limit behaviors.

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?

Extremely verbose with massive duplication of structured data. Includes exhaustive response examples (JSON for 200, 400, 401, etc.) despite the existence of an output schema. Every parameter is re-documented in narrative form when the input schema is fully descriptive. Not front-loaded; the actual purpose is one sentence followed by pages of API documentation.

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?