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

With no annotations, the description carries the full burden and does so well: it declares the operation read-only against a local file, discloses the result ordering ('newest first') and cap ('max 20'), and adds a caution ('after verification') before suggesting pg_terminate_backend. It does not discuss permissions or failure modes, but for a local read-only file query those are largely irrelevant.

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 diagnostic question, then reads naturally into scope, priority, fix, args, and returns. The Args/Returns blocking is easy to scan and no sentence is wasted, though the remediation instruction adds some length beyond strict tool description.

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, but the description inlines the return shape ({blockers: [{ts, kind, pid, age, query, slot}]}), ordering, and count limit, so an agent knows what it will get. Combined with the arg documentation and remediation steps, the definition is complete for a one-parameter 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% for the single parameter, so the description must compensate, and it does: 'db: Path to the SQLite timeline file (default: BLOAT_DB env)'. This explains both the meaning and the environment-based default that the bare schema ('default: ""') 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?

States a specific resource and the exact diagnostic payload ('Who is pinning VACUUM: blocker pid + query + xmin age + slot'), which is far more informative than a name restatement. It implicitly contrasts with the live-diagnosis sibling by noting it is 'Read-only on the local timeline file', but it never names bloat_live_diagnose or the other siblings explicitly, so differentiation is inferential rather than stated.

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 supplies a priority ordering (prepared-xact > stale-slot > idle-in-transaction) and a remediation path ('end the named session, then VACUUM the table'), which implies the diagnostic scenario. However, it never states when to call this versus bloat_live_diagnose or the other bloat_* siblings, leaving tool selection 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?

With no annotations provided, the description carries the full burden and does well: it explicitly declares read-only behavior and that it never touches Postgres, only the local SQLite timeline. It also enumerates the verdict taxonomy and what evidence contains, though it omits any permission or file-access caveats.

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 and the read-only guarantee before the Args/Returns blocks, so a scanning agent gets the essentials immediately. The explicit verdict enumeration is long but earns its place by defining the output vocabulary.

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, so the Returns section is doing real work: it names the findings list, the per-item shape {table, verdict, evidence, action}, the full verdict enum, and what evidence carries. Combined with the documented single param, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0% and the single param is titled only 'Db', so the description must compensate — and it does, documenting that db is a path to the SQLite timeline file with a BLOAT_DB env fallback and a 'timeline.db' default, plus how to obtain it.

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 (diagnose) and resource (PostgreSQL bloat) plus the input source (a collected timeline), which implicitly separates it from bloat_live_diagnose. It names bloat_collect as the producer of its input, though it never explicitly contrasts itself with the other bloat_* 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?

Clear context is given: run bloat_collect first to obtain a timeline, or pass any timeline.db path, and the read-only/offline nature is stated. It stops short of saying when to prefer this over bloat_live_diagnose or bloat_blockers, so the sibling routing is only implied.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the read-only transaction, the 5s statement timeout, the pg_stat_* view requirement plus optional pgstattuple extension, that no agents are spawned, and that the password is never logged. It even reveals the side effect of writing a snapshot file (db: path). It stops short of describing cost/load on prod or what happens on repeated collection into the same timeline.

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 action, followed by a safety paragraph and explicit Args/Returns blocks. Nearly every line earns its place; the only slack is the loosely formatted 'Returns' line rather than any redundant sentence.

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

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

There is no output schema, yet the description sketches the return shape ({snapshot, db path, findings with an action per table/index}), covers required extensions and permissions, and documents the single parameter's default. An agent has what it needs to call this correctly; the only missing element is sibling routing.

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 compensate, and it does: it gives an example DSN string with a readonly user, states the BLOAT_DSN environment fallback matching the empty-string default, and notes the password is never logged. That is materially more than the bare 'Dsn' string 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 concrete verb and resource: take a read-only Postgres snapshot into the timeline and return verdicts. That is specific enough to distinguish it from a pure reader like bloat_timeline, but it never names a sibling or explains the boundary, so the differentiator is inferred rather than stated.

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 'Safe on prod' framing implies this is intended as a first collection step against production, but there is no explicit statement of when to choose bloat_collect over bloat_live_diagnose or bloat_check, and no prerequisites or exclusions are given. Usage is implied, not guided.

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

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

With no annotations, the description carries the full burden and delivers: read-only transaction, 5s timeout, temp DB created and discarded, password never logged, and no mutation of the timeline file. These are exactly the safety facts an agent needs before pointing it at a production DSN.

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 dense supporting detail. The explicit Args:/Returns: blocks are slightly redundant given the structured schema, but every line still carries information.

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

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

No annotations or output schema, yet the description still documents the return shape ({findings, blockers}) and how it relates to bloat_check's output. Nothing an agent needs to invoke this safely 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% (bare string with no description), so the description compensates by explaining dsn is a Postgres DSN with a BLOAT_DSN env-var default and a no-logging guarantee. Only one low-complexity parameter keeps this from being richer.

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 ('one-shot live diagnosis') and pins down its mechanism (snapshot into throwaway temp DB). Differentiates from siblings by naming bloat_check's verdict set plus added xmin-holder evidence, and from bloat_timeline by not touching the timeline file.

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?

'Safest option for prod DSNs' gives clear context for selecting this over siblings, and the no-timeline-touch note implies the timeline-based alternative. It stops short of explicit when-not conditions or naming bloat_check/bloat_timeline with a routing 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?

With no annotations, the description carries the full burden and does well: it explicitly declares the read-only, local-file nature of the operation and adds real interpretive value ('Rising dead = vacuum-starved; spike-then-zero = was blocked, blocker left'). It omits any dependency on prior collection by bloat_collect, which is the main behavioral gap.

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

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

Front-loaded summary line followed by clearly labeled Args and Returns blocks; nothing is redundant. The Returns block is dense but justified since no output schema exists.

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 no annotations, the description supplies the return shape and even explains how to read the series, which is the information an agent actually needs. The missing prerequisite (data collected first) and any retention/range limits keep it short of a 5.

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 compensate, and it does: it explains table filtering with an example ('churn', empty = all tables) and documents db as the path to the SQLite timeline file with a BLOAT_DB env default. Minor mismatch with the schema's empty-string default for db is a small blemish.

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 and framing: a 'dead-tuple + approx + index-bloat time series' answering 'when the bloat started'. This implicitly separates it from the live/diagnostic siblings (bloat_live_diagnose) and the point-in-time check (bloat_check), though no sibling is named 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?

Usage is implied by 'when the bloat started' and 'Read-only on the local timeline file', which suggests a historical/lookup use case. However, it never says when to prefer this over bloat_live_diagnose or bloat_blockers, nor that the timeline must already be populated by bloat_collect.

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