Server Quality Checklist

Tool Scores

• db_backupA
  3.8/5.0
  Behavior1/5

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

  The description contradicts the annotations. It says the tool 'saves' backup files to a directory, which is a filesystem side effect, while readOnlyHint is true. It also calls the tool 'idempotent' while idempotentHint is false and the clarifying clause ('creates separate backup files') actually indicates non-idempotent behavior. Despite otherwise useful behavioral notes, the contradiction makes this dimension fail.

  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 organized into short sections: an opening summary, when to use, parameter guidance, behavioral notes, and return value. Every section adds practical information, and the key action is front-loaded.

  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 no output schema, the description covers prerequisites (pg_dump or Docker), fallback behavior, performance implications, return value, and automatic directory creation. It loses one point because the incorrect idempotence claim and readOnlyHint contradiction could mislead an agent about side effects.

  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 already provides 100% coverage for label, database, and confirmed. The description adds meaningful value beyond the schema by showing the exact filename format with a timestamp, giving a concrete 'pre-migration' example, and clarifying that confirmed is an explicit user confirmation gate.

  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: 'Creates a full SQL dump of the database using pg_dump and saves it to the configured backup directory.' It also clarifies that the backup includes the full schema and data, making it easy to distinguish from the db_* query and schema 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 'When to use' section lists concrete triggers: risky migrations, bulk operations, periodic maintenance, and explicit user requests to back up/export. It does not explicitly mention when not to use the tool, but there are no obvious backup sibling alternatives to exclude.

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

• db_use_databaseA
  3.9/5.0
  Behavior1/5

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

  The annotations declare readOnlyHint=true, but the description explicitly states the tool 'switches the default database' and affects subsequent tool calls—this is a session-state mutation, directly contradicting the read-only annotation. Because of this annotation contradiction, behavioral transparency must be scored 1 per rubric, despite the otherwise rich behavioral notes.

  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-organized with clear sections: main purpose, when to use, behavioral notes, and return value. Every sentence adds relevant information, and the most important behavior is front-loaded. No unnecessary repetition or filler 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?

  The description covers prerequisites (config listing), idempotency, lazy connection behavior, unreachable-database handling, session scoping, and return value. There is no output schema, but the return format is described. For a state-changing tool with one parameter, this is complete.

  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 single parameter 'database' is fully described in the schema, and the description adds meaningful constraints and behavior: the target must be listed in pgautopilot.json, is lazily connected on first use, and that unreachable targets lead to connection errors later. This exceeds the baseline expected with 100% schema coverage.

  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: 'Switches the default database for subsequent tool calls.' It clearly explains the scope and effect without ambiguity, and the tool is distinct from sibling tools like db_list_databases and db_table_info. This is a clear, actionable definition.

  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 'When to use' section provides explicit contexts, such as after db_list_databases or when switching between production and analytics databases. It does not explicitly name alternatives or state when not to use the tool, but the usage context is sufficiently clear to guide tool selection.

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

• db_overviewA
  4.4/5.0
  Behavior5/5

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

  With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds meaningful behavioral context: row counts are estimates from pg_stat rather than exact COUNT(*), only configured schemas are shown (default public), and safety metadata is included so the agent knows what operations are allowed. This goes well beyond the annotations and helps set accurate 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 well-organized with clear 'When to use' and 'Behavioral notes' sections, and it front-loads the core purpose. It earns its length, though there is minor redundancy: the first paragraph already says to use it as a first call, and the 'When to use' bullets restate similar scenarios.

  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 equips an agent to select and call the tool correctly: it explains what the overview contains, when to use it, how row counts behave, what schemas are visible, and what the return JSON includes. Since there is no output schema, the explicit 'Returns' statement is especially valuable and complete.

  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 covers the single optional parameter at 100%, describing it as 'Name of the database to query (from pgautopilot.json). Omit to use the current default database.' The description does not add parameter-level detail, so the schema carries the full burden; the 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 uses a specific verb ('Provides a high-level overview') and resource ('connected PostgreSQL database'), then enumerates exactly what the overview contains: tables, row counts, foreign keys, server mode, and safety rules. It also positions itself as the 'first call' when exploring an unfamiliar database, which clearly distinguishes it from more detailed sibling tools like db_schema or db_table_info.

  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 'When to use' section gives explicit trigger scenarios: start of a session, 'What's in this database?' questions, and before writing queries to confirm names and relationships. It provides clear context but does not explicitly name sibling tools to avoid, such as db_schema for detailed schema or db_table_info for per-table details.

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

• db_explainA
  4.5/5.0
  Behavior4/5

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

  The description adds substantial behavioral context beyond annotations: only SELECT is accepted, query has no persistent side effects, output includes execution plan JSON/cost/time/buffers/analysis, and no extensions are required. Minor imprecision: 'The query is NOT executed' is technically misleading for EXPLAIN ANALYZE, which executes internally to gather timing.

  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 longer than average but strictly organized into overview, when-to-use, parameter guidance, and behavioral notes. Every section carries necessary information, and there is no filler or redundancy beyond the minor execution phrasing.

  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 4-parameter tool with no output schema, this is complete: it covers invocation, parameter format, behavioral limits, result contents, analysis focus, and prerequisites. An agent has enough to decide when to call it and what to expect.

  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 already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value with a full example query, clarifies the effect of analyze/buffers defaults, and lists result components. The database parameter is not elaborated, but the schema covers it adequately.

  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 first sentence names a specific action ('Runs EXPLAIN ANALYZE') and resource ('SQL SELECT query'), and the rest specifies the output (execution plan, performance characteristics, bottlenecks). It is clearly differentiated from sibling row-returning tools (db_find_many, db_raw_query) by being explicitly about query plan analysis.

  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?

  A dedicated 'When to use' section lists four concrete scenarios, from 'Why is this query slow?' to 'Before creating indexes'. No explicit when-not-to-use or alternative tool names are given, so it stops short of a full 5.

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

• db_find_firstA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations: sensitive columns are automatically redacted, null is returned rather than an error, and the result is a single object. This is strong but not exhaustive—the meaning of 'first' row is not clarified with respect to ordering.

  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 for usage, parameters, and behavior, and it front-loads the core purpose. It is slightly repetitive—'use db_find_many instead' appears in both the opening and the behavioral notes—but this redundancy is minor and aids routing.

  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 return type, null behavior, sensitive column redaction, parameter guidance, and sibling differentiation, which is substantial given no output schema. The only notable omission is clarifying whether 'first' implies a defined ordering or is database-dependent, which could matter for exact-result expectations.

  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 75% schema coverage, the schema documents table, where, and database, but select lacks a description. The description compensates by explaining where as a JSON filter object with concrete examples, emphasizing specificity, and defining select as an optional JSON array of column names.

  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 plus resource: 'Finds a single row matching the given filter', and clearly distinguishes itself from db_find_many by emphasizing a single object rather than an array. It also states the null return case, making the tool's purpose 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 explicitly says to use this tool 'instead of db_find_many when you expect exactly one result' and provides concrete scenarios like unique identifier lookups. It also repeats the exclusion in the behavioral notes, so an agent has clear routing guidance.

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

• db_table_infoA
  4.5/5.0
  Behavior5/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds meaningful behavioral details beyond that: exact row count via COUNT(*) may be slow on large tables, typos produce clear errors with schema suggestions, and table size is approximate via pg_table_size(). This is exactly the kind of context an agent needs.

  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 a summary, 'When to use,' 'Behavioral notes,' and 'Returns' sections. Every sentence contributes concrete information, and the key purpose is front-loaded.

  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 no output schema, the description compensates by listing the exact returned fields (row_count, columns, indexes, foreign_keys, size_bytes). It also covers use cases, performance caveats, error behavior, and parameter guidance, making it complete enough for an agent to invoke 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?

  The input schema has 100% coverage with descriptions for both parameters, so the baseline is 3. The description adds little parameter-specific detail, but it doesn't need to; 'single table' reinforces the required table parameter and the return summary implicitly clarifies what the operation yields.

  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: 'Returns detailed information about a single table' and enumerates exact contents (row count, columns, indexes, foreign keys, size). It also distinguishes this tool from list-like siblings by emphasizing 'single table' and 'go beyond the overview.'

  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' bullets covering drill-down after db_overview, user questions, performance-sensitive query preparation, and debugging. It clearly explains the intended context, though it does not name a full set of alternatives or exclude cases where another sibling would be better.

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

• mcp_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces this by stating it 'never modifies anything' and is 'purely informational'. It also adds non-obvious behavior: returning actionable configuration fixes, handling multi-database mode, and disclosing exact return fields.

  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 front-loaded with the core purpose, then uses a compact 'When to use' list and a concise return-value summary. Each section adds new information without redundant filler.

  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 status tool with no output schema, the description fully covers invocation context, return shape, error behavior, and read-only guarantees. An agent has everything needed to select and interpret this 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?

  The tool has zero parameters, so the input schema carries no burden and the baseline is 4. The description still adds value by naming the return fields status, database, mode, and readonly, which compensates for the lack of an output 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 reports MCP server readiness, the connected database, and configuration mode. It explicitly frames this as server-level health/configuration status, which distinguishes it from database-specific siblings like db_health and db_overview.

  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 scenarios for when to use the tool: at session start, after connection errors, or when asked about server configuration. It does not explicitly say when not to use it or name alternative tools, so it stops just short of full exclusionary guidance.

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

• db_createA
  4.6/5.0
  Behavior5/5

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

  Even with annotations present, the description adds substantial behavioral detail: schema validation, sensitive-column stripping, transactional rollback on constraint violations, dry-run semantics, and the return value including auto-generated fields. These are meaningful behaviors not visible in the annotations or schema.

  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 into clear sections and front-loads the core purpose. It is somewhat long and repeats the schema-validation point twice, but the structure and examples make the information easy to consume.

  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 having no output schema, the description explains what the tool returns on success, how dry_run behaves, and what validation or rollback guarantees exist. It is complete enough for an agent to call this tool correctly without opening the schema, and the database parameter is already covered in the input schema.

  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%, so the schema already documents all parameters. The description adds a concrete data example and clarifies dry_run behavior, which is helpful. However, it refers to the parameter as dry_run while the schema defines dryRun, and it does not mention the database parameter at all, creating a minor invocation risk.

  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: 'Inserts a new row into the specified table.' It clearly differentiates this from sibling tools by framing it as the single-row INSERT operation and even contrasts it with db_raw_query for multiple inserts.

  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 'When to use' examples and gives a clear routing rule: for multiple inserts, call this tool once per row or use db_raw_query with confirmed=true. This tells an agent exactly when this tool is appropriate and when an alternative is better.

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

• db_healthA
  4.6/5.0
  Behavior5/5

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

  The description discloses single- versus multi-database behavior, empty replication results on standalone instances, idle/active connection semantics, the >80% pool-utilization guidance, and which system tables are queried. These details go far beyond the annotations' readOnly/idempotent hints and give the agent accurate 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 organized into clear sections, front-loads the primary purpose, and uses bullets for usage guidance. It is longer than average, but every section carries distinct operational information for a complex diagnostic tool, so the length is earned.

  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?

  Even without an output schema, the description enumerates the exact returned fields (connected, pool stats, uptime, total requests, database summary, and each health check) and covers edge cases such as standalone instances and mode differences. An agent has enough context to invoke the tool correctly and interpret its result.

  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 100% and the schema already explains the database parameter and its default. The description adds multi-database mode behavior ('omit the database parameter to see health status for all configured databases simultaneously') and clarifies the parameter's source, which is meaningful context 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 opens with a specific verb and resource: 'Checks database connectivity, connection pool statistics, server uptime, and total request count' and then targets specific PostgreSQL system checks. This clearly distinguishes db_health from siblings like db_overview or mcp_status by naming concrete metrics rather than a generic health phrase.

  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?

  A dedicated 'When to use' section lists clear trigger scenarios: session startup, connection-health queries, slow-response troubleshooting, periodic pool checks, and production vacuum/replication checks. It does not explicitly name sibling tools to exclude, so it stops short of a 5, but the context is unambiguous.

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

• db_list_databasesA
  4.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond those: the single-database mode fallback message, how failed connections appear, and the lazy connection behavior on first use. It does not contradict 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 organized with the core function first, followed by usage guidance and return details. It is longer than strictly necessary but every sentence adds useful information, such as status values and lazy connection behavior, rather than repeating schema or annotation data.

  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?

  There is no output schema, so the description correctly compensates by specifying the array shape and its fields. It also covers edge behavior (single-database mode, failed startup connections) and practical usage context. For a parameterless discovery tool, nothing important 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 and the input schema confirms this, so the baseline is 4. The description correctly avoids inventing parameter semantics and instead explains what the returned entries contain, which is appropriate for a parameterless tool.

  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?

  States a clear verb ('Lists') and specific resource ('databases configured in pgautopilot.json'), and specifies exactly what fields are shown, including connection status, host, port, schema, and read-only setting. It also differentiates the tool's purpose by noting it is meaningful only in multi-database mode.

  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?

  Provides explicit 'When to use' guidance with three concrete scenarios, positions it as a precursor to db_use_database, and notes when it is not meaningful (single-database mode). This is strong routing guidance relative to alternatives.

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

• db_schemaA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds non-redundant behavioral context: live introspection from information_schema, no caching to catch DDL changes, PG_SCHEMAS filtering with public default, and the relationship diagram's use for JOIN queries. No statement contradicts the 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?

  Well-structured with a front-loaded summary, explicit use cases, behavioral notes, and a return-shape section. There is minor redundancy between 'introspected live from PostgreSQL's information_schema' and 'fetched fresh on every call (not cached)', and the Returns paragraph partly repeats the opening sentence, so it is not a perfect 5.

  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?

  Even with no output schema, the Returns paragraph specifies the JSON shape (tables with columns, type, nullable, default, constraints, indexes, relationships array). Behavioral notes cover freshness and schema scope, and the one optional parameter is fully described in the schema, so nothing essential is missing for correct 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 single optional `database` parameter is fully documented in the input schema (100% coverage), so the baseline is 3. The description does not add parameter-specific details beyond the schema, which is acceptable given the schema already explains the parameter's meaning and default behavior.

  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?

  States a specific verb and resource: 'Returns the full database schema with column-level detail' and enumerates exact contents (columns, data types, nullability, defaults, constraints, indexes, foreign keys). It explicitly contrasts with db_overview ('beyond what db_overview provides'), making sibling differentiation clear.

  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?

  Provides a dedicated 'When to use' list with concrete triggers: needing column-level detail, verifying column names/types before constructing queries, answering structure/constraint/relationship questions, and debugging type/constraint errors. It names db_overview as the alternative and the condition that selects this tool, giving an agent clear routing guidance.

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

• db_upsertA
  4.6/5.0
  Behavior5/5

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

  The description adds substantial behavioral detail beyond the annotations: it explains the conflict-target constraint, the validation against schema constraints, the exact behavior when a match exists versus not, the return of the final row, and dry-run usage. This meaningfully informs an agent about side effects and safety.

  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 and front-loaded mechanics. It is somewhat lengthy and repeats the dry-run and ON CONFLICT concepts, but the extra detail is mostly purposeful and improves usability.

  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 mutating tool with no output schema, this description is complete: it defines required parameters, conflict resolution, optional update behavior, dry-run preview, validation failure, returned value, and idempotency. Nothing critical to calling the tool correctly 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?

  Schema description coverage is 100%, so the baseline is 3. The description adds rich guidance for table, where, create, update, and dry_run, including examples and conflict semantics. However, it refers to 'dry_run' while the schema property is 'dryRun', a naming mismatch that could confuse an agent.

  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: 'Inserts a new row or updates an existing one using PostgreSQL's ON CONFLICT mechanism.' This specific verb-plus-resource framing distinguishes it from sibling tools like db_create and db_update_many.

  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 'When to use' section provides concrete examples and identifies idempotent insert-or-update operations as the target scenario. It does not explicitly state when not to use the tool or name alternatives, so it stops short of full exclusion guidance.

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

• db_aggregateA
  4.7/5.0
  Behavior5/5

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

  Annotations only signal read-only, idempotent, non-destructive. The description adds genuinely useful behavior: read-only transaction with configurable timeout, default sorting by the aggregate, zero-row groups being excluded, and return shape as an array of group objects. This goes well beyond annotation data.

  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 organized into purpose, usage, parameter guidance, and behavioral notes; every sentence adds operational value. It is longer than one-liner tools but justified by 10 parameters and no output schema.

  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 10-parameter tool with no output schema, the description covers selection, invocation patterns, parameter semantics, ordering, limits, filtering, and return behavior. Count semantics are slightly implicit since there is no count input parameter, but the orderBy guidance and examples treat count as a returned aggregate key, so the description remains complete enough for correct 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 coverage is 100%, so the baseline is 3, but the description adds practical parameter meaning: comma-separated syntax for by, JSON shape with '_count'/'_sum' keys for orderBy, where being applied before grouping, and take's default. It does not enrich the table/database parameters, so not a 5.

  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 action—'Groups rows by ... and computes aggregate functions'—and names the exact resource pattern. It also says 'This is the tool for analytical queries' and gives concrete query examples, making it easy to distinguish from row-retrieval siblings like db_find_many or db_count.

  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?

  There is an explicit 'When to use' section with four query-pattern examples that map user intents to parameters. It does not name sibling tools or state when not to use it (e.g., for unaggregated rows use db_find_many), so it stops just short of full exclusion guidance.

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

• db_delete_manyA
  4.7/5.0
  Behavior5/5

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

  Even though annotations already mark destructiveHint=true, the description adds crucial behavior: irreversibility without backup, the confirmAll safety gate, warning on >10 rows, atomic transaction behavior, returned deleted count, and the strong recommendation to dry-run first. This goes well beyond the annotations and gives an agent a full risk profile.

  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 organized into clear sections: overview, when to use, parameter guidance, and behavioral notes. Some safety guidance is repeated, but for a destructive tool that repetition reinforces the most critical behavior without becoming bloated.

  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 covers the full calling context: when to use, how to use safely, what counts as dangerous, the transaction guarantee, and the return value. Since there is no output schema, the statement that it returns the count of deleted rows is especially valuable and completes the picture.

  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?

  Schema coverage is 100%, but the description adds important semantic weight: where is a JSON filter with a concrete example, '{}' is explicitly labeled dangerous and requires confirmAll=true, dryRun is strongly recommended as a preview mechanism, and confirmAll's purpose is explained. This materially helps an agent invoke parameters correctly.

  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: 'Deletes all rows matching the given filter.' It clearly distinguishes this as a destructive bulk deletion tool, and the examples and safety gate make its scope unambiguous relative to siblings like db_update_many or db_find_many.

  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 'When to use' section provides concrete, realistic scenarios and explicitly warns about the empty-filter case and the confirmAll requirement. It does not explicitly contrast with alternatives such as db_update_many, but the guidance is clear enough for an agent to decide when deletion is appropriate.

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

• db_update_manyA
  4.7/5.0
  Behavior5/5

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

  Even with annotations already marking destructiveHint=true and readOnlyHint=false, the description goes well beyond: it explains live-schema validation, the empty-filter safety gate requiring confirmAll, the >10-row warning, atomic transaction behavior, dry_run previewing, and the affected-row count. No contradiction with 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 structured into clear sections—overview, when to use, parameter guidance, and behavioral notes—and every sentence conveys necessary operational detail. For a dangerous data-mutating tool, the length is justified and well-organized.

  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 no output schema, the description covers return value (affected row count), error behavior (empty filter without confirmAll), safety mechanisms, and transaction semantics. It gives an agent all the information needed to invoke the tool correctly, including the required safety flag for full-table updates.

  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 100%, so the baseline is 3, but the description adds concrete examples for 'where' and 'data', clarifies the dangerous '{}' case, and explains when confirmAll is required. The only drawback is the parameter naming discrepancy: description says 'dry_run' while the schema defines 'dryRun', which could mislead an agent.

  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: 'Updates all rows matching the given filter.' It clearly distinguishes itself from siblings like db_delete_many, db_find_many, and db_create. The title 'Update Rows' is expanded meaningfully by the first sentence and the safety-focused details.

  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 'When to use' section gives concrete, realistic examples ('Mark all pending orders as shipped', 'Update user 42's email...') that make selection intent clear. However, it does not explicitly mention when NOT to use this tool or contrast it with alternatives like db_upsert or db_create, so it misses the top tier.

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

• db_find_manyA
  4.8/5.0
  Behavior5/5

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

  Annotations already mark this read-only and idempotent, and the description adds meaningful behavior beyond them: automatic redaction of sensitive columns, read-only transaction timeout, live schema validation, pagination metadata, and error messages. No statement contradicts the 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 organized into clear sections: summary, when-to-use examples, parameter guidance, and behavioral notes. It is long but every section adds operational value; no filler or repetition of the schema 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?

  For a 7-parameter read tool with no output schema, the description covers invocation, parameter semantics, defaults, limits, security behavior, and error handling. The only minor omission is explicit routing to sibling tools, but the usage examples make the tool's scope sufficiently clear.

  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?

  Schema coverage is 100%, but the description goes well beyond it by documenting where operators (eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn), providing concrete JSON examples for where/select/orderBy, and stating take default/max. The database parameter is only in the schema, but the schema description 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 first sentence states a specific verb ('Queries rows') and resource ('from a table') and enumerates capabilities: filtering, column selection, sorting, and pagination. The phrase 'primary tool for reading data' helps distinguish it from sibling read tools, and the title 'Find Many Rows' reinforces the many-row semantics.

  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 'When to use' section lists concrete natural-language triggers and explicitly says any read query needing filtering, sorting, or pagination. It does not explicitly name alternatives or exclusions (e.g., use db_find_first for a single row), so guidance is clear but not fully contrastive.

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

• db_countA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses that the tool runs exact COUNT(*) queries, may be slow on millions of rows, and returns an integer rather than a row object. This adds meaningful behavioral context that annotations alone do not provide.

  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-organized with clear sections, front-loaded core behavior, and no redundancy. Every sentence contributes guidance: exactness, use cases, parameter guidance, and performance caveats.

  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 three parameters, no output schema, and the need to differentiate from many sibling tools, this description is complete. It covers return type, performance trade-offs, filtering syntax, helpful examples, and when to choose an alternative.

  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 100%, providing a baseline of 3, but the description adds value by clarifying table is required, explaining the where parameter uses the same syntax as db_find_many, and noting the result type. This goes beyond the basic 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 states a specific verb and resource: 'Returns the exact number of rows in a table, optionally filtered.' It explicitly contrasts with an estimate ('exact COUNT(*) query — not an estimate') and helps distinguish itself from siblings like db_aggregate and db_find_many.

  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 gives concrete when-to-use examples ('How many users signed up this week?', 'Count all orders with status pending') and explicitly recommends an alternative tool for large tables ('consider using db_aggregate'). It also references db_find_many's syntax, giving clear routing among siblings.

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

• db_raw_queryA
  4.9/5.0
  Behavior5/5

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

  The description goes far beyond the annotations by disclosing the read-only transaction, timeout default, mandatory LIMIT enforcement, single-statement restriction, blocked dangerous functions, 5000-row cap, and column redaction. It is consistent with readOnlyHint=true and destructiveHint=false. One caveat: the schema's sql/confirmed descriptions imply non-SELECT writes are possible, which conflicts with this description; however, the description itself is transparent and aligned with the 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 longer than average, but the length is justified for a raw SQL tool with safety implications. It is well-structured with clear sections. A small redundancy exists between the intro's list of complex query types and the 'When to use' bullets, but the overall organization makes it easy to scan.

  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, no-output-schema tool, the description covers essentially everything an agent needs: what queries are allowed, safety constraints, timeouts, result caps, redaction, and where to route write operations. The absence of an output schema is mitigated by describing result limitations and redaction.

  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?

  Schema coverage is 100%, and the description adds meaningful guidance beyond it: a complete SQL example, the mandatory LIMIT rule, and clarification that confirmed is currently informational. The database parameter is adequately covered by the schema, so no further description is needed.

  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 the specific verb ('Executes'), the resource ('raw SQL SELECT statement'), and the defining constraint ('mandatory LIMIT clause'). It also clearly frames the tool as an 'escape hatch' for queries that structured tools cannot express, distinguishing it from siblings like db_find_many and db_aggregate.

  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 'When to use' section explicitly lists complex JOINs, CTEs, window functions, subqueries, and custom aggregations. It also provides clear exclusions: write operations should use structured tools like db_create and db_update_many. This gives an agent concrete routing criteria.

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