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

Annotations indicate readOnlyHint=true, and description adds behavioral details: sampling rows, computing L2 norms, applying heuristic, and reporting availability. No contradiction; description supplements annotations well.

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

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

Description is front-loaded with purpose, then details steps and heuristic, then return values. It is relatively long but every sentence adds value. No fluff.

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

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

Given the output schema exists and annotations are provided, the description covers the heuristic, sampling method, return values (metric, rationale, stats), and availability check. It is complete for the tool's complexity.

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

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

Schema description coverage is low (20%), but description adds meaning by explaining how schema, table, and column are used (sampling embeddings) and the role of sample_size. It clarifies sampling behavior beyond schema but could be more explicit about parameter types.

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

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

Description clearly states it recommends a pgvector distance metric (cosine, l2, inner_product) based on embedding-magnitude distribution. It distinguishes from siblings like analyze_hnsw_recall and analyze_vector_search_efficiency.

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

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

Description provides context for when to use (e.g., to choose a distance metric based on embeddings) but does not explicitly exclude alternatives or state when not to use. The heuristic explains the decision process, but lacks explicit guidance versus sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds value by explaining that the tool performs a sweep of ef_search values, compares against exact brute-force, and returns latency and recall metrics. It does not contradict annotations and provides useful behavioral context, though it omits potential performance impact warnings.

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 extremely concise: two sentences that front-load the action and purpose, then detail the output format. No wasted words; each sentence earns its keep.

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

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

Given the tool's complexity (sweeping ef_search, computing trade-off) and the presence of an output schema, the description is nearly complete. It explains what, why, and what is returned, but does not specify how ef_search values are chosen (e.g., range, defaults) or warn about potential long execution time.

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 low (14%), so the description should compensate. While it provides overall context (e.g., query_vector is the query vector, k for recall@k), it does not explicitly describe each parameter beyond the database parameter's schema description. The description helps interpret parameters but lacks detailed mapping.

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 that the tool sweeps ef_search values to measure the latency-recall trade-off for a pgvector query vector against exact brute-force ground truth. It uses a specific verb ('sweeps') and identifies the resource (pgvector query vector), distinguishing it from sibling tools like analyze_vector_search_efficiency or vector_recall_at_k.

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

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

The description implies the tool is for tuning recall vs. latency and mentions a prerequisite (requires vector extension), but it does not explicitly guide when to use this tool versus alternatives among the many analyzer siblings. It lacks 'when to use' and 'when not to use' guidance.

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

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

Annotations already indicate read-only and open-world false. The description confirms read-only behavior and details the return structure, adding transparency about output shape and that it never modifies state.

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-loading the main action and read-only nature, followed by pairing advice and return type details. It is well-structured without unnecessary 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?

Given the tool's simplicity, the description covers purpose, usage, output, and example. It compensates for any missing output schema by detailing the return object. Completeness is high.

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

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

Schema coverage is 100% with a clear description of the single optional parameter. The description does not add significant beyond the schema; baseline 3 is appropriate.

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

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

The description clearly states the tool analyzes lock hotspots by ranking pg_stat_lock rows with wait dominance and stable reason codes. It distinguishes from siblings like read_pg_stat_lock and pairs with find_blocking_chains for specific active lock types.

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

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

The description provides explicit pairing advice with find_blocking_chains for specific hot lock types, guiding when to use this tool. It does not list exhaustive conditions for alternatives but gives useful context.

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

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

Annotations declare readOnlyHint=true, openWorldHint=false. The description adds value by confirming no writes/DDL, detailing the safety pre-flight, and explaining the output (slice count, motion nodes, metadata). It also discloses the vanilla PG behavior. No contradictions with annotations.

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

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

The description is concise, front-loaded with the core action, and organized into clear sentences. It ends with a relevant example. Every sentence contributes value without redundancy.

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

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

Given the complexity of MPP query plan analysis, the description covers key outputs (slice count, motion types, metadata), safety constraints, and availability. The presence of an output schema (context) reduces the need to detail return fields. Minor gap: edge cases or error handling not addressed.

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 50% (database param documented, sql param not). The description adds meaning for 'sql' via its purpose and example, but does not detail the database parameter beyond what the schema provides. This partially compensates; baseline 3 is appropriate.

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

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

The description clearly states the tool runs EXPLAIN (ANALYZE, FORMAT JSON) on SQL and rolls up MPP-specific facts like slice count and motion nodes. It differentiates itself from sibling analyze_query_plan by referencing the same safety pre-flight, and specifies behavior on vanilla PG (returns available=false). This provides a specific verb+resource and distinguishes from siblings effectively.

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 indicates that writes/DDL are rejected (when not to use) and that the tool is MPP-specific (vanilla PG returns false). It gives an example and mentions the safety pre-flight analogy to analyze_query_plan(io=True). However, it does not explicitly contrast with other plan analysis tools or state prerequisites (e.g., MPP extension), which would improve guidance.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable context about the io flag's behavioral impact (adding actual timing, buffer stats, and AIO fields). No contradiction.

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

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

The description is concise: two sentences plus an example. It front-loads the main purpose and uses precise language. Every sentence adds value.

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

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

Given the tool's complexity and the presence of an output schema, the description covers the essential aspects (purpose, parameter effects, example). It does not explain error handling or all output fields, but the output schema fills that 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 coverage is low (33%), but the description compensates by explaining the io parameter in detail (what extra fields it adds) and providing an example. The database parameter is already described in schema, and sql is explained implicitly.

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

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

The description clearly states the tool's purpose: 'Summarise a query's execution plan' with specific elements (cost, rows, node types, sequentially-scanned tables). It distinguishes itself from siblings like explain_query or optimize_query by focusing on summarizing the plan.

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

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

The description provides explicit guidance on when to set io=true and why (for actual timing and AIO details). However, it does not compare to sibling tools or state when not to use this tool.

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

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

Discloses data source (mcpg_rag.rerank_events) and edge cases (zero counts when table missing or window empty). No contradiction with annotations (readOnlyHint=true).

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 sentences, front-loaded with the core metric, efficient wording, no redundancy.

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

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

Given output schema exists, annotations present, and parameters explained, the description covers behavior, edge cases, and data source adequately.

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

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

Schema coverage is only 25% (only database has description), but description adds meaning for model and retrieval_index filters and implies days default. It partially compensates for 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?

Description clearly states the core function: computing per-query Spearman and Kendall correlations between bi-encoder and cross-encoder ranks. It also mentions a specific alert (reranker_idle), making the tool's purpose precise and distinguishable.

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

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

Description provides interpretation guidance (low correlation = active reordering, high = confirming) and mentions optional filters. However, it does not explicitly compare to sibling tools like analyze_rerank_ndcg or state when not to use this tool.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description adds behavioral details: it reads from mcpg_rag.rerank_events, returns zero counts when no labeled rows exist, and surfaces specific indicators. No contradictions with annotations.

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

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

The description is two sentences, clear and front-loaded, but slightly verbose. Could be trimmed without losing meaning. Still efficient.

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

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

Given an output schema exists, the description does not need to explain return values. It covers key behavioral aspects and constraints (reads specific table, handles missing data). Lacks mention of performance or window implications, but is complete for its purpose.

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 only 20% schema description coverage, the description does not explain the parameters k, days, model, database, or retrieval_index beyond what the schema provides. The schema has descriptions only for database. The description adds no parameter semantics, which is insufficient for an agent to correctly invoke the 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 clearly states the tool computes NDCG@k comparing bi-encoder vs cross-encoder ordering, reports a delta, and surfaces specific indicators. It distinguishes itself from sibling tools like analyze_reranker_lift by focusing on NDCG and the delta.

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

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

The description explains what the delta means (positive vs negative) and indicates critical vs good evidence. However, it does not explicitly state when to use this tool over similar alternatives, such as analyze_reranker_lift, nor does it provide when-not 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. The description adds value by specifying the data source (mcpg_rag.rerank_events), the computation details (equal-width histogram, top-decile share), and the advisory finding logic (score_clustering warning). This provides useful behavioral context beyond the annotations.

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

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

The description is concise (three sentences), front-loads the main action, and each sentence adds essential information. There is no redundancy or unnecessary detail.

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

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

Despite five parameters, the description explains the core analysis, the source table, the advisory finding, and the return fields. With an output schema available, the description is complete enough for an agent to understand the tool's behavior and results.

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

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

Schema description coverage is only 20% (database parameter). The description adds meaning for 'days' (window) and 'n_buckets' (bucket count), but does not explain the 'model' or 'retrieval_index' parameters. It partially compensates for low coverage, but not fully.

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

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

The description clearly states it produces an equal-width histogram of cross_encoder_score values and calculates the top-decile share, distinguishing it from sibling analysis tools that focus on other metrics (distance, recall, etc.). The verb 'analyze' is specific to this resource.

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

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

The description implies usage for rerank score distribution analysis and flagging score clustering, but provides no explicit guidance on when to choose this tool over the many sibling analysis tools. It does not mention when not to use it or suggest alternatives.

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

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

Beyond the annotations (readOnlyHint=true), the description adds rich behavioral details: it reads `mcpg_audit.events`, flags tools exceeding a threshold, handles idle sessions, handles the case where the audit table doesn't exist, and explains different findings for catalogue-listing vs. other tools. No contradictions with annotations.

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

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

The description is front-loaded with the main purpose in the first sentence. It is detailed but efficient, covering key behaviors without unnecessary wordiness. The example at the end helps clarity. Could be slightly more structured but overall concise for the complexity.

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

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

Given that there is an output schema (not shown but indicated), the description already covers all necessary context: the input parameters, the source table, behavioral edge cases (missing table, idle sessions, category-specific findings), and the structure of the return object. It is very complete for an agent to use effectively.

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

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

The description adds meaning beyond the input schema: it explains the default and cap for `lookback_minutes`, the default for `hot_threshold`, and that `database` is optional for targeting a secondary read-only database (referencing `list_databases`). Given 33% schema coverage, this compensates 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 clearly states 'Surface hot-path inefficiencies from the audit log' and specifies reading from `mcpg_audit.events`. It distinguishes from sibling analyze tools by focusing on session cost based on audit log data, which is unique among the many analyze_* tools listed.

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

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

The description provides clear context for when to use the tool (to find hot-path inefficiencies), includes default values and constraints (capped at 1440 minutes), and gives an example. However, it does not explicitly state when not to use this tool or mention alternatives among sibling tools, leaving some room for ambiguity.

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 discloses key behavioral traits: the two estimation methods (catalog vs. I/O-heavy precise), fallback to estimate if pgstattuple is missing, and the return of a method field. This adds significant value beyond the annotations (readOnlyHint, openWorldHint), which already indicate read-only behavior. No contradiction.

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

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

The description is concise (3 sentences plus an example), well-structured, and front-loaded. The first sentence states the purpose, the second explains methods, and the third describes the return structure. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (two methods, multiple output fields), the description provides sufficient context: it mentions return fields (tables, indexes, est_bloat_pct, available, method) and the fallback behavior. The presence of an output schema further supplements completeness. No gaps remain for an AI agent to misuse the tool.

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

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

Schema coverage is low (25%), but the description adds meaning by explaining the precise parameter's effect and fallback. It mentions limit, schema, and precise in the example. However, it does not describe the schema or limit parameters in depth beyond what the schema provides. The output schema likely documents return fields, so the description compensates adequately for the low parameter 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?

The description clearly states the tool's purpose: 'Rank a schema's tables and indexes by estimated bloat, worst first.' It uses a specific verb ('rank'), identifies the resource ('tables and indexes'), and specifies the scope ('by estimated bloat'), distinguishing it from sibling tools like analyze_lock_hotspots or analyze_query_plan that focus on other metrics.

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

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

The description explains when to use the tool (for bloat analysis) and provides an example. It also clarifies the precise parameter behavior and fallback logic. However, it does not explicitly state when not to use it or mention alternative tools for related tasks, though the sibling list provides context.

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

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

Annotations already mark the tool as read-only and deterministic. The description adds valuable behavioral details including data source ('mcpg_rag.rerank_events') and edge-case behavior ('returns a report with zero counts when table doesn't exist or window is empty'). This fully satisfies transparency beyond annotations.

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

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

The description is concise (two sentences) and front-loaded with the core purpose. It wastes no words, but the structure could be improved with clearer separation of purpose, usage, and behavior. Still, it is more efficient than typical verbose descriptions.

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

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

Given the tool's moderate complexity (5 parameters, zero required) and presence of an output schema, the description fails to cover parameter semantics adequately. However, it does cover edge behavior and provides sufficient context for the core metric. Sibling tools are distinct, so identification is clear.

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 only 20% schema description coverage, the description adds no parameter explanations. While parameter names ('k', 'days', 'model', 'database', 'retrieval_index') are somewhat self-explanatory, the description does not clarify their semantics, defaults, or interplay. This is inadequate for a 5-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?

The description clearly states the tool's purpose: calculating Jaccard overlap between top-K by bi-rank and cross-rank per query. It uses a specific verb ('analyzes') and distinct resource ('top-k stability'), and uniquely positions itself among sibling analyze tools.

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

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

The description indicates when to use the tool (to detect if the reranker is not changing top-K membership, with a 'topk_stable' warning). It lacks explicit when-not-to-use guidance or comparison to alternatives like 'analyze_reranker_lift', but provides clear context.

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

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

The description discloses significant behavioral traits beyond the annotations: it burns queries (resource use), emits specific findings with severity levels (baseline_recall_low, rerank_lift_flat, etc.), and requires extensions. The readOnlyHint=true annotation is consistent with 'report', and the description adds that it runs queries (read-only but costly) and provides diagnostic output.

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 four sentences long and packs dense technical information. It is front-loaded with the main purpose. While a bit verbose with acronyms and technical details, every sentence adds value. Could be slightly tighter, but overall efficient.

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

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

Given the tool's complexity (10 parameters, output schema exists, multiple backends), the description is remarkably complete. It covers what the tool does, how it works (sweep knobs, exact baseline comparison, per-query latency, page-pruning ratio), what findings it emits, its resource cost, and prerequisites. The output schema (not shown) likely documents return values, so the description rightly focuses on behavior.

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% (only database has a description). The description adds context for sample_size and candidate_multipliers (mentions sweeps across a multiplier curve) and implies how k and metric are used. However, it does not explain parameters like schema, table, column, id_column, or index_name in detail. It partially compensates by explaining the overall algorithm, but many parameters remain underspecified.

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 it produces a 'cross-backend retrieval-quality report' for ANN indexes, naming specific backends (HNSW, IVFFlat, turboquant) and listing the exact metrics computed (recall@k, latency, rank correlation). This clearly distinguishes it from sibling tools like analyze_hnsw_recall, vector_recall_at_k, and tune_vector_index, which have narrower scopes.

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

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

The description provides clear usage guidance: it is an 'ad-hoc diagnostic, not a cron tool' and warns about the query burden ('Burns sample_size x (1 + len(candidate_multipliers)) queries'). It also states prerequisites (vector extension, pg_turboquant for turboquant metrics). However, it does not explicitly contrast with similar tools like analyze_hnsw_recall or recommend when to use this over them.

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 discloses that the tool depends on the pg_stat_statements extension and reports availability=false if not installed, adding behavioral context beyond the readOnlyHint annotation. It does not detail every behavioral aspect but is sufficient given 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 succinct sentences plus an example, front-loaded with key information. Every sentence adds value, achieving high efficiency.

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 the tool's core functionality, dependency on an extension, and availability behavior. With an output schema present, explanation of return values is unnecessary, making the description complete.

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

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

Schema coverage is 50% with only the database parameter described. The description provides an example using the limit parameter but no further semantics. Baseline is 3 due to coverage, and the description adds only marginal value beyond the schema.

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

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

The description clearly states the tool returns the slowest queries by mean execution time, a specific verb+resource. It distinguishes from sibling analysis tools by focusing on workload via pg_stat_statements and explicitly mentions the availability flag when extension is missing.

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 indicates usage for identifying slow queries with an example syntax, providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives among the many sibling analyze tools.

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

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

Annotations declare readOnlyHint=true, and the description adds context by naming the resources scanned (memory, checkpoints, etc.), which are all read operations. It discloses caching behavior with fresh parameter. No contradictions; description adds value beyond annotations.

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

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

The description is a single paragraph that is fairly concise and front-loads the purpose. It avoids fluff but could benefit from bullet points for the return object fields or parameters. Still efficient.

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

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

Given the presence of an output schema and 4 parameters, the description covers the return structure (fields listed) and key behavioral points. It lacks mention of permission requirements or failure modes, but is generally complete for a read-only 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 low (25%). The description adds meaning for fresh (cache bypass) and log_table (custom logging tables), and implies schema scope, but does not fully explain database or schema parameters beyond minimal wording. Compensates partially but not completely.

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

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

The description clearly states the tool performs a comprehensive DBA-level audit, listing specific areas it scans and return fields. It distinguishes itself from siblings by being 'deep, comprehensive DBA-level', but could explicitly differentiate from similar tools like check_database_health.

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

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

The description provides guidance on when to use fresh=true (after schema change) but lacks explicit when-not-to-use, prerequisites, or alternatives. It implies use for comprehensive audits but offers no exclusions.

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

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

Consistent with annotations (readOnlyHint=true), the description explicitly states 'Pure read'. It adds valuable context about PG<10 availability and the catastrophic nature of overflow, providing behavioral details beyond annotations.

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

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

The description is concise yet comprehensive, covering purpose, importance, read-only nature, PG version caveat, and return structure in a few efficient sentences. Every sentence adds value, and the example at the end aids understanding.

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 purpose and complexity, the description is highly complete. It explains the return object fields in detail, handles the PG<10 edge case, and is sufficient for an agent to understand and invoke the tool correctly without needing the output schema.

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

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

Schema coverage is low (33%), but the description adds meaning by defining the purpose of warning_pct and critical_pct with defaults and giving an example call. This compensates for the schema's lack of descriptions for those parameters.

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

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

The description clearly states the tool flags sequences nearing their ceiling, specifying serial/identity/explicit sequences and the warning/critical thresholds. This distinguishes it from sibling tools like list_sequences which list all sequences without risk analysis.

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

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

The description implies usage for proactive overflow monitoring and notes that overflow is catastrophic and silent. However, it does not explicitly contrast with alternatives like list_sequences or when not to use it, slightly limiting guidance.

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

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

The description comprehensively discloses behavior: it lists specific settings flagged, explains cross-setting comparisons, and details RAM-relative ratios with the caveat that PostgreSQL cannot see host RAM. This significantly adds context beyond the annotations (readOnlyHint, openWorldHint), accurately reflecting a non-destructive read audit.

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 yet packed with information, using clear formatting (backticks for settings, bullet-like listing, example call). Every sentence adds value, and the example at the end helps illustrate usage without redundancy.

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

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

Given the tool's complexity (auditing multiple dimensions of PostgreSQL configuration), the description covers all key aspects: dangerous toggles, cross-setting issues, RAM analysis, and return format. The output schema exists, so detailed return description is not necessary. The example further clarifies usage, making the description fully complete for an AI agent.

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

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

For the total_ram_mb parameter, the description adds critical meaning: 'when total_ram_mb is supplied — RAM-relative ratios for shared_buffers / effective_cache_size (PostgreSQL can't see host RAM itself).' This compensates for the schema lacking a description for that parameter. The database parameter is already well-described in the schema, so overall parameter clarity is excellent.

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

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

The description clearly states it performs a 'Sanity-sweep of postgresql.conf via pg_settings' and enumerates specific dangerous toggles, cross-setting issues, and RAM-relative analysis. It distinguishes from sibling tools like audit_database and audit_sequences by its focus on configuration settings rather than schema or data audits.

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

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

The description implies usage for auditing PostgreSQL configuration, emphasizing it is a 'Pure read' operation. It provides context on when the total_ram_mb parameter is useful but does not explicitly state when not to use this tool or mention alternative tools for similar purposes.

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 transparently lists the health checks performed and the return structure (status and checks list). Since annotations already mark it as read-only, this adds useful behavioral context without contradiction.

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

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

The description is concise: two sentences plus an example. It is front-loaded with the core action and details. Every sentence adds value, with 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?

Given the simple single optional parameter and the described output structure (status and checks), the description is complete. It covers what the tool does, input, and return format. No additional context needed.

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

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

Schema description coverage is 100% with a clear explanation of the optional parameter. The tool description does not add further parameter semantics, but the schema already provides adequate meaning. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool runs database health checks and lists specific checks (connection utilisation, buffer cache hit ratio, tables needing vacuum, invalid indexes). This differentiates it from sibling analysis or audit tools, making the purpose explicit and distinct.

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

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

No explicit guidance on when to use this tool versus alternatives like audit_database or other check tools. The description implies a quick health overview but does not provide context for selection or exclusion.

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

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

The description fully discloses behavior: read-only, no secrets emitted, checks specific GUCs and archiving status. Annotations already indicate readOnlyHint=true, so the description adds value by detailing what is checked and what is not changed.

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 yet comprehensive. It front-loads the core purpose, then details the composed checks and return fields. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema (context signals), the description does not need to explain return values. It covers the logical flow and includes an example call. Complete for the tool's complexity.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema by explaining the parameter's purpose (target secondary database) and providing guidance (call list_databases). This is very helpful for the agent.

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

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

The description clearly states the tool's purpose: assessing PITR readiness for a cluster. It uses specific verbs ('assess', 'check') and defines the resource (cluster readiness). It distinguishes itself by referencing sibling tools like get_wal_archive_status.

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

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

The description explains the tool is a read-only advisor that changes nothing, implying safe use. It mentions composing other tools but does not explicitly state when not to use it or provide alternatives. However, the context of a readiness check is clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds significant context: it explains the specific behavior (walking gp_segment_configuration), return format (per-segment with aggregated counts), and the edge case of returning `available=false` on vanilla PG. No contradiction.

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

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

The description is concise (4 sentences), well-structured, and front-loaded with the main purpose. It includes an example call. Every sentence adds value, and there is no unnecessary 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 tool has an output schema (not shown but signaled), the description covers all necessary aspects: main functionality, output details, edge case, and example. It is complete for a simple health-check tool with one optional 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?

The single parameter `database` is fully described in the input schema (optional, target secondary DB). The description adds the helpful instruction 'Call list_databases to see the configured ids', which aids agent understanding beyond the schema.

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

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

The description clearly states it walks `gp_segment_configuration` to surface MPP segment posture, details the output fields (status, mode, role vs preferred_role, top-level counts), and distinguishes its read-only nature and behavior on vanilla PG. This is specific and avoids confusion with sibling tools like `check_database_health`.

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

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

The description implies usage for MPP segment health checking via `gp_segment_configuration` and mentions top-level summary for quick branching. While it does not explicitly state when not to use or list alternatives, the niche is clear given sibling tools. A slight improvement would be to add a note like 'not for single-node PG'.

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?

The description discloses algorithm details (Lloyd's, k-means++ seeding), metric behavior (l2 vs cosine normalization), determinism via seed, sampling, and output structure (centroids with size, assignments with cluster index and distance). Annotations (readOnlyHint: true) are consistent with the read-only nature of clustering. 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 yet comprehensive, using a single paragraph with an illustrative example. Every sentence adds value: start with verb, then algorithm details, then parameter specifics, then a clear example. No redundant or vague statements.

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 10 parameters, 4 required, and the presence of an output schema (which handles return values), the description covers all necessary aspects: purpose, conditions, algorithm details, parameter behavior. The example ties everything together. It is complete for an AI agent to understand and invoke the tool correctly.

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

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

Schema coverage is only 10% (only 'database' parameter has a description), but the description compensates fully by explaining the role and default of sample_size, seed, metric, id_column, k, and max_iterations. The example further clarifies parameter usage. This adds significant meaning beyond the bare schema.

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

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

The description clearly states it performs k-means clustering on a pgvector column, specifying the algorithm, inputs, and outputs. It distinguishes itself from sibling tools by being a dedicated clustering function, which is unique among the listed tools.

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

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

The description provides explicit usage context: requires pgvector installed, k >= 2, at least 2k rows, and default sample size. It also mentions fallback behavior ('Reports available=false if pgvector is not installed'). Although no direct alternatives are mentioned, the tool's purpose is distinct, making usage 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?

The description reveals that renames surface as paired add+remove and lists the exact structural elements compared. This adds value beyond the readOnlyHint annotation by detailing the diff behavior and limitations.

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

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

The description is three sentences long, front-loaded with the main purpose, and includes a concise example. Every sentence adds necessary information without redundancy.

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

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

The description covers what is compared, the exclusion of views and custom types, and how renames appear. With an existing output schema for return format, the description is sufficiently complete for a structural diff 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 33% (only 'database' described). The description compensates with an example showing left_schema and right_schema as schema names, clarifying their usage. However, it does not elaborate on additional constraints or values.

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

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

The description clearly states the tool returns a structural diff between two schemas, listing specific elements (tables, columns, indexes, etc.) and explicitly excludes views and custom types. This distinguishes it from any sibling tool, as no other tool performs schema comparison.

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 specifies that only base tables are compared and gives an example call. Although it does not explicitly list alternatives or exclusions, the scope is clear and sufficient for an agent to understand when to use it.

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

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

The description goes well beyond the readOnlyHint annotation. It details the exact steps (locate source row, read embedding, pgvector k-NN query), dimensional verification upfront, clear error handling for missing id and missing pgvector. This provides comprehensive behavioral transparency.

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 at ~100 words, with front-loaded main action and separate error handling. Every sentence adds value with no redundancy. The structure is logical and easy to scan.

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

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

Given the complexity (cross-table embedding similarity) and minimal annotations, the description covers the main functionality, error conditions, prerequisites (pgvector, dimension match), and the use case. The output schema exists separately, so return value details are not required. The description is complete enough for an agent to correctly select and invoke the tool.

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

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

Despite only 9% schema coverage, the description explains the roles of many parameters through the narrative of the operation (source/target schema/table/embedding columns, id column/value, k, metric). It adds meaning beyond the schema titles, though it could explicitly list and describe each parameter for full clarity.

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

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

Clearly states the specific action: 'Find the k rows in target_schema.target_table most similar to a specific row in source_schema.source_table.' This verb-resource combination with cross-table scope is distinct from sibling tools like vector_search (same-table) and analyze_* tools. The entity-resolution use case further clarifies 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?

Provides a clear use case: 'entity-resolution / linking across tables whose embeddings come from different models but share a dimension.' This implies when to use it. However, it does not explicitly mention when not to use or list alternatives, which would improve guidance. Still, the context of siblings like vector_search suggests differentiation.

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 explicitly says 'Read-only' which matches the readOnlyHint annotation. It also describes the clean return for non-AO tables and behavior on vanilla PG, providing behavioral context beyond the annotation.

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

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

The description is concise with two sentences and one example. It front-loads the purpose and key details, with 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?

Given the tool's complexity and the presence of an output schema, the description covers all necessary aspects: metadata fields, edge cases (non-AO, vanilla PG), and read-only behavior. It provides a complete picture for the agent.

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

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

Schema coverage is 33% with only the 'database' parameter having a description. The description includes an example with schema and table parameters but does not add details for the database parameter beyond what's in the schema. The example helps but does not fully compensate for the low schema 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?

The description clearly states the tool describes AO/AO/CO storage metadata for one table, listing specific attributes like compression_type, compression_level, etc. It distinguishes itself from sibling tools like describe_table by focusing on a specific table type.

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 specifies it is for one table, that it returns is_ao=false for regular heap tables, and mentions behavior on vanilla PG. While it doesn't explicitly state when not to use it or list alternatives, the niche is clear enough for an agent to select it appropriately.

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 provide `readOnlyHint` and `openWorldHint`. The description adds value by noting the PG version requirement and error behavior, plus describing the return shape (including field names).

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 focused sentences plus an example, front-loaded with purpose, no wasted words. Every sentence contributes.

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

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

Given the simple tool, annotations, and output schema presence, the description covers purpose, usage context, version requirement, return format, and an example. No gaps.

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

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

Schema coverage is 33% (only `database` has a description). The description does not add parameter-level meaning beyond the example, failing to compensate for low schema 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?

The description clearly states the tool describes a property graph by schema-qualified name, distinguishing it from `list_property_graphs` and `run_pgq` with explicit usage context.

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

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

The description provides explicit when-to-use guidance: after `list_property_graphs` and before composing a `run_pgq` query. It includes a Prerequisite (PG 19+) but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint=true, confirming safe read operation. The description adds value by detailing error conditions (table doesn't exist or isn't redis_fdw) and the complete return structure. It could mention permissions or latency but is sufficient given the annotation context.

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

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

The description is concise, front-loaded with the core action, and every sentence adds value: purpose, attributes, error behavior, return structure, and an example. 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?

Given the presence of an output schema, the description still provides valuable return structure details, enhancing completeness. It covers purpose, parameters implicitly, errors, and output, but lacks explicit parameter descriptions or prerequisites. Still, it is fairly complete for a simple descriptive 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% (only the database parameter is described in the schema). The description does not explain the 'schema' and 'table' parameters, relying solely on their names. With low coverage, the description fails to compensate for the missing parameter details, resulting in a score of 2.

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

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

The description clearly states the tool describes a foreign table backed by redis_fdw, listing specific attributes such as server mapping, key structure, key-prefix, TTL, and column shape. It distinguishes itself from siblings like describe_table by specifying the redis_fdw requirement and from other describe tools by targeting Redis cache tables.

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

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

The description implicitly indicates when to use the tool—for Redis-backed foreign tables—but does not explicitly state when not to use it or provide alternatives. However, the specificity of 'redis_fdw' makes the intended use case clear, earning a 4.

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

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

Annotations already 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?

Adds valuable behavioral context beyond annotations: mentions caching by default, ability to bypass cache with `fresh=true`, and specifies return fields. No contradiction with readOnlyHint annotation.

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

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

Two concise sentences plus an example, front-loaded with the main action. 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?

Given the tool's simplicity, presence of annotations, and existence of an output schema, the description fully covers essential context: caching behavior, return format, and typical usage via example.

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 only 25% schema description coverage, the description compensates by explaining the `fresh` parameter and providing an example. The schema already describes `database`; `schema` and `table` are self-explanatory. Adds meaning beyond bare 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?

Clearly states it describes columns of a table in ordinal order, distinguishing from siblings like list_tables or describe_self. The verb 'describe' + resource 'table' is specific and unambiguous.

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

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

Provides an example but no explicit guidance on when to use vs alternatives or when not to use. The context implies usage for retrieving column metadata, but lacks comparative or exclusionary advice.

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 declare readOnlyHint=true, and description adds behavioral context: results are candidates, can trip on cache-miss patterns, and reports availability if pg_stat_statements missing. This goes beyond annotations.

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

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

Two sentences plus a brief note; front-loaded with main purpose. Every sentence adds value, no waste.

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 exists, description explains key output ordering and false positive risk. Covers availability flag. Adequate for a diagnostic tool with moderate complexity.

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

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

Schema description coverage is low (20%), with only 'database' described. The description mentions tunable thresholds and gives examples ('hundreds of calls', 'row or two') linking to parameters, but lacks detailed explanations for all parameters.

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

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

The description clearly states the tool surfaces query templates resembling an N+1 loop, specifying source (pg_stat_statements), criteria (many calls, few rows, significant time), and sort order. It distinguishes from sibling analysis tools by its specific 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?

The description guides treatment of results as 'candidates, NOT verdicts' and gives a false positive example. It mentions availability condition but does not explicitly contrast with siblings or state when not to use.

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

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

The description discloses sampling behavior, clustering method (same as cluster_vectors), per-cluster scoring, sorting, and capping. It also notes the 'available=false' condition if pgvector is missing, which adds context beyond the readOnlyHint annotation. 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 a single, dense paragraph that efficiently covers functionality, algorithm, return values, and constraints. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (12 parameters, algorithm details) and presence of an output schema, the description thoroughly explains how it works, what it returns, and prerequisites. It addresses both parameter semantics and behavioral nuances.

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 only 8% schema coverage, the description provides extensive context for many parameters: sample_size, zscore_threshold, k, max_results, id_column, etc., explaining their roles and defaults. This significantly compensates for the sparse schema descriptions.

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

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

The description clearly states it flags rows with embeddings far from cluster centroids, explains the per-cluster z-score method, and distinguishes it from global outlier detection. It also mentions the return structure and includes the tool name's 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?

The description explains when to use (find outliers within clusters) and provides prerequisites (k >= 2, at least 2k rows, pgvector installed). It implicitly contrasts with a global approach but does not explicitly list alternatives or when not to use.

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

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

Discloses that default mode does not execute the query, while io=true runs it with ANALYZE. Mentions safety allowlist and PG 19 specifics. No contradictions with annotations.

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

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

Two succinct sentences followed by an illustrative example. Every sentence adds value, and the structure is front-loaded with purpose.

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

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

With output schema present, the description covers all needed context: purpose, two modes, parameter hints, and safety. The example clarifies usage. Complete for a tool with 3 parameters.

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 has only 33% description coverage. The description compensates by explaining the io parameter effect in detail and briefly notes the database parameter, but the sql parameter is not elaborated beyond its role.

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

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

The description clearly states it returns the PostgreSQL execution plan, distinguishes default EXPLAIN from ANALYZE mode, and contrasts with execution tools like run_select. It is specific and distinguishes from siblings.

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

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

Clearly explains when to use default vs io=true mode, and mentions safety allowlist. However, does not explicitly differentiate from the sibling tool analyze_query_plan, which also deals with query plans.

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. Description adds truncation behavior, pagination flag, and format serialization. Does not detail auth needs or error states.

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 example. Front-loaded with purpose. 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?

Has output schema covering return values. Describes pagination and format. Lacks details on error handling or performance, but sufficient for most use cases.

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 has only 25% coverage (description for 'database'). The description provides an example showing format and limit usage but does not fully explain each parameter's semantics or constraints.

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

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

Description clearly states verb (run, serialise), resource (SQL query results), and output formats (CSV/JSON). Distinguishes from siblings like run_select and export_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?

Mentions reuse of SQL-safety checks from run_select and pagination via limit truncation. No explicit when-not-to-use or alternative tools, but context is clear.

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