Server Quality Checklist

Tool Scores

• describe_tableA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full behavioral burden. It transparently lists the result contents and implies a read-only operation, but it does not mention potential caveats such as row-count cost on large tables, required permissions, or error behavior for missing tables.

  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, well-organized sentence that front-loads the core action and then lists the returned metadata without any filler. Every part earns its place.

  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?

  The tool is fairly simple and the parameter schema is complete, but with no annotations and no output schema the description would benefit from a little more context, such as usage intent or caveats. It is adequate but not fully self-sufficient.

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

  Parameters3/5

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

  Schema description coverage is 100%, so both parameters (table and connection) are already fully documented in the input schema. The description adds only the 'one table' scope and does not provide additional parameter nuance beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Describe one table', then enumerates the exact metadata returned (columns, indexes, foreign keys, CREATE statement, row count). This clearly separates it from siblings like list_tables, sample_rows, query, and explain_query.

  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?

  Usage is implied: use this tool when you need schema-level details about a single table rather than listing tables, sampling rows, or running queries. However, there is no explicit guidance about when to choose this over alternatives or any exclusions.

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

• sample_rowsA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It correctly states the action and default, but it omits an important caveat: 'first N rows' has no guaranteed order without an ORDER BY clause. It also does not mention whether this is a simple LIMIT query or the potential performance implications on large tables.

  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?

  A single sentence that front-loads the action, includes the default, and closes with practical use-case guidance. Every word earns its place, with no redundancy or filler.

  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 simple preview tool, the description covers the essence: what it does, the default behavior, and the intended use case. It could be improved by noting that rows are unsorted unless specified and that this is effectively a SELECT * FROM table LIMIT n, but the existing text is sufficient for an agent to select and invoke it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no parameter-specific meaning beyond restating the default limit already present in the schema, which keeps it at the baseline.

  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 a specific action ('Fetch the first N rows of a table') with a concrete resource and a default limit. It also explains the purpose ('to see real values... before writing queries'), which distinguishes it from siblings like describe_table or explain_query without needing to open the schema.

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

  Usage Guidelines4/5

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

  It provides explicit context for when to use the tool: 'useful for understanding data shape before writing queries.' It does not explicitly name alternatives or exclusions, but the use case is clear enough relative to the sibling tools.

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

• explain_queryA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states that the statement is not executed and that write statements are safe, and it also describes what the plan reveals. This is strong behavioral transparency for a relatively simple tool.

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

  Conciseness5/5

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

  The description is two concise sentences with no filler. The core purpose is front-loaded, and 'Safe on write statements' adds an important behavioral note without extra verbosity.

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

  Completeness5/5

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

  For a low-complexity tool, the description covers purpose, safety, non-execution behavior, and even the nature of the output (index usage, scan order, estimated rows). Combined with a fully documented parameter schema, an agent has enough context to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the input schema already fully documents the sql, params, and connection parameters. The description adds no parameter-level meaning beyond the schema, which is acceptable but not extra value.

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

  Purpose5/5

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

  The description states a specific verb ('Show the execution plan'), a clear resource ('a statement'), and explicitly distinguishes it from execution by saying 'without running it'. This makes it easy to separate from the sibling query tool, which actually runs statements.

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

  Usage Guidelines4/5

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

  The description clearly communicates when to use this tool: when you need index usage, scan order, or estimated rows without executing the statement. It also notes it is safe on write statements, which is useful context, though it does not explicitly name alternative tools or list 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.

• list_tablesA
  4.3/5.0
  Behavior4/5

  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 transparently discloses the scope ('default schema'), the return content ('tables and views... with column counts'), and implies a read-only operation. It does not mention potential permission requirements or pagination, but for a listing tool this is adequate.

  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?

  Two sentences with no redundancy. The action and scope are front-loaded in the first sentence, and the usage guidance is a single clear instruction in the second.

  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?

  This is a low-complexity tool with one optional parameter and no output schema. The description covers what the tool lists, the scope of that listing, the result detail (column counts), and when to call it. Nothing an agent needs to invoke it correctly is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the connection parameter is already fully documented in the schema. The description adds no parameter-specific meaning beyond 'use this first,' so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('List') and resource ('all tables and views in the connection's default schema') with an additional detail ('with column counts'). It clearly distinguishes itself from siblings like describe_table (which targets a single table) and query (which executes arbitrary SQL).

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

  Usage Guidelines4/5

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

  The description gives an explicit instruction, 'Use this first to discover what to query,' which tells the agent when this tool is appropriate. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

• queryA
  4.4/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 behavioral disclosure burden. It does this well by explaining return shapes per statement type, the maxRows cap/default, multi-statement script support, and parameter binding conventions. It stops short of discussing side effects or permissions, but the core runtime behavior is transparent.

  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?

  Three dense, well-structured sentences with no filler. The purpose is front-loaded, behavior is grouped logically, and every sentence contributes information.

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

  Completeness4/5

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

  For a general SQL execution tool with no output schema and no annotations, the description covers the essential decision factors: return modes, row limits, binding syntax, and multi-statement support. It leaves some room for connection-selection details, but those are documented in the schema.

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

  Parameters4/5

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

  Schema coverage is already 100%, giving the baseline of 3. The description adds useful semantics beyond the schema by connecting sql statement categories to their return behavior and clarifying maxRows as a per-query cap with a default of 1000.

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

  Purpose5/5

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

  The description opens with 'Run a SQL statement', giving a clear verb and resource, then distinguishes this general-purpose execution tool from the specialized siblings list_tables, describe_table, sample_rows, and explain_query by covering the statement types it handles.

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

  Usage Guidelines4/5

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

  The description clearly conveys that this is the tool for arbitrary SQL execution and enumerates which statement categories it supports. It does not name sibling alternates explicitly, but the practical context is strong enough for an agent to choose it over the specialized table-introspection siblings.

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