Server Quality Checklist

Tool Scores

• find_tablesA
  4.3/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses the return JSON structure, matching behavior on both table and column names, and critical presentation instructions (never mentioning the tool name, rendering modes). This is substantial behavioral context that helps the agent act correctly.

  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 front-loaded purpose, followed by usage, return format, and presentation rules. It is longer than typical but every section serves a distinct purpose, and the presentation rules are essential for correct agent behavior. Slightly verbose but not wasteful.

  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 moderate complexity, the rich schema (100% coverage), and the presence of an output schema, the description is complete: it covers search behavior, usage, output structure, and presentation. It does not need to explain return values (output schema exists). Minor gaps like case sensitivity or matching semantics are not critical for basic invocation.

  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 input schema already has 100% coverage with descriptions for all three parameters. The description adds minimal extra meaning beyond the schema—it mainly clarifies that 'term' matches names, which is already in the schema. Baseline 3 applies.

  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: 'Find tables by matching table or column names.' This clearly distinguishes the tool from siblings like list_tables (which lists all tables) and describe_table (which describes a specific table). The purpose 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?

  The description states when to use the tool: 'Use this tool when the user knows roughly what they're looking for... but not the exact table.' This is clear usage guidance. However, it does not explicitly mention alternatives or when not to use it, 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.

• describe_tableA
  4.4/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses the return format (JSON structure), presentation rules (never mention tool name, card-based layout, not pasting raw JSON), and behavior (highlighting primary keys). This adds substantial behavioral context not available from annotations alone.

  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 relatively long but well-structured with sections for purpose, usage, return format, and presentation. Every sentence serves a purpose, though it could be tightened without losing essential guidance.

  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 simple describe tool, the description covers purpose, usage, output format, and presentation rules. The presence of an output schema further reduces the need to explain return values. It is complete for the tool's complexity.

  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 coverage is 100% for all parameters. The description does not add extra parameter-level detail beyond what the schema already provides, so the 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 clearly states the tool's purpose with a specific verb and resource: 'Get the column structure of a table (DESCRIBE output).' It distinguishes from siblings by focusing on column metadata (types, keys, defaults) rather than querying or listing tables.

  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 provides explicit usage context: 'Use this tool when the user asks about a table's columns, types, keys, or defaults.' It does not explicitly mention alternatives or exclusions, but the context is clear enough.

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

• health_checkA
  4.4/5.0
  Behavior5/5

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

  The description goes well beyond the readOnlyHint annotation by detailing the exact JSON response shape for both success and failure scenarios, and by specifying precise presentation rules (card layout, Markdown fallback, never mention tool name, format uptime in human units). This equips the agent to handle the tool's output correctly and addresses all behavioral nuances.

  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 and front-loaded with the purpose and usage, followed by return format and formatting rules. It is somewhat lengthy but every sentence contributes necessary information, especially the output and presentation details. It could be tightened, but the organization is logical and not wasteful.

  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, the description is comprehensive: it covers purpose, usage triggers, output schema (via example JSON), error handling, and rendering instructions. The presence of an output schema further reduces the need to explain return values. Nothing essential is missing for an agent to use this tool effectively.

  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 only parameter, db_id, is fully described in the input schema with clear semantics ('Optional named database profile configured on the server'). The tool description adds no additional meaning, but with 100% schema description coverage, the baseline of 3 is justified.

  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: 'Check MySQL connection health and basic server status.' It uses a specific verb and resource, and the distinction from sibling tools (query, list_tables, etc.) is obvious. This is a focused health check tool with no ambiguity.

  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 provides explicit when-to-use guidance: 'when the user asks whether the database is reachable, what version it runs, or when queries are unexpectedly failing.' It does not name alternatives or mention when not to use it, but the context is clear enough that no exclusions are needed. Since no alternative is explicitly provided, a 4 is appropriate rather than a 5.

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

• inspect_schemaA
  4.4/5.0
  Behavior5/5

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

  Despite annotations already declaring readOnlyHint=true, the description adds substantial behavioral context: the exact return JSON structure, presentation rules ('never mention this tool's name...'), fallback formats, and the caveat that rowsEstimate is approximate. This goes well beyond the annotation and helps the agent set correct expectations.

  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 longer than average but well-organized: purpose, usage, return format, presentation, and formatting rules each have their own sentence group. It front-loads the core purpose and every sentence adds practical guidance, though a couple of formatting details could be tightened without loss.

  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 complex tool with nested outputs, the description is remarkably complete. It explains the return structure, the rendering modes (card vs Markdown), forbidden actions (raw JSON), and approximation caveats. Even with an output schema present, the description adds enough contextual detail to fully prepare the agent for invocation and response formatting.

  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%, meaning all four parameters (db_id, database, include_columns, include_indexes) are already documented in the input schema. The description adds no additional parameter semantics, which is acceptable given full schema coverage. Baseline 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 opens with a specific verb+resource+scope: 'Inspect all tables, columns, and indexes of a database at once.' This clearly differentiates from sibling tools like list_tables or describe_table by emphasizing the whole-schema scope. The purpose is unambiguous and concrete.

  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?

  Explicitly states when to use: 'Use this tool when the user wants an overview of a whole schema — e.g. to understand an unfamiliar database or plan queries.' Provides clear context and example scenarios, but does not name alternative tools or state when not to use it, so it misses the full 'alternatives' guidance.

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

• list_tablesA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint: true, so the bar for additional disclosure is lower. The description adds significant behavioral context: it specifies the return format (JSON object with tables and database), and details on presentation (never mention tool name, card vs. Markdown layout, formatting rules). This goes well beyond the annotation.

  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-organized with clear sections (purpose, usage, return format, presentation). It is more verbose than strictly necessary, but every section contributes useful guidance. The first sentence immediately conveys the core action, and the structured formatting rules are justified for consistent agent output.

  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 simple read-only tool, the description covers all essential aspects: what it does, when to use it, what it returns, and how to format the answer. The presence of an output schema and annotations covers remaining structural details, making the description comprehensive.

  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%, with both parameters (db_id and database) well-documented in the schema itself. The description does not add parameter-specific details, but the schema already explains optionality and defaults, 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 clearly states 'List tables in a database' with a specific verb and resource. It further clarifies the purpose ('when the user wants to see what tables exist') and distinguishes from sibling tools like list_databases and describe_table by focusing on the list of tables.

  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 explicitly says 'Use this tool when the user wants to see what tables exist,' providing a clear use case. However, it does not mention alternatives or when not to use it, so it stops short of full comparative guidance.

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

• sample_rowsA
  4.4/5.0
  Behavior5/5

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

  Annotations only say readOnlyHint=true, but the description adds significant behavioral context: the return JSON structure, the 50-row cap, and detailed presentation instructions (never mention the tool name, card-based layout, formatting rules, note that it's a sample). This goes well beyond the annotation, providing the agent with clear expectations for output and interaction.

  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 longer than average due to presentation and formatting rules, but it is front-loaded with the core purpose and well-organized into paragraphs. Every sentence provides value for correct invocation and presentation; only minor trimming could make it even crisper.

  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 tool with 4 parameters, output schema, and readOnly annotation, the description covers purpose, when to use it, return format, presentation, and formatting rules. It is sufficiently complete for an agent to select and invoke the tool correctly, with no notable gaps.

  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 input schema already covers all parameters with descriptions (coverage 100%). The description does not add extra meaning to the parameters themselves; it only references 'table' and 'limit' in the return structure. Per the baseline rule for high schema coverage, a 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 opens with 'Read a small sample of rows from a table (capped at 50)' — a specific verb, resource, and scope. It clearly distinguishes itself from sibling 'query' by noting 'without writing SQL', and from 'describe_table' by implying it shows data, not 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?

  Description explicitly says 'Use this tool to show the user what a table's data looks like without writing SQL' and gives an example ('right after describe_table'). However, it does not explicitly mention when not to use it or name alternative tools, though the 'without writing SQL' caveat implies distinction from 'query'.

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

• list_databasesA
  4.5/5.0
  Behavior5/5

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

  The description adds significant behavioral detail beyond the readOnlyHint annotation: it discloses the exact JSON return format, instructs the agent to never mention the tool's name, defines card vs. Markdown rendering rules, and specifies skipping system schemas unless asked. These are concrete behaviors that aid invocation and response formatting, going well beyond the annotation.

  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 and front-loaded with purpose, then usage, then return format, and finally presentation/formatting. Every sentence contributes essential information for the agent to act correctly, including rendering details that would otherwise be missing. Nothing is redundant or verbose relative to the tool's needs.

  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 (no required parameters) and the existence of an output schema (as indicated in context signals), the description is complete: it explains the purpose, when to use, the return shape, how to present results, and formatting exceptions. There are no gaps that would prevent an agent from using the tool effectively.

  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 input schema already contains a complete description of the single optional parameter `db_id`, achieving 100% schema coverage. The tool description does not add further parameter-level context; it only implicitly references the default connection when omitting the parameter. Per the rubric, a 3 is the baseline when schema covers all parameters, and no extra semantics are provided.

  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-resource statement: 'List all databases visible to the configured MySQL account.' This clearly distinguishes the tool from siblings like list_tables or describe_table, which target tables or schemas. It also uses the synonym 'schemas' to remove ambiguity, making the purpose absolutely clear.

  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 second sentence explicitly states when to use: 'Use this tool when the user wants to know which databases (schemas) exist on the server.' It gives clear context, though it does not name exclusionary conditions or direct users to alternative sibling tools for other intents. That keeps it a 4 rather than 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.5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses the exact allowed statements (SELECT/SHOW/DESCRIBE/EXPLAIN), explicitly refuses writes and dangerous functions (INTO OUTFILE, SLEEP, GET_LOCK, BENCHMARK, LOAD_FILE), explains placeholder syntax, and specifies the return JSON shape including truncation behavior. It even details presentation rules and warns against mentioning the tool name, all of which are valuable behavioral insights not captured by 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 long but exceptionally well-structured: it opens with a crisp purpose, then systematically covers usage context, safety restrictions, placeholder syntax, return format, and presentation rules. Every sentence earns its place given the tool's complexity and the number of constraints an agent must understand to invoke it correctly.

  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 description is fully complete for a tool of this complexity with an output schema. It covers accepted and refused operations, placeholder conventions, result truncation, and even output formatting for both rich and Markdown contexts. No ambiguity remains about how to select, invoke, or interpret the result of this tool.

  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 baseline is 3. The description reinforces the placeholder style ('use %s, not ?') and the params_json format, but these are already stated in the input schema. It adds no substantially new parameter-level semantics beyond what the schema already provides.

  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+resource ('Execute a read-only SQL query and return rows as JSON') and clearly distinguishes itself from siblings by targeting ad-hoc read queries with filtering, joining, aggregating, and questions the schema tools cannot answer. It also explicitly enumerates allowed statement types, leaving no ambiguity about its scope.

  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 provides explicit guidance on when to use this tool ('when the user wants to read data with SQL... or ad-hoc questions the schema tools cannot answer') and implicitly excludes write operations by listing refused statements. However, it does not name specific sibling alternatives (e.g., describe_table) as fallbacks, so the guidance is clear but not exhaustive.

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

• explain_queryA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses accepted input types, output JSON structure, and presentation constraints such as 'never mention this tool's name' and 'never paste raw JSON unless explicitly asked.' This adds substantial behavioral context 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.

  Conciseness5/5

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

  The description is well-structured: front-loaded purpose, then usage guidance, output structure, and presentation rules. Every section earns its place, and there is no filler or repetition of schema details.

  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?

  The description fully covers tool behavior: what it accepts, what it returns, how to present results, and formatting rules. With the readOnlyHint annotation and output schema present, this is complete for a read-only analysis 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?

  Schema covers all 4 parameters with descriptions (100% coverage), so baseline is 3. However, the description adds the critical constraint that sql must be a SELECT statement and not SHOW/DESCRIBE/EXPLAIN, which is not present in the schema. This adds meaningful parameter semantics.

  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 'Run EXPLAIN on a SELECT query and return the execution plan.' This is a specific verb+resource statement that distinguishes the tool from siblings (query, describe_table) by focusing on execution plans and explicitly restricting to SELECT statements.

  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?

  Explicitly states when to use: 'Use this tool when the user asks why a query is slow, whether an index is used, or how MySQL will execute a SELECT.' Also provides exclusions: 'Only SELECT statements are accepted (not SHOW/DESCRIBE/EXPLAIN).' This is clear guidance with context and alternatives.

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