Server Quality Checklist

Tool Scores

• list_databasesA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds no further behavioral context (e.g., filtering, sorting, output format), so it neither adds nor contradicts.

  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, highly efficient sentence that front-loads the core purpose. No extraneous information is present.

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

  Completeness5/5

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

  Given the tool's simplicity (0 parameters, rich annotations, output schema available), the description is sufficient. It clearly states what the tool does, and the return values are documented externally.

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

  Parameters4/5

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

  With zero parameters and 100% schema coverage, the baseline is 4. The description does not need to add parameter details, as the schema already fully documents the empty parameter set.

  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 'List available Hydrolix databases' uses a specific verb and resource, clearly differentiating from siblings like list_tables and get_table_info that operate at the table level.

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

  Usage Guidelines3/5

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

  The description provides no explicit guidance on when to use this tool versus alternatives. Usage is implied by the name and sibling context, but no when-not or alternative suggestions are given.

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

• get_table_infoA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral details like column categories (Column, AliasColumn, AggregateColumn, SummaryColumn), merge_function usage, and the distinction between summary and non-summary tables, which beyond annotations.

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

  Conciseness4/5

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

  The description is well-structured with a clear purpose, bullet points for return fields, and a numbered workflow. However, it is slightly verbose, repeating the workflow in both narrative and list form. Front-loaded with the essential usage instruction.

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

  Completeness5/5

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

  Despite the lack of parameter descriptions, the description fully covers the tool's purpose, return fields (including column categories and merge_function), and the complete workflow for using the tool alongside run_select_query. Given the output schema exists, return values are adequately explained.

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

  Parameters2/5

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

  The input schema has two required parameters (database, table) with no descriptions (0% coverage). The description only mentions 'Call get_table_info('database', 'table_name')' but does not define what database or table mean, leaving the agent to infer from context. This is insufficient compensation for the missing schema documentation.

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

  Purpose5/5

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

  The description clearly states 'Get detailed metadata for a specific table including columns and summary table detection.' It uses a specific verb ('Get') and resource ('table metadata'), and the sibling tools (list_databases, list_tables, run_select_query) are distinct, so there is no confusion.

  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 mandates 'Call this tool BEFORE querying ANY table' and provides a numbered workflow detailing when and how to use it. It also implicitly guides when not to use it (after metadata is obtained) by linking to run_select_query.

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

• run_select_queryA
  4.8/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, destructiveHint), the description discloses critical behaviors: a 30-second timeout, result truncation when cell count exceeds a limit, and the exact response shape with conditions. It explains edge cases like row_count=0 and the meaning of total_row_count. This transparency ensures the agent understands the tool's operational characteristics.

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

  Conciseness4/5

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

  The description is lengthy but well-structured with clear sections (output shape, pre-query check, summary table rules, examples). It is front-loaded with the core purpose. While every sentence adds value given the tool's complexity, some redundancy exists (e.g., repeating the pre-query check in examples). Slightly more conciseness would elevate it, but overall it is efficient for the domain.

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

  Completeness5/5

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

  Given the tool's complexity, the presence of an output schema (though not shown), and the 0% parameter description coverage, the description covers all necessary aspects: input format, output shape, error conditions, dependencies (get_table_info), performance best practices, and detailed syntax rules for summary tables. It leaves no significant gaps for an agent to use the tool correctly.

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

  Parameters4/5

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

  Although the input schema has no parameter descriptions (0% coverage), the description adds substantial meaning. For the required 'query' parameter, it specifies valid SQL dialect, required table naming format, and syntax examples. For 'max_cells', it explains truncation behavior and how to handle row_count=0. The extensive query patterns and examples compensate for the lack of formal schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Run a SELECT query in a Hydrolix time-series database using the Clickhouse SQL dialect.' This specific verb+resource combination, along with the mention of Clickhouse dialect and Hydrolix database, distinguishes it from sibling tools like get_table_info or list_databases, which handle metadata.

  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, including a mandatory pre-query check (call get_table_info first), performance guard requirements (LIMIT or primary key filter), and detailed rules for summary vs. regular tables. It also suggests when to use substring matching and warns against SELECT *. This comprehensive guidance helps the agent decide when and how to use this tool.

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

• list_tablesA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that the tool returns basic table info WITHOUT column details, with empty columns lists and is_summary_table not set, and explains the performance rationale. There is no contradiction between description and annotations.

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

  Conciseness5/5

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

  The description is concise, well-structured with a lead sentence, bullet points, and an important note. It front-loads the purpose and uses efficient language without redundancy. Every sentence adds value.

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

  Completeness5/5

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

  Given the tool complexity, existence of output schema, and annotations, the description is complete. It explains what the tool returns and what it deliberately omits (column details, is_summary_table), and provides guidance on next steps (get_table_info). This suffices for an agent to understand and invoke the tool correctly.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description needs to compensate. It explains the 'database' parameter and that 'like' and 'not_like' are for pattern filtering. However, it does not specify the exact pattern format (e.g., SQL LIKE syntax), which would be helpful. Overall, it adds meaning beyond the schema but could be slightly more precise.

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

  Purpose5/5

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

  The description clearly states it lists tables in a database for exploration and discovery. It specifies the verb 'list', the resource 'tables', and the context 'in a database'. It differentiates from siblings by noting it is lightweight and that column details are intentionally omitted, with a reference to get_table_info for more detail.

  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 says when to use the tool: to discover tables, filter by name pattern, and get basic metadata. It gives an 'IMPORTANT' instruction to call get_table_info before querying a specific table, and explains that this tool is intentionally lightweight to avoid loading schema, thus guiding the agent to alternative tools when needed.

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