Server Quality Checklist

Tool Scores

• list_objectsA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool returns approximate row counts (not exact), mentions it is 'Cheap' (a performance trait), and lists the scope of object types covered. It doesn't discuss permission requirements or error behavior, but the 'Cheap' and approximate-count disclosures are genuinely useful behavioral context beyond 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?

  Three sentences, each adding value: scope+behavior, filtering instructions with example, and sibling differentiation. The front-loaded first sentence is information-dense. Minor deduction for somewhat technical phrasing ('a SQL LIKE name_pattern') that could be more direct, but it's economical and well-organized.

  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 tool has an output schema (so return values are covered there) and 3 params with 0% schema coverage, but the description documents the main semantics of the two filter params and the scoping behavior. It's complete enough for an agent to select and call correctly. Minor gaps: no mention of whether schema must exist, ordering of results, or pagination/limits, but the 'Cheap' note and existing structure make this adequate.

  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 0%, so the description must compensate. The description explains the semantics of object_type (filter by type, with allowed values implied by the sibling mention of table/view/etc.) and name_pattern (SQL LIKE pattern, with example 'order%'). However, the 'schema' parameter is never described beyond being the target namespace, and the anyOf/null structure isn't fully clarified. The description adds meaningful value but doesn't fully cover all 3 params.

  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 specific verbs and enumerates the exact resource types (tables, views, materialized views, sequences, foreign tables) in a schema. It clearly distinguishes from siblings by mentioning the full shape of a single relation belongs to describe_object, and the general-purpose execute_query is implied as an alternative for arbitrary queries.

  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 explicit guidance on when to use this tool vs describe_object ('Prefer describe_object for the full shape of a single relation'), provides filtering examples with object_type and SQL LIKE name_pattern ('order%'), and notes it is 'Cheap' so agents know it's safe to call. The when/when-not guidance is explicit and actionable.

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

• server_infoA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the tool is read-only-ish ('Report'), 'Cheap' (low cost/low latency expectation), and non-destructive in nature, which is appropriate for what appears to be a diagnostic read operation. The 'Cheap' disclosure is behavioral context beyond what schema conveys. It doesn't mention error conditions or response shape, but the output schema exists to cover that.

  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?

  Three sentences, all earning their place: the first enumerates the reported fields, the second notes the cost profile, the third gives usage guidance. Slightly dense opening sentence but efficient overall. No filler or redundancy.

  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 zero-parameter, zero-tool diagnostic with a rich output schema present, the description is complete: it enumerates what will be returned, signals cost, and gives usage intent. The output schema covers return structure. The only minor gap is that it doesn't explicitly note this is read-only/safe, but the verb 'Report' and 'Cheap' reasonably imply 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 tool has zero parameters, so the baseline is 4 per the rubric. Schema coverage is 100% and there is nothing to document param-wise. The description adds all necessary context about what is reported without needing any parameter explanation.

  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 ('Report') with a clear resource (server info) and enumerates the exact content items: version, role, database, access mode, timeouts, search_path, recovery state. It clearly distinguishes itself from siblings like list_schemas/list_objects/list_extensions by focusing on server-level metadata, and uses the qualifier 'Cheap' to differentiate cost profile.

  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 it: 'Useful for orientation and for diagnosing permission or timeout surprises.' It doesn't explicitly name alternatives or when-not-to-use, but the 'orientation' framing plus 'Cheap' cost note effectively guides an agent toward this for quick diagnostics over heavier query tools. A clear exclusions list would push this to 5.

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

• execute_queryA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses key behaviors: read-only nature, single-statement enforcement, result capping with truncation notices, no injected LIMIT, and cost dependency on the query. It doesn't mention permission requirements or what happens on SQL errors, but covers the significant behavioral traits well.

  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?

  Compact multi-line description with zero wasted words. Front-loaded with the core action, then the return contract, then params usage, then the truncation/cost caveats. Every sentence earns its place — no filler or repetition of schema fields.

  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 an output schema present and several behavioral nuances, the description is thorough. It covers the single-statement constraint, placeholder usage, truncation semantics, and cost guidance. It's slightly shy of complete — could mention error handling and permissions — but given the complexity and the presence of an output schema, this is well covered.

  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 0% and there are 2 params with an empty schema (sql and params have no descriptions). The description compensates well: it explains the %s placeholder mechanism for params and the placeholder-binding pattern. It doesn't detail param type constraints beyond 'user-supplied values', but adds meaningful semantics to an otherwise bare 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?

  Description states a specific verb+resource: 'Run a single read-only SQL statement' and explicitly frames it as READ ONLY within a transaction. It specifies the return shape ({columns, rows, row_count, truncated, notice?}) and distinguishes itself by requiring 'Exactly one statement per call' — differentiating from siblings like describe_object and list_objects.

  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 gives strong usage context: how to use %s placeholders with params, that results are capped with truncation notice, and that no LIMIT is injected. It explicitly says to 'run explain_query first for anything potentially expensive', which advises on when to use a sibling tool. It could add explicit when-not-to-use conditions but the guidance is substantive.

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

• describe_objectA
  4.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the operation is cheap/read-only, that row counts are approximate (from reltuples, not exact), and enumerates the full scope of what's returned. This is strong transparency for an introspection tool with zero annotation support.

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

  Conciseness5/5

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

  Three sentences, all high-value: what it returns, cost signal, and when to use. Front-loaded with the core purpose, no wasted words.

  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 an output schema (covering return values), so the description need not enumerate the response format. The tool is simple (2 params, no nesting) and the description fully covers behavioral caveats (approximate count, cheap) and usage context. Nothing substantive is missing.

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

  Parameters3/5

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

  Schema coverage is 0% for two trivial parameters (schema, name). The description explains what the tool does but doesn't elaborate on the parameters themselves beyond what's obvious from their names and types. However, for introspection tools, schema and name are self-evident; the baseline 3 is acceptable since the description doesn't add semantics the names don't already convey.

  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?

  Specific verb+resource: 'Describe one relation' followed by an exhaustive enumeration of what it returns (columns, PK, FKs both directions, indexes, constraints, row count). Clearly distinguishes from siblings like execute_query and list_objects by being a dedicated introspection tool.

  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 guidance: 'Prefer this over querying catalogs by hand; use it before writing queries against unfamiliar tables.' Also notes cheapness ('Cheap'), giving clear cost-based rationale for use. Mentions pg_class.reltuples for approximate counts, setting expectations.

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

• explain_queryA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full burden and excels at it. It transparently discloses that analyze=true actually executes the statement, that the transaction always rolls back, and that despite rollback the runtime cost is incurred. This is exactly the kind of behavioral nuance an agent needs to make safe decisions about using analyze mode.

  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 three sentences, front-loaded with the core purpose, and every sentence adds value. It's compact but covers the essential caveats. Minor inefficiency: 'for a single statement' is slightly redundant with EXPLAIN semantics, but this is a minor nit.

  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 annotations and 0% schema coverage, the description thoroughly covers the critical safety context (transaction rollback, real execution cost), parameter constraints (inline literals only), and purpose. With an output schema present and only 2 simple parameters, this description is fully adequate for safe and correct tool 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?

  Schema coverage is 0%, so description must compensate. The description explains the analyze parameter's semantics well (executes for real timing, rolls back, costs runtime) and notes sql takes inline literals not parameters. However, it doesn't detail the sql parameter's format expectations beyond that, leaving the agent to infer SQL syntax requirements.

  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 returns a PostgreSQL EXPLAIN execution plan in JSON format for a single statement. It distinguishes itself from execute_query (which actually runs queries) by emphasizing this is EXPLAIN only, and the verb+resource ('Return the PostgreSQL execution plan') is specific and accurate.

  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 explains when to use analyze=true vs false, notes that parameters are not supported (inline literals required), and clarifies the transactional rollback behavior. This gives clear guidance on how to invoke the tool correctly, particularly the important caveat that runtime cost is 'fully paid' even though the transaction rolls back.

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

• list_extensionsA
  4.7/5.0
  Behavior4/5

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

  No annotations provided, so the description carries the disclosure burden. It signals the tool is 'Cheap' (low cost), disclosing performance characteristics. The read-only nature is implicit from 'list installed and available extensions.' It doesn't describe the output format, but with an output schema present and a 0-param read operation, the behavioral disclosure is adequate.

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

  Conciseness5/5

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

  Three sentences, zero waste. The first sentence states purpose and contents, the second notes cost, the third gives a concrete usage scenario. Every sentence earns its place and the actionable guidance is front-loaded and clear.

  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 0-parameter introspection tool with an output schema present, the description is complete. It explains what data is returned (versions, descriptions), notes cost, and gives a practical use case. No missing prerequisites, parameters, or behavioral caveats are relevant here.

  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 0 parameters, so there is nothing to document. Schema coverage is 100% (trivially). The baseline for 0-param tools is 4, and the description doesn't need to add parameter semantics since none exist. The examples enumerate extensions it will surface, adding semantic color beyond the empty 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?

  Specific verb+resource (list extensions) with clear scope: 'installed and available PostgreSQL extensions with versions and descriptions.' The examples (pg_stat_statements, postgis, hypopg) and the phrase 'Cheap' add useful distinctiveness. It's clearly differentiated from sibling list_schemas/list_objects.

  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?

  Explicit guidance on when to use: 'Check here whether an extension exists before writing queries that depend on it.' This is a clear usage directive with a concrete scenario. Though it doesn't name alternatives, the purpose (introspection-check before query) is unambiguous for a 0-param read tool.

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

• list_schemasA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the operation is 'Cheap' (performance characteristic) and that output respects an allowlist filter. These are genuinely useful behavioral traits beyond what schema/annotations convey.

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

  Conciseness5/5

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

  Three sentences, zero wasted words. The description front-loads the core purpose, adds the allowlist behavioral note, flags cost ('Cheap'), and ends with actionable next-step guidance. Every sentence earns its place.

  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 listing tool with an output schema present, the description is fully complete. It declares purpose, scoping behavior, cost profile, and the follow-up tool to use. The output schema handles return-value documentation, so nothing critical 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 schema coverage is 100% (trivially, since there are no params to document). The baseline for 0-param tools is 4, and the description appropriately adds no parameter noise while providing purpose context that helps the agent understand what the (empty) invocation will return.

  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+resource ('List database schemas visible to this server') with precise scope ('honoring the configured schema allowlist'). It clearly distinguishes from siblings by pointing to list_objects as the tool for looking inside a schema, positioning list_schemas as the top-level listing operation.

  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?

  Explicit guidance is provided: 'Call this first to see what exists; then use list_objects to look inside a schema.' This tells the agent when to invoke it (as an entry point) and directs to the appropriate alternative (list_objects) for the next step.

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