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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior on top: it samples at most sample_size non-NULL rows, computes L2 norms, applies a named heuristic, and returns metric + rationale + distribution stats. It also discloses a degradation path ('Reports available=false if the pgvector extension is not installed'), which is exactly the kind of operational detail annotations cannot convey.

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

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

The opening clause front-loads purpose, then mechanism, heuristic branches, return shape, and failure mode follow in a logical order with no filler sentences. The parenthetical heuristic chains are dense but every clause carries decision-relevant information, so the slight density is acceptable.

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

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

An output schema exists, so return values did not need spelling out, yet the description still names the payload (metric + rationale + distribution stats). Combined with sampling behavior and the pgvector-unavailable case, an agent has everything needed to call this correctly and interpret the result.

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 only 20%, so the description must compensate, and it does: it explains that schema.table.column identifies the embedding column being profiled and that sample_size bounds the number of non-NULL rows sampled. The only gap is the optional 'database' parameter, which the schema itself already documents well.

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

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

The description opens with a specific verb and resource ('Recommend a pgvector distance metric') and immediately enumerates the three candidate metrics, so the agent knows exactly what comes back. This is clearly distinguishable from neighboring tools such as tune_vector_index or analyze_hnsw_recall, which tune indexes rather than choose a metric.

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 clear decision criteria for the metric choice itself (CV < 5% and mean ≈ 1.0 → inner_product; near-constant magnitude → cosine; variable magnitude → cosine), which is real guidance on the outcome. However, it never states when to reach for this tool versus siblings like tune_vector_index, vector_recall_at_k, or recommend_vector_quantization, nor any prerequisite such as the column being of type vector.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it requires the vector extension and computes 'exact brute-force ground truth', which signals an expensive exact scan, and it states that the output is one row per ef_search value tested. It stops short of warning about runtime cost, sweep size, or row limits.

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

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

Two sentences, front-loaded with the operation and its measurement, then the return contract. The field list is dense but earns its space by describing the row shape. Minor redundancy with the output schema, which already defines those columns.

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

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

An output schema exists, so repeating the return columns is optional rather than necessary, and annotations cover read-only safety. However, for a 7-parameter analytical tool with 14% schema coverage, the description leaves the semantics of k, metric, and the swept ef_search range unexplained, which is the main gap an agent would hit when invoking it.

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 only 14%, so the description must carry almost all the weight, and it does not. It never explains what k, metric, table, or column do, nor what range of ef_search values is actually swept (ef_search is not even an input parameter). Only the query vector and the extension prerequisite get any narrative support.

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 action ('sweeps ef_search values') plus the measured quantity ('latency and recall trade-off curve') and the ground-truth baseline, so the agent knows exactly what the tool produces. It does not distinguish itself from nearby siblings such as vector_recall_at_k or recommend_hnsw_ef_search, leaving the agent to infer the difference from the output shape.

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 routing guidance is the prerequisite 'Requires the vector extension', which is a condition for success rather than a when-to-use rule. There is no statement of when to prefer this sweep over vector_recall_at_k (single-k recall) or recommend_hnsw_ef_search (a recommendation), so selection among these siblings is only implied by the description's emphasis on a full curve.

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 establish readOnlyHint=true and openWorldHint=false, so the 'Read-only — never modifies state' sentence is largely redundant. What does add value is the PG 19 version dependency and the enumerated reason codes (contention_dominant, high_wait_time, high_wait_count, low_contention), which tell the agent how results will be bucketed and that classification is heuristic rather than absolute.

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 and the sibling routing are front-loaded in the first two sentences, which is the right ordering. The last portion enumerates return fields that an output schema already declares, which is filler, though the example call is short and harmless.

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

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

With an output schema present, restating the return shape is unnecessary, but the description does supply the piece the schema cannot: the PG 19 version gate and what `available` implies for fallback behavior. An agent has enough to call it correctly; only the relationship to the raw-read lock siblings is left implicit.

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

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

There is a single optional database parameter whose schema description already covers it at 100%, including the secondary/primary targeting rule and rejection of unconfigured names. The description text adds no further meaning about that parameter, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Rank PG 19 pg_stat_lock rows by wait dominance') and names the exact output artifact ('stable reason codes'). It also distinguishes itself from the nearby lock-related siblings by pointing at find_blocking_chains for active culprits, so an agent can choose between them without opening either schema.

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

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

It gives explicit routing guidance: use this for ranked hotspot analysis, and pair with find_blocking_chains when you need the active culprits behind a specific hot lock_type. What is missing is any exclusion relative to read_pg_stat_lock or list_locks, which return the raw rows this tool ranks, so the agent must infer that boundary.

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

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

Beyond readOnlyHint/openWorldHint, the description discloses that writes and DDL are rejected by the same pre-flight as analyze_query_plan, that the result degrades gracefully to available=false off MPP, and what redistribute_count means. One notable behavior is left implicit: EXPLAIN ANALYZE actually executes the statement, so cost/latency implications of running it are not stated.

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 and output shape, then safety, then degradation behavior, then an example. Each clause carries information, though the parenthetical 'Redistribute Motion / Broadcast Motion / Gather Motion' enumeration is slightly heavy and the trailing example is arguably optional.

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

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

An output schema exists, and the description still helpfully names the key rollup fields; annotations cover the read-only profile. Completeness is high for a 2-parameter tool, with the only real omission being the execution cost of running EXPLAIN ANALYZE on a live query.

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 50%: the database parameter is fully documented in the schema, while sql is not. The description compensates by defining sql as the statement handed to EXPLAIN ANALYZE and giving a concrete example invocation, which is enough meaning to call it correctly, though it does not state constraints on the SQL (e.g. SELECT-only) beyond the write/DDL rejection.

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 ('Run EXPLAIN (ANALYZE, FORMAT JSON) on sql') and immediately narrows scope to MPP-specific rollups: slice count, motion nodes, per-motion metadata. It is clearly differentiated from the sibling analyze_query_plan by its MPP focus and its 'available=false on vanilla PG' caveat.

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 establishes context (MPP databases) and signals when the tool is inapplicable ('On vanilla PG returns available=false'), plus relates itself to analyze_query_plan(io=True) for the safety model. It stops short of an explicit 'use analyze_query_plan instead when not on an MPP cluster' routing sentence, leaving that inference to the agent.

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 openWorldHint=false, so safety basics are covered, and the description does add genuine behavior detail about what the io variant returns and the PG 19 aio_* rollups. However, the most consequential behavioral fact is undisclosed: EXPLAIN ANALYZE actually executes the statement, so io=true incurs real runtime cost and can trigger side effects for volatile functions or writes — a caveat an agent needs before flipping that flag.

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 summary of outputs is front-loaded and the io toggle explanation follows logically, with a concrete example at the end. There is mild redundancy in the trailing sentence "Reasoning about AIO needs `io=true`," which restates what the preceding parenthetical already implies, but overall the text is dense and purposeful.

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

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

An output schema exists, so the description is not obliged to document return shapes, and it sensibly limits itself to flagging the extra io fields. The remaining gap is material for a plan-inspection tool: no statement of which statements are safe to analyze, no warning about execution cost under io=true, and no relation to the overlapping explain_query 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 only 33%: `database` is well documented in the schema, while `sql` and `io` carry no schema descriptions at all. The description compensates strongly for `io` (it explains precisely what extra fields the flag produces and why AIO reasoning requires it) and partially for `sql` via a worked example, but it never states whether `sql` must be a single statement, whether writes/DDL are permitted, or whether placeholders are supported.

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

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

The description opens with a specific verb+resource ("Summarise a query's execution plan") and enumerates exactly what is summarised: total estimated cost, estimated rows, node types, and sequentially-scanned tables. It is clear what the tool produces, but it never distinguishes itself from nearby siblings such as explain_query, why_is_this_slow, or analyze_mpp_query_plan, so an agent must infer the boundary itself.

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 real mode-selection guidance for the io flag: use io=true to get EXPLAIN (ANALYZE, BUFFERS, TIMING) with actual timings and block I/O, and it names the specific case ("Reasoning about AIO needs io=true"). What it lacks is any when-to-use-this-vs-explain_query routing or a statement of when plan-only is preferred (e.g., for expensive or non-SELECT statements).

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses the underlying source table (mcpg_rag.rerank_events), the degradation behavior when the table is missing or the window is empty (zero-count report rather than an error), and that it can emit a reranker_idle WARNING. That is genuine behavioral context an annotation cannot convey; the only gap is the absence of a threshold definition for 'rarely changes ordering'.

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?

Four dense sentences with the metric definition front-loaded, followed by interpretation, optional filters, warning behavior, and edge cases — a sensible priority order with no filler. Parenthetical clarifications earn their space; only slight tightening would be possible.

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

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

An output schema exists, so return-value explanation is rightly omitted, and the description still covers data source, aggregation scope, filters, warning emission, and empty/missing-table behavior — a lot for a 4-parameter read-only tool. The remaining shortfall is quantitative: no guidance on what counts as 'low' vs 'high' correlation or what minimal volume of rerank events is needed for a meaningful signal.

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 only 25% (just `database`), so the description must carry weight: it flags `model` and `retrieval_index` as optional filters and the 'window' wording maps loosely to `days`. However, it gives no format or default for `days`, no example values for `model`/`retrieval_index`, and does not say whether the filters apply to queries, documents, or both — partial compensation only.

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 computation (per-query Spearman + Kendall correlation between bi-encoder and cross-encoder ranks, aggregated over a window), which is far more precise than the title alone. It implicitly separates itself from neighbors like analyze_rerank_ndcg or analyze_rerank_score_distribution by stating exactly which statistic it produces, though it never names an alternative explicitly.

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

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

It explains how to interpret results (low correlation = reranker actively reordering, high = confirming), which implies the diagnostic use case, but there is no explicit 'use this when…' statement, no exclusions, and no pointer to the sibling rerank tools (ndcg, score distribution, recommend_rerank_strategy). An agent knows what the number means but not when to prefer this over the other rerank analyses.

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?

Adds substantial behavior beyond the readOnly annotation: source table mcpg_rag.rerank_events, the labeling precondition (ground_truth_relevance IS NOT NULL), the emitted finding names with severities (rerank_hurts_ndcg CRITICAL, rerank_lifts_ndcg GOOD evidence), and the zero-count edge case when no labeled rows exist.

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?

Dense but front-loaded: metric and comparison first, delta semantics next, then findings and data-source caveats. Terminology like 'bi-encoder ordering vs cross-encoder ordering' is necessary; no filler sentences.

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

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

An output schema exists, so return shape need not be spelled out, and behavioral coverage is strong. However, with five parameters and four of them undocumented anywhere, the description is not complete enough for an agent to size the window, tune `k`, or scope by `model` without guessing.

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 only 20% (only `database` is documented). The description never explains `k`, `days`, `model`, or `retrieval_index`; only 'in the window' loosely implies `days` is a time range. An agent must guess what `k` sets and how `model` filters.

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 metric (NDCG@k), the two orderings being compared (bi-encoder vs cross-encoder), the aggregation unit (labeled queries), and the reported quantity (delta = cross - bi). This is clearly distinct from siblings like analyze_reranker_lift and analyze_rerank_score_distribution.

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 sign interpretation ('positive = adding real ranking quality, negative = hurting') gives result-reading guidance, but there is no explicit statement of when to choose this over analyze_reranker_lift or recommend_rerank_strategy. Usage is implied rather than directed.

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 readOnlyHint and openWorldHint, so the description carries the real behavioral load: it names the source table (mcpg_rag.rerank_events) and defines the exact WARNING trigger (more than half of scores in the top decile of the range). It adds meaningful interpretation semantics beyond the annotations, though it says nothing about cost, volume, or limits on the scan.

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

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

Three dense sentences that are front-loaded with the core measure and then the alert semantics; nothing is padding. The final enumeration of return fields is somewhat redundant given an output schema exists, keeping it short of a 5.

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

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

For a read-only analytical tool with zero required parameters, the description covers purpose, source, and alert condition well, and the output schema handles return values. However, with four of five parameters undocumented and no guidance on choosing this analysis over its reranker-analysis siblings, an agent lacks enough to pick and configure it confidently.

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 only 20% — just the `database` parameter is documented — so the description must compensate and largely does not. 'Over the window' loosely implies `days`, and 'equal-width histogram' loosely relates to `n_buckets`, but `model` and `retrieval_index` are never explained, and no defaults or filter semantics 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 precise verb and measure: 'Equal-width histogram of cross_encoder_score values over the window plus the top-decile share', and names the specific finding it produces (`score_clustering`). This is concretely distinguishable from sibling analyses such as analyze_reranker_lift and analyze_rerank_ndcg, which measure lift and ranking quality rather than score spread.

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 says it surfaces `score_clustering` when the reranker isn't discriminating, which hints at a diagnostic use case. It never states when to pick this over analyze_reranker_lift, analyze_rerank_ndcg, or recommend_rerank_strategy, and offers no exclusions or prerequisites.

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 openWorldHint=false, and the description adds real value on top: the data source, the 1440-minute cap on lookback, the default thresholds, and the specific finding taxonomy (redundant_listing, hot_repeated_call, idle_session). It also discloses graceful degradation to audit_table_present=False when the audit table is absent, which is exactly the kind of behavioral trait annotations cannot express. However, it never states cost or volume characteristics — e.g. how expensive scanning a 1440-minute window is, or whether results are sampled — leaving the agent without a sense of call risk on large windows.

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

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

The description is front-loaded with the core action and source, then layers thresholds, finding types, and the failure mode in a logical order, closing with a concrete call example. It is dense but each clause carries information; the one redundancy is restating the return object shape, which the output schema already defines.

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

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

Given an output schema exists, the description need not enumerate return fields, yet it does — a minor duplication rather than a harm. Everything an agent needs to invoke it correctly is present: source table, both tunable thresholds with defaults and a cap, finding semantics, and the no-audit-table diagnostic path. The only real omission is the role of the `database` parameter for this read path.

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 only 33% (only `database` is documented in-schema), so the description must carry the rest — and it does, giving defaults for `lookback_minutes` (60) and `hot_threshold` (10) plus the 1440 cap that the schema does not express. The `database` parameter is not mentioned at all in the description, so it is unclear whether the audit events are read from the primary or the selected secondary, which is a meaningful gap for a multi-database tool.

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

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

The description opens with a specific verb and resource — "Surface hot-path inefficiencies from the audit log" — then names the exact source table (mcpg_audit.events) and the finding categories produced. It is clearly distinguishable from siblings like list_audit_events (raw events) or analyze_workload (query workload), since it is scoped to per-tool call counts and redundant catalogue listings.

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 clear triggering context (analyzing audit-log call patterns with configurable lookback and hot threshold) and even routes the agent onward via the 'suggestion' field (get_compact_schema for redundant listings). It does not explicitly say when to prefer this over analyze_workload or list_audit_events, nor state prerequisites such as the audit subsystem needing to be enabled — only the degradation behavior is described.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses that the default path reads relpages/reltuples plus pg_stat_user_tables, that the precise path is I/O-heavy, and — critically — that the tool silently falls back to the estimate and reports `method='estimate'` when pgstattuple is absent. That fallback semantics is exactly the kind of non-obvious behavior an agent needs before interpreting results.

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 purpose in the first sentence, then default behavior, then the opt-in precise mode, then the return shape, then a concrete example. Every clause carries information — the row-width floor, the dead-tuple ratio, and the fallback are all load-bearing.

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 4-parameter read-only analysis tool with an output schema, this covers everything needed: cost profile, extension dependency, fallback reporting, and which keys come back. Nothing an agent needs to call it correctly or interpret `method` 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 only 25% (only `database` is documented inline), so the description must compensate, and it largely does: `precise` gains fallback/extension semantics, `limit` is explained as a per-collection cap on `tables` and `indexes`, and `schema` is demonstrated in the example. Only `database` is left to the schema, which already documents it adequately.

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 (rank) and resource (a schema's tables and indexes) plus the ordering guarantee (worst bloat first). No sibling tool in the list covers bloat estimation, and the description makes the output shape explicit enough that an agent can distinguish it from neighbors like summarize_table or recommend_index_drops.

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 when-to-use guidance for the key decision: default cheap catalog-only estimate versus `precise=true` when exact pgstattuple/pgstatindex reads are needed and the extension is installed. It flags the I/O cost of the precise path, which is the main tradeoff an agent must weigh. It does not explicitly say when not to use the tool or name an alternative sibling, so it falls 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by naming the data source (mcpg_rag.rerank_events), the emitted flag (topk_stable at WARNING severity), and the degraded path — zero counts when the table is absent or the window is empty. That empty-table fallback is exactly the kind of behavior an agent cannot infer from the annotations.

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

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

Leads with the metric definition, then interpretation, then the emitted signal, then data-source and edge-case handling — a sensible front-loaded ordering with no filler. Four sentences is proportionate, though the double-backtick markup around topk_stable is noise.

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

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

With an output schema present, the description needn't explain the report shape and correctly focuses on method, interpretation, and failure mode. For a 5-parameter analytical tool with 0 required parameters and near-zero schema coverage, however, the absence of any guidance on k, days, model, or retrieval_index leaves the caller guessing at scope.

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?

Five parameters with only 20% schema description coverage, and the description explains none of them beyond the incidental phrases 'at this K' and 'the window'. It never says what k selects, what unit days represents, or how model and retrieval_index scope the query, so it does not compensate for the low coverage.

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 the exact computation (Jaccard overlap between top-K-by-bi-rank and top-K-by-cross-rank, aggregated per query) and the meaning of the score, which is specific enough to separate it from NDCG/lift siblings in the rerank family. It never names a sibling explicitly, so differentiation is implicit 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?

Usage is implied by 'High mean Jaccard means the reranker isn't actually changing the top-K membership' and 'when the rerank is barely earning its place at this K', which tells an agent the diagnostic situation. There is no explicit when-to-use / when-not-to-use statement and no routing to analyze_rerank_ndcg or analyze_reranker_lift for the adjacent 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses scan mechanics (detects backend, sweeps the matching knob across a multiplier curve), emitted finding codes with severities, and cost — sample_size × (1 + len(candidate_multipliers)) queries burned. It also flags read scoping and extension dependencies that annotations alone do not convey.

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

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

One dense but well-ordered paragraph: purpose first, then method, then outputs, then cost and prerequisites. Every clause carries information, though the parenthetical enumeration of finding codes and metric lists makes it heavier than necessary for an at-a-glance read.

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

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

An output schema exists, so return values need not be spelled out, yet the description still usefully summarizes finding codes and severities. For a complex diagnostic tool with read-only annotations, the main remaining gaps are parameter-level semantics and explicit sibling routing rather than missing behavioral 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 coverage is only 10% across 10 parameters, so the description must carry the load. It implicitly explains k (recall@k), sample_size (query cost), and candidate_multipliers (curve), but leaves metric (cosine/l2/ip options), id_column, index_name, schema/table/column, and database targeting unaddressed — and database semantics live only in 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?

States a specific verb and resource — a cross-backend retrieval-quality report for a pgvector or pg_turboquant ANN index — and immediately names the scope (HNSW / IVFFlat / turboquant) and what is computed. An agent can distinguish it from siblings like vector_recall_at_k, analyze_hnsw_recall, or recommend_hnsw_ef_search without opening a 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?

Gives explicit when-not guidance ("ad-hoc diagnostic, not a cron tool") and prerequisites (vector extension required; turboquant-arm metrics require pg_turboquant). It does not name the narrower sibling tools (e.g. analyze_hnsw_recall or recommend_hnsw_ef_search) that an agent might prefer for single-backend knob tuning, so routing is only partially covered.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses a real behavioral trait: the tool is unavailable unless the pg_stat_statements extension is installed, and it degrades to availability=false rather than erroring. That failure mode is exactly the kind of context annotations cannot convey; only the return shape is left to the output schema.

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

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

Two tight sentences with the core behavior front-loaded, followed by a short example. The example adds modest value by showing the limit parameter in context, but it borders on redundant with the default already visible 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 two-parameter read-only tool with an output schema, this covers the essentials: what is measured, the extension dependency, and the degraded response. Only the semantics of limit and the meaning of 'slowest' relative to other ranking options remain unstated.

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

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

Schema coverage is 50%: database is well documented in the schema, but limit has no description at all. The example analyze_workload(limit=10) hints at usage and the default but never states that limit truncates the result set to the top N by mean time, so the gap is only partly closed.

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

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

The description names a specific verb and resource with its ranking metric: return the slowest queries by mean execution time. That distinguishes it from neighbors like list_active_queries (current activity) and why_is_this_slow, though it never explicitly names an alternative to route away 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?

Usage is implied by the narrow framing (workload = slowest by mean time), and the pg_stat_statements prerequisite is stated. But there is no explicit when-to-use/when-not or pointer to a sibling such as why_is_this_slow or analyze_query_plan for drill-down.

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 annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it discloses the caching behavior and how `fresh=true` forces live re-reading, and it describes the broad set of areas scanned. It does not discuss runtime cost or permissions, but it adds meaningful context beyond the annotations.

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

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

The description is front-loaded with the core purpose and scan domains, and the `fresh` guidance is placed usefully after that. The final enumeration of returned fields is somewhat redundant because an output schema exists, but overall the description remains readable and mostly earns its 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?

For a complex audit tool, the description covers purpose, scan scope, cache behavior, and output shape. Rich structured data is present (output schema and annotations), and the schema documents the `database` targeting parameter, but the `log_table` parameter remains underspecified in both description and schema, leaving a small 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 only 25%, with only the `database` parameter documented in the schema. The description compensates somewhat by explaining `fresh` behavior and implying optional log-table scanning, but it does not explain the `log_table` parameter format or give details on the required `schema` scope beyond 'over the specified schema.' This is adequate but leaves clear gaps.

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: 'Run a deep, comprehensive DBA-level database performance, logs, and health audit over the specified schema.' It also enumerates the scan areas (memory, checkpoints, temp file spills, contention locks, dead tuple cleanliness, custom logging tables), which clearly distinguishes it from narrower sibling tools such as check_database_health or audit_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?

The description gives useful runtime guidance for the `fresh` flag, telling the agent to set it true after a schema change to bypass the cache. However, it does not explicitly say when to choose this tool over similar siblings like check_database_health, run_advisors, or analyze_workload, so the tool-selection guidance is implied rather than explicit.

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

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

Annotations already cover readOnlyHint, but the description goes further: it declares the PG-10-and-up requirement, the availability flag, the sort order of returned rows, and that only at-risk sequences are returned. This is meaningful behavior beyond what the annotation block provides; it only lacks guidance on cost/side effects for very large catalogs.

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

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

Front-loaded with the purpose, then rationale, then preconditions, then return shape, then an example. Dense but every sentence carries information; the return-field enumeration partly duplicates the output schema and could be trimmed.

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

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

Given an output schema exists, the description covers what the agent still needs: the triggering condition, defaults, the PG-version limitation, and the meaning of `available`. Only the `database` parameter semantics are left uncovered by both description and schema coverage.

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 only 33% and two parameters (warning_pct, critical_pct) have no schema descriptions, so the description earns credit for explaining that these are thresholds on last_value/max_value with defaults 80 and 95, and for the worked example. However it says nothing about the `database` parameter (secondary read-only targeting), leaving a real gap.

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 ('Flag sequences nearing their ceiling') plus the exact predicate (last_value/max_value exceeding warning_pct or critical_pct). It also implicitly distinguishes itself from list_sequences by being a threshold-based audit rather than an enumeration, so an agent can pick between them without opening a 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?

Explains the use case and the motivating failure mode ('nextval() raises reached maximum value'), and gives a runtime precondition (available=false on PG < 10). It stops short of naming an explicit alternative or saying when not to bother running this audit.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false; the description is consistent ('Pure read') and adds substantive context beyond them: the source of truth is `pg_settings`, host RAM is invisible to PostgreSQL hence the optional parameter, and `findings` contains only tripped rules. That is exactly the kind of behavior an agent needs to predict the outcome 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 core action, then rule categories, then a return-value summary and an example; almost no filler. The middle sentence is heavily parenthetical and dense, which costs a little readability, but every clause 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?

With annotations covering safety and an output schema covering the return object, the description only needs to cover behavior — which it does, including the optional RAM-aware mode. It omits any mention of required privileges or version dependence of the checked settings, a minor gap for a config-audit tool.

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

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

Schema coverage is 50%: `database` is well documented in the schema, while `total_ram_mb` has no schema description. The description compensates by explaining that supplying it enables RAM-relative ratios and why (PostgreSQL cannot see host RAM), plus a worked example with 16384. Units and plausible bounds are only implied by the parameter name.

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: a sanity sweep of `postgresql.conf` via `pg_settings`, enumerating the exact rule classes it checks (dangerous toggles, cross-setting ratios, RAM-relative ratios). This is clearly distinct from adjacent siblings like `inspect_guc` (single setting) and `recommend_postgres_conf` (recommendations rather than pass/fail findings).

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 conditional 'when `total_ram_mb` is supplied' clause makes the two invocation modes explicit, and the example shows a concrete call. It does not, however, say when to prefer this over `recommend_postgres_conf` or `check_database_health`, so the agent must infer the boundary from names.

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 openWorldHint=false, so the safety profile is covered. The description goes beyond that by naming the four concrete checks and the severity model ('ok'/'warning'/'critical'), which tells the agent what a call actually costs and what signal it yields. It does not say whether thresholds are configurable or whether the check is expensive on large clusters.

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 tight sentences front-load the checks, then the return shape. The return-shape sentence is partly redundant given an output schema exists, and the `check_database_health()` example adds little since it passes no arguments, but neither is costly.

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?

Return values are covered by the output schema, so the description needn't explain them. However, for a health/diagnostic tool it leaves out what the status levels mean operationally, and it ignores the optional secondary-database targeting that changes what is being checked.

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

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

Schema coverage is 100% and the sole parameter's description already explains the primary-vs-secondary targeting and the rejection of non-configured names. The tool description says nothing about the `database` argument, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Run database health checks") and enumerates the exact checks performed: connection utilisation, buffer cache hit ratio, vacuum-needed tables, invalid indexes. That is far more precise than the title alone, but it never distinguishes itself from sibling diagnostics such as audit_database or run_advisors.

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, no prerequisites, and no pointer to alternatives among the many diagnostic siblings (audit_database, run_advisors, analyze_table_bloat). The agent must infer the invocation context purely from 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 openWorldHint=false; the description reinforces this with "changes nothing, emits no secrets" and adds substantive behavior the annotations cannot convey: which four gates are evaluated and why each matters. It does go on to enumerate return fields even though an output schema exists, which is mildly redundant, but the gate semantics are genuinely additive.

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 claim is front-loaded in the first clause, and the intervening gate rationale is dense but purpose-driven. The trailing enumeration of return fields and the example call are somewhat redundant given the output schema, costing a point but not obscuring the main point.

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

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

For a zero-required-parameter read-only advisor with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: what is checked, what the gates mean, that nothing is mutated, and that remediation guidance is returned. Nothing material 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?

With a single optional `database` parameter and 100% schema description coverage, the schema already explains that it targets a configured secondary and that non-configured names are rejected. The description adds no additional meaning about this parameter, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Assess whether the cluster is ready for point-in-time recovery") and frames the scope as a composite readiness verdict rather than a raw metric dump. It explicitly names the sibling it composes (`get_wal_archive_status`), so an agent can distinguish this advisory tool from the lower-level archive-status tool.

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 a clear situational trigger — "could I actually recover to an arbitrary point right now, and if not what's missing?" — which tells the agent when this one-call check is the right choice over manually inspecting GUCs. It stops short of explicit when-not-to-use guidance or naming sibling alternatives (e.g. inspect_guc, read_pg_stat_recovery) for partial checks.

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 restating 'Read-only' adds little; the value comes from disclosing the code semantics ('u' = up, 's'/'n'/'c' modes), the aggregate counters that let an agent branch without walking the array, and the graceful degradation to `available=false` on vanilla Postgres. That is genuine behavioral context beyond the annotations and schema.

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

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

The description is front-loaded with the core action and return shape, and each sentence carries information (field codes, aggregate counters, fallback behavior). Minor waste: 'Read-only' duplicates the annotation, and the trailing example `check_segment_health()` is near-redundant for a zero-required-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 an output schema present, the description needn't explain return values, yet it still summarizes the key fields and the vanilla-PG degradation path, which is the most likely source of agent confusion. The only gap is that it doesn't state why one would target a secondary database via the `database` parameter.

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

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

Schema coverage is 100% and the single optional `database` parameter is fully documented in the schema, including the rejection of non-configured names. The description adds nothing about the parameter, so the baseline 3 applies rather than a higher score.

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

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

The description names a specific verb and resource (walk `gp_segment_configuration`, surface MPP segment posture) and enumerates the exact fields returned (status, mode, role vs preferred_role). It is clearly distinguishable from generic siblings such as check_database_health or get_warehousepg_status because it is explicitly scoped to MPP segments and post-failover state.

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 through the motivation (detect post-failover state, branch on `unhealthy_count`/`out_of_sync_count`) and the exclusion cue that vanilla PG yields `available=false`. However, it never explicitly says when to pick this over `check_database_health`, `get_warehousepg_status`, or `list_replicas`, leaving the agent to infer the boundary.

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

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

The description claims to 'release its dedicated connection', implying a state change, while annotations mark readOnlyHint=true. This contradicts the annotation's implication of no side effects, warranting a score of 1 per the rules.

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

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

The description is two sentences, no wasted words, and conveys essential information efficiently.

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?

While an output schema exists, the description lacks guidance on the required parameter 'cursor_id' and does not mention potential errors or prerequisites. For a tool with one required param, this is insufficient.

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 description does not explain the parameter 'cursor_id' beyond its name. The description adds no meaning to the input schema.

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

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

The description clearly states the action ('Close a server-side cursor and release its dedicated connection'), uses specific verb 'close', and distinguishes it from sibling tools like open_cursor and fetch_cursor.

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 notes idempotency and the behavior when cursor is not open, giving guidance on safe reuse. However, it does not explicitly contrast with alternatives or state prerequisites, though this is straightforward for a cursor lifecycle tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description still adds substantial context: sampling cap of sample_size non-NULL rows, k-means++ seeding with seed for determinism, per-iteration re-normalisation under cosine, and a graceful available=false path. It stops short of describing cost/latency or iteration behaviour at the max-iterations cutoff.

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 core operation, then mechanics, then constraints, then a runnable example. Dense but almost every clause adds operational meaning; the parenthetical defaults are slightly redundant with the schema but serve as a quick reference.

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 10-parameter analytical tool with an output schema present, the description covers the essential mechanics, metric semantics, constraints and failure mode. The one real hole is max_iterations, which affects runtime and result quality but is never described.

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 only 10%, so the description carries most of the burden and does well for sample_size (default 5000), seed, metric ('l2' squared Euclidean vs 'cosine' normalised), k (>= 2) and id_column (assignment identity vs positional sample index). However max_iterations is never mentioned and the sampling/failure semantics of the remaining params are thin, so it only partly compensates for a 10% coverage schema.

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

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

States a specific verb and resource: 'k-means cluster a pgvector column' on schema.table.embedding_column. An agent can tell this apart from retrieval siblings like vector_search or diagnostic siblings like detect_vector_outliers 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?

Usage is implied rather than stated: it covers preconditions (pgvector required, k >= 2, at least 2k parseable rows, available=false otherwise) which tells the agent when it will fail, but never says when to pick this over sibling tools such as analyze_distance_metric or detect_vector_outliers. No explicit when-to-use/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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description goes further with real behavioral context: the granularity of objects diffed, the exclusion of views and custom types, and the notable quirk that renames appear as a paired add + remove rather than as a rename — something an agent could otherwise misreport. It doesn't discuss size/limits of the diff output, which is the only meaningful 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?

Three short sentences front-load the return value, then scope limits, then the rename quirk, with the example last. No filler, and each sentence carries distinct information.

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

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

An output schema exists, so the description isn't obligated to explain the diff structure, and for a two-schema comparison tool the stated scope and rename behavior are nearly sufficient. The missing piece is the left/right directionality, which matters for interpreting any diff result.

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 only 33%: the database parameter is well documented inline, but left_schema and right_schema have no schema-level descriptions. The example supplies value semantics for those two (schema names such as 'public' and 'staging'), but the description never states the direction of the diff — which side counts as 'added' versus 'removed' — leaving a real risk of inverted interpretation.

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 result object — 'structural diff between two schemas' — and enumerates exactly what is compared (tables/columns/indexes/constraints/foreign-keys). It also carves out scope ('base tables only; views and custom types are not compared'), which cleanly separates it from siblings like list_views, list_composite_types, or generate_schema_diagram.

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?

Explicit exclusions tell the agent when this tool will NOT answer the question (views, custom types), and the worked example demonstrates a concrete call. It stops short of naming an alternative tool for the excluded cases, so the agent must infer that from siblings, but the usage context is otherwise clear.

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

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

Well beyond the readOnlyHint/openWorldHint annotations, it discloses the internal sequence (locate source row by id, read embedding, issue k-NN against target), the up-front dimension validation that converts a silent cast error into a clear failure, and the two sentinel outcomes (source_embedding_found=false, available=false when pgvector is missing). That is exactly the failure-mode information an agent needs.

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 primary action is front-loaded in the first sentence and each subsequent sentence adds a distinct, non-redundant fact: mechanism, validation guarantee, intended use, and return flags. No filler or restatement of the title.

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

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

For an 11-parameter tool with an output schema, the description covers the workflow, the dimension precondition, and the noteworthy return flags. The remaining gap is the distance-metric parameter and its allowed values, which an agent must still guess at.

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 9%, so the description must carry parameter meaning, and it does explain the role of source_id_column, source_id_value, source_embedding_column, target_embedding_column and both schema/table pairs through the narrative. However, `metric` is never mentioned and no supported values are given, and `k` is only implied by "the k rows" with no note that it defaults to 10.

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?

"Find the k rows in target_schema.target_table most similar to a specific row in source_schema.source_table" gives a concrete verb, both resources, and the direction of the join. The description then names the exact mechanism (id lookup, embedding read, pgvector k-NN), which separates it from siblings like vector_search or mmr_search that operate within a single table.

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 states the intended use case explicitly: "Useful for entity-resolution / linking across tables whose embeddings come from different models but share a dimension." That gives a clear context for reaching for this tool, but it never names an alternative tool or says when not to use it (e.g. same-table search should go to vector_search).

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

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

Beyond the readOnlyHint annotation, the description discloses that it reads pg_appendonly, returns is_ao=false for regular heap tables, and returns available=false on vanilla PostgreSQL. These are meaningful behavioral details about data source and fallback outcomes, though permissions and output shape are left to schema/annotations.

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

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

The description is compact and front-loaded: it states purpose, lists returned metadata, explains fallback behavior, and ends with a single example. Every sentence contributes relevant information without repetition.

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

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

Given the output schema and read-only annotation, the description provides enough context to call the tool correctly, including fallback cases for regular heaps and vanilla PostgreSQL. Minor gaps remain around parameter semantics and explicit sibling comparison, but the core behavior is well covered.

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 only 33%, and the description does not compensate by explaining the schema and table parameters beyond a minimal example. The optional database parameter is described in the schema, not the tool description, so parameter meaning is largely left to structured fields.

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

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

The description names a specific verb and resource: describing append-optimized storage metadata for one table. It lists the concrete metadata fields and clearly distinguishes this from a generic table description by focusing on AO/AOCO orientation and compression details.

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 usage context is clear: call this when you need AO/AOCO storage metadata for a specific table, and the example shows the required schema/table combination. It does not explicitly compare against sibling tools such as describe_table, but the AO-specific scope makes the intended use evident.

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 description's 'Describe' operation is consistent. The description adds value by specifying return object fields (`graph_name`, `vertex_labels`, `edge_labels`), providing behavioral context beyond the annotations.

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

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

Two sentences, 20 words, no fluff. Efficiently conveys purpose and return structure.

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?

Tool is simple with one parameter and an output schema. Description covers main purpose and return format. Lacks mention of prerequisites (e.g., graph must exist) or error behavior, but these are minor gaps.

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

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

The sole parameter `graph_name` has no schema description (0% coverage). The description only says 'specific property graph', adding minimal meaning about what value to provide. For a single required parameter, more guidance is needed.

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

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

Description clearly states the tool describes schema structure, vertex labels, and edge labels of a property graph, and lists return fields. However, it does not distinguish from the sibling 'describe_property_graph', which likely serves a similar purpose.

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 guidance on when to use this tool versus alternatives like 'describe_property_graph' or when not to use it. Lacks context for appropriate invocation.

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 and openWorldHint, so the safety profile is covered; the description adds genuinely new behavior in the PG 19+ version gate and the fact that it raises an error otherwise. It also enumerates the returned fields (`schema`, `name`, `vertex_tables`, `edge_tables`), though that information is largely duplicated by the existing output schema.

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

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

Three tight sentences plus an example; the version gate and usage path are front-loaded before the return-shape detail. The example is mildly redundant with the parameter names but cheap and clarifying.

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

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

The description covers version requirements, error behavior, call-site context, and return contents, and an output schema exists so return details need not be fully restated. The one real hole is the undocumented `database` parameter for secondary read-only targets, which an agent could easily overlook.

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 only 33%: `schema` and `name` have no schema descriptions, and the third parameter `database` (targeting a configured secondary read-only database) is never mentioned in the description. The worked example (`describe_property_graph(schema='public', name='org_chart')`) partially compensates for the two required params, but the multi-database targeting behavior is left entirely to 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?

States a concrete verb and resource ("Describe one SQL/PGQ property graph by schema-qualified name") and scopes it to a single object, which separates it from the list-style siblings. The "SQL/PGQ" qualifier implicitly distinguishes it from the Apache AGE-oriented `describe_graph`/`list_graphs` tools, and it is not a tautology of the title.

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 upstream/downstream chain: locate the graph with `list_property_graphs`, then call this, then compose a `run_pgq` query. It does not explicitly say when NOT to use it (e.g., when `describe_graph` is the right tool for non-PGQ graphs), so the routing is strong but not exhaustive.

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 openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it discloses the error behavior for missing/non-redis tables and enumerates the returned fields, which annotations cannot convey.

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

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

The text is front-loaded with purpose, then behavior, then return shape, then a compact example — a sensible structure. It is somewhat dense with return-field enumeration, but each clause carries information 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?

An output schema exists, so the return-field listing is partially redundant, but for a describe-style tool the extra specificity is harmless. Combined with the error behavior and the example, an agent has enough to invoke it correctly; the only gap is guidance on when to prefer this over describe_table or list_foreign_tables.

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 only 33% — only the optional `database` parameter is documented (and that is documented in the schema, not the description). The description's example call clarifies the required `schema` and `table` as identifier arguments, but adds no semantics for the primary/secondary database targeting beyond what the schema already states.

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

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

The description opens with a specific verb and resource ('Describe one foreign table backed by redis_fdw') and immediately enumerates what is disclosed (server mapping, Redis key type, prefix, TTL, SQL column shape). This distinguishes it clearly from sibling tools like describe_table or list_foreign_tables, which are generic rather than redis_fdw-specific.

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 redis_fdw scoping and the error condition ('raises an error when the table doesn't exist or isn't backed by redis_fdw'), which implicitly routes agents with ordinary tables to describe_table. However, no sibling is named explicitly and there is no explicit 'use this instead of X when Y' guidance.

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

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

Annotations already provide readOnlyHint=true, and the description adds 'Read-only; no database access,' which is consistent and adds useful behavioral context. No contradictions.

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

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

The description is concise, front-loads the purpose, and every sentence adds value. No wasted words.

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

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

For a zero-parameter tool with annotations and an explicit output schema, the description fully covers what the tool does and its context. It is 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?

No parameters exist, so baseline 4 applies. The description need not add parameter information, and it doesn't.

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 explicitly states the tool returns a high-level summary of mcpg's capabilities organized into buckets. It clearly distinguishes itself from siblings by stating it's 'much more compact than walking the full tool catalogue.'

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

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

The description explicitly says 'Call this first when discovering mcpg's surface' and suggests pairing with list_tools, providing clear when-to-use and relative advantage over alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: results are cached by default and fresh=true forces a live re-read after DDL. It does not discuss what happens for a nonexistent table or schema, which is a minor remaining 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?

Three short sentences plus a concrete example, with the core action and output shape front-loaded and the fresh-flag caveat immediately after. The example is mildly redundant since both named parameters are required and self-explanatory, but it earns its place as a call-shape illustration.

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 introspection tool with an output schema present, the description covers the action, ordering, caching behavior, and result shape, which is close to sufficient. The only notable omission is error behavior for missing schemas or tables, which an agent may need when probing unknown objects.

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 only 25%, with just `database` documented inline, so the description must compensate and largely does: it explains the cache-bypass meaning of `fresh` and demonstrates schema/table usage in the example. The optional `database` targeting is handled by the schema itself, leaving no parameter entirely unexplained across the two sources.

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 — describing the columns of a table, returned in ordinal order — which is far more precise than the title alone. It doesn't explicitly distinguish itself from nearby siblings like list_tables, list_generated_columns, or describe_ao_table, so an agent must infer the boundary, but the column-level intent 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?

Usage guidance exists but is scoped to one parameter: set fresh=true after a schema change to bypass the cache. There is no statement of when to choose describe_table over list_tables or another metadata sibling, and no exclusions or prerequisites 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 declare readOnlyHint=true and openWorldHint=false. Description reinforces with 'Read-only; no database access.' and describes error behavior (registered=false + did_you_mean). No contradictions.

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

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

Concise single sentence covering return value, usage context, error handling, and read-only nature. Followed by example. No redundant information.

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

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

Given the tool's simplicity (1 required param, no nested objects, output schema exists), the description covers all necessary aspects: purpose, usage, error handling, safety, and example. Fully adequate.

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?

Only one parameter (name) with no schema description coverage (0%). Description adds value by mentioning 'by name' and providing an example: describe_tool(name='run_select'), but does not elaborate on format or constraints beyond what's obvious.

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?

Clearly states it returns the full registered schema for one MCP tool by name, including description, input_schema, output_schema, and capability bucket. Distinguishes from siblings like describe_self by specifying it targets a single tool.

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 advises using this tool when an agent encounters a tool error and needs to verify the call shape without re-walking the full describe_self payload, especially when transport only surfaces tools/call. Also mentions did_you_mean on error, providing clear guidance.

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

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

Annotations cover read-only/local behavior, and the description adds real value beyond them: result ordering (total time descending), the availability=false signal when pg_stat_statements is not installed, and the caveat about interpretation. It does not mention auth requirements or cost/latency of the scan itself, but it is well above the annotation floor.

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

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

Front-loaded with the purpose, then ordering, then tuning knobs, then the interpretation caveat and failure mode. Each sentence carries distinct information with no filler or repetition.

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

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

With an output schema present and read-only annotations supplied, the description covers what is needed to call and interpret the tool: purpose, ordering, tunables, caveat, and extension-absent behavior. The only real gap is that `limit` and the precise threshold semantics are left to a sparse schema.

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

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

Schema description coverage is only 20% (only `database` is documented), so the description has to compensate. It does name the three tunable thresholds (min_calls, max_rows_per_call, min_total_ms) and implies their meaning through the N+1 shape description, but it never explains `limit` or states defaults/exact semantics for the thresholds. Partial compensation only.

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 ('Surface query templates in pg_stat_statements that look like an N+1 loop') plus the exact detection shape (hundreds of calls, one or two rows each, meaningful wall-clock time). That is clearly distinct from siblings like recommend_indexes, analyze_workload, or why_is_this_slow, which are broader diagnostics.

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 strong usage context: results are candidates for investigation, not verdicts, and it names the false-positive shape (hot cache-miss on a primary-key lookup). It also states the failure mode when pg_stat_statements is absent. It stops short of naming a specific alternative tool to run instead when the result set is noisy or when the extension is missing.

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

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

Annotations only cover read-only and closed-world safety, and the description goes well beyond them: it discloses the sampling strategy (up to sample_size non-NULL rows, default 5000), the hard preconditions (k >= 2, at least 2k parseable rows), and the availability failure mode (available=false when pgvector is absent). It does not mention cost/latency implications of sampling and clustering a large table, which keeps it from a 5.

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

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

A single dense paragraph with the core action front-loaded and no filler sentences; the sampling, threshold, and return-value details each add information. It would read faster with light structure given its length, and the return-value sentence is partly redundant with the existing output schema.

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

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

For a 12-parameter analytical tool with an output schema, the description covers what an agent needs: what is sampled, how scoring works, preconditions, failure modes, and result shape. The remaining undocumented knobs (metric, seed, max_iterations) are tuning parameters with sensible defaults rather than blockers to a correct first call.

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 only 8%, so the description carries most of the burden and largely does: it defines sample_size, zscore_threshold, id_column, max_results, and k, including defaults and the k >= 2 constraint. It leaves metric, seed, and max_iterations entirely unexplained in both schema and description, which is a real gap for a 12-parameter tool.

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: 'Flag pgvector rows whose embedding sits far from any cluster centroid.' The method (k-means per cluster, then z-score of centroid distance) is spelled out, so the agent can distinguish this from sibling clustering/drift tools like cluster_vectors or monitor_embedding_drift 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?

It states the intended semantics of the operation, noting that per-cluster scoring 'is usually what find outliers should mean' versus weird-overall detection, which gives real context for choosing it. It also points at cluster_vectors as the shared engine. It stops short of explicit when-not conditions or naming alternative tools for adjacent tasks (drift monitoring, recall analysis), so it falls shy of a 5.

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