Server Quality Checklist

Tool Scores

• describe_tableA
  4.2/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 explicitly states 'Read-only' and 'no confirmation needed,' which explains side-effect and execution expectations. It does not cover error behavior or permission requirements, but those are minor for a simple describe operation.

  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 tightly constructed: purpose in the first sentence, behavior in the second, and a minimal Args block. There is no filler, and the most important information is front-loaded. Every sentence earns its place.

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

  Completeness4/5

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

  Given a single required parameter and an output schema, the description covers the key aspects: what the tool returns, how to specify the table, and that it is read-only and immediate. It doesn't explicitly explain when to prefer it over but siblings, but that gap is already captured under usage guidelines. Overall it is sufficient for invocation.

  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 must compensate. It does: the Args block defines 'table' as 'Name of the table to describe,' giving meaning beyond the bare schema property. It doesn't add constraints like case-sensitivity or schema qualification, but it fully covers the only parameter's semantic role.

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

  Purpose5/5

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

  The description opens with a specific verb 'Show' and names the exact resource: 'columns, types, constraints and foreign keys of one table.' This clearly distinguishes it from siblings like list_tables (probably lists tables) and propose_change/confirm_change (change tools). The purpose is immediately unambiguous.

  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 signals usage context through 'Read-only. Runs immediately, no confirmation needed,' implying this is a safe inspection tool that does not require the change workflow. However, it never explicitly names alternatives or states when not to use it, so the routing relies on inference rather than explicit guidance.

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

• confirm_changeA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral disclosure burden. It discloses that the statement is re-validated and re-executed before committing, and that commit requires a valid, unused, unexpired change_id. This goes beyond the tool name and helps the agent understand side effects and constraints, though it doesn't discuss failure modes or output.

  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 compact and well-organized: a one-sentence summary, a short behavioral/constraint paragraph, and an Args section. Every sentence contributes meaningful information without repetition or fluff.

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

  Completeness4/5

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

  The description covers the essential context for correct invocation: where change_id comes from, the re-execution behavior, and the expiry/unused constraints. An output schema exists, so return-value details are not needed. It could mention what happens on invalid or expired IDs, but the current information is enough for a competent agent.

  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 schema only declares change_id as a required string with zero coverage in its description. The tool description compensates by stating 'change_id: The id returned by propose_change,' explaining the parameter's origin and relationship to another tool. It would be stronger with validation rules, but for a single parameter this is sufficient.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Commit a change that propose_change previewed.' This clearly identifies the action and the object, and it distinguishes confirm_change from propose_change by positioning it as the commit step. The added sentence 'There is no way to commit a write without one' reinforces its unique role among the sibling tools.

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

  Usage Guidelines4/5

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

  The description states that change_id must come from propose_change and be unused and unexpired, which tells the agent when to call this tool: after a proposal exists and when a commit is intended. It does not explicitly name alternatives or say 'do not use for read-only queries,' but the lifecycle context makes the usage condition clear.

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

• list_pending_changesA
  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 disclosure burden. It explicitly marks the operation read-only and states the returned fields (change_id, SQL, expiry remaining), which gives the agent a clear behavioral model. It does not discuss edge cases like empty results, but that is minor for a zero-parameter list operation with an output schema.

  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 short, focused sentences with no fluff. The core purpose comes first, and the read-only note plus output contents are placed immediately after.

  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 zero-parameter read-only listing tool with an output schema, the description is complete: it identifies the resource, the state of the items, and the key fields returned. Nothing necessary for correct invocation is missing.

  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 input schema is empty and has no parameters, so parameter documentation is not needed. The description instead adds value by explaining what each listed item contains, which is appropriate given there are no inputs to describe.

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

  Purpose5/5

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

  The description uses a clear verb ('List') with a specific resource ('proposed changes that are still awaiting confirmation'), and distinguishes the tool from its siblings like run_query and confirm_change by focusing specifically on pending changes. The scope is unambiguous.

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

  Usage Guidelines4/5

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

  It clearly implies this tool is for reviewing proposed changes before they are confirmed, and the read-only note helps the agent understand it is safe to inspect. It does not explicitly name alternatives or say when not to use it, so I cannot give a 5.

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

• run_queryA
  4.6/5.0
  Behavior5/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 reveals that the connection is opened read-only, that input is validated before reaching the database, and that non-SELECT statements are rejected. This is significant behavioral context that would otherwise be invisible to the agent and goes well beyond the input schema.

  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 compact and front-loaded with the primary purpose, followed by necessary safety details, and ends with an Args section. Each sentence contributes either to scope, constraints, or parameter meaning, with no filler or redundant schema repetition.

  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 one-parameter tool with an output schema available, the description covers the essential behavioral constraints and parameter meaning. It does not explicitly mention error behavior or how returned rows are structured, but the output schema likely handles the return shape. Minor gap: it could more directly say 'use this for read-only SQL exploration,' but the read-only emphasis already communicates that.

  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 input schema only defines sql as a required string with no description, so schema coverage is 0%. The description compensates partly by specifying 'A single SELECT statement,' which adds the essential constraint on the parameter. It could add more detail about whether semicolons are allowed or how to structure complex queries, but for a single parameter the provided semantics are adequate.

  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 one read-only SELECT and return the rows,' a clear verb-resource pair that defines exactly what the tool does. It also distinguishes itself from siblings by restricting input to SELECT statements, while siblings like list_tables and describe_table serve different schema-introspection purposes.

  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 states that only a single SELECT is accepted and that writes, DDL, PRAGMA, ATTACH, stacked statements, and comments are rejected, which tells the agent when this tool is appropriate and what it is not for. It does not explicitly name alternative tools for write operations, but the sibling list and the rejection behavior make the boundary clear.

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

• list_tablesA
  4.7/5.0
  Behavior5/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 explicitly discloses that the operation is read-only and runs immediately without confirmation. This is exactly the kind of safety and side-effect information an agent needs before invoking an unknown 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?

  Two short sentences deliver complete value: the first states exactly what the tool returns, and the second adds the critical behavioral context. There is no filler, redundant schema repetition, or unnecessary detail.

  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 zero parameters and an output schema that presumably documents the return shape, the description covers everything necessary for an agent to call this tool confidently. It names the returned content, confirms read-only safety, and clarifies execution behavior. No material information is missing.

  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 zero parameters, so there is no parameter ambiguity for the description to resolve. The baseline of 4 applies because the description cannot add parameter-level meaning where none exist. The schema already confirms 100% coverage with no properties.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'List every table in the database with its row count and columns.' This clearly distinguishes the tool from describe_table, which targets a single table. There is no ambiguity about what the caller gets.

  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 conveys clear use context: it is a read-only, immediate action with no confirmation required. It does not explicitly name sibling tools or say when not to use it, but the contrast with confirmation-requiring siblings is implied. A small gap is the lack of explicit routing versus describe_table.

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

• propose_changeA
  4.8/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full disclosure burden, and it excels at this. It reveals that the statement is actually executed in a transaction and rolled back, that nothing is written, and that the returned id is single-use and expires. These are exactly the behavioral traits an agent needs to understand to use the tool safely.

  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 compact and front-loaded, covering purpose, mechanics, follow-up guidance, and constraints in a few tight sentences. No filler or redundant restatement of the tool name exists.

  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 single parameter and the rich behavioral detail provided, the description is complete for selecting and using the tool correctly. It explains the write-preview workflow, the follow-up confirm_change step, and the expiry behavior. An output schema exists to cover return-value details, so nothing critical is missing.

  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 only defines sql as a string, but the description adds critical meaning: it must be a single INSERT, UPDATE, or DELETE statement against an existing table, with a mandatory WHERE clause for UPDATE and DELETE. This goes well beyond the raw schema and fully documents the parameter's constraints.

  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 exactly what the tool does: preview a write without committing it and return a change_id. It distinguishes itself from sibling confirm_change by labeling this as the preview step, and from run_query by focusing on write 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?

  It clearly explains when to use the tool: before committing a write, with the preview shown to a human and confirm_change called afterward. It also gives explicit constraints on accepted statements (single INSERT/UPDATE/DELETE, WHERE clause required for UPDATE/DELETE), though it does not enumerate alternatives such as when to prefer run_query.

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