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

The description adds behavioral context beyond annotations, such as excluding idle connections and the server itself, and details default parameter behavior. Annotations already indicate read-only and non-destructive, which the description reinforces without contradiction.

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

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

The description is concise and well-structured with clear sections for description, arguments, and returns. Every sentence provides essential information without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format in both JSON (with fields) and Markdown (table columns), covering all necessary details for a monitoring tool.

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

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

With 100% schema coverage, the description adds value by clarifying defaults and the purpose of each parameter, e.g., 'default: 0 = all active' for min_duration_seconds and the output format options for response_format.

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

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

The description clearly states the verb 'List' and resource 'queries', with specific exclusions (idle connections and the MCP server itself). It distinguishes itself from sibling tools like pg_slow_queries by focusing on currently running queries.

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

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

The description explicitly states use cases: 'finding long-running queries, blocked transactions, and identifying performance bottlenecks.' However, it does not explicitly mention when not to use it or provide alternatives among siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds context about dead-tuple accumulation from UPDATE/DELETE and its impact on query performance and storage, which is beyond the annotations. No contradiction; behavior is well disclosed.

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

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

Description is front-loaded with main purpose and uses a structured docstring format (Args/Returns). It is concise but could be slightly more streamlined; every sentence adds value. Well-organized for quick scanning.

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

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

Given no output schema, description explicitly documents return formats (JSON with BloatInfo fields and count, Markdown sorted by dead%) and includes threshold defaults. Covers all necessary context: purpose, parameter explanations, behavioral impact, and output shape. Fully adequate for a reporting tool.

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

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

Schema coverage is 100%, so baseline is 3. Description reiterates parameter names and default values similarly to schema, but adds minimal extra context (e.g., 'Filter to a specific schema (optional)'). Not enough added value to raise score above baseline.

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

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

Description clearly states the tool identifies tables with high dead-tuple ratios needing vacuum attention. It uses specific verb 'identify' and resource 'tables... that need VACUUM or AUTOVACUUM attention', distinguishing it from sibling tools like pg_vacuum (performs vacuum) or pg_table_stats (general stats). Includes context on dead row accumulation and performance impact.

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

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

Description explains when to use (to find tables needing vacuum) and provides a threshold guideline ('Tables over ~20% dead tuples should be vacuumed'). However, it does not explicitly state when not to use or mention alternatives among siblings. Clear context with reasonable exclusion missing.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds important behavioral context: it excludes the MCP server's own backend connection from counts, and details the output format for both JSON and Markdown. This helps the AI agent understand exactly what the tool returns and its non-destructive nature.

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

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

The description is concise and well-structured: a brief purpose statement, followed by use cases, a clear Args section, a Returns section, and a critical note. Every sentence adds value, and there is no redundancy with the input schema.

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

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

Given that there is no output schema, the description fully compensates by detailing the return structure for both JSON and Markdown formats. The tool has 3 parameters, all documented, and the description includes a note about connection exclusion. This is comprehensive for a read-only diagnostic tool.

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

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 restates the parameters and their defaults but adds no new semantic detail beyond what the schema already provides. For example, the group_by enum values are listed in both places. No additional constraints or examples are given.

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

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

The description clearly states the tool shows a summary of current PostgreSQL connections grouped by database, user, application, or state. It specifies the resource (connection statistics) and action (show summary), distinguishing it from sibling tools like pg_active_queries which focuses on active queries.

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

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

The description explicitly states use cases: monitoring connection pool utilization, finding idle connections, and detecting connection leaks. While it doesn't list when not to use or directly name alternatives, the context signals and sibling tools list imply that for different monitoring needs (e.g., active queries) other tools exist.

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

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

Annotations already provide readOnlyHint and destructiveHint. The description goes beyond by detailing the CSV output format, error handling for invalid queries, and parameters like limit, delimiter, and null_value. 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.

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

The description is structured with clear sections (Args, Returns, Errors), uses bullet points, and is concise—every sentence provides essential information without redundancy.

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

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

With no output schema, the description fully covers return value (CSV text), all parameters, constraints (SELECT only, row limit), and error cases. It is complete for a tool of this complexity.

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

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

Despite 100% schema coverage, the description adds substantial meaning: sql is required and must be read-only; limit range and default; delimiter default character; null_value default. This enriches the agent's understanding beyond schema constraints.

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

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

The description clearly states 'Execute a SELECT query and return the results formatted as CSV with headers,' specifying a concrete verb and resource. The title 'Export Query Results as CSV' distinguishes it from siblings like pg_execute and pg_query, which likely return different formats.

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

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

The description includes explicit notes on when to use (SELECT only) and error conditions for non-SELECT. However, it does not explicitly compare against sibling tools like pg_execute or pg_query to guide selection for similar operations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds value by specifying that it provides an exact count, supports optional WHERE clause, and includes a large-table performance note. No contradictions.

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

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

Concise and well-structured: main purpose sentence, then Args/Returns/Note sections. Every sentence adds value; no redundancy.

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

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

With annotations and simple output, description fully covers behavior: exact count, filter usage, return format, and alternative for large tables. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats parameter names and meanings from schema (e.g., 'table: Table name (required)') without adding new semantic details or format constraints.

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

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

Description clearly states 'Get exact row count for a table', using specific verb 'Get' and resource 'row count'. It distinguishes from sibling tool 'pg_table_stats' which provides estimated counts.

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

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

Explicitly provides a usage alternative: 'For large tables (>10M rows), pg_table_stats provides a faster estimated count.' Also mentions optional filter condition, guiding appropriate use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool returns JSON or Markdown and lists possible errors. It does not disclose additional behavioral traits 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.

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

The description is concise with clear sections for Args, Returns, and Errors. Every sentence is informative without unnecessary words. It is well-structured and front-loaded with the core purpose.

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

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

The description fully explains the tool's functionality, inputs, return formats, and error cases. Despite lacking an output schema, it details both JSON and Markdown output structures, making it complete for a read-only describe tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats parameter explanations (table name, schema default, response_format enum) but adds minor context like default values and error messages. It does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it provides a full description of a table including columns, data types, constraints, indexes, and foreign keys. It uses specific verbs and resource, distinguishing it from sibling tools like pg_list_tables or pg_get_ddl.

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

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

The description explains the usage context (table name, optional schema, format) and expected outputs. However, it does not explicitly state when to use this tool versus alternatives among the many sibling tools, though the purpose is clear enough for inference.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false. The description adds crucial context: irreversible operations require confirm_destructive, no auto-transaction, and the return format (JSON with command, rows_affected, duration_ms, plus Markdown). This goes beyond annotations to disclose important behavioral traits.

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

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

The description is well-organized with clear sections: purpose, special conditions, Args, Returns, Examples, Warning. Each sentence serves a purpose without redundancy. It is concise yet comprehensive, fitting within a few lines.

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

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

The description fully covers the tool's behavior: what it does (write operations), special confirm_destructive requirement, timeout parameter, return format, and transaction warning. Given the absence of output schema, the return description is sufficient. The sibling context further clarifies the tool's role.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the role of confirm_destructive (required for certain operations) and providing examples that illustrate parameter usage. It does not repeat schema information unnecessarily.

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

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

The description clearly states 'Execute a non-SELECT SQL statement' and lists specific operations (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, TRUNCATE). This distinguishes it from sibling tools like pg_query (for SELECT) and other specialized tools. The verb 'Execute' and resource 'SQL Statement' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use confirm_destructive for DROP/TRUNCATE/DELETE without WHERE. It warns about lack of automatic transaction wrapping. While it doesn't explicitly say 'use pg_query for SELECT', the phrase 'non-SELECT' strongly implies it. The examples cover common use cases.

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

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

The description warns that EXPLAIN ANALYZE executes the query with potential side effects, contradicting the readOnlyHint: true annotation which asserts the tool is read-only. This is a critical inconsistency that undermines trust.

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

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

The description is concise (about 10 lines) with clear sections (Args, Returns, Warning), front-loaded with the main purpose. Every sentence adds value, no fluff.

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

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

Given the tool's moderate complexity and no output schema, the description covers all key aspects: parameters, return format, and a critical warning about side effects. It is complete for an agent to invoke the tool correctly.

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

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

The description adds meaningful context beyond the schema, explaining the difference between sql and analyze, the dependency of buffers on analyze, and the format options. Schema coverage is 100%, so the baseline is 3, and the description provides extra clarity.

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

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

The description clearly states 'Show the execution plan for a SQL query using EXPLAIN or EXPLAIN ANALYZE', which is a specific verb (show) and resource (execution plan). It distinguishes from siblings like pg_execute (which runs queries) by focusing on plan analysis.

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

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

The description explains when to use EXPLAIN vs EXPLAIN ANALYZE, providing clear context on the trade-offs (planned strategy vs real execution with I/O cost). However, it does not explicitly compare with 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds return format details (JSON fields, Markdown code block) and lists supported object types, enhancing transparency beyond annotations.

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

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

The description is concise with two paragraphs: a purpose sentence, then args, return format, and usage. It is front-loaded with the essential action and well-organized.

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

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

Despite no output schema, the description explains the return JSON fields and Markdown formatting. It covers tool purpose, parameters, return, and usage scenarios fully, given the tool's complexity.

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

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's 'Args:' section mirrors the schema and adds readability but does not provide new semantic meaning beyond what the schema already conveys.

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

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

The description specifies the verb 'Get' and the resource 'CREATE statement (DDL)' for multiple object types. It clearly distinguishes from sibling tools like pg_describe_table or pg_list_tables by focusing on DDL retrieval.

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

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

The description explicitly states use cases: 'understanding table structure, reproducing objects in other environments, or code review.' It does not mention when not to use or alternatives, but sibling differentiation is inherent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds valuable behavioral context: statistics reset on pg_stat_reset() or server restart, and low scans on new server may not indicate unused. This goes beyond annotations.

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

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

Well-structured: one-line summary, motivational sentence, Args list, Returns section, behavioral note. Every sentence adds value. Front-loaded with key purpose. No fluff or repetition.

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

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

Completeness given complexity: no output schema but description specifies return formats (JSON and Markdown) with sorting details for Markdown. Covers behavioral notes and all parameters. Standalone sufficient for agent to understand and invoke tool correctly.

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

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

Input schema covers all 4 parameters with descriptions (100% coverage). Description repeats parameters in Args block with slight additional context (e.g., emphasis on filtering for unused indexes). Does not significantly add meaning beyond schema, but integrates parameters into the overall purpose. Baseline 3 is appropriate.

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

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

Description clearly states 'Show index scan counts and tuple statistics to identify unused or underused indexes.' It uses a specific verb and resource, and distinguishes from sibling tools like pg_list_indexes (listing) and pg_bloat_report (bloat).

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

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

Provides clear context for usage: identifying unused/underused indexes, mentions that indexes with 0 scans and not primary keys waste storage. Notes limitations about statistics reset and new server interpretation. Lacks explicit comparison to alternatives but sufficiently guides appropriate usage.

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

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

Annotations already mark destructiveHint=true, but the description elaborates: cancel sends SIGINT (safe, connection stays), terminate sends SIGTERM (forceful, connection killed). Also states it cannot kill own backend or superuser without privileges. 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.

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

Highly concise: one sentence for purpose, then clear sections for modes, args, returns, and note. Every sentence adds essential information with no redundancy.

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

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

Despite no output schema, the description covers return value ('Whether the signal was successfully sent'), edge cases (own backend, superuser), and sources for the PID. This is comprehensive for a straightforward kill tool.

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

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

Schema coverage is 100%, but the description adds value by specifying that pid comes from pgs_active_queries or pg_list_locks, and explaining the two mode values with their default. This goes beyond the schema's basic descriptions.

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

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

The title and first sentence clearly state that the tool cancels or terminates a PostgreSQL backend by PID. It distinguishes two modes (cancel vs terminate) and explains their effects. No sibling tool does this, so purpose is unambiguous.

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

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

Explicitly describes when to use cancel (safe, leaves connection alive) vs terminate (when cancel doesn't work). Notes that PID comes from sibling tools (pg_active_queries, pg_list_locks) and warns about privilege limitations. This gives agents clear decision criteria.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds return fields (name, encoding, collation, size, connection limit), output formats (JSON/Markdown), and error conditions, which provides additional behavioral context beyond annotations.

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

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

The description is brief, structured with sections for returns and errors, and contains no unnecessary words. Every sentence adds value.

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

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

With no output schema, the description fully explains return values and errors. For a simple tool with one optional parameter, it covers all necessary information for an agent to use it correctly.

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

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

Schema coverage is 100% with one parameter (response_format). The description explains the effect of the parameter by detailing the return formats (JSON vs Markdown table), adding meaning beyond the enum values.

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

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

The description clearly states the specific action 'List all non-template databases accessible on the connected PostgreSQL server', distinguishing it from sibling tools that list other objects (tables, schemas, roles, etc.).

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

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

The description implies usage for listing databases, and no sibling tool provides this exact functionality, so the context is clear. However, it doesn't explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description doesn't need to restate those. However, it adds useful details about the return format (JSON/Markdown) and the fields included (name, installed version, etc.), which enhances transparency beyond the schema.

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

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

The description is three sentences long, front-loaded with the action ('List all extensions'), and efficiently conveys the return format and fields. Every sentence serves a purpose without unnecessary verbosity.

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

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

Given the tool's low complexity (1 optional parameter, no output schema), the description is complete. It explains the output format and content, and the parameter is already well-documented in the schema. No additional information is needed for an agent to use this tool correctly.

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

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

Schema coverage is 100%, with the single parameter 'response_format' fully described (enum, default, description). The description does not add additional semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'List all extensions currently installed in the PostgreSQL database' with a specific verb and resource. It distinguishes itself from sibling tools (e.g., pg_list_tables, pg_list_databases) by focusing on extensions, leaving no ambiguity about what it does.

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

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

The description makes it clear that this tool is for listing extensions, which is straightforward given the tool name and title. While it does not explicitly state when to avoid using it or name alternative tools, the context of sibling tools provides sufficient differentiation for an agent to select the correct tool.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds context about return formats (JSON or Markdown) and the specific types of functions listed, which goes beyond annotations without contradiction.

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

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

The description is concise and front-loaded with the main purpose. It includes structured 'Args:' and 'Returns:' sections, which is helpful but slightly redundant with the schema. No wasted sentences.

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

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

Given no output schema, the description fully specifies the return structure for both JSON and Markdown formats. It also covers the default schema, making the tool's behavior completely understandable.

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

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

Both parameters are well-documented in the input schema (100% coverage). The description restates them with defaults and return format options, adding minimal additional meaning beyond what the schema provides.

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

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

The description clearly states it lists user-defined functions, procedures, aggregates, and window functions in a schema. This is specific and distinguishes it from other pg_list_* tools like pg_list_tables, pg_list_triggers, etc.

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

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

The description implies usage for listing functions in a schema but does not explicitly provide when-to-use or alternatives. Context from sibling tools helps, but no direct guidance is given.

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

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

Annotations declare readOnlyHint, destructiveHint, and idempotentHint, but the description adds context about the return format (JSON vs Markdown) and the types of objects covered. No contradictions.

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

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

The description is structured with Args and Returns sections but is slightly verbose. It could be more concise while retaining all necessary details.

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

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

Despite no output schema, the description fully explains the return structure (JSON with grants array and count, Markdown table with specific columns), covering all needed context for a read-only tool.

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

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

Schema coverage is 100%, and the schema already includes clear descriptions for each parameter. The description's Args section adds minimal new information beyond restating the schema fields.

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

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

The description clearly states the tool lists privileges on tables, views, sequences, and functions in a schema. It uses specific verbs ('show all privileges') and distinguishes from sibling tools like pg_list_roles and pg_list_schemas by focusing on grants.

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

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

The description mentions the tool is useful for security audits and understanding access, providing a clear use case. However, it does not explicitly state when not to use it or contrast with alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing the return formats (JSON and Markdown) and structure, which goes beyond what annotations provide. No contradictions.

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

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

The description is well-structured with separate Args and Returns sections, but it is slightly redundant with the schema. Every sentence serves a purpose, and it is front-loaded with the main action.

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

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

Given full schema coverage, annotations, and clear purpose, the description is complete. It explains return formats and structure, which compensates for the lack of an output schema. Edge cases like empty results are not covered but are not critical for a list tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description's Args section largely repeats schema info, adding little new meaning. Baseline of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the tool's function: 'List indexes in a schema, optionally filtered to a specific table.' The verb 'List' combined with the resource 'indexes' and optional table filter makes it distinctive from sibling tools like pg_describe_table or pg_index_usage.

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

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

The description provides clear context for when to use (listing indexes, optionally filtered). It doesn't explicitly state when not to use or alternatives, but the context of sibling tools and the straightforward purpose imply proper usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: privilege requirement, output format options, and the effect of the include_granted parameter. No contradictions.

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

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

The description is well-structured with a clear summary, usage line, argument list, returns section, and note. Every sentence adds value, and it is appropriately concise.

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

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

Given 2 optional parameters, good annotations, and no output schema, the description fairly complete. It explains the output structure for both JSON and Markdown formats. Minor gap: no detailed column list, but overall sufficient.

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

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

Schema coverage is 100%, and the description explains both parameters (include_granted and response_format) with defaults and their role. It adds meaning beyond schema by stating defaults and context.

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

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

The description clearly states it shows currently active locks and waiting queries, using specific verb 'Show' and resource 'locks'. It distinguishes itself from sibling tools like pg_active_queries by focusing on lock contention, deadlocks, and long-running transactions.

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

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

The description explicitly mentions debugging lock contention, deadlocks, and long-running transactions. It also notes the privilege requirement. However, it does not provide explicit when-not-to-use guidance or contrast with alternatives.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description adds value by detailing what the tool returns (bounds, size, row estimates) and the output formats, but does not disclose additional behavioral traits beyond those annotations.

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

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

The description is concise (two short paragraphs), front-loaded with the main action, and efficiently lists Args and Returns without extraneous text. Every sentence serves a purpose.

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

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 no output schema, the description explains the output structure (JSON and Markdown). All parameters are documented. Minor gaps: no mention of behavior when no partitions or invalid filters, but generally complete for its simplicity.

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

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 repeats parameter purposes and adds default for response_format, but does not significantly enhance understanding beyond what the schema already provides.

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

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

The description starts with a specific verb ('List all partitioned tables and their child partitions') and clearly states the resource and attributes (bounds, size, row estimates). It distinguishes itself from all sibling pg_list_* tools, as none list partitions.

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

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

The description implies usage for partition listing but does not explicitly state when to use vs alternatives, nor does it provide when-not or exclusion criteria. Usage is clear from context but not explicitly guided.

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

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

Annotations already indicate read-only, safe operation. The description adds significant value by detailing that it shows both policies and their expressions, and even tables without policies. This helps the agent predict output and side effects beyond 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.

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

The description is well-structured, front-loaded with the main purpose, followed by clear Args and Returns sections, and a helpful note. Every sentence adds value without redundancy.

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

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

Despite having no output schema, the description fully details return formats (JSON and Markdown) including fields like PolicyInfo, count, rls_enabled_tables. It also notes edge case behavior (empty policies). This is complete for a read-only listing tool.

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

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

Input schema covers 100% of parameters with descriptions. The tool description restates the parameter names and defaults but does not add new semantic meaning beyond the schema. Baseline score is appropriate.

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

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

Description clearly states it lists all RLS policies in a schema, including USING and WITH CHECK expressions. It uses a specific verb ('List') and resource ('RLS policies'), distinguishing it from sibling tools like pg_list_grants or pg_list_indexes.

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

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

The description provides clear context for when to use the tool (to inspect RLS policies), but does not explicitly mention when not to use it or name alternative tools. Since it's the only tool for policies among siblings, usage is implied, but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds specific behavioral details: it returns both login and group roles, shows attributes like superuser status, replication, and output formats (JSON/Markdown). No contradiction; adds context beyond annotations.

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

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

The description is concise with front-loaded purpose, a clear list of args, and no redundant information. Every sentence adds value, and the structure is easy to parse.

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

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

Given the tool's simplicity (2 optional params, no output schema), the description covers the purpose, behavior, output structure, and use cases completely. No gaps remain for an agent to effectively use the tool.

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

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 restates parameters with minor clarifications (e.g., 'actual users, not groups' for login_only) and describes return formats, but adds limited new meaning beyond the schema descriptions.

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

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

The description clearly states it lists all PostgreSQL roles with attributes and group memberships, distinguishing it from sibling like pg_list_grants or pg_list_tables. It specifies the exact resource (roles) and action (list), and contrasts with other list tools.

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

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

The description mentions 'Useful for access audits, permission reviews, and understanding role hierarchy,' providing clear context for when to use the tool. It doesn't explicitly state when not to use it, but the sibling list makes alternatives obvious, scoring 4.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it excludes system schemas and returns specific fields, providing useful behavioral context beyond annotations.

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

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

Two focused sentences plus return format description. No redundant information, front-loaded with purpose.

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

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

Simple listing tool; description fully covers what it does, returns, and exclusions. No output schema needed since return structure is described. Annotations cover safety.

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

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

Schema coverage is 100% with parameter description covering format options. Description mentions return formats but does not add new meaning beyond the schema; baseline 3 applies.

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

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

Description clearly states it lists user-defined schemas, excludes system schemas, and returns specific fields (name, owner, description, table/view count). This distinguishes it from sibling tools that list other objects like tables or databases.

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

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

Implies use when you need information about user schemas; no explicit alternatives but sibling tools cover different object types, so context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return format (JSON/Markdown with specific columns) and a critical behavioral note: 'last_value reflects the last allocated value, not necessarily the next one to be issued.' This provides clarity beyond annotations.

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

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

The description is concise with two clearly separated paragraphs (purposes and return format/note). Every sentence adds value, and the most critical information is front-loaded in the first sentence.

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

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

For a simple listing tool with no output schema, the description adequately covers the return structure (JSON/Markdown with specific columns) and the important last_value nuance. However, it lacks details on error handling or behavior when the schema does not exist, which would make it more robust.

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

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

Schema coverage is 100% with both parameters (schema, response_format) fully described in the input schema. The description restates them in the Args section but adds no additional semantics or constraints beyond what the schema already provides.

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

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

The description clearly states 'List all sequences in a schema with their configuration and current state.' It uses a specific verb+resource combination and distinguishes the tool from siblings like pg_list_tables or pg_list_indexes.

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

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

The description implies usage for listing sequences but does not explicitly mention when to use this tool versus alternatives or provide exclusion criteria. The note about last_value is a usage nuance but does not serve as a guideline.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds further transparency by explaining the 'context' field and categories, detailing where settings can be changed (internal, postmaster, sighup, user). 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.

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

The description is well-structured with sections (Args, Returns, Common categories, Note) and front-loaded with the main purpose. It is concise but includes necessary details; no redundant sentences. Minor room for trimming.

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

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

The description thoroughly covers the tool's inputs, outputs, and behavioral context (context field and common categories). Since there is no output schema, the description compensates well by describing the return format and including useful notes. Slightly more could be added about the use of response_format, but overall complete.

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

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

Input schema coverage is 100% (all parameters described in schema). The description adds value by providing concrete examples for name_pattern and category, and clarifying the meaning of modified_only and response_format. This extra detail justifies a score above the baseline of 3.

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

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

The description clearly states the tool searches and inspects PostgreSQL runtime settings from pg_settings, with a specific verb and resource. It distinguishes from sibling tools by focusing on configuration inspection, which is unique among the list.

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

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

The description does not explicitly state when to use this tool vs. alternatives. While the purpose is clear, there is no guidance on when not to use it or mention of alternative tools for modifying settings (e.g., pg_execute). The context field explanation is helpful but does not substitute for usage guidelines.

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

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

Beyond the readOnlyHint annotation, the description reveals that row estimates are approximate (from pg_class.reltuples) and that the tool supports two output formats (JSON/Markdown). 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.

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

The description is front-loaded with the primary purpose, followed by a structured parameter list, return format description, and a caveat. Every sentence adds value; no extraneous content.

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

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

Given the tool's low complexity (3 optional parameters, no output schema), the description thoroughly covers the action, parameter defaults, return structure (both formats), and the approximate nature of estimates. It also suggests an alternative for exact counts, making it complete for an agent.

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

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

All three parameters have descriptions in the input schema (100% coverage). The description repeats parameters and adds minimal extra meaning (e.g., 'human-readable' for markdown). With high schema coverage, baseline is 3 and the added value is insufficient to raise the score.

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

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

The description clearly states it lists tables in a PostgreSQL schema with size and row estimates, optionally including views. This specific verb-resource combination distinguishes it from sibling tools like pg_describe_table (single table), pg_list_views (only views), or pg_count_rows (exact count).

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

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

The description includes a note that estimated_rows is approximate and recommends pg_count_rows for exact counts, providing guidance on when to use this tool vs an alternative. However, it does not explicitly exclude other use cases or compare to additional siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds some value by specifying return formats (JSON/Markdown), but no new behavioral traits 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.

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

The description is concise, front-loaded with the main action, and includes necessary parameter and return details without wasted words.

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

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

For a simple listing tool with safety annotations, the description adequately covers purpose, parameters, and return format. No output schema, but the return description suffices.

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

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

Schema coverage is 100%; the description repeats parameter info without adding new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it lists triggers in a schema, optionally filtered by table. This distinguishes it from sibling tools like pg_list_functions 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.

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

No explicit guidance on when to use vs alternatives. Usage is implied by the tool's purpose (listing triggers), but no when-not-to-use or comparative context is provided.

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

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

Annotations already indicate readOnly, non-destructive, idempotent. Description adds value by explaining return formats (JSON/Markdown) and providing examples of output data, beyond what 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.

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

Well-structured with summary, Args, Returns, Examples. No superfluous text, every sentence earns its place.

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

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

No output schema, but description compensates with clear return structure and examples. All parameters documented. Complete for a read-only listing tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning with examples (e.g., enum values, base type) and explains how parameters filter results, going beyond schema.

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

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

Clear verb 'List' and specific resource 'user-defined types in a schema', enumerating categories (enums, composites, domains, ranges). Distinguishes from sibling tools like pg_list_tables and pg_list_views.

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

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

No explicit guidance on when to use vs alternatives. The description implies usage for listing types, but does not specify when not to use or compare with other tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds details like include_definition option and response_format, which are consistent. No contradictions, but no deeper behavioral insights beyond schema and annotations.

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

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

Two short paragraphs, front-loaded with the main action, no wasted words. Parameter list is compact and return info is clear. Excellent conciseness.

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

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

For a simple listing tool with full schema coverage and annotations, the description covers everything needed: purpose, parameters, return format. No gaps.

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

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

All parameters are fully described in the input schema (100% coverage). The description reiterates the args and adds return structure (JSON/Markdown), providing value beyond the schema. Baseline 3, but the return description earns a 4.

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

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

The description clearly states the tool lists views and materialized views in a PostgreSQL schema, using specific verbs and resources. It distinguishes itself from sibling tools like pg_list_tables or pg_list_functions by focusing on views.

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

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

No explicit guidance on when to use vs alternatives is provided. The description only states what it does, leaving the agent to infer usage context from the tool name and sibling list. Implied but not explicit.

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

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

Annotations already provide readOnlyHint=true. Description adds concrete constraints: allowed statements, limit bounds (1-1000), timeout (1000-300000), response formats, and error handling for disallowed queries. No contradictions.

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

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

Description is well-organized with clear sections (Args, Returns, Examples, Errors). Every sentence adds value. Front-loaded with main action. Concise and to the point.

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

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

Despite lacking output schema, the description comprehensively covers parameter details, allowed operations, return format, and error conditions. No missing information for an agent to use the tool correctly.

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

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

Schema coverage is 100% (baseline 3). Description adds value by reinforcing allowed SQL types, providing default values, adding examples, and clarifying error cases. Exceeds minimum.

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

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

Title and description clearly state the tool executes read-only SQL SELECT queries. Lists allowed statement types (SELECT, WITH, TABLE, EXPLAIN) and explicitly excludes mutating statements. Distinguishes from siblings like pg_execute and pg_explain.

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

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

Explicitly states when to use (read-only queries) and what statements are allowed. Implicitly guides not to use for writes. Could explicitly mention pg_execute as alternative for mutating queries, but context with siblings makes it clear.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false. The description adds behavioral context beyond annotations, such as the return format (JSON/Markdown) and specific data fields (replicas, is_standby, lsn). No contradictions.

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

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

The description is concise, front-loaded with the main purpose, and structured into clear sections. Every sentence serves a purpose, though the 'Returns' section could be integrated more succinctly.

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

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

Given the simple parameter set (1 optional param, 100% schema coverage) and no output schema, the description adequately explains the return format and use case. It covers core aspects without major gaps.

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

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

Schema coverage is 100%, and the description adds modest value by explaining the return format differences. It does not elaborate further on the parameter's effect or constraints beyond what the schema already provides, resulting in a baseline score.

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

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

The description clearly states it shows the status of all streaming replication standbys with replay lag. It distinguishes itself from sibling tools (e.g., pg_active_queries, pg_connection_stats) by focusing specifically on replication health.

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

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

The description explicitly notes 'Only meaningful on a primary server with active streaming replication,' providing clear context. While it doesn't specify when not to use it, the condition is sufficient for a monitoring tool with no direct alternatives.

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

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

No contradiction with annotations (readOnlyHint=true, destructiveHint=false). The description adds context about security validation of table/schema names and specifies return formats (JSON and Markdown), which goes beyond annotations.

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

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

The description is well-structured with a clear main purpose and bullet-like arg list. It is somewhat verbose but effective. The main purpose is front-loaded, making it easy for an AI to parse.

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

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

Given 7 parameters, 100% schema coverage, no output schema, and existing annotations, the description covers purpose, parameter nuances, return formats, and security notes. Minor missing details about sampling algorithm and performance, but overall complete.

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

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

Schema description coverage is 100%, baseline is 3. The description adds value by clarifying syntax for where_clause and order_by (omit keywords) and explaining response_format options, which enriches parameter semantics.

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

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

The description clearly states 'Retrieve a sample of rows from a PostgreSQL table' with optional filtering and column selection. This specific verb-resource combination distinguishes it from sibling tools like pg_count_rows (counts only) and pg_execute (custom SQL).

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

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

The description implies usage for quick sampling with optional filters, but does not explicitly state when to use this tool versus siblings like pg_query or pg_count_rows. No exclusion criteria or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds useful behavioral context: return format (JSON or Markdown), grouping by type, and example patterns. No contradictions.

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

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

The description is well-structured with Args, Returns, and Examples sections. It is concise yet comprehensive, with every sentence adding value. Front-loaded with the main purpose.

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

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

Given the moderate complexity (4 parameters, no output schema), the description is complete. It covers all parameters, return format, and usage examples. No gaps remain.

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

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 LIKE wildcards, providing examples for each parameter, and clarifying the default behavior for optional parameters.

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

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

The description specifies a clear verb ('search'), resource ('database objects'), and scope ('by name pattern'). It explicitly lists object types and distinguishes from sibling list tools by offering combined search.

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

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

The description explains when to use the tool with examples and context. It does not explicitly state when not to use it or contrast with siblings, but the usage is clear from the purpose and examples.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds value by detailing the return structure (version, current_database, current_user, settings, uptime) and format options (JSON or Markdown), going 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.

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

The description is three sentences, efficiently structured: first sentence states purpose, second lists return types, third gives use case context. No wasteful words, front-loaded with key information.

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

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

Given the tool has low complexity (one optional parameter), rich annotations, and no output schema, the description adequately covers what the tool returns, output format options, and use cases. It is complete for an informational tool.

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

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

Schema description coverage is 100% with one parameter (response_format) fully described via enum and default. The description mentions output formats but does not add significant meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves detailed PostgreSQL server information including version, connection details, memory settings, WAL configuration, and runtime parameters. This specific verb+resource combination distinguishes it from siblings like pg_list_settings (which lists individual settings) and pg_connection_stats (focused on connection statistics).

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

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

The description provides clear usage context: 'Useful for understanding the server environment, verifying connection details, and checking key configuration values.' However, it does not explicitly state when not to use this tool or suggest alternatives, which would strengthen the guidance.

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

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

Annotations already indicate readOnlyHint=true, so the description adds value by stating the extension requirement, the output formats (JSON and Markdown with fields), and error conditions. This provides useful behavioral context beyond 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.

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

The description is concise and well-structured with separate sections for arguments, returns, and errors. The first sentence immediately conveys the tool's purpose, making it easy to scan.

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

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

The description covers all essential aspects: purpose, prerequisites, parameter details, return formats with field descriptions, and error handling. It is complete for the given schema and no output schema.

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

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

With 100% schema description coverage, the baseline is 3. The description repeats parameter defaults and options but does not add new meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: analyzing slow queries using pg_stat_statements and ranking by mean execution time. It distinguishes from sibling tools like pg_active_queries and pg_query by focusing specifically on slow queries.

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

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

The description mentions the prerequisite (pg_stat_statements extension) and provides default values for parameters, but does not explicitly guide when to use this tool versus alternatives, nor does it specify when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by noting that the tool requires pg_stat_user_tables access and explaining that row counts come from autovacuum/analyze statistics rather than exact counts. 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.

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

The description is well-structured with Args and Returns sections, but it is slightly verbose by repeating some schema details. It could be more concise while retaining all essential information. Still, it is clear and front-loaded.

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

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

The tool has no output schema, but the description details the return format (JSON or Markdown) and key fields. Important notes about row count accuracy and required privileges are included. For a read-only tool with three optional parameters, this is sufficiently complete.

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

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

Schema coverage is 100% and each parameter has a description. The description adds minor context (shows all user schemas if omitted) but does not significantly enhance beyond the schema. Baseline 3 is appropriate as the schema already carries the burden.

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

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

The description clearly states the tool retrieves detailed table statistics (size, rows, vacuum/analyze info, scan counts). It distinguishes itself from sibling tools like pg_count_rows (exact counts) and pg_bloat_report (bloat-specific), making its unique purpose evident.

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

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

The description explicitly lists use cases: identifying bloated tables, missing vacuums, or underused indexes. It also advises when to use an alternative (pg_count_rows for exact counts), providing clear guidance on when to use this tool vs. others.

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

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

Description details atomic rollback behavior, confirms destructive hint from annotations, explains error response with rolled_back and failed_at_index, adding significant context beyond annotations.

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

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

Description is concise with clear sections: purpose, behavior, parameters, return format, and example. All sentences are essential without redundancy.

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

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

Covers all key aspects: atomicity, parameters, return format, error handling, and destructive confirmation. Appropriate for a transaction tool with no missing information despite lack of output schema.

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

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

Schema coverage is 100%, but description adds value by explaining statements as required array, clarifying confirm_destructive as mandatory for destructive operations, and providing usage examples.

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

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

Description explicitly states 'Execute multiple SQL statements atomically in a single transaction' with a specific verb and resource, clearly distinguishing it from siblings like pg_execute which executes individual statements without transaction guarantees.

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

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

Description indicates ideal use for atomic multi-step operations and provides examples, but does not explicitly state when not to use or contrast with non-transactional execution alternatives.

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

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

Beyond annotations (e.g., idempotentHint: true), the description adds critical behavioral details: VACUUM FULL acquires exclusive locks and blocks queries, the return value includes duration and confirmation, and it recommends analyze for most cases. 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.

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

The description is well-organized with clear sections (modes, args, returns, warning). Each sentence is purposeful, no fluff. It is concise yet thorough, perfectly balancing detail and brevity.

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

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

Given the tool's complexity (locking, blocking, multiple modes), the description covers prerequisites (confirm_full), behavioral nuances (non-blocking vs. blocking), return format, and performance warnings. Annotations handle idempotency and destructive nature, so no gaps remain.

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

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

With 100% schema coverage, the description still adds value by explaining default values (schema=public, mode=analyze), requiring confirm_full for 'full' mode, and clarifying the effect of each mode on table locking and statistics. This provides actionable semantics beyond the schema's property descriptions.

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

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

The description clearly states the tool executes VACUUM operations on a table to reclaim storage, and distinguishes three modes. It stands out from sibling tools (e.g., pg_bloat_report, pg_count_rows) by focusing on maintenance operations rather than inspection.

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

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

The description provides excellent guidance on when to use each mode (standard, analyze, full) and warns that VACUUM FULL requires maintenance windows due to exclusive locks. However, it does not explicitly contrast with alternative sibling tools for similar tasks, such as when to use pg_bloat_report instead.

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