Server Quality Checklist

Tool Scores

• get_transaction_by_hashC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It states what the tool does but doesn't cover important aspects like error handling (what happens with invalid hashes), performance characteristics, rate limits, authentication requirements, or whether this is a read-only operation. The description is functionally correct but lacks 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 efficiently structured with clear sections for purpose, arguments, and returns. Each sentence serves a distinct purpose without redundancy. The formatting with headers makes it easy to parse, though the 'Returns' section could be more specific given there's no output schema.

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

  Completeness2/5

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

  For a tool with no annotations, no output schema, and 0% schema description coverage, the description is insufficiently complete. It covers the basic operation but lacks critical information about what 'detailed information' includes, error conditions, performance expectations, and how this tool relates to the available SQL query alternatives on the server.

  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 description explicitly documents the single parameter 'tx_hash' and its purpose ('The transaction hash to look up'), which adds value beyond the schema's 0% description coverage. However, it doesn't provide format details (e.g., hex string, length requirements) or validation rules that would be helpful for proper usage.

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

  Purpose4/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 with a specific verb ('Get') and resource ('detailed information about a transaction'), making it immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'query_blockchain_sql' or 'query_dataset' that might also retrieve transaction data through different mechanisms.

  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 provides no guidance on when to use this tool versus alternatives. With siblings like 'query_blockchain_sql' and 'query_dataset' available, there's no indication whether this is the preferred method for transaction lookups, if it's faster for single transactions, or when SQL queries would be more appropriate.

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

• get_latest_ethereum_blockB
  3/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return includes 'block number,' but doesn't specify other behavioral traits such as rate limits, error conditions, data freshness, or whether it's a read-only operation. This leaves significant gaps in understanding how the tool behaves beyond its basic function.

  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 concise and well-structured, with two sentences that efficiently convey the tool's purpose and return value. There's no wasted language, and it's front-loaded with the main function. However, it could be slightly more polished by integrating the return information into the first sentence for better flow.

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

  Completeness2/5

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

  Given the complexity of blockchain data retrieval and the lack of annotations and output schema, the description is incomplete. It mentions returning 'information about the latest block including block number,' but doesn't detail other returned fields (e.g., timestamp, transactions), error handling, or performance considerations. This leaves the agent with insufficient context for effective use.

  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?

  The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline of 4 is applied since no parameters exist, and the description doesn't introduce confusion about them.

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

  Purpose4/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: 'Get information about the latest Ethereum block.' It specifies the verb ('get') and resource ('latest Ethereum block'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_transaction_by_hash' or 'query_blockchain_sql,' which prevents a perfect score.

  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 provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate (e.g., for real-time block data) or when to use other tools like 'query_blockchain_sql' for more complex queries. This lack of contextual direction leaves the agent without usage instructions.

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

• list_datasetsB
  3.2/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool returns a list but doesn't specify format, pagination, rate limits, authentication needs, or whether it's read-only. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

  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 a single, efficient sentence that directly states what the tool does. It's front-loaded with the core action and resource, with zero wasted words or redundant information, making it highly concise and well-structured.

  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 simplicity (0 parameters, no output schema, no annotations), the description is adequate as a basic read operation. However, it lacks details about return format, data scope, or how it fits with sibling tools, which would help the agent use it more effectively in context.

  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?

  The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter information, and it appropriately doesn't mention any. Baseline for 0 parameters is 4, as the description focuses on the tool's purpose without unnecessary parameter details.

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

  Purpose4/5

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

  The description clearly states the action ('Return a list') and resource ('all available cryo datasets'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'lookup_dataset' or 'list_available_sql_tables', which prevents a perfect score.

  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 provides no guidance on when to use this tool versus alternatives like 'lookup_dataset' or 'query_dataset'. It lacks any context about prerequisites, timing, or exclusions, leaving the agent to infer usage from the tool name alone.

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

• get_sql_examplesA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the return format ('Dictionary of example queries categorized by dataset type and workflow patterns'), which is helpful. However, it doesn't mention potential limitations like rate limits, authentication needs, or whether the examples are static or dynamically generated. The description doesn't contradict any annotations (none exist).

  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 clear sections (purpose, workflow tips, combined approach, returns). It's appropriately sized for the complexity, though the workflow tips section is somewhat lengthy for a tool that just returns examples. Every sentence earns its place by providing practical guidance, but it could be slightly more concise by integrating tips more tightly with the core purpose.

  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 (parameterless, no output schema, no annotations), the description is quite complete. It explains the purpose, provides extensive usage guidance, and describes the return format. The only minor gap is lack of explicit behavioral constraints (e.g., whether examples are curated/static), but overall it's well-rounded for this type of helper 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?

  The tool has 0 parameters, and schema description coverage is 100% (empty schema). The description appropriately doesn't discuss parameters, which is correct for a parameterless tool. It focuses instead on output semantics and usage context, adding value beyond the empty 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's purpose: 'Get example SQL queries for different blockchain datasets with DuckDB'. It specifies the exact resource (example SQL queries) and distinguishes from siblings like query_sql (executes SQL) or list_datasets (lists datasets). The verb 'Get' is specific and unambiguous.

  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 explicit usage guidance through 'SQL WORKFLOW TIPS' and 'OR use the combined approach', detailing when to use this tool (for learning/example queries) versus alternatives like query_sql or query_blockchain_sql (for actual execution). It names specific sibling tools (query_dataset, get_sql_table_schema, query_sql, query_blockchain_sql) and explains their roles in workflows.

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

• get_sql_table_schemaA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it returns schema, sample data, and row count; it's for exploration (not modification); and it requires a file path from other tools. It doesn't mention performance characteristics or error handling, but covers the core functionality adequately.

  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 clear sections (purpose, workflow note, usage example, args, returns) and every sentence adds value. It's slightly longer than minimal but justified by the comprehensive guidance. The front-loaded purpose statement is excellent.

  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?

  For a single-parameter tool with no annotations and no output schema, the description provides excellent context: clear purpose, usage guidelines, parameter explanation, and return value description. It doesn't detail the exact output structure, but given the tool's exploratory nature and the sibling context, this is reasonably complete.

  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 input schema has 0% description coverage, so the description must compensate fully. It clearly explains the single parameter's purpose ('Path to the parquet file'), source ('from list_available_sql_tables or query_dataset'), and provides usage examples showing how to obtain and use it, adding significant value 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?

  The description clearly states the specific action ('Get the schema and sample data'), resource ('for a specific parquet file'), and distinguishes it from siblings like list_available_sql_tables (which lists files) and query_sql (which executes queries). The WORKFLOW NOTE further clarifies its exploratory purpose.

  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 explicitly states when to use this tool ('to explore the structure of parquet files before writing SQL queries') and provides a detailed workflow example showing how it integrates with sibling tools (list_available_sql_tables and query_sql). It clearly positions this as a preparatory step for querying.

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

• list_available_sql_tablesA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by explaining what gets returned (file path, dataset type, metadata), how to use the output (with read_parquet() and query_sql()), and the prerequisite that files must be 'already downloaded'. It doesn't mention performance characteristics or error conditions, but provides substantial behavioral context.

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

  Conciseness5/5

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

  The description is well-structured with clear sections, front-loads the core purpose, and every sentence adds value. The USAGE NOTES bullet points efficiently convey critical information 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?

  For a zero-parameter tool with no annotations or output schema, the description provides excellent context about what the tool does, how to use its output, and relationships to other tools. It could mention error conditions or performance, but covers the essential usage context thoroughly.

  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?

  The tool has 0 parameters with 100% schema coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on what the tool does and how to use its output.

  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 verb 'list' and the resource 'parquet files that can be queried with SQL', specifying that these are files that have already been downloaded. It distinguishes from siblings like list_datasets by focusing specifically on SQL-queryable parquet files rather than datasets in general.

  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 USAGE NOTES section explicitly states when to use this tool (to get file paths for SQL queries) and how to use the output with query_sql(). It also distinguishes from alternatives by noting these are 'already downloaded' files, implying list_datasets might show available datasets that aren't yet downloaded.

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

• lookup_datasetA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by explaining the tool's behavior: it's a read-only lookup (implied by 'look up' and 'return information'), it provides schema details and required parameters, and it includes sample data generation capabilities. However, it doesn't mention rate limits, authentication needs, or error conditions.

  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 appropriately sized and front-loaded with the core purpose and important usage guideline. Every sentence adds value, though the example section is somewhat lengthy. The structure flows logically from purpose to usage to parameters to returns.

  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?

  For a tool with 5 parameters, 0% schema coverage, no annotations, and no output schema, the description does an excellent job of explaining what the tool does, when to use it, and what parameters mean. The main gap is lack of information about return format details, though it describes what information will be included.

  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 has 0% description coverage, but the description fully compensates by explaining all 5 parameters in detail. It clarifies that 'name' is the dataset identifier, and the other 4 parameters control sample data generation (with specific examples like 'sample_blocks_from_latest'). This adds substantial meaning 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?

  The description clearly states the tool's purpose with specific verbs ('look up', 'return detailed information') and resource ('dataset'), distinguishing it from siblings like list_datasets (which lists datasets) or query_dataset (which queries data). It explicitly explains this is for understanding dataset parameters and schema before querying.

  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 explicit guidance on when to use this tool ('Always use this function before querying a new dataset') and when to use alternatives (query_dataset for actual queries). It includes a concrete example showing the workflow between lookup_dataset and query_dataset, making the usage context clear.

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

• query_blockchain_sqlA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the two SQL query approaches, dataset-specific parameter requirements, and the return format ('SQL query results and metadata'). However, it doesn't mention performance characteristics, rate limits, or error conditions that would be helpful for a complex tool with 10 parameters.

  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 clear sections (purpose, convenience note, SQL approaches, dataset-specific guidance, examples, alternative workflow, and parameter details). While comprehensive, some sections could be more concise - the examples are quite detailed, and the description is lengthy overall for a tool description.

  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?

  For a complex tool with 10 parameters, 0% schema coverage, no annotations, and no output schema, the description does an excellent job of providing context. It explains the tool's relationship to siblings, provides usage examples, clarifies parameter semantics, and describes return values. The main gap is lack of information about performance, limits, or error handling.

  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?

  With 0% schema description coverage and 10 parameters, the description compensates excellently. It provides detailed explanations for key parameters like 'contract' with specific examples, clarifies parameter relationships (blocks vs start_block/end_block), and explains default behaviors. The 'Args' section adds crucial semantic context 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?

  The description clearly states the tool's purpose: 'Download blockchain data and run SQL query in a single step' and explicitly distinguishes it from siblings by naming 'query_dataset' and 'query_sql' as separate tools that this one combines. It specifies the exact functionality and differentiates from alternatives.

  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 explicit guidance on when to use this tool vs alternatives: it states this is a 'CONVENIENCE FUNCTION' that combines two other tools, and provides an 'ALTERNATIVE WORKFLOW' section detailing when to use the separate steps for 'more control'. It clearly delineates the trade-offs between convenience and control.

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

• query_datasetA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it downloads data to files, returns a dictionary of file paths, and integrates with query_sql. It mentions dataset-specific requirements and workflow dependencies, though it doesn't cover potential errors, rate limits, or file storage details.

  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 clear sections (workflow note, dataset-specific parameters, Args, Returns) and uses bullet points for readability. It's appropriately sized for a complex tool but could be slightly more concise by integrating the example workflow more tightly with the parameter explanations.

  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?

  For a complex tool with 10 parameters, 0% schema coverage, no annotations, and no output schema, the description provides comprehensive context. It explains the tool's role in a larger workflow, details all parameters, and describes the return value. The main gap is lack of error handling or performance considerations, but it's largely complete given the constraints.

  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?

  Given 0% schema description coverage, the description compensates fully by explaining all 10 parameters in detail. It clarifies dataset-specific usage (e.g., contract parameter for address filtering), provides examples for blocks and output_format, and explains parameter relationships (e.g., blocks vs. start_block/end_block). This adds significant meaning 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?

  The description clearly states the tool's purpose: 'Download blockchain data and return the file paths where the data is stored.' It specifies the verb ('download'), resource ('blockchain data'), and output ('file paths'), distinguishing it from siblings like query_sql or list_datasets that don't download data.

  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 explicit guidance on when to use this tool vs. alternatives: 'When running SQL queries, use this function first to download data, then use the returned file paths with query_sql() to execute SQL on those files.' It also advises to use lookup_dataset() first to check dataset parameters, offering clear workflow instructions.

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

• query_sqlA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains the tool's behavior: it executes SQL queries against parquet files, supports two query approaches (direct table references or read_parquet()), and mentions DuckDB as the underlying engine. It also notes that results include query results and metadata. The main gap is lack of information about error handling, performance characteristics, or limitations.

  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 clear sections (purpose, workflow, examples, parameter explanations, return value). While comprehensive, it could be more concise - some information is repeated (e.g., both workflow steps and DuckDB approaches mention the two query methods). Every sentence earns its place, but some tightening is possible.

  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 (SQL execution with file dependencies), no annotations, and no output schema, the description provides substantial context. It explains the workflow, parameter usage, and return values. The main gap is lack of output format details - while it mentions 'Query results and metadata', it doesn't specify the structure. For a SQL execution tool, more detail on result format would be helpful.

  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?

  With 0% schema description coverage, the description fully compensates by explaining all three parameters. It clarifies that 'query' is the SQL to execute with syntax examples, 'files' are typically from query_dataset results, and 'include_schema' controls whether schema information is included in results. The description adds substantial value 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?

  The description clearly states the tool's purpose as 'Run a SQL query against downloaded blockchain data files', specifying both the action (run SQL query) and the target resource (downloaded blockchain data files). It distinguishes this from sibling tools like query_dataset (which downloads data) and get_sql_table_schema (which shows schema).

  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 explicit workflow guidance: 'This function should be used after calling query_dataset to download data.' It names the specific prerequisite tool (query_dataset) and explains the sequence of operations. The 'IMPORTANT WORKFLOW' section clearly defines when to use this tool versus alternatives.

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