Server Quality Checklist

Tool Scores

• pg_list_tablesA
  3.9/5.0
  Behavior5/5

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

  The description adds valuable behavioral detail beyond the annotations: it specifies the returned fields, explains the meaning of null and 0 row counts across PostgreSQL versions, and notes the reltuples source. This is rich context that helps an agent interpret results correctly.

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

  Conciseness5/5

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

  The description is compact and front-loaded: purpose first, return semantics second, pagination last. Every sentence adds distinct value, with no fluff or repetition of schema fields.

  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 read-only listing tool with rich annotations and an output schema, this description is complete. It covers the tool's scope, return fields, important version-dependent caveats, and pagination. No critical information needed to call it correctly is missing.

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

  Parameters3/5

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

  Schema coverage is 100%, so parameters are already well documented. The description adds marginal semantic value by tying 'optionally views' to includeViews and mentioning pagination, but it does not substantially expand on the parameter meanings provided by the schema.

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

  Purpose4/5

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

  The description clearly states the tool 'List tables (and optionally views) in a schema' with a specific verb and resource. It does not explicitly differentiate this from sibling tools like pg_list_views or pg_list_schemas, but the name and description make the core 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 Guidelines2/5

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

  There is no guidance on when to choose this tool over siblings such as pg_list_views or pg_describe_table. The only usage-related hint is pagination for large schemas, which addresses how to page results, not when to select this tool versus alternatives.

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

• pg_list_extensionsA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the return column names (name, version, schema, description), which is useful, but it does not add meaningful behavioral context beyond what the annotations and output schema already imply.

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

  Conciseness5/5

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

  The description is compact and front-loaded with the core action, followed by relevant return fields and a concrete use case. Each sentence earns its place, and the concrete extension examples add practical value without bloat.

  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, parameterless, read-only introspection tool with rich annotations and an output schema, the description is complete. It explains what the tool lists, what it returns, and why an agent would use it, leaving no obvious gap 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?

  The tool takes zero parameters and the schema has no properties, so there is no parameter semantics risk for the agent. Per the rubric, a zero-parameter tool receives a baseline of 4; no additional parameter documentation is needed.

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

  Purpose4/5

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

  The description states a clear verb and resource: 'List installed PostgreSQL extensions.' It also mentions the returned fields, making the tool's purpose unmistakable. However, it does not explicitly contrast itself against the many sibling list_* tools, so sibling differentiation relies on the object type rather than direct comparison.

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

  Usage Guidelines4/5

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

  The description gives a concrete use case: checking for extensions like pgvector, postgis, pg_stat_statements, and uuid-ossp before writing dependent queries. This provides clear context for when to invoke the tool, though it does not state when not to use it or mention any alternative tool.

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

• pg_list_rolesA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful content detail (attributes and inherited memberships) and notes it reads pg_authid indirectly, but does not disclose auth requirements, error behavior, or other operational traits.

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

  Conciseness5/5

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

  Two focused sentences: the first states exactly what is listed, the second gives the motivating use case. No filler or restatement of the title.

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

  Completeness4/5

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

  For a one-optional-parameter listing tool with annotations and an output schema, the description is nearly complete. It could marginally strengthen the 'access' framing by noting that this returns role-level principals rather than object-level privileges, but the core information is sufficient.

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

  Parameters3/5

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

  Schema coverage is 100%: the includeSystem parameter already has a clear description in the schema. The main description does not discuss parameters, so it adds no meaning beyond the schema, matching the baseline.

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

  Purpose5/5

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

  Opens with a specific verb and direct object: 'List database roles (users and groups)' and enumerates the exact attributes returned. The mention of answering 'who has access to this database?' and avoiding pg_authid clearly frames what this tool is for and separates it from table/view/function inspection siblings.

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

  Usage Guidelines4/5

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

  The description gives a concrete use case ('Use this to answer "who has access to this database?"') but does not explicitly state when not to use it or name an alternative sibling. It is clear context without exclusionary guidance.

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

• pg_healthA
  4.3/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior (_warnings and null fields), cumulative counter semantics, state_unavailable under-counting implications, NULL wait events for running backends, and version-dependent wait_event spelling. This goes far beyond what the annotations or schema 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?

  The description is long but every section earns its place: a front-loaded summary, then structured bullets that clarify connections, active_queries, and database_stats with actionable diagnostic guidance. There is no filler or redundancy.

  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 this complex, the description covers output semantics, edge cases, permission-gated failures, and interpretation pitfalls such as under-counted active connections and cumulative stats. The existing output schema can handle the return structure, and nothing essential for correct invocation or interpretation 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?

  The schema already documents activeQueryLimit with default, min, max, and a description (100% coverage). The tool description does not add parameter-specific context beyond mentioning active queries generally, so the schema carries the load and the baseline of 3 is appropriate.

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

  Purpose4/5

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

  The description names a specific resource ('Database health snapshot') and lists concrete components: server version, database size, connection counts, active queries with wait events, pg_stat_database rollup, and table count. It clearly identifies what the tool produces, though it does not explicitly distinguish itself from specialized sibling tools like pg_io_stats or pg_top_queries.

  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 clear use cases: 'connection sanity check' and detecting runaway queries, connection-cap pressure, and lock/IO waits. It gives strong context for when to invoke the tool but does not mention alternatives or exclusion criteria relative to sibling tools.

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

• pg_list_functionsA
  4.3/5.0
  Behavior4/5

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

  Annotations already establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral detail by specifying exactly what is returned: name, arguments, return type, kind, and implementation language. It does not mention ordering or error behavior, but that is not essential for a simple listing tool with an output schema.

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

  Conciseness5/5

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

  The description is a single sentence that front-loads the action and resource before enumerating return fields. There is no filler, redundant restatement, or unnecessary detail. Every part of the 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 simple listing tool, the combination of a complete parameter schema, a full output schema, and safety-relevant annotations means nothing critical is missing. The description adds the remaining contextual detail by naming the output fields. An agent can invoke this tool correctly without further information.

  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 fully documents the single optional 'schema' parameter, including its default and meaning. The description adds little beyond reaffirming the schema scope, so it does not substantially improve on what the schema already provides. This matches the baseline for high schema description 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 uses a specific verb ('List'), identifies a concrete resource ('functions, procedures, and aggregates'), and scopes that resource to a schema. This clearly distinguishes it from sibling list tools such as pg_list_tables and pg_list_views. An agent can immediately understand what this tool operates on.

  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 are no explicit 'when to use' or 'when not to use' instructions, and no alternative tools are named. However, the description makes the usage context clear: it is for listing function-like objects within a schema, which is distinct from the other list tools. The context is clear enough even without explicit exclusions.

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

• pg_list_viewsA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context about returning SQL definitions and covering materialized views, but does not deeply describe output behavior; the output schema exists to fill that gap.

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

  Conciseness5/5

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

  Two sentences with no filler. The core functionality is stated first, followed by a precise differentiation from a sibling tool.

  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 tool is simple, has only two optional parameters fully described in the schema, carries read-only annotations, and has an output schema. The description supplies the missing usage context, so nothing an agent needs to call it correctly is absent.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents both parameters. The description adds no new meaning beyond associating views with a schema and mentioning materialized views, which aligns with the existing parameter 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 ('List') and resource ('views and materialized views in a schema'), and clarifies that SQL definitions are included. It also distinguishes itself from the sibling `pg_list_tables` with `includeViews: true`, making its 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 tells the agent when to prefer this tool over `pg_list_tables` with `includeViews: true`: when the view body is needed, not just names. This provides clear selection logic among sibling tools.

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

• pg_io_statsA
  4.4/5.0
  Behavior5/5

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

  The description goes far beyond the readOnly/idempotent hints: it explains NULL vs 0 semantics, the meaning of 0 timing values with non-zero counts, cumulative counters and stats_reset, absent keys vs empty arrays on PG18, omitted zero rows, per-query sub-failures appending to _warnings, and permission gating. 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.

  Conciseness4/5

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

  The description is long, but nearly every clause carries a non-obvious behavioral detail that is essential for correct interpretation (e.g., absent vs empty keys, timing=0 caveat, zero-row omission). It is structured with bullets between focused sections and front-loads the overall purpose before the 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?

  For a high-complexity PostgreSQL observability tool with an output schema available, the description covers version requirements, permission-gated failures, counter semantics, reset interpretation, zero-row filtering, and in-flight I/O caveats. An agent has enough information to call it correctly and interpret the result.

  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% and both parameters are already documented with defaults and meaning. The description reinforces includeZeroRows and limit, but it adds little that is not already in the input schema; the baseline of 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 'I/O observability' and precisely defines the resource: cumulative per-backend-type I/O from pg_stat_io plus in-flight async I/O from pg_aios. It also differentiates itself from siblings by calling itself 'the layer underneath pg_top_queries and pg_health' and noting that per-query or per-table views cannot show the subsystem/path involved.

  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 tells the agent when this tool is appropriate: when the question is which subsystem (client backends vs autovacuum vs checkpointer) and which I/O path is responsible, as opposed to per-query or per-table views. It also states required PostgreSQL versions and the includeZeroRows behavior for quiet systems, though it does not give explicit 'when not to use' alternatives beyond the sibling references.

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

• pg_table_privilegesA
  4.4/5.0
  Behavior5/5

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

  Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read. The description adds crucial behavioral context beyond annotations: the tool is backed by information_schema.table_privileges, which postgres filters by the calling role's visibility, and a least-privileged role may miss grants. It also specifies ordering (by table then grantee) and the behavior when `table` is omitted. This is exactly the kind of behavioral disclosure that annotations alone cannot convey.

  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 roughly four sentences, each carrying meaningful content: purpose, omission behavior, usage scenarios, and the visibility caveat with a recommendation. It is front-loaded with the core purpose and stays information-dense without wordiness. It could be slightly tighter (e.g., merging the usage and caveat sentences), but it is still well-structured and earns its length.

  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 read-only tool with two optional parameters and an output schema present, the description covers all essential invocation context: what happens with and without `table`, the schema default, the visibility limitation, and how to get complete results. Since an output schema exists, the lack of a return-format explanation is not a gap. Nothing an agent needs in order to call this correctly or interpret the scope is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both `table` and `schema` having descriptions. The description rephrases the omission behavior already present in the schema ('Omit to list privileges for all tables in the schema'), so it adds no new parameter-specific meaning. The only extra value is the ordering detail (by table then grantee), which is output behavior rather than parameter semantics. Thus 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 clearly states the verb/resource (shows roles and their privileges) and enumerates the specific privilege types (SELECT, INSERT, etc.). It distinguishes itself from sibling tools (e.g., pg_list_tables, pg_describe_table) by focusing exclusively on privilege grants. It also provides a concrete use question ('who can write to this table?'), which removes any ambiguity about the tool's intent.

  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 explicitly identifies when to use this tool: to answer 'who can write to this table?' or to audit schema-wide access before a migration. It also advises running as a superuser for a complete picture, which is a practical usage hint. However, it does not name alternatives or state when *not* to use it, so it lacks explicit exclusions. This fits the 'clear context, no exclusions' benchmark.

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

• pg_describe_tableA
  4.5/5.0
  Behavior5/5

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

  The description goes far beyond the readOnlyHint/idempotentHint annotations by explaining exactly what is included in the result, how plain views behave, which column types are not writable, and how PostgreSQL 18+ adds extra fields. It also clarifies that 'generated' columns report 'generation_expression' rather than 'default_value', which prevents misinterpretation of output.

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

  Conciseness5/5

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

  While the description is long, every sentence carries operational value: relation kinds, output fields, view behavior, writability caveats, generated column handling, and PG18 additions. It is front-loaded with the core result shape and then layers important caveats in a logical order.

  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 an output schema exists and annotations already establish the read-only and idempotent nature, the description fully covers what an agent needs to correctly invoke and interpret this tool. It explains edge cases (views, generated/identity columns, NOT VALID constraints) that would otherwise be surprising.

  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 does not add meaningful parameter-level semantics beyond the schema — it describes output structure and behavioral details rather than clarifying what 'table' or 'schema' mean or how they should be formatted.

  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 opens with the precise verb-resource pair 'Describe a relation' and immediately enumerates the full set of returned dimensions (kind, columns, primary key, foreign keys, constraints, indexes, partition info). It distinguishes itself from generic listing siblings by explaining it returns structural metadata, not just table names or rows.

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

  Usage Guidelines4/5

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

  The description gives clear context on when this tool is appropriate, notably that it works on views and materialized views and that PK/FK/constraint lists will be empty for plain views. It advises using 'kind' to disambiguate before assuming writability, which is practical guidance, though it does not explicitly name sibling tools as alternatives.

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

• pg_inspect_locksA
  4.5/5.0
  Behavior5/5

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

  Beyond the read-only/idempotent annotations, the description discloses non-obvious behavior: one row per blocked/blocking pair, duplicate rows for multi-blocker sessions, and a caveat that `relation` is only a best-effort guess for transactionid/virtualxid waits. This is exactly the kind of behavioral nuance annotations do not 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?

  The description is dense but every sentence earns its place: purpose, use case, row-shape semantics, and a critical caveat are all covered without redundancy. The most important information 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?

  With an output schema present and read-only/idempotent annotations, the description covers the remaining essentials: what columns are returned, how to interpret duplicate rows, and how to disambiguate the unreliable `relation` field. An agent has enough to invoke and interpret the tool correctly.

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

  Parameters3/5

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

  The only parameter, `limit`, is fully described in the input schema (max blocked/blocker pairs, default 50, range). Since schema description coverage is 100%, the description's lack of parameter-specific detail is acceptable and matches the baseline.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Show current lock contention.' It clearly enumerates outputs (blocked PID, blocking PID, lock types, relation, queries) and uniquely positions the tool among the sibling diagnostics, none of which target lock contention.

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

  Usage Guidelines4/5

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

  The description gives an explicit usage trigger: 'Use this first when a tool call hangs or the app feels stuck.' It does not name alternatives or when-not-to-use conditions, but the context is clear enough for an agent to know when to choose this tool.

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

• pg_list_schemasA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare the operation is read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral detail about which schemas are omitted, including `pg_catalog`, `information_schema`, and other `pg_*` internals, which is not conveyed by the 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.

  Conciseness5/5

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

  The description is two short sentences with no redundancy. The primary action and scope are stated first, followed by a precise exclusion list, making the description efficient and easy to parse.

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

  Completeness5/5

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

  For a zero-parameter, read-only listing tool with an output schema and clear annotations, the description is fully adequate. Nothing an agent needs to invoke this 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?

  The tool takes zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description accurately reflects that the operation is unconditional.

  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 ('List') with a clear resource ('non-system schemas') and explicitly differentiates from siblings by stating what is excluded. An agent can immediately understand this tool is for enumerating user-defined schemas, not tables, views, or functions.

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

  Usage Guidelines4/5

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

  The description clearly establishes the tool's scope by excluding system schemas, providing sufficient context for when to use it. It does not explicitly name an alternative tool, but the sibling list and the self-contained nature of the operation make the intended use obvious.

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

• pg_replication_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. The description adds valuable behavior beyond these hints: it sources data from pg_stat_replication, distinguishes primary vs replica behavior, and promises empty arrays on standalone databases instead of errors. This is useful context beyond the structured 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?

  Three sentences, each earning its place: first defines scope, second gives usage guidance, third covers the standalone edge case. Information is front-loaded and no filler 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 parameterless read-only status tool with annotations covering safety and an output schema available, the description is complete. It covers what data is returned, where to run it, and the edge-case behavior on standalone databases.

  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 already complete at 100%. With no params to document, the baseline of 4 applies; the description need not add parameter-level detail.

  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 identifies the tool as a replication overview covering replication slots, connected replicas, and WAL position. It distinguishes itself from sibling tools by being specifically about replication status rather than general database health or performance.

  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 explicitly tells the agent when to use it: on a primary to spot lagging/disconnected replicas, and on replicas to see upstream status. It does not name specific alternatives or exclusions, but the guidance is clear enough for this specialized status tool.

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

• pg_seq_scan_tablesA
  4.5/5.0
  Behavior5/5

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

  Annotations establish read-only/idempotent behavior, and the description goes well beyond them by explaining cumulative counters, the meaning of stats_reset and null, and the PostgreSQL 16+ last-scan timestamps. These caveats prevent a common misreading of the ratio.

  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?

  Longer than average, but every sentence carries a distinct piece of information: purpose, return shape, interpretation, reset caveat, and version-specific fields. The purpose is front-loaded and the structure progresses naturally from decision to 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?

  The description covers what the tool does, how to interpret its output, the critical stats-reset caveat, and version differences, while annotations cover safety. An agent has enough context to invoke it correctly and use the results.

  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?

  All three parameters already have descriptions in the schema, including defaults and bounds, so the description need not repeat them. It adds useful context that the ratio matters on large tables and uses live tuples, but no parameter-specific syntax 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 opening sentence states a specific diagnostic goal — identifying tables with high sequential-scan counts relative to index scans — and names the tool as the first place to look for missing-index candidates. This is clearly differentiated from sibling diagnostics like pg_unused_indexes and pg_top_queries.

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

  Usage Guidelines4/5

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

  The description gives explicit when-to-use guidance ('the first place to look') and explains the follow-up action: pair with pg_top_queries to find the responsible query. It does not explicitly say when to prefer pg_unused_indexes or pg_index_advisor, so it stops short of full alternative routing.

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

• pg_advisorA
  4.6/5.0
  Behavior5/5

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

  Even though annotations already declare read-only/idempotent/non-destructive, the description adds substantial behavioral context: per-category query failures append to _warnings and return empty, system catalogs and TOAST tables are intentionally included, threshold semantics are explained, and PG18+ key-absence behavior is disclosed. This is far beyond what annotations alone provide.

  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 long, but it earns its length for a roll-up diagnostic tool with four complex finding categories. It is well-structured with bolded category names, nested field descriptions, and a clear closing usage note. A few asides could be trimmed, but the density is justified by the tool's scope.

  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 all finding categories, their exact row structures, threshold behaviors, edge cases, failure modes, and follow-up tools. Despite the output schema being available, this description makes the tool's behavior fully understandable without needing additional context. Nothing essential for correct invocation or interpretation is missing.

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

  Parameters4/5

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

  The input schema already documents all four parameters at 100% coverage, so the baseline is 3. The description goes further by explaining how wraparoundThreshold applies to both xid and multixact ratios independently, and how seqExhaustionThreshold relates to last_value/max_value. This adds meaningful semantic detail beyond the schema field 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 opens with 'Rolled-up DBA lint pass' and immediately enumerates the four distinct categories of findings with detailed definitions. It clearly identifies this as the broad advisor tool, distinct from more focused siblings like pg_unused_indexes or pg_table_bloat.

  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 explicitly positions the tool as the 'what should I be looking at?' starting point and names the perf-side drill-down alternatives: 'pg_unused_indexes, pg_table_bloat, pg_seq_scan_tables'. It lacks an explicit 'don't use when...' statement, but the guidance is clear enough for an agent to choose it as the first-pass diagnostic.

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

• pg_explainA
  4.7/5.0
  Behavior5/5

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

  The description discloses far more than the annotations alone: plain EXPLAIN does not execute, ANALYZE does execute, non-SELECT requires ALLOW_WRITES=1, and writes during EXPLAIN ANALYZE are rolled back. It also explains version-gated behavior, explicit version errors instead of parse failures, HypoPG dependency, and teardown of hypothetical indexes. None of this contradicts the annotations, and the destructiveHint is consistent with the fact that ANALYZE actually runs the statement.

  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 long, but proportionately so: it must explain 14 parameters plus cross-cutting version requirements and side effects. It front-loads the core behavior first, then works through options in a logical order. It loses a point because it is a dense wall of prose in places, and some default information is repeated from the schema rather than relying on the structured field.

  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 14 parameters, execution side effects, version constraints, and an output schema, the description is remarkably complete. It covers behavior, security/authorization implications, rollback semantics, extension requirements, and parameter combinations. The presence of an output schema means the description does not need to document return-value structure, and nothing critical is missing for correct invocation.

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

  Parameters5/5

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

  The schema already covers 100% of parameters, but the description adds significant meaning on top: default-on behavior for buffers when analyze is true, PostgreSQL version requirements per option, incompatibilities such as generic_plan vs analyze/params, and the semantics of serialize levels. This goes well beyond the schema's standalone property 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 opens with a precise verb and resource: 'Get the query plan for a SQL statement.' It immediately clarifies the key distinction between plain EXPLAIN and EXPLAIN ANALYZE, which separates this tool from siblings like pg_query or pg_advisor. The raw-SQL-not-prefixed instruction further disambiguates the input contract.

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

  Usage Guidelines4/5

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

  The description gives strong option-level usage guidance: when to use buffers ('fastest way to tell a bad plan from a cold cache'), settings ('usual explanation for a plan that looks impossible'), memory ('ask why planning a statement is expensive'), and generic_plan. It also records important constraints such as 'cannot be combined with analyze or params.' However, it never explicitly routes the agent to an alternative sibling for cases where EXPLAIN is not the right tool, so it misses the 'when not to use this tool' part.

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

• pg_index_advisorA
  4.7/5.0
  Behavior5/5

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

  Even though readOnlyHint/openWorldHint/idempotentHint/destructiveHint already cover safety, the description adds substantial beyond-annotation behavior: no SQL parser, EXPLAIN-only execution inside BEGIN READ ONLY, session-scoped HypoPG reset on success and failure, greedy bounded search with budget_exhausted, PG18 skip-scan handling, and planner-estimate caveats. Nothing 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 long but every block earns its place, covering generation, pruning, caps, version-specific behavior, side effects, and cost interpretation. The core purpose and proof requirement are front-loaded, followed by the most decision-critical 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 the tool's complexity and the existence of a rich output schema, the description covers all operational essentials: the honest no-parser limit, HypoPG requirement and cleanup, read-only safety, bounded search semantics, PG18 version reversal, and the correct interpretation of costs. No major decision-relevant context is missing.

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

  Parameters4/5

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

  The input schema already describes all 8 parameters at 100% coverage, setting a baseline of 3. The description adds meaningful interplay context: statements vs limit choice, max_candidates/max_explains as stopping caps that produce budget_exhausted, and call-count weighting, so it moves above baseline.

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

  Purpose5/5

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

  The opening line names a specific verb and resource — 'Recommend indexes for a workload' — and adds a concrete behavioral promise: each index must prove it pays for itself. This clearly distinguishes pg_index_advisor from siblings like pg_advisor, pg_explain, and pg_unused_indexes.

  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 explains the two input modes (statements vs pg_stat_statements), states the HypoPG dependency, and tells the agent to validate with pg_explain and create with CONCURRENTLY. It does not explicitly say 'use this when...' or name when not to use it, but the context is clear enough to route a caller correctly.

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

• pg_search_columnsA
  4.7/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. The description adds useful behavioral context beyond annotations: LIKE semantics, case-insensitivity, and cross-schema search behavior. No contradictions 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?

  Four short sentences, each earning its place: scope, LIKE syntax, case-insensitivity, and when-to-use guidance. Front-loaded with the primary action and scoping, no filler or repetition.

  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 rich annotations, a complete input schema with 100% parameter coverage, and an output schema, the description covers all essential behavioral and routing information. There is no material gap for an agent to select and invoke 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?

  Schema coverage is 100%, so the baseline is 3. The description still adds value by clarifying that `%` is a substring wildcard, `_` matches exactly one character, and matching is case-insensitive, which goes beyond the schema's brief 'LIKE pattern' 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?

  States a specific verb ('Search'), a precise resource ('columns by name'), and a clear scope ('across all user schemas'). It distinguishes itself from pg_describe_table by naming what it is not and why it would be preferred.

  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 tells the agent when to use this tool: 'Use this instead of iterating pg_describe_table when the user asks which tables have X.' This gives a direct usage rule and names the alternative, so no inference is needed.

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

• pg_top_queriesA
  4.7/5.0
  Behavior5/5

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

  The description goes well beyond the readOnly/idempotent annotations by disclosing cumulative counter semantics, the meaning of stats_reset: null, dealloc-based eviction risks, version-dependent behavior, and database scoping. It explains the exact conditions under which the ranking can be misleading and what remediation looks like. This is exceptionally transparent and contradicts no 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 purpose and primary use case are front-loaded in the first two sentences, and the remaining paragraphs each address a distinct operational risk: reset clocks, dealloc churn, version differences, IO timing fields, and cross-database leakage. It is long, but every sentence earns its place because it prevents a real misinterpretation of the results.

  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 all the contextual knowledge an agent needs: extension prerequisite, exact return shape, reset-window semantics, dealloc caveats with a remedy, version-specific field availability, and scoping behavior. Combined with the rich input and output schemas, there are no meaningful gaps left for the agent to infer.

  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?

  Both parameters already have full schema descriptions and the enum is well documented, so the baseline is 3. However, the description adds interpretive depth beyond the schema: the ranking values are measured over a reset-defined window, and a nonzero dealloc can invalidate conclusions drawn from any ordering. That context materially helps an agent choose and interpret orderBy.

  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 operation: returning top N queries by total or mean execution time, and names the underlying resource (pg_stat_statements). It also states the intended use ('find slow queries worth optimizing'), which distinguishes it from sibling tools like pg_explain or pg_index_advisor. Even without explicit sibling names, an agent can tell what this tool is for.

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

  Usage Guidelines4/5

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

  The description gives a clear prerequisite (pg_stat_statements must be installed/enabled) and states its intended use case. It also warns against conflating its stats_reset timestamp with those from pg_seq_scan_tables/pg_unused_indexes. It stops short of explicitly saying 'when not to use this and use alternative X instead', so it earns 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.

• pg_unused_indexesA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the operation as read-only and non-destructive, but the description adds substantial behavioral context: scan counters only reflect the window since stats_reset, PK/UNIQUE indexes are excluded, PostgreSQL 16+ includes last_idx_scan, and PostgreSQL 18+ changes skip-scan reasoning. This goes far beyond what annotations 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?

  Front-loaded with a clear definition and return shape, then each paragraph covers a distinct and necessary caveat. Though long, every sentence earns its place given the dangerous 'recommend a drop' use case, and there is no repetition of 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?

  The description is complete for safe invocation and interpretation: it explains the output envelope, reset-window caveats, excluded constraint indexes, version-specific fields, and Postgres 18 behavior. The output schema exists, so the description need not exhaustively specify every return field.

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

  Parameters4/5

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

  The input schema already documents all three parameters fully, so the baseline is 3. The description enriches maxScans by explaining that the scan counter is only meaningful relative to stats_reset, which is critical for interpreting that parameter. It does not add much for limit or schema, but their schema descriptions are already clear.

  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?

  First line defines the output precisely: indexes never scanned or with very low usage, largest first, with the title supplying the 'find' verb. It is clearly distinct from the sibling pg_index_advisor, which is oriented toward recommending indexes to add rather than identifying dead ones.

  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?

  Provides a concrete trigger: before adding a new index, check whether dropping a dead one is the real fix. It also warns when the data is not trustworthy after a stats reset, but it does not explicitly compare against sibling tools or state when not to use this tool.

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

• pg_table_bloatA
  4.8/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and idempotentHint annotations, the description discloses non-obvious behavior: stats_reset semantics on PostgreSQL 19+, the distinction between absent and null keys, the fact that reset clears several counters together, and the statement_timeout risk when calling method='exact' without a schema. This is rich, actionable behavioral context.

  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 each paragraph earns its place: purpose/outputs, a critical stats_reset caveat, and method selection with a concrete timeout warning. The structure is logical and front-loaded with the core action, though a slightly tighter version could avoid some repetition with schema method descriptions.

  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 moderate complexity, output schema availability, and 100% parameter schema coverage, the description covers everything needed to invoke it correctly: returned columns, interpretation cues, method tradeoffs, extension installation, superuser requirement, and a specific call-safety warning for exact scans. No obvious operational gap remains.

  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. The description adds substantial meaning beyond the schema for the method parameter, explaining tradeoffs, extension prerequisites, and a timeout warning tied to schema usage. It does not add comparable detail for limit or minDeadRatio, but those are already well described by the schema.

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

  Purpose5/5

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

  The description states a specific verb ('Estimate'), a specific resource ('table bloat ... for tables in a schema'), and enumerates the returned diagnostic fields. This clearly distinguishes it from sibling tools like pg_unused_indexes or pg_health while matching the tool name and title.

  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 when-to-use guidance: 'estimate' is marked as the default and 'Use this first', while 'approx' and 'exact' are contrasted by accuracy, speed, extension requirements, and timeout risk. It also provides a practical interpretation rule for high dead_ratio alongside stale last_autovacuum.

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

• pg_killA
  4.9/5.0
  Behavior5/5

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

  Goes well beyond the annotations: explains that cancel is graceful and terminate is forceful, that it changes database session state, and describes the signaled=false note behavior including concrete examples of cause-specific messages. Annotations already mark it destructive and non-readonly, and the description enriches rather than contradicts them.

  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 information-dense without padding. Core operation is front-loaded, followed by prerequisites, permission nuances, and failure interpretation. Each sentence contributes necessary operational knowledge.

  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?

  Covers prerequisites, permissions, mode differences, failure causes, and how to find inputs. An output schema exists, so return value details are not required. Nothing material is missing for an agent to select and invoke 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?

  Schema coverage is 100%, so baseline is 3. The description adds value by explaining the practical meaning of mode ('Cancel is graceful; terminate is forceful') and how to obtain the PID, plus the behavior of signaled=false for interpreting failures. This exceeds baseline but PID semantics remain largely defined by 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?

  Description states a specific verb/resource pair: cancel a running query or terminate a backend by PID. It names the signal equivalents (SIGINT/SIGTERM), making the behavior unambiguous. It is clearly distinguished from sibling read-only tools like pg_health and pg_inspect_locks.

  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 on when to use the tool and prerequisites: find PID via pg_health or pg_inspect_locks, require ALLOW_WRITES=1, and need pg_signal_backend role or superuser. It also explains the permission limitation around superuser-owned backends, so an agent knows when this tool will fail.

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

• pg_readonlyA
  4.9/5.0
  Behavior5/5

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

  Goes well beyond the readOnlyHint annotation by explaining the BEGIN READ ONLY transaction, unconditional rollback, and the caveat that READ ONLY does not block every side effect. It also discloses privilege constraints, parameterized-query advice, and result truncation behavior, giving the agent a thorough behavioral model.

  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 every sentence carries essential operational information: purpose, transaction semantics, side-effect caveat, privilege model, injection safety, and truncation. It is front-loaded with the primary purpose and then layers in the caveats a caller must know.

  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 flexible SQL execution tool with an output schema and rich annotations, the description covers all major calling concerns: what can run, transaction guarantees, exceptions to read-only enforcement, parameter encoding, and row limits. Nothing essential for selecting or invoking this tool 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 coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema by explaining how params map to Postgres types: strings, numbers, booleans, null, arrays for ANY, and objects for json/jsonb. This is genuinely useful for constructing valid calls.

  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, specific verb and resource: 'Run a SQL statement with no persistent data changes.' It names the exact statement types accepted (SELECT, EXPLAIN, SHOW, VALUES, WITH ... SELECT), which distinguishes it from sibling read tools like pg_explain or pg_list_tables.

  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 says 'Use this whenever the goal is to read' and lists the applicable SQL forms. It also warns about side-effect functions like pg_cancel_backend that are not blocked, and contrasts with pg_kill, giving the agent concrete when-to-use and when-not-to-use guidance.

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

• pg_queryA
  5/5.0
  Behavior5/5

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

  Annotations already signal destructive capability, and the description adds meaningful behavioral context: Postgres role privileges are the primary safety gate, ALLOW_WRITES only lifts the read-only wrapper, and writes are server-rejected without the role's permission. It also discloses result truncation behavior and the truncated flag, going beyond the structured metadata.

  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 efficiently adds safety, alternatives, parameter usage, and truncation behavior. Each sentence provides actionable details without redundancy or 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?

  Given the output schema exists and the tool is a general SQL executor, the description covers what an agent needs: what the tool does, safety constraints, parameterized usage, supported types, and result limits. No critical invocation detail is missing.

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

  Parameters5/5

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

  The schema already covers both parameters fully, and the description adds substantial extra meaning: supported parameter types (strings, numbers, booleans, null, arrays, objects), ISO-format handling for dates/UUIDs, and positional $1/$2 binding. It also advises using params to avoid SQL injection.

  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: 'Run a SQL query against the configured PostgreSQL database.' It also distinguishes this tool from the read-only sibling 'pg_readonly', so an agent can tell them apart without inspecting schemas.

  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 prefer pg_readonly for read-only access, explains the role-based safety posture, and describes when this tool is useful (managed databases where creating a second role is awkward). It gives clear guidance on using parameters for safety.

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