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

The annotations already declare readOnlyHint=true, and the description's '[READ]' tag merely restates that. Beyond the safety profile it discloses nothing behavioral: no ordering, no truncation semantics for limit, no cost/performance caveat for inspecting many tables, no indication of what a missing target does.

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?

Tight, front-loaded two-part structure with no filler sentences. The redundant '[READ]' prefix is the only wasted token, since readOnlyHint already covers it.

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

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

With no output schema, the description does outline the returned columns, which is the main gap it needs to fill. It stops short of stating ordering, whether limit truncates the highest-risk tables, or the behavior for an unknown target, leaving an agent guessing about result shape for a two-param diagnostic tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: limit is defined as the number of tables to inspect, and target is explained as a config target name whose omission yields the default. It misses only how limit interacts with result ordering/cutoff.

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?

Names a specific resource (autovacuum status) and enumerates the metrics returned: per-table dead tuples, mods-since-analyze, and last (auto)vacuum times. That is enough to distinguish it from run_vacuum/run_analyze, though it never explicitly contrasts itself with the adjacent bloat_and_vacuum_analysis sibling.

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

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

No statement of when to reach for this versus bloat_and_vacuum_analysis or the run_vacuum/run_analyze actions. The only usage-like guidance is that target may be omitted for the default, which is a parameter note rather than a usage rule.

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

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

Annotations only supply readOnlyHint=true; the description adds real operational context by disclosing the two execution modes (injected rows vs live pull) and that recommendations carry their cited numbers. No permissions, rate limits, or return shape are described, which keeps it below a 5 for a live-querying 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?

Front-loads the [READ] marker and core purpose, then follows with the mode guidance and a compact Args block. The Args section partly restates the prose, but the total length is proportionate to a three-parameter 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 no output schema and only a readOnly annotation, the description covers the calling modes and all parameters, and hints at output ('cites its numbers'). It stops short of stating prerequisites or the shape/ordering of the ranking, but nothing essential for correct invocation 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 0%, so the description carries the full burden and it does explain all three params: 'tables' as injected table-bloat rows, 'limit' as how many to pull when not injected, and 'target' as a named config entry. 'target' in particular stays vague ('Target name from config'), so it compensates well but not fully.

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?

Names a specific verb and resource ('Rank tables needing vacuum') plus the exact inputs it ranks by ('dead-tuple ratio + autovacuum recency'). This is distinguishable from siblings like table_bloat (raw bloat report) and run_vacuum (the fix), and the [READ] tag further pins it as a diagnostic.

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 explicit invocation modes: pass 'tables' (as produced by table_bloat) for offline analysis, or omit it to pull the worst tables live. It names a sibling as the upstream source, but does not state when to prefer this over autovacuum_status or run_vacuum for acting on the results.

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?

readOnlyHint=true is consistent with the '[READ]' tag, so no contradiction. The description adds real behavioral context beyond annotations: omitting 'pairs' triggers a live pull from pg_blocking_pids, while supplying it enables offline analysis. No mention of permissions or result volume, but the annotation already covers the safety profile.

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-loads the '[READ]' marker and core purpose, then usage modes, then parameter notes. Every line earns its place with no padding or redundancy.

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

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

With no output schema, the description should ideally sketch the return shape; it implies one ('the wait-for tree' and root blocker name) but does not describe it. For a 2-param read-only tool it is otherwise complete: purpose, mode selection, and both parameter behaviors are present.

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 has to carry the load, and it does: 'pairs' is explained as {blockedPid, blockingPid, ...} with a live fallback, and 'target' as a config name with default fallback. It adds genuine meaning the schema lacks, though the structure is shown only by example rather than fully specified.

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 output: 'Build the wait-for tree from blocking pairs and name the root blocker,' which is clearly distinct from sibling reads like list_locks or list_activity. It does not explicitly name a sibling to contrast against, so it falls just short of top marks.

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 a clear usage fork: pass 'pairs' for pure/offline analysis, or omit to pull the blocking graph live. This is actionable context, though it addresses which mode to use rather than when to pick this tool over alternatives like slow_query_rca or list_locks.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds context the annotations cannot carry: there is no undo, the pid+query are captured for audit, and the tool self-protects by refusing to cancel its own backend pid even under dry_run. That last detail is a non-obvious behavioral guardrail that directly affects whether a call succeeds.

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 risk tag and the purpose are front-loaded, and the Args block is compact with no filler. Slightly verbose in the audit/no-inverse paragraph, but every sentence conveys decision-relevant behavior.

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 high-risk, non-idempotent mutation with no output schema and no annotated permission model, the description supplies everything needed: irreversibility, preview path, audit side effect, parameter sources, and the self-pid refusal. Nothing material is missing for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: pid is sourced from list_activity, dry_run is defined as a preview flag, and target is explained as a config name with omission defaulting to the default target. All three parameters are covered with meaning beyond their bare types.

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 (cancel a backend's running query) plus the underlying primitive (pg_cancel_backend), which immediately separates it from terminate_backend in the sibling list. 'No inverse' pins down the semantics precisely in four words.

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?

Tells the agent when to preview (dry_run=True) and where the pid comes from (list_activity), which is real routing guidance. It does not explicitly say when to choose this over terminate_backend, so an agent must infer the query-vs-session distinction on its own.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: reversibility via a recorded undo ('undo drops the created name'), the CONCURRENTLY non-blocking trait, dry-run preview, and shape validation on definition. This is real behavioral disclosure the annotations do not carry.

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-loads the operation, risk level, and reversibility, then uses a clean Args block. Given 9 parameters and zero schema coverage, every sentence earns its place with no 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 9-parameter write tool with no output schema and no schema descriptions, the definition covers inputs, behavioral traits, reversibility, preview mode, and even the return value ('the created name is returned'). 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 0% and the schema only carries titles/defaults, so the description must compensate. It documents all 9 parameters with meaning: schema-qualified table, auto-generated name, the btree/hash/gist/gin/brin/spgist method list (an enum not present in the schema), and the mutual exclusivity of definition vs table/columns. This adds meaning well beyond the raw 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+resource ('Create an index') with an explicit [WRITE][risk=medium] tag and the reversible undo semantics. It also implicitly separates itself from drop_index and reindex siblings by describing the recursive undo relationship.

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 clear selection guidance for its own options: CONCURRENTLY for non-blocking builds, dry_run=True to preview, and 'definition INSTEAD of table/columns' as the mutually exclusive alternative. It lacks any explicit when-not-to-use or routing to reindex/drop_index, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the operation is reversible because pg_get_indexdef is captured first, the undo recreates the index, and CONCURRENTLY avoids a table lock. It omits failure modes and required privileges, but the core behavioral contract is well disclosed.

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

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

Front-loads the risk marker and one-line purpose, then adds the reversibility mechanism before the argument list. Slightly redundant in restating reversibility twice, but every sentence carries operational information and nothing 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?

With no output schema, four parameters at 0% schema coverage, and a destructive annotation profile, the description supplies the essential safety context (reversibility, preview mode, lock behavior). Remaining gaps — permission requirements and behavior on failure — are minor for a drop-a-single-object tool.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it documents all four parameters with added meaning: schema-qualified index names, CONCURRENTLY meaning no table lock, dry_run as preview-only, and target as a config name that defaults when omitted. The coverage is complete, though the explanations are terse rather than rich.

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 (drop an index) and immediately flags it as a write operation with high risk, distinguishing it from siblings like create_index, reindex and invalid_indexes. The scope of the operation is unambiguous from the first sentence.

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 clear operational context: preview with dry_run=True before dropping, and the harness captures the definition so the drop can be undone. It does not explicitly name alternatives (e.g. reindex vs. drop, or point to undo_apply for reversal), so it stops short of full when/when-not 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?

The readOnlyHint annotation only tells the agent the tool is safe; the description goes further by disclosing the key behavioral trait that the annotation cannot express — that analyze=True actually executes the statement to gather real timings, while the default does not execute at all. It also explains target resolution ('Target name from config; omit for the default').

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 one-line purpose, then the default/analyze behavior, then a compact Args block. Every sentence adds information; the only cosmetic nit is the double-backtick around ``sql``.

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

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

With no output schema, the description still names the return value (a JSON execution plan), and it covers the analyze safety caveat and the target default for a 3-parameter tool. Nothing needed to invoke 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 description coverage is 0%, so the description carries the full burden, and it does: sql is defined as a single statement to EXPLAIN, analyze as the execute-for-real-timing switch, and target as a config target name that can be omitted. All three parameters gain meaning absent from the schema.

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

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

The description states a specific verb and resource: return the JSON execution plan for a given SQL statement (EXPLAIN). Combined with the '[READ]' tag and the explicit default-vs-analyze split, an agent can immediately tell this is the plan-inspection tool, distinct from the query-statistics siblings like top_queries or slow_query_rca.

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 clearly states the conditional behavior of the analyze flag and gives an explicit guardrail: 'only use it for read-only SQL'. That is strong when-to-use guidance for the main parameter decision, though it never mentions when to prefer sibling diagnostics over EXPLAIN.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' tag adds no credit. The description does add genuinely useful behavioral context beyond annotations: results are a 'coarse' estimate and 'all inputs returned for transparency', telling the agent not to treat the numbers as exact.

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 core purpose leads, followed by a compact Args block; each sentence and line carries information. Minor redundancy in labeling a read-only tool with '[READ]' when the annotation already says so.

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 read-only tool the parameter documentation is adequate, but with no output schema the description should sketch what a 'coarse estimate' returns (fields, units, whether bloat is a ratio or bytes) and what a 'target' refers to in config. These gaps leave the agent guessing about result interpretation.

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 0%, so the description carries the full burden, and it does: 'limit' is documented as the number of indexes to inspect, ordered largest first, with default 50, and 'target' is explained as a config name that can be omitted. The ordering semantics ('largest first') are meaning the schema does not convey.

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 resource (index bloat) and scope ('coarse ... estimate'), which separates it from the sibling table_bloat and the heavier bloat_and_vacuum_analysis. It is clear about what it returns at a high level, though it never explicitly names the sibling it differs from.

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 word 'coarse' implies this is a quick screening call rather than the deeper bloat_and_vacuum_analysis, so usage is implied but never stated. There is no explicit when-to-use, when-not-to-use, or prerequisite 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?

The readOnlyHint annotation already declares this a safe read, and the [READ] tag merely restates it. The description does add one genuinely useful piece of behavior: that 'invalid' means a failed CONCURRENTLY build, which is not derivable from annotations or schema. It says nothing about output shape or whether duplicates are reported separately.

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 operation type and subject, then a short args block that earns its place by explaining the one parameter. No filler, though the '[READ]' prefix is redundant with the readOnlyHint annotation.

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 single-optional-parameter read-only listing tool with no output schema, the description covers what it returns (the two index problem classes) and how to address the target. It is close to complete; only the absence of any selection guidance against sibling index tools keeps it short of full marks.

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 carries the burden, and it does: 'target' is identified as a name from config and the null default is explained as 'omit for the default'. This meaningfully exceeds the bare anyOf[string,null] schema, though it doesn't say what targets are available.

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 precise resource - invalid indexes and duplicate indexes - and even defines the term of art ('failed CONCURRENTLY builds'). An agent can immediately tell this apart from siblings like unused_indexes or index_bloat without opening any 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?

There is no guidance on when to reach for this tool versus the adjacent index tools (unused_indexes, index_bloat, reindex, drop_index). The only usage-like text, 'omit for the default', is parameter behavior rather than when-to-use context.

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?

readOnlyHint=true already covers the safety profile, and the '[READ]' tag plus the description's note about idle-in-transaction backends holding resources adds genuine context about what gets surfaced. It does not disclose result ordering, row volume, or whether it touches the target server in a costly way.

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-loads the [READ] marker and a one-line summary, then adds a single relevant caution before the arg list. Every line earns its place; only the args block is mildly redundant with the 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?

With no output schema, the description adequately signals the return shape ('per-state counts', flagged idle-in-transaction backends) and documents all three parameters. Cross-references to sibling diagnostic tools are the only notable omission.

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 schema alone gives only titles and defaults; the description compensates by enumerating valid state values (active, idle, 'idle in transaction'), restating the include_idle default with intent, and explaining that target comes from config and defaults when omitted.

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 ('Current sessions (pg_stat_activity) with per-state counts'), naming the underlying catalog view and the shape of the result. It implicitly separates itself from lock/query siblings but never names or contrasts them, so it stops short of full sibling differentiation.

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?

Usage is implied by the 'flags idle-in-transaction backends (open transactions holding resources)' note and the state/include_idle knobs, which tell the agent this is a session-inspection tool. There is no explicit when-to-use versus list_locks or long_running_queries, and no stated prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' tag is redundant with structured data. The description does add useful context about the returned fields and ordering, but says nothing about pagination, filtering, or connection/permission requirements. With annotations carrying the safety profile, this is adequate but thin.

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-loads the substance (what is listed and how it is sorted) in one line, with the parameter note kept short. No wasted sentences.

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

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

For a simple read-only listing tool with no output schema, the description supplies enough: what the rows contain and the sort order. Missing only edge-case behavior (empty results, error handling), which is minor here.

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 carry the burden, and it does: it explains that 'target' is a config name and that omitting it uses the default. That default behavior is meaningful semantic information the schema does not provide.

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 (list) and resource (databases) and even specifies what each row contains (owner, encoding, on-disk size) plus sort order (largest first), which clearly separates it from table_sizes or list_activity. It stops short of naming a sibling it might be confused with, but the purpose is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance and no alternatives referenced among the many sibling list/inspection tools. Usage is only implied by the tool name.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix merely restates that. The description does add one non-obvious behavioral fact — that it reports newer-version availability — but says nothing about permissions, connection scope, or output shape.

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 verb and resource, and the Args block is minimal with no filler. Appropriately sized for a one-parameter read 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?

For a simple read-only list tool with one optional parameter and no output schema, the definition is adequate but leaves the return format and connection/permission context unspecified.

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 0% for the single optional `target` param, but the description compensates by explaining it is a 'Target name from config' and that omitting it yields the default. That adds real meaning beyond the bare schema, though no format examples are given.

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

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

States a specific verb (list) and resource (installed extensions) plus a useful scope detail (whether a newer version is available). It is clearly distinct from siblings like list_databases and list_roles, though it does not explicitly name an alternative.

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 no when-to-use guidance, prerequisites, or alternatives; the only contextual hint is 'omit for the default' for the target param. Usage is implied only by the clear resource name.

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

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

The readOnlyHint annotation already establishes this is a safe read, and the '[READ]' prefix merely restates it. The description does contribute useful behavioral context beyond the annotation by stating that lock rows are joined to the owning backend and object, but it says nothing about volume, ordering, or permissions required to see other backends' locks.

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

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

Two short lines, front-loaded with the operation and scope, followed by a single argument note. No filler, nothing that restates the tool name or the annotation.

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 one-parameter, read-only listing tool with a readOnlyHint annotation and no output schema, the description covers the action, the scope of the join, and the single argument. A brief note on what the returned columns/ordering look like would make it fully self-sufficient.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it explains that 'target' is a target name from config and that omitting it selects the default. That is more than the schema's bare anyOf[string, null] reveals, though it does not say where the config names come from or whether the name is case-sensitive.

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 (list held/awaited locks) and adds scope detail ('joined to their owning backend and object'), so an agent knows it is a raw lock listing rather than an analysis tool. It does not name the closer sibling blocking_lock_chain_rca, so it stops short of full sibling differentiation.

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?

Usage is only implied: the description frames this as a raw inventory of held and awaited locks, which an agent can infer is the prerequisite view before reaching for blocking_lock_chain_rca. There is no explicit when-to-use, when-not-to-use, or alternative guidance anywhere in the text.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, so the '[READ]' prefix is largely redundant. The description does add value by naming the attributes exposed (superuser/login/replication), but it omits any hint about privileges needed to enumerate roles or the shape of the result.

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?

Very short and front-loaded: purpose first, then a compact Args block. The bracketed '[READ]' tag is mildly redundant with the annotation but costs almost nothing.

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 single-optional-parameter, read-only listing tool with no output schema, the description covers purpose and parameter semantics adequately. Only the absence of return-format or privilege context keeps it from being fully complete.

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

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

Schema coverage is 0% and the schema only declares an anyOf string/null with default null, so the description carries the burden. It does so well: 'target: Target name from config; omit for the default' explains both the meaning and the default behavior of the sole parameter.

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 ('list' + 'roles') and even enumerates the attribute types returned (superuser/login/replication). No sibling tool overlaps with role listing, so no differentiation is needed; the '[READ]' tag is decorative but the core statement is clear.

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 never says when to use this tool versus alternatives, nor does it give conditions or exclusions. The only usage-like hint is the parameter note 'omit for the default', which is about the argument, not tool selection.

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

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

The readOnlyHint annotation already declares this a safe read. The description adds the ordering behavior (oldest first) and the notion of 'active' queries, but says nothing about pagination, result size limits, or whether terminated/finished queries are excluded. With annotations covering the safety profile, this is adequate but not rich.

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 [READ] tag and a single-sentence summary before the Args block, so the essential scope is visible immediately. The Args formatting is slightly verbose but each line earns its place.

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

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

With no output schema, no required params, and a simple read, the description covers both parameters and the core behavior sufficiently. Only the exclusion of sibling tools and any return-shape hints are missing, which are minor 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 coverage is 0%, so the description must carry the param burden, and it does: min_seconds is defined as minimum age in seconds with default 60, and target is explained as a config target name with an omit-for-default rule. Both parameters gain meaning the bare schema lacks.

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 resource (active queries), a threshold scope (running at least min_seconds), and an ordering (oldest first), which is more than a tautology. It does not, however, differentiate itself from siblings like top_queries, slow_query_rca, or list_activity, so an agent must still infer the boundary 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?

There is no when-to-use guidance and no named alternatives despite a crowded sibling set (top_queries, slow_query_rca, list_locks, list_activity). The description never says when this tool is preferable to those, leaving selection entirely 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?

Annotations already declare readOnlyHint=true, and the description adds only a redundant [READ] prefix. It does not disclose what the output looks like, how 'few index scans' is computed, whether thresholds are cumulative or per-table, or any cost/scan concern — all of which would be new information beyond the annotation.

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, one-line purpose followed by a compact Args block with no filler. The defaults repeated in the prose duplicate what the schema already declares, which is minor 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?

For a read-only diagnostic with three optional params and no output schema, the definition covers inputs adequately but says nothing about the shape of results (per-table rows? suggested indexes?), which an agent would need to interpret the response. Adequate but with a clear gap.

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

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

With schema description coverage at 0%, the description carries the full burden and mostly succeeds: min_seq_scan (cumulative sequential scans to flag, default 1000), min_live_tup (minimum live tuples to qualify, default 10000), and target (config target name; omit for default) each get a one-line meaning. Only 'target' remains vague about what a target actually is.

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 resource (tables with heavy sequential scans and few index scans) and frames it as a read-only diagnostic, which separates it from siblings like unused_indexes, index_bloat, or invalid_indexes. It stops short of explicitly stating the outcome, e.g. that it surfaces candidate tables for a new index, so an agent must infer the use case from 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?

There is no guidance on when to reach for this tool versus top_queries, unused_indexes, or explain_query, nor any exclusions. The only usage information is the parameter list, which describes knobs rather than context.

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

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

Annotations already carry readOnlyHint=true, so the '[READ]' tag is redundant. The genuinely additive detail is that each section is captured defensively so a failing probe does not sink the rest, telling the agent to expect partial results and a possibly degraded snapshot. It does not mention permissions, cost, or rate limits, but the partial-result disclosure is real value beyond the annotation.

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 read tag and the snapshot purpose, then the return content, then args. The enumerated section list is long but every item is informative rather than padding, and there is no 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?

There is no output schema, so the description bears the burden of describing returns — and it enumerates the sections returned plus the defensive partial-result behavior. It is complete enough to call correctly, though it says nothing about the shape/format of each section or ordering.

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 0% and the schema only shows 'target' as a nullable string, so the description has to carry the semantics — and it does: 'Target name from config; omit for the default' explains the value's origin and the default behavior. It stops short of naming where config targets come from or listing valid values, keeping it a 4 rather than 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?

States a specific verb+resource up front ('One-shot cluster health snapshot') and then enumerates the exact signals returned (uptime, connections by state, idle-in-transaction, longest query, worst dead-tuple table, standby replay lag). This aggregate framing distinguishes it from the single-purpose siblings like list_activity, server_version, and replication_status without opening any 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 'one-shot' framing implies a quick overall health check, and the enumerated content implies it aggregates what siblings cover piecemeal, but the description never states when to use it versus those siblings (e.g. use overview for a quick triage, then drill into long_running_queries or replication_status). Usage is inferable but not explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real context beyond them: 'rebuild in place, no undo' and 'there is no inverse,' plus a safe preview path via dry_run. It stops short of describing locking impact or expected duration, which CONCURRENTLY implies but never explains.

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?

Risk/write tags and the destructive caveat are front-loaded, and the args list is compact with no filler. The docs mirror the parameter names closely enough that a few lines are near-redundant, but nothing is padded.

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 5-parameter, 0%-schema-coverage mutation tool with no output schema, the description supplies the essential missing semantics (destructiveness, irreversibility, preview flag, kind values). It leaves gaps on concurrency/locking behavior and post-run effects, but covers enough for correct invocation.

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 carries the full burden and documents all five parameters, including the kind enum values (INDEX, TABLE, SCHEMA) and the config-sourced 'target'. The 'concurrently' entry merely restates the field name ('Rebuild with CONCURRENTLY') without explaining reduced locking, so it is not complete.

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?

Starts with a specific verb+resource ('REINDEX an index/table/schema') and adds a parenthetical that clarifies semantics ('rebuild in place, no undo'), which cleanly separates it from siblings like run_vacuum, run_analyze, and create_index.

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 one concrete usage pointer ('Pass dry_run=True to preview'), which is helpful, but never states when to choose reindex over run_vacuum/create_index or when reindexing is inappropriate. Usage is implied rather than framed against alternatives.

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

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

The readOnlyHint annotation already establishes the safety profile, and '[READ]' merely restates it. The description does add useful behavioral value by disclosing that it identifies inactive slots retaining WAL, which tells the agent what the output is for, but it says nothing about ordering, fields, or thresholds.

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?

Very short and front-loaded; the purpose leads and the argument follows. The trailing 'Args:' block is slightly wasteful formatting but costs nothing in comprehension.

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

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

With no output schema, the description supplies the essential return-value framing (inactive slots retaining WAL) and the sole parameter's meaning. It is close to sufficient for a single-parameter read-only diagnostic, missing only detail about the returned fields.

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 0%, so the description must carry the parameter alone, and it does: 'target' is a named target from config, and omitting it selects the default. That is exactly the semantics the schema lacks, though no format or valid-value examples are given.

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

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

States a specific resource (replication slots) plus the key diagnostic behavior: flagging inactive slots that retain WAL. It is distinguishable from siblings like replication_status and wal_status, though it never explicitly contrasts itself with 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?

Usage is only implied — the topic (replication slots) tells an agent when it might be relevant, and the target guidance hints at multi-target setups, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many replication/WAL siblings.

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

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

Annotations already declare readOnlyHint=true, and the description's '[READ]' tag merely restates that. Beyond the data-source name, it discloses nothing about behavior for a read-only monitoring tool: that results may be empty with no standbys, that visibility of all rows requires pg_monitor/superuser privileges, or what the lag columns represent.

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 operation and scope in one line, then a compact Args block. Minor waste in the '[READ]' tag that duplicates the annotation, and the trailing blank line, but overall tight.

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

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

With no output schema, the description does state what is returned (standbys and replay lag), which is the key gap it must fill. It omits privilege requirements and empty-result behavior, which matter for a monitoring query against a stats view.

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: it explains that target is a config name and that omitting it selects the default, which the bare anyOf/null schema does not convey. It stops short of saying what values are valid or what happens with an unknown target.

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 resource and what is reported: connected standbys and their replay lag, and names the underlying source (pg_stat_replication). This is clearly separable from siblings like replication_slots and wal_status, which cover different replication objects.

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?

Usage is implied by the content ('replay lag' clearly signals replication-lag monitoring), but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as replication_slots or wal_status for adjacent replication questions.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description goes further by explaining that counters cannot be restored and that no undo is recorded, which is meaningful context beyond the structured hints, though it stops short of naming required privileges or side effects on other sessions.

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 risk tag and irreversibility statement are front-loaded, and the Args section is compact. The bracketed [WRITE] tag and prose restating the same caution are slightly redundant, but nothing is wasted at length.

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

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

With no output schema and only two optional parameters, the description covers the destructive nature, the dry-run escape hatch, and the meaning of both params. An agent has enough to invoke it safely, missing only what the call returns and any permission requirements.

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 carries the burden and does document both parameters: dry_run as a preview toggle and target as a config name with a default fallback. It lacks any format or naming examples for target, but both params are meaningfully explained.

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 (Reset) and resource (pg_stat_statements accumulators), and the irreversible qualifier narrows the meaning further. It is clearly distinguishable from siblings like cancel_query, terminate_backend, or undo_apply, none of which reset statistics counters.

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 dry_run preview instruction implies a safe practice for using the tool, but the description never states when a user should reset stats versus simply reading them via top_queries or list_activity. No explicit alternatives or when-not conditions are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds genuinely non-derivable context: 'No undo', prior stats 'captured for audit', a risk=medium label, and a preview path via dry_run. It stops short of describing permissions, locking impact on concurrent queries, or cost/duration.

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 write/risk tag, then the effect, reversibility, and preview hint in three short sentences before the Args list. Efficient overall, with minor waste from restating the dry_run preview hint twice and from the Args block repeating names already in the schema, though at 0% coverage that block still earns its place.

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

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

For a 3-parameter mutation tool with no output schema, the description covers what changes (planner statistics), reversibility and audit capture, preview mode, and all three parameters. It leaves unclear what the call returns (no output schema exists) and omits concurrency/locking implications, so it is strong but not exhaustive.

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 carry the parameter burden, and it does: 'table' is documented as optionally schema-qualified, 'dry_run' as a no-execution preview, and 'target' as a config lookup where omission means the default. The only shortfall is that the dry_run explanation is duplicated between the body and the Args block rather than expanded.

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 (ANALYZE) and resource (a table) plus the effect (refresh planner statistics), and fronts it with a [WRITE][risk=medium] tag that signals mutation scope. It does not name or contrast any sibling (run_vacuum, reindex), which is the only thing keeping it from a 5, though ANALYZE is naturally distinct from the maintenance siblings.

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?

Usage is implied by the purpose (maintenance op to refresh stats) and there is one actionable instruction, 'Pass dry_run=True to preview.' There is no explicit when-to-use/when-not guidance and no routing to alternatives such as run_vacuum, which is a clear gap for a write tool in a crowded maintenance sibling set.

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

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

Annotations only declare destructive=true/non-idempotent; the description goes well beyond by disclosing that vacuums have no inverse, that prior dead-tuple/last-vacuum stats are captured for audit, and that VACUUM FULL takes an exclusive lock. It even offers a dry_run escape hatch. This is exactly the kind of behavioral context that matters for a destructive operation.

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?

Risk/verb front-loaded in the first line, behavioral caveats next, then a tight Args list. No wasted sentences; every line earns its place.

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

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

For a destructive, no-output-schema tool, the definition covers what changes, irreversibility, locking impact, preview mechanism, and all parameters. An agent has everything needed to invoke it safely.

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 carry all five parameters, and it does: table (with schema-qualification example), full (rewrite + exclusive lock), analyze (VACUUM ANALYZE), dry_run (preview), and target (config target, omit for default). Each adds meaning the bare schema lacks.

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 (VACUUM) and resource (a table), with modifiers FULL/ANALYZE called out. The [WRITE][risk=medium] tag immediately separates it from read-only siblings like bloat_and_vacuum_analysis or list_locks, so an agent can route correctly 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?

Implies context through parameter docs (dry_run preview, target selection) and notes risk, but never says when to prefer this over run_analyze or bloat_and_vacuum_analysis, nor when not to vacuum. Usage is inferable but no explicit alternatives or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so the '[READ]' prefix adds nothing. The description does add value by enumerating the returned data points (version, uptime, recovery state, data directory), which gives the agent a sense of what a call yields, but it says nothing about permissions, connection scope, or failure behavior.

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?

Very short and front-loaded: the purpose sentence comes first, then a compact Args block. The Google-style docstring formatting ('Args:') is slightly mechanical for a tool description but costs little and no sentence is 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 no output schema, the description compensates by naming the fields returned, and the single optional parameter is documented. Nothing about pagination or error modes is needed for a one-shot diagnostic read, so the definition is close to sufficient, short only on connection/authorization context.

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 carries the full parameter burden, and it does: 'target' is a target name from config, and omitting it selects the default. That is exactly the semantics an agent needs to invoke correctly, though it doesn't hint at valid formats or where the config lives.

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 (read) and resource (server version/uptime/recovery state/data directory), so an agent knows exactly what it returns. It does not differentiate from overlap-prone siblings such as overview or replication_status, which is the only thing keeping it from 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 only usage signal is 'omit for the default' on the target argument, which is a parameter note rather than a when-to-use rule. There is no guidance on when to pick this over overview or other diagnostics tools, and no 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?

The readOnlyHint annotation already declares this a safe read operation, so the '[READ]' prefix is largely redundant. The description adds nothing about permissions, scope of settings returned, or output behavior, but it does not contradict anything either.

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 one-line summary followed by two tight argument descriptions; no wasted prose, though the Args block is mechanical.

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 2-optional-param, read-only tool with no output schema, the description covers both parameters and the data source. It could note what is returned (a settings list) but the pg_settings reference conveys that adequately.

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 0%, so the description must carry both parameters, and it does: 'pattern' is described as a case-insensitive substring filter with examples, and 'target' is explained as a config target name. 'target' is still slightly vague ('from config'), preventing 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?

States a specific verb (read) and resource (configuration parameters from pg_settings), which cleanly separates it from the mutation sibling update_setting. It is clear but never explicitly names or contrasts with any sibling.

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 gives no when-to-use context, prerequisites, or alternatives (e.g. update_setting for changes). Usage is only implied by the '[READ]' tag and the fact that it reads config.

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?

readOnlyHint=true already declares this a safe read, and the description adds real value beyond that: it pulls live top statements by default when no rows are injected and optionally runs an EXPLAIN so plan node types feed the analysis. It doesn't discuss permissions or the exact shape of the emitted causes/actions, but the behavioral flow is well disclosed.

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

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

Front-loads the [READ] tag and core purpose, then explains modes, then consolidates parameters in an Args block. It is slightly long with a bulleted list, but each sentence contributes needed information with no 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 four-parameter read-only analysis tool with no output schema, the description covers what is analyzed, the selection criterion, the live-vs-injected modes, the optional EXPLAIN enrichment, and the nature of the output (cited causes + concrete actions). 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 description coverage is 0%, so the description carries the full burden and documents all four parameters: statements (injected rows, sourced from top_queries), explain_sql (optional SQL to EXPLAIN), limit (count pulled when not injected, default 20), and target (config name, omit for default). Coverage is complete, though definitions stay at a summary 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?

States a specific verb and resource: root-cause analysis of the worst pg_stat_statements entry. It specifies the exact selection rule (greatest total execution time) and the transformation performed (numbers mapped to cited causes and concrete actions), which distinguishes it from siblings like top_queries (listing) and explain_query (raw plan).

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?

Clearly explains the two operating modes: pass 'statements' for offline analysis or omit to pull top statements live, and references top_queries as the source of injectable rows. It gives actionable context but names no explicit alternative RCA/diagnostic sibling or when-not conditions.

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

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

The readOnlyHint annotation already declares this is a safe read, and the [READ] tag merely restates it. The description adds minor value with the metric definition and the fact that omitting target uses the default config, but says nothing about return format, cost, or rate behavior.

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 with the highest-value information (metric and ordering), followed by a compact Args block for the two parameters. No wasted sentences, though the bracketed [READ] tag is redundant with the annotation.

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

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

For a simple two-parameter read-only tool with no output schema, the description covers purpose, metric, ordering, and both parameters adequately. Only return-value shape is unspecified, which is acceptable for a low-complexity read operation.

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 carry the parameter burden, and it does document both: limit is the number of tables inspected (default 50) and target is a config-defined name that defaults when omitted. This resolves the otherwise opaque "target" parameter.

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?

"Dead-tuple bloat proxy per table" states a specific verb/resource and even defines the metric (dead / (live + dead)) and ordering (worst first), which sets it apart from siblings like table_sizes and index_bloat. It does not explicitly contrast itself with bloat_and_vacuum_analysis, leaving that differentiation to inference.

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 [READ] tag and the metric description imply when the tool is useful (inspecting table bloat), but there is no explicit when-to-use guidance and no routing against the closely related index_bloat or bloat_and_vacuum_analysis 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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds useful context: what 'size' includes (table + indexes + TOAST) and that results are ordered largest-first. No mention of cost, sampling, or cross-target behavior, so it stays at a solid-but-limited 3.

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 [READ] signal and a one-line purpose, followed by compact Args. No wasted sentences; the structure is easy to scan, though the Args block is slightly verbose for only two parameters.

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

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

For a simple two-parameter read tool with annotations covering safety and no output schema, the description covers purpose, ordering, defaults, and target resolution. It stops short of describing the returned columns, which would fully close the loop.

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 0%, so the description must carry the burden — and it does, documenting both parameters: 'limit' as a count with largest-first ordering and a default, and 'target' as a config name with omit-for-default semantics. It adds real meaning the bare schema lacks.

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 — largest tables ranked by total relation size — and even disambiguates the metric by defining it as table + indexes + TOAST. This distinguishes it from siblings like table_bloat and index_bloat, though it doesn't name 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?

The [READ] tag implies a read-only inspection use case, but there is no explicit when-to-use guidance and no mention of when to prefer this over table_bloat, index_bloat, or other size-related siblings. The agent must infer context.

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

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

Annotations already declare destructive/not-idempotent/not-readonly, yet the description adds substantial context beyond them: no safe inverse, an audit trail capturing pid+query, a live dry-run preview mode, and the self-pid refusal that applies even during dry_run. This is exactly the behavioral depth annotations cannot express.

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?

Risk tag is front-loaded, followed by impact, preview, and refusal behavior, then an Args block. Every sentence adds information and the param list is warranted given 0% schema coverage. Slightly dense but no 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 high-risk mutation with no output schema, the description covers everything an agent needs: irreversibility, audit trail, preview path, refusal constraint, and per-parameter sourcing/defaults. Nothing essential to correct invocation 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 0%, so the description carries the full burden, and it documents all three params: pid (sourced from list_activity), dry_run (preview behavior), and target (from config, omit for default). This compensates well, though pid's expected value range/format is not elaborated.

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 ("Terminate a backend") and maps it to the underlying pg_terminate_backend call, so the effect is unambiguous. The [WRITE][risk=high] tag reinforces the operation class. It does not explicitly differentiate itself from the softer sibling cancel_query, which would have earned 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 concrete operational guidance: use dry_run=True to preview, and pid comes from list_activity. The refusal condition (own backend pid, even under dry_run) is spelled out. No explicit when-not/alternative guidance relative to cancel_query, so it stops 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?

The '[READ]' prefix aligns with readOnlyHint=true and adds no contradiction. It adds a modest constraint ('whitelisted metric') and the 1..200 limit bound, but says nothing about how many rows the stats cover, whether stats must be reset first, or freshness of pg_stat_statements data.

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 read-only marker and the core action, then a compact Args block. Every line carries information; the only slack is the slightly redundant restatement of defaults already in the 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 simple read-only ranking tool with no output schema and no required parameters, the description covers purpose, all three parameters, and safety. What the returned rows contain (query text, metric values) is left unstated, which is the main remaining gap.

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 carries the burden and does it well: it enumerates the five valid order_by values (total_time, mean_time, calls, rows, io), the limit range and default, and the meaning of target. 'Target name from config' is the only vague spot.

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 resource (top statements from pg_stat_statements) and the ordering axis ('by a whitelisted metric'), which distinguishes it from mere listing tools like list_activity. It does not explicitly name a sibling it contrasts with, so it stops 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 explains what arguments do but never says when to reach for this tool versus slow_query_rca, long_running_queries, or explain_query. Usage must be inferred from the tool name alone.

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

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

Annotations already flag destructive=true and non-idempotent, and the description is consistent with them while adding context the annotations cannot convey: the inverse executes under its own governed tool with its own risk tier and audit row, and a token can only be applied once. The single-use constraint is a critical behavioral detail. It still doesn't describe failure behavior or what the response contains.

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?

Risk tags are front-loaded, the prose paragraph covers behavior, and the Args block covers parameters. There is minor overlap between the dry_run prose sentence and its Args line, but nothing wasteful enough to penalize.

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 destructive, non-idempotent dispatcher with no output schema and zero schema documentation, the description supplies the key facts an agent needs: source of the id, preview path, one-time application, and separate audit trail. What's missing is only failure semantics and the shape of a dry-run preview.

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 carry the load — and it does, explaining all three parameters: undo_id's origin, dry_run's preview semantics, and target's pass-through behavior ('when it accepts a target'). The remaining ambiguity is inherent to target's tool-dependent nature, not an omission.

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 ('Apply a recorded undo by dispatching its inverse tool') plus the annotated mode '[WRITE][risk=medium]'. It is immediately distinguishable from the sibling undo_list, which supplies the undo_id rather than consuming it.

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?

Tells the agent where the required id comes from ('The undoId from undo_list (or an _undo_id in a write result)') and when to reach for dry_run=True. It lacks an explicit 'do not use this when…' clause, but the guidance is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by explaining effectVerified and the PROBABLE-vs-confirmed semantics of a reversed write, plus a warning not to misreport results. This is real behavioral context beyond structured data, but permissions and error behavior are unaddressed.

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 read marker and purpose, then an Args block. The effectVerified paragraph is longer than the rest but each sentence carries non-obvious semantics, so little is 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?

No output schema exists, yet the description enumerates the returned entry fields (original tool, inverse tool, human note, undoId, effectVerified) and the sort order, which is exactly the missing context an agent needs to interpret results.

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

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

With 0% schema description coverage, the description fully compensates: it documents limit ('Max rows to return', default 50) and explains that target is inert and only present for CLI uniformity — critical to prevent an agent from inventing a filtering behavior for target.

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?

Opens with a specific verb and resource ('List recorded, not-yet-applied undo tokens'), plus ordering semantics (most recent first). It is clearly distinguishable from the sibling undo_apply, which consumes the tokens this tool produces.

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

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

Explicitly routes the agent: 'Use the undoId with undo_apply', and adds a conditional warning to verify live state before applying when effectVerified is false. Clear usage context, though it never states when not to call this tool.

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

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

readOnlyHint=true already signals a safe read, and the '[READ]' prefix merely repeats it. Beyond that the description adds little behavioral context: it does not note that index scan counters depend on the stats collector, that reset_query_stats can invalidate results, or what fields come back.

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 one-line purpose followed by a compact Args block; no filler. The '[READ]' marker is redundant with annotations and the docstring formatting is a bit template-ish, but overall it is tight.

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 parameterless-required read tool with no output schema, the description covers what is selected but not what is returned (index identity, size, scan counts) nor caveats about statistics freshness that materially affect trust in the 'zero scans' claim.

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 carries the full burden and does it reasonably: min_size_bytes is explained as a size threshold with default 0, and target as a config target name with 'omit for the default'. 'Target name from config' remains vague with no enumerated values, but the semantics are substantially clarified.

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 resource and qualifying scope: 'Non-unique, non-primary indexes with zero scans (drop candidates)'. This meaningfully narrows what is returned and distinguishes it from neighbors like invalid_indexes and index_bloat, though it never names those siblings 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?

The parenthetical '(drop candidates)' implies the intended use (finding indexes to remove via drop_index), but there is no explicit when-to-use guidance, no mention of the alternative diagnostics tools, and no note of prerequisites such as index usage statistics being enabled or recently reset.

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?

Discloses rich behavior beyond the annotation hints: it writes postgresql.auto.conf, most changes need pg_reload_conf() which is reported but NOT performed, prior state is captured for undo, and specific postmaster settings are refused even under dry_run. This is exactly the operational context the annotations lack.

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 tags and the core action, then behavior, refusals, and args in labeled order. Dense and largely waste-free, though the explanation of the recorded inverse is somewhat lengthy relative to what's strictly needed.

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?

A mutation tool with no output schema and only safety-hint annotations, yet the description covers effect mechanism, reload requirement, undo recording, refusals, and dry_run behavior. An agent has everything needed to 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?

Schema coverage is 0%, so the description carries the burden, and it does: each of the five parameters (name, value, reset, dry_run, target) is explained with usage conditions such as omitting value when reset=True.

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 ('ALTER SYSTEM SET (or RESET) a parameter') with tags labeling it a WRITE and medium risk. An agent can immediately distinguish it from read-only siblings like show_settings.

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?

Clearly explains internal modes: when reset=True applies instead of setting, when to use dry_run to preview, and when value must be omitted. It does not explicitly name alternatives (e.g. show_settings for reading current values), so it stops short of full when-vs-alternative routing.

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

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

The readOnlyHint annotation already declares this as a safe read, so the [READ] tag is largely redundant. The description does add value by enumerating what is reported (WAL position, level, size settings, archiver health), which is more than the annotation conveys. It does not discuss return format, thresholds, or health semantics.

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 [READ] tag and the resource list, then a compact Args block. No filler sentences. Slightly awkward that the docstring formatting implies a Python signature, but it is efficient.

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 single-parameter read-only diagnostic tool with no output schema, the description is adequate but thin. It names the reported dimensions but does not explain what healthy or unhealthy WAL/archiver output looks like, which an agent may need to interpret results.

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 carry the parameter. It clarifies that 'target' is a config target name and that omitting it uses the default, which adds real meaning beyond the bare anyOf/null schema. It stops short of stating what targets are available or how config targets are named.

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 set – WAL position, level, size settings, and archiver health – with a clear [READ] verb tag. It is easy to distinguish from siblings like replication_status or overview. It lacks explicit sibling differentiation, but the resource is specific enough to stand alone.

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 use this tool versus alternatives such as replication_status or overview. Usage is only implied by the resource names. No prerequisites, no exclusion conditions, no routing guidance.

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