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

No annotations are provided, so the description carries the full behavioral burden. It clearly implies a read-only retrieval and enumerates the returned fields (PID, username, database, client address, status, current query), but it does not disclose permission requirements, visibility limits for non-superusers querying pg_stat_activity, or whether results are paginated or truncated on busy servers.

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 content is organized into labeled sections with the purpose front-loaded, making it easy to scan. It is slightly longer than necessary: the 'Returns' line largely repeats the display fields already listed under 'Exact Functionality,' which is minor redundancy rather than a structural flaw.

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?

An output schema exists, so the description does not need to explain return values, yet it helpfully names the key fields anyway. For a zero-parameter read-only monitoring tool, the description is nearly complete; the notable gap is the absence of permission or visibility caveats when reading active sessions.

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 tool takes zero parameters and the schema has no properties, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4; the description adds no misleading parameter information.

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 opens with a specific verb and resource: 'Retrieve all active connections and session information on current PostgreSQL server.' It scopes the tool to the current server and enumerates the returned fields (user, database, client address, status, current query), which clearly separates it from sibling monitoring tools like get_wait_events, get_lock_monitoring, or get_pg_stat_statements_top_queries that cover different diagnostic domains.

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 when-to-use triggers ('active connections', 'current sessions', 'connection status', server load/performance diagnosis, checking specific users or applications) and a 'Strictly Prohibited Use Cases' section excluding termination, query history, and auth changes. However, it does not name the specific sibling tools an agent should invoke instead for those prohibited needs, leaving alternative routing implicit.

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?

With no annotations present, the description must carry the disclosure burden and it largely does: it makes clear this is a read-only retrieval, enumerates the content of the returned statistics, and explicitly rules out any mutation (reset, maintenance, optimization). What it omits is operational context — that scanning all tables can be expensive on a large catalog, and any permission requirements — which is the one remaining gap for a no-annotation tool.

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 bracketed headings make the content easy to scan and it is front-loaded with purpose. The three prohibited-use bullets are near-synonyms (maintenance / reset / optimization are all 'not a mutation tool'), which is minor redundancy that keeps it from a 5.

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 only two optional parameters and an output schema in place, the description needn't explain return values, and it covers purpose, content, triggers, and exclusions thoroughly. The only missing element is cost/scale caveat for a whole-catalog scan, a modest gap for this complexity level.

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 schema already documents both database_name and include_system; the description only echoes the system-tables option ('including system tables if requested'). That echo is consistent and mildly reinforcing but adds no syntax or default behavior beyond the structured fields, so 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?

The description states a specific verb and resource — 'get comprehensive statistics for all tables' — and the functionality list pins down exactly which statistics (sequential scans, index scans, tuple operations, live/dead tuples). The 'all tables' scope implicitly separates it from single-table siblings like get_table_size_info or get_index_usage_stats, though it never names an alternative explicitly.

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?

It provides both a 'Required Use Cases' list and a 'Strictly Prohibited Use Cases' list, telling the agent exactly which phrasings should route here and which requests (VACUUM, ANALYZE, stats reset, optimization) belong elsewhere. That is the full when/when-not pattern.

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 annotations are supplied, so the description carries the full burden; it discloses the key non-obvious behavior — graceful degradation to configuration-only output on PostgreSQL versions below 18 — plus the underlying source view. It never explicitly states that the tool is read-only and side-effect free, though 'Monitor' and 'Show' strongly imply it, and no permission prerequisites are mentioned.

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?

Content is front-loaded and every block earns its place, with the version caveat placed near the top where it matters. The bracketed section headers and bullet scaffolding are somewhat heavier than needed for a one-parameter read tool, but nothing is padded or redundant.

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?

An output schema exists, so return formatting need not be explained, and the version-fallback behavior plus the enum of covered data make this callable without further reading. The only real omission is read-only/safety framing and any note on how the async-I/O view relates to the other I/O stats tools.

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 single optional parameter (database_name) is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about database scoping — notably, it does not say whether pg_aios statistics are cluster-wide or per-database when database_name is supplied.

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?

States a specific verb and resource — monitoring the asynchronous I/O subsystem — and scopes it to PostgreSQL 18+ with a documented fallback. The three bullet points concretely enumerate what is shown (active operations from pg_aios, configuration/concurrency, file handle usage), which is far more than a restatement of the name.

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 explicit 'Required Use Cases' with quoted trigger phrases and an explicit 'Strictly Prohibited Use Cases' section covering configuration and storage changes. What is missing is sibling differentiation: the toolset contains get_io_stats, get_table_io_stats, get_index_io_stats and get_per_backend_io_stats, and the description never says when to prefer the async-I/O view over those.

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?

With no annotations, the description carries the full behavioral burden. The prohibited-use list does implicitly establish this as an observational, read-only tool that cannot control or reconfigure autovacuum, which is valuable. But it says nothing about data provenance or limits (e.g. dependence on pg_stat_* counters, stats reset behavior, required privileges), which matters for an activity-history tool.

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 bracketed sections make it scannable and front-loaded, which helps. But there is overlap: 'Track recent autovacuum and autoanalyze execution patterns' in Functionality merely restates the purpose line, and several Functionality bullets and Use Case bullets cover the same ground (frequency/timing vs. monitoring performance).

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?

An output schema exists, so return values need no explanation, and all parameters are optional and schema-documented. The description covers what it does, when to invoke it, and what it refuses to do. The main omission is sibling disambiguation against the multiple other vacuum-related tools in this server.

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 all four optional parameters (limit, hours_back, schema_name, database_name) are already fully documented in the schema, including ranges and defaults. The description adds no additional meaning about their interaction, such as whether hours_back bounds the interval calculations. Baseline 3 applies when the schema 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 opens with a specific verb and resource: monitoring recent autovacuum and autoanalyze activity patterns and execution history. That is materially clearer than the name alone and separates it from control operations. However, it never distinguishes itself from close siblings such as get_autovacuum_status, get_running_vacuum_operations, or get_vacuum_effectiveness_analysis, so an agent cannot route confidently between them.

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?

It provides explicit trigger phrases ('autovacuum activity', 'autovacuum history') plus three concrete scenarios (performance monitoring, scheduling troubleshooting, workload distribution). The prohibited-use section usefully rules out control/config/mutation requests. The gap is that no alternative tool is ever named for the excluded or adjacent 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?

With no annotations, the description carries the full disclosure burden and does well: it makes clear the tool only reads/analyzes and never mutates, and it specifies what the analysis covers (trigger conditions, current ratios, per-table settings, tables needing attention). It omits operational traits such as cost on large catalogs or any permission requirements, which is why it isn't a 5.

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?

Bracketed headers make it front-loaded and scannable, and the use-case sections are the highest-value content. It is slightly padded — the 'Exact Functionality' bullets overlap with the purpose line and with each other (trigger conditions vs dead tuple ratios vs next execution likelihood).

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?

An output schema exists, so return shape needn't be explained, and all four parameters are schema-documented; use cases and exclusions are thorough. The remaining gap is sibling differentiation inside a 40-tool namespace, where get_autovacuum_activity and get_running_vacuum_operations sit closest to this one.

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 limit, schema_name, database_name, and table_pattern are already fully documented in structured fields. The description adds no filtering syntax hints or defaults beyond the schema ('per table', 'tables requiring attention'), which is the expected baseline for a fully-covered 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?

States a specific verb and resource ('Analyze autovacuum configuration and current maintenance status for tables') and enumerates concrete computations (dead tuple ratios vs trigger points, per-table settings, next-run likelihood). An agent can tell this is a read-only configuration/threshold analysis tool. However, it never names the closely overlapping siblings (get_autovacuum_activity, get_running_vacuum_operations, get_vacuum_analyze_stats, get_vacuum_effectiveness_analysis), so the boundary must be inferred from the prohibited 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 'Required Use Cases' section gives explicit trigger phrases and scenarios, and 'Strictly Prohibited Use Cases' cleanly rules out config changes, manual VACUUM, and process control. What it lacks is routing to a specific alternative tool for those excluded needs — it describes the boundaries but does not point the agent at a sibling.

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?

With no annotations, the description carries the burden and mostly succeeds: the prohibited-use list makes clear this is a read-only observation tool, and it discloses real behavior beyond the name — automatic version adaptation, with PostgreSQL 17+ reading a separate checkpointer view. It stops short of stating required privileges or whether the stats are cumulative since reset.

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?

Section headers front-load purpose, functionality, and use cases, so an agent can scan it quickly. It is somewhat longer than needed — the bracketed section headers and the closing 'Returns' sentence largely restate points already made and duplicate the existing output 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?

For a no-param, read-only stats tool with an output schema present, the description supplies what the schema cannot: what the numbers mean, version-dependent behavior, and negative scope. Return-value detail is correctly left to the output schema, so no meaningful gap remains.

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 tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool applies. Nothing in the description misrepresents the empty 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 names a concrete verb+resource pair (analyze background writer and checkpoint statistics) and enumerates the exact statistics exposed (checkpoint timed vs requested, write/sync timing, per-process buffer writes). This clearly separates it from siblings like get_io_stats or get_database_stats, though it never names those alternatives directly.

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?

It gives explicit trigger phrases ("checkpoint stats", "bgwriter performance", "buffer stats"), three concrete diagnostic scenarios, and a dedicated 'Strictly Prohibited Use Cases' block excluding checkpoint execution, parameter changes, and stats resets. This is the full when/when-not/alternative pattern.

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?

With no annotations, the description carries the full burden and does so reasonably: 'Get/Show/Display' make clear this is a read-only, non-destructive introspection call, and the multi-database/connection-context framing explains why it exists. It stops short of stating permission requirements or what happens when the target database is unreachable.

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 bracketed section headers make it scannable and purpose is front-loaded, but the functionality bullets largely restate the opening sentence, and several prohibited use cases (auth changes, config modifications) are things no sane agent would attempt with this tool, so they are low-value padding.

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 is simple, has an output schema documenting return values, and one fully documented optional parameter; the description covers purpose, scope, and triggers adequately. The only real gap is the unmentioned ability to target a different database via the parameter.

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 single optional database_name parameter is already documented in the schema. The description never mentions that a non-default database can be targeted, but with full schema coverage the baseline of 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?

The description names a specific verb and resource ('Get information about the current database connection') and enumerates exactly what is returned (name, encoding, locale, size). It implicitly distinguishes itself from sibling get_database_list by scoping to the *current* connection, but it never names that sibling explicitly.

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?

It gives concrete trigger phrases ('what database am I connected to?') and explicit prohibited categories, which is well above typical. The exclusions, however, are out-of-scope mutating operations rather than real alternatives, and no sibling tool is offered as a substitute for overlapping cases like database size.

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?

With no annotations, the description carries the full behavioral burden, and it does clarify that the tool summarizes and reports rather than performing maintenance, cleanup, or restructuring. It does not explicitly state read-only status, permissions, or rate limits, but its prohibited-use section meaningfully reduces ambiguity about side effects.

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 and front-loads the purpose, functionality, and usage constraints. It is somewhat verbose with labeled sections and repetitive prohibited-use bullets, but the structure remains useful rather than bloated.

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 low complexity, only two optional parameters, full schema description coverage, and an output schema, the description is complete enough for correct invocation. It covers purpose, scope, use cases, and exclusions without needing to explain return values in detail.

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 schema already documents both parameters, including limit and database_name. The description adds no parameter-specific guidance beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: provide a database-wide bloat overview and summary statistics. It clarifies scope with 'across all schemas', 'per schema', and aggregate dead tuple counts, which distinguishes it from table-level siblings such as get_table_bloat_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?

It gives explicit required use cases and strictly prohibited use cases, including when to use it for high-level storage efficiency or maintenance planning. It does not explicitly name alternative sibling tools for more granular analysis, so it stops short of a full when/when-not/alternatives routing statement.

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 annotations, so the description carries the burden: verbs like "Show/Display/Provide" plus the prohibition on resolution actions and statistics reset signal a purely read-only, side-effect-free diagnostic. It also discloses the key constraint that it is only relevant on replicas. It does not mention permission requirements, but that is minor for a stats-read tool.

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?

Bracketed section headers front-load purpose and functionality before use cases, making it easy to scan. Slightly verbose with some overlap between "Exact Functionality" and "Required Use Cases", but no sentence is truly wasted.

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 an output schema present, return values need not be explained, and the single optional parameter is documented in the schema. The description covers use cases, exclusions, and the replica-only constraint, leaving only minor gaps around permissions/limits.

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?

One optional parameter with 100% schema description coverage, so the schema already explains database_name and its default behavior. The description adds no format or selection guidance beyond what the schema states, so 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?

States a specific verb+resource ("Analyze query conflicts") and scopes it to standby/replica environments, which cleanly separates it from siblings like get_replication_status or get_wal_status. The enumerated conflict types (tablespace, lock, snapshot, bufferpin, deadlock) make the resource concrete.

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 both positive triggers ("replication conflicts", "standby conflicts", replica performance troubleshooting) and a strictly prohibited list (conflict resolution actions, replication configuration changes, statistics reset). The agent knows exactly when to select this tool and when not to.

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?

With no annotations, the description carries the disclosure burden and does state this is a read-only listing plus the exact attributes surfaced (owner, encoding, size, connection limit), which is meaningful behavioral context. It omits operational traits such as whether elevated privileges are needed to see all databases or the cost of enumerating a large cluster.

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?

Bracketed section headers make it scannable and the purpose is front-loaded in the first line. There is mild redundancy between the Exact Functionality bullets and the trailing Returns block, which restates the same fields, but no sentence is truly wasteful.

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 zero-parameter read tool with an output schema declared, the description covers purpose, invocation triggers, exclusions and the shape of results, which is essentially everything an agent needs. The only shortfall is the absence of privilege/performance notes, which matter little given the output schema already defines the return values.

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 tool takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing to disambiguate; baseline is 4. The description correctly signals the tool is unfiltered ('all databases') and takes no arguments.

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?

States a specific verb and resource ('Retrieve list of all databases and their basic information on PostgreSQL server') and scopes it to the whole server rather than a single database, which separates it from siblings like get_database_schema_info or get_table_list. The Exact Functionality block enumerates the returned attributes, so an agent knows exactly what this tool answers.

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 explicit positive triggers ('database list', 'DB list', checking what databases exist, size/owner needs) and a Strictly Prohibited list that steers away from tables, schemas, DDL and permissions work. It never names the alternative sibling tools (e.g. get_table_list, get_database_size_info) that should be picked instead, so the routing is implied rather than 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?

No annotations are supplied, so the description carries the load; it does so reasonably by framing the tool as a pure read/introspection call and enumerating the categories of metadata surfaced (owners, privileges, statistics, objects). It stops short of stating explicitly that the call is read-only and side-effect free, and says nothing about cost or permission requirements for reading schema metadata.

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?

Front-loaded with the purpose and organized under labeled sections, so an agent can skim to the relevant block. It is somewhat over-formatted and repetitive — 'Exact Functionality' bullets overlap the 'Required Use Cases' bullets, and 'usage patterns' is vague filler — but nothing is seriously off-topic.

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 two-parameter introspection tool with a full output schema, the description covers scope, contents, and boundaries well enough to call it correctly. The only real gap, given zero annotations, is the absence of an explicit read-only/no-side-effects statement and any note on the permissions needed to view schema metadata.

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 both parameters are already documented in the schema, including the null-means-all-schemas default. The description confirms the all-vs-specific scope behavior in prose but adds no format, syntax, or naming details beyond what the schema supplies.

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 opens with a specific verb+resource (retrieve schema/namespace info and their contents) and enumerates exactly what is returned: schemas, owners, permissions, table counts, sizes, contained objects. It explicitly separates itself from get_table_schema_info, so an agent can distinguish it from that sibling without opening either schema.

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 explicit 'Required Use Cases' (schema overview, namespace structure, org/permission analysis) and explicit 'Strictly Prohibited Use Cases', including a named alternative for table-level detail. This is the when-to-use/when-not/alternative triad stated outright.

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?

With no annotations, the description carries the full burden and discloses that the tool retrieves and analyzes disk usage rather than mutating data, explicitly prohibiting deletion, configuration changes, and backup/restore. It also states the return format as table-format, sorted by size. It does not mention read-only status or permission requirements, but the behavioral boundaries are largely covered.

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 organized into clear sections and front-loads the purpose. It is appropriately sized, though slightly verbose with repeated mentions of storage usage and sorting.

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 zero parameters, an existing output schema, and no annotations, the description is nearly complete: it covers purpose, usage contexts, prohibited contexts, and return shape. It could better distinguish itself from look-alike siblings such as get_database_stats, but an agent has enough to select 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?

The tool has zero parameters, so parameter semantics are not a concern. The description correctly implies no input is needed; baseline for zero parameters is 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 states a specific verb and resource: analyze size and storage usage of all databases in a PostgreSQL server. It distinguishes the scope as server-wide database size rather than table size, but it does not explicitly name or contrast with close siblings such as get_table_size_info or get_database_stats.

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?

It provides explicit required use cases (database size, disk usage, storage space, capacity management, cleanup needs) and strictly prohibited use cases (deletion, configuration changes, backup/restore). It lacks explicit alternatives, but the when/when-not guidance 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?

With no annotations present, the description carries the full burden and does disclose the returned metric families and implicitly establishes read-only behavior via the prohibited-use list (no reset/modification). It stops short of stating which database instance/scope is covered, whether it aggregates across all databases, or the cost/latency of the query.

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?

Front-loaded with a clear purpose line and bracketed sections, but the '[Exact Functionality]' bullet list is substantially restated by the closing 'Returns:' paragraph, so several sentences do not earn their place. The header scaffolding is heavier than the content requires.

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?

An output schema exists, so return values need no further explanation, and with zero parameters and no annotations the remaining burden is modest. The one real gap is scope ambiguity: it never says whether 'database-wide' means the connected database only or all databases, which matters given the get_database_list and get_current_database_info siblings.

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 tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add and the description correctly does not invent any. Schema coverage is 100% for the empty object, leaving nothing unaddressed.

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?

States a specific verb and resource ('Get comprehensive database-wide statistics and performance metrics') and enumerates the exact statistic families returned (transactions, block I/O, tuples, temp files, deadlocks, checksums, I/O timing). The scope word 'database-wide' distinguishes it from the many per-table, per-index, and per-backend I/O siblings in the tool 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?

Provides explicit '[Required Use Cases]' with trigger phrases ('database statistics', 'transaction stats') and an explicit '[Strictly Prohibited Use Cases]' section excluding reset, configuration change, and tuning requests. This is the when/when-not pattern at full strength, though it never names a specific sibling as the alternative.

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?

With no annotations, the description implies a read-oriented analysis tool through verbs like 'Show', 'Identify', and 'Provide', and the prohibited use cases reinforce that it does not perform optimization or configuration changes. However, it does not explicitly state side-effect behavior, permissions, or execution characteristics beyond that implication.

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 and organized into purpose, functionality, use cases, and prohibited use cases. It is somewhat repetitive between the purpose and functionality sections, but the structure makes selection easy and there is little wasted text.

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 a moderate-complexity read-only analysis tool with two fully documented parameters and an output schema, the description covers purpose, selection guidance, and exclusions adequately. It could be more complete by naming sibling alternatives or explicitly confirming read-only behavior, but no critical invocation information is missing.

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 both schema_name and database_name are already documented in the input schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable but not value-adding at the parameter level.

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 states a specific resource and scope: index-level I/O performance statistics including disk reads versus buffer cache hits. It clearly separates index I/O from general or table I/O by repeated use of 'index-level' and 'per index', though it does not explicitly name sibling alternatives.

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?

It provides explicit use cases such as analyzing index-level I/O performance and identifying indexes causing excessive disk I/O, plus prohibited cases like optimization actions, buffer cache configuration changes, and statistics reset. Alternatives among sibling tools are not explicitly named, so it falls short of full when-versus-which 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?

With no annotations, the description carries the full burden. It discloses that the tool analyzes all indexes, identifies unused indexes, and returns scan count and tuple return statistics. It implicitly describes a read-only analysis operation but does not explicitly state that it is non-destructive or mention any performance impact of scanning statistics, leaving a minor gap.

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 organized with clear bracketed sections and front-loads purpose and functionality. It is appropriately sized, though the repeated 'Requests for...' phrasing in the prohibited section adds mild redundancy. Every section earns its place, and no critical information is buried.

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 an output schema, so return values needn't be explained. The single parameter is fully documented in the schema and mentioned in context ('all indexes in database'). The description covers purpose, behavior, and usage constraints well; only explicit read-only/non-destructive confirmation is missing due to the absence of annotations.

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% for the single optional database_name parameter, and the schema already states it 'uses default database if omitted.' The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource: 'Analyze usage rate and performance statistics of all indexes in database.' The bulleted functionality clarifies scope (usage frequency, unused indexes, scan counts, tuple returns). It does not explicitly distinguish itself from the sibling tool get_index_io_stats, so it falls short of a 5.

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 'Required Use Cases' and 'Strictly Prohibited Use Cases.' It tells the agent exactly when to invoke the tool (index usage rate, performance optimization, cleanup) and when not to (creation/deletion, REINDEX, statistics reset). This is precise routing 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?

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses version-gated behavior and a fallback path (pg_stat_io vs pg_statio_*), which materially changes what the agent will get, and it clarifies the operation is read-only by prohibiting tuning/reset actions. It stops short of stating permissions or cost/latency expectations for a stats scan.

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?

Clearly front-loaded with purpose first, then mechanics, then usage gates — good information ordering. The bracketed section labels ([Tool Purpose], [Exact Functionality], [Strictly Prohibited Use Cases]) and some restated phrasing add mild overhead, but no sentence is genuinely wasteful.

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 an output schema present, return values needn't be explained, and both parameters are fully documented in the schema, so the remaining burden is behavioral and routing context — which the version fallback and use-case gates largely cover. The one real gap is disambiguation from the four I/O-focused siblings, which an agent would need in order to pick 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 description coverage is 100% — both 'limit' (1-100, default 20) and 'database_name' are fully documented in the schema. The description adds nothing about what limiting means here (top-N by what?) or how database scoping interacts with instance-level pg_stat_io, so the 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?

The description gives a specific verb+resource ('Analyze comprehensive I/O statistics across all database operations') and even discloses version-dependent implementation (pg_stat_io for 16+, pg_statio_* for 12-15). It does not, however, explicitly distinguish itself from close siblings like get_table_io_stats, get_index_io_stats, or get_per_backend_io_stats, so the agent must infer the scope difference from 'across all database operations'.

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?

Strong explicit context: enumerated trigger phrases ('I/O stats', 'buffer cache analysis'), four use cases, and three strictly prohibited cases (config changes, storage modification, stats reset). What it lacks is named alternatives — it never says to use get_table_io_stats or get_per_backend_io_stats for the narrower scopes, which is the main ambiguity among these 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?

With no annotations, the description carries the full burden and does well: it makes clear this is a read-only listing of current state (explicitly not historical), and that it cannot kill sessions or alter configuration. It does not mention required privileges or the cost of scanning pg_locks on a busy server, which would matter for a diagnostic query.

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 bracketed sections front-load purpose, functionality, and use cases, which is easy to scan. It is somewhat verbose and the 'Required Use Cases' bullets partially repeat the 'Exact Functionality' bullets, but no section is pure filler.

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 six-parameter, read-only diagnostic tool with full schema coverage and an output schema, the description covers purpose, exclusions, and result scope (current state only). The only meaningful omissions are permission requirements and any caveat about how the filters combine.

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 each filter is already documented with examples in the schema; baseline 3 applies. The description's filter list ('granted status, state, mode, lock type, or username') largely restates the schema and even omits the database_name parameter, adding no syntax or interaction guidance.

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 states a specific verb and resource ('Monitor current locks and potential deadlocks in PostgreSQL') and then enumerates exactly what is returned: held/waited locks, blocked and blocking sessions, lock types, wait status. This clearly separates it from siblings like get_wait_events or get_active_connections, which do not report lock-level contention.

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?

It gives explicit required use cases (lock monitoring, deadlock check, blocked sessions, lock-contention performance diagnosis) and an explicit 'Strictly Prohibited' list (killing sessions, changing config, historical data). An agent knows both when to pick this tool and when to look elsewhere.

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?

With no annotations, the description carries the full burden and does well: it discloses the PG 18 dependency, the underlying pg_stat_get_backend_io()/pg_stat_get_backend_wal() functions, and that it degrades to a version notice on older servers. It never explicitly states read-only/non-mutating, but 'Analyze... statistics' plus the prohibited-mutation note makes it clear.

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?

Purpose is front-loaded and the bracketed section headers aid scanning, but the bracketed labels, stray quotes, and repeated note about the underlying functions add bulk. The quoted example phrases are useful for matching; the duplication of the PG 18 note is not.

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?

An output schema exists so return values need not be described, and the version gate plus parameter defaults are covered. What an agent needs to call this correctly is present; only the explicit read-only nature and any result-ordering (e.g., does limit return the top I/O backends?) are implicit.

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 limit (range and default) and database_name fully documented in the schema. The description adds no meaning beyond that, so the 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?

States a specific verb and resource: 'Analyze per-backend I/O and WAL statistics', and names the exact PG 18 functions used. The per-backend scope distinguishes it clearly from siblings like get_io_stats, get_table_io_stats and get_index_io_stats that aggregate at other levels.

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 explicit required use cases (per-backend I/O hotspots, per-connection patterns) and explicit exclusions (backend termination, I/O config changes). The PG 18+ constraint is stated up front with fallback behavior. It stops short of naming sibling tools to redirect to, which keeps it from a 5.

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 annotations are provided, so the description carries the behavioral burden. It clearly describes a retrieval/analysis operation and explicitly prohibits use for query execution, data modification, configuration changes, or data reset, effectively signaling read-only monitoring behavior. It does not mention permission requirements, rate limits, or other operational constraints, so it is strong but not complete.

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 and organized into clear sections for purpose, functionality, required cases, and prohibited cases. It is somewhat repetitive across those sections, repeating 'recently executed queries' and 'detailed monitoring', which keeps it from being maximally 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 the tool's complexity, lack of annotations, complete parameter schema, and existence of an output schema, the description provides enough context to call it correctly. It covers purpose, functionality, appropriate use, prohibited use, and the prerequisite that pg_stat_monitor be installed.

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 both parameters are fully documented in the schema. The description does not add any parameter-specific semantics such as guidance on choosing limit values or using database_name. With the schema doing all parameter documentation, the baseline 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 states a specific verb and resource: analyze recently executed queries using pg_stat_monitor. It distinguishes itself from pg_stat_statements by noting it provides more detailed monitoring including client IP and time bucket information. This is enough for an agent to understand the tool's purpose without opening the schema.

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 has explicit Required Use Cases and Strictly Prohibited Use Cases, including requests for recent queries, detailed monitoring, and pg_stat_monitor, plus exclusions for missing extension, execution/modification, and configuration/reset requests. It does not explicitly name the sibling alternative get_pg_stat_statements_top_queries or state when to choose it instead, which keeps this below a 5.

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?

With no annotations, the description carries the burden well: it names the prerequisite (pg_stat_statements installed), lists the metrics returned (call count, average execution time, cache hit rate), and the prohibited list implies a read-only nature. It does not explicitly declare read-only semantics or any limits, leaving a small gap.

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?

Bracketed section headings front-load purpose, functionality and usage, and every section carries useful content. Slightly verbose formatting but no filler 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?

An output schema exists so return values need not be explained, and the description covers prerequisites, metrics, and scope. Complete enough to call correctly; only read-only semantics and any result-size caveats are unstated.

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 both 'limit' and 'database_name' are fully documented in the schema including default and max. The description adds no parameter-level detail beyond that, so 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?

States a specific verb and resource ('Analyze top queries that consumed the most time') and scopes it to the pg_stat_statements extension, which implicitly separates it from the pg_stat_monitor sibling. It stops short of naming an alternative tool explicitly, so it is clear but not fully differentiated.

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 explicit 'Required Use Cases' (slow queries, performance analysis, tuning) and 'Strictly Prohibited Use Cases' (extension absent, query execution, reset/config changes). An agent has concrete trigger phrases and clear exclusions.

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?

With no annotations, the description carries the burden and does well: the prohibited-use section makes clear this is a read-only tool that cannot change or restart anything, and it discloses that output includes changeability and restart-required flags. It stops short of stating the response format or pagination/limits, so not a full 5.

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 bracketed section headers front-load purpose, functionality, and use cases, and each bullet is a discrete fact. It is somewhat verbose and the functionality bullets partially duplicate the use-case bullets, keeping it below a 5.

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?

An output schema exists, so return values need not be explained, and the description already covers modes, filtering, and safety boundaries. For a two-optional-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema. The description restates the same behavior (all configs when config_name omitted, text filtering with filter_text) without adding syntax, matching rules, or format details beyond the schema, so 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?

The description opens with a specific verb+resource ('Retrieve and analyze PostgreSQL server configuration parameter values') and enumerates exactly what is returned in each mode. An agent can distinguish this from the many sibling stats/monitoring tools because it is explicitly about configuration parameters.

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?

It provides both a '[Required Use Cases]' list of triggering scenarios and a '[Strictly Prohibited Use Cases]' list that rules out mutation, restart, and system-level changes. This is explicit when-to-use and when-not-to-use guidance, leaving little to 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?

No annotations are provided, so the description carries the full disclosure burden, and it discloses very little. 'Returns' implies a read-only operation, but the description never says what happens when both parameters are omitted (presumably full), whether section overrides mode, or what the returned template contains. The three output shapes are named but not characterized.

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 purpose sentence is front-loaded and short, and the two argument lines are tight. The raw 'Args:' block is functional though slightly less polished than prose, and each line does add information. Little waste overall.

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?

An output schema exists, so return-value documentation is not required, and the description correctly focuses on inputs. However, with zero schema coverage and no annotations, the brief argument list is not quite enough—an agent still cannot predict the default behavior or the section/mode interaction before calling.

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 0%, so the description must compensate, and it does partially: 'section' is clarified as 'section number or keyword' and 'mode' enumerates 'full', 'headings', or None. Crucially, it never explains the interaction between the two—what a section means under 'headings' mode, or what mode=None defaults to. This rescues it from a 1 but falls short of full compensation.

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 names a verb ('Returns') and a resource ('the MCP prompt template'), which is enough to grasp the general shape. But 'MCP prompt template' is never anchored to anything concrete—which template, whose prompt, or what content—and nothing distinguishes this tool from its long list of database-inspection siblings. An agent knows it retrieves something template-like but not what.

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?

There is no statement of when to call this versus alternatives, and no explanation of when to use 'headings' mode versus 'full' versus a section lookup. The optionality of both parameters leaves the agent to guess at the intended call patterns. Nothing is misleading, but no routing guidance is offered at all.

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 annotations are provided, so the description carries the behavioral burden; the word 'Monitor' and the prohibited mutation use cases make the read-only nature clear, and the return summary lists the status categories. It does not explicitly state permission requirements, rate limits, or a formal no-side-effects guarantee, but the behavioral profile is sufficiently clear for a zero-parameter status tool.

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 purpose is front-loaded and the bracketed sections are easy to scan. However, the functionality and returns sections repeat status/statistics content, and the structured headings add some verbosity. It remains appropriately sized for a monitoring tool.

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 an output schema present and zero parameters, the description supplies the needed purpose, usage boundaries, and return categories. It omits explicit routing guidance versus the sibling get_wal_status tool, leaving a small gap in context completeness.

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 tool accepts zero parameters, so the baseline is 4. The description appropriately adds no parameter semantics because there are no inputs to explain.

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 names a specific verb and resource: monitor PostgreSQL replication status and statistics. The functionality list scopes this to replication connections, lag, WAL sender/receiver processes, and slots. It is clear, but it does not explicitly distinguish itself from the related sibling tool get_wal_status.

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?

It enumerates concrete required use cases such as replication status, standby lag, replication monitoring, diagnosing replication issues, and checking replication slot usage. It also gives strict prohibited use cases covering configuration changes, slot creation/deletion, and failover/switchover. The guidance is explicit, though it does not name a sibling alternative.

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 annotations are provided, so the description carries the behavioral burden. It makes clear that this is a monitoring/read-oriented tool by stating that it shows and identifies running operations and explicitly prohibits starting, terminating, or changing VACUUM processes. It does not mention privilege requirements or potential monitoring overhead.

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 purpose and functionality, then use cases and exclusions. The bracketed section headers make it slightly verbose, but the structure is clear and each section contributes useful guidance.

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 an output schema present and full schema description coverage, the description does not need to explain return values or parameter details. It supplies the missing behavioral context by describing what is monitored, when to use it, and what it must not be used for.

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 single optional database_name parameter is fully described in the schema. The description does not add filter syntax or behavior beyond the schema's note that omitting the database shows operations across all databases.

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 states a specific monitoring action and resource: currently running VACUUM, ANALYZE, and REINDEX operations in real-time. The real-time, currently-active scope distinguishes it from sibling tools focused on historical vacuum/analyze statistics or autovacuum status.

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?

It gives explicit trigger phrases and use cases such as checking running VACUUM, troubleshooting stuck operations, and monitoring progress. It also clearly lists prohibited use cases, including terminating, starting, or configuring VACUUM operations, which prevents misuse.

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?

With no annotations, the description carries the full burden and does well: it discloses that only retrieval occurs, that connection settings are password-masked, and that extension availability is checked. It stops short of stating permission requirements or behavior when the server is unreachable (e.g., error vs. partial result), which keeps it from a 5.

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?

Bracketed section headers front-load purpose, functionality, use cases, and prohibitions in a scannable order with no filler sentences. It is somewhat longer than strictly necessary for a zero-argument status tool, but every section carries routing or scoping 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?

For a no-parameter read-only status tool, the description covers what it returns, when to call it, and when not to, and an output schema exists to carry return-value detail. An agent has everything needed to select and invoke 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?

The tool takes zero parameters, so the baseline is 4; the description correctly implies no inputs are needed and adds nothing misleading about arguments.

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?

States a specific verb and resource ("Check basic information and connection status of PostgreSQL server") and enumerates exactly what it retrieves: version, connection settings, accessibility, extension install status. That scope is clearly distinct from siblings like get_postgresql_config, get_database_stats, or get_active_connections.

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 explicit trigger phrases ("server info", "PostgreSQL status", "connection check"), contextual triggers (preliminary check before monitoring tools), and a 'Strictly Prohibited' list that routes performance stats, table data, and config changes to the correct sibling 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?

With no annotations, the description carries the full burden, and it does most of the work: it makes clear this is a read-only analysis that never executes VACUUM or modifies data, and explains that results are derived from dead tuple statistics and sorted by severity. It does not disclose cost/performance on large catalogs or the scope of scanning when schema_name is omitted, which are the remaining behavioral gaps.

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?

Headers (Purpose / Exact Functionality / Use Cases / Prohibited) make it front-loaded and skimmable, and each bullet is a distinct fact rather than filler. It is longer than strictly necessary for a single filtered-read tool, with some redundancy between the purpose line and the functionality bullets.

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?

An output schema exists, so return values need no explanation, and all five parameters are optional and schema-documented; the description fills in the analysis semantics and the safety boundaries an agent needs. The one missing piece is how to choose between this tool and get_database_bloat_overview or get_vacuum_analyze_stats when the user's intent is ambiguous.

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 real value by specifying that table_pattern supports SQL LIKE or ILIKE matching and by stating that schema_name omitted means 'all user schemas' and that database_name falls back to POSTGRES_DB. It does not elaborate on limit or min_dead_tuples beyond the schema text, so it stops short of a 5.

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 names a specific verb and resource ('Analyze table bloat based on dead tuple statistics and size information') and enumerates exactly what is computed (bloat ratio, bloat size, last VACUUM timestamps, severity sorting). It is clear what the tool does, but it never distinguishes itself from the closely-related siblings get_database_bloat_overview or get_table_size_info, so an agent must infer the split.

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?

It provides explicit 'Required Use Cases' with literal trigger phrases ('table bloat', 'dead tuples') and an explicit 'Strictly Prohibited Use Cases' block ruling out VACUUM execution, cleanup, and data modification. This is a full when-to-use / when-not-to-use contract, with only the sibling routing left implicit.

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 annotations are provided, so the description carries the full behavioral burden. It implies a read-only analytical operation and explicitly prohibits optimization actions, configuration changes, and resets, but it does not explicitly state read-only behavior, permissions, performance impact, or any rate/scope limits.

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 purpose and organized into useful sections. It is somewhat over-structured with bracketed headings, but each section adds practical guidance and avoids true 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 an output schema present and only two optional parameters, the description covers purpose, functionality, and use-case boundaries adequately. It still lacks explicit alternative routing among the many I/O-related sibling tools and explicit read-only behavioral disclosure.

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 parameters are already documented in the schema. The description does not add meaning about schema_name or database_name beyond what the schema provides, so the baseline 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 states a specific verb and resource: analyze table-level I/O performance statistics, including heap, index, and TOAST components. It is clear, but it does not explicitly differentiate itself from close siblings such as get_io_stats or get_index_io_stats.

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?

It gives explicit required use cases and a strict prohibited-use list, so the agent knows when to call it and when not to. It does not name alternative sibling tools for related I/O requests, which keeps it just short of a 5.

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

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

No annotations exist, so the description carries the full burden. It discloses what is returned (schema, owner, size, table-type distinction) and that read-only intent, but says nothing about privilege requirements, cost on large catalogs, or how views/foreign tables are labeled in output. Adequate but with real gaps for an unannotated tool.

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?

Bracketed section headers make the content scannable and front-loaded, with purpose stated before details. The formatting is slightly heavy for a one-parameter list operation, but each block carries distinct information and nothing is redundant filler.

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?

An output schema exists, so return-value shape need not be spelled out, and the description still summarizes the key fields. Combined with explicit scope and exclusions, an agent has what it needs to invoke correctly; only privilege and performance behavior are unaddressed.

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% and the single parameter already documents that omitting it uses the current database. The description's parenthetical '(or current DB)' merely repeats that, adding no 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?

States a specific verb and resource: retrieve the list of all tables plus schema, owner, and size, from a named or current database. It also implicitly separates itself from get_table_schema_info by prohibiting 'detailed column information of specific tables'. It does not name those siblings directly, so a 4 rather than a 5.

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?

Gives both a 'Required Use Cases' list and a 'Strictly Prohibited Use Cases' list, which is stronger than most definitions. The exclusions route the agent away from data queries, DDL, and detailed column lookups, but they are phrased as categories rather than naming the actual sibling tools (get_table_schema_info, get_all_tables_stats), so the routing is inferential.

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?

With no annotations, the description must carry the behavioral burden, and it largely does: it makes clear the tool is a read-only analysis (modification/DDL is prohibited), discloses the categories of output (inbound/outbound FKs, dependencies, inheritance, orphans), and sets scope (database-wide vs. single table). It does not mention cost/latency on large schemas or required privileges, which keeps it from a 5.

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 bracketed section headers make it highly scannable and front-load purpose before use cases. It is slightly verbose with some redundancy between the functionality list and the use-case examples, but every block contributes actionable 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?

An output schema exists, so return-value description is unnecessary, and the description fully covers purpose, scope (database-wide vs. table-specific), allowed and disallowed scenarios. Nothing an agent needs to decide to call this tool and pass correct arguments is missing.

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 all four parameters (including the optional table_name and the relationship_type filter) are already documented in the schema. The description adds no syntax, format, or behavioral nuance about these parameters beyond what the schema states, so the 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?

The description opens with a specific verb+resource ('Analyze table relationships') and enumerates the exact relationship classes covered (foreign keys, view dependencies, inheritance/partitions, orphaned tables). This clearly separates it from neighbors like get_table_schema_info or get_table_list, which deal with structure and inventory rather than relational topology.

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?

It provides explicit 'Required Use Cases' with trigger phrases ("table relationships", "foreign keys", "dependencies") and an explicit 'Strictly Prohibited Use Cases' block excluding data retrieval, DDL/modification, and performance statistics. This is the strongest form of when/when-not guidance, and it routes the agent away from misuse.

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