MCPg - Production-grade PostgreSQL MCP Server
Server Quality Checklist
Latest release: v0.6.15
- Disambiguation3/5
With 185 tools, there is significant potential for overlap. Many tools deal with similar domains like vector search and query analysis, and while descriptions are detailed, an agent could easily misselect (e.g., vector_search vs. hybrid_search vs. mmr_search). Some tools have near-overlapping purposes (e.g., find_blocking_chains vs. walk_blocking_chains).
Naming Consistency4/5The naming follows a mostly consistent verb_noun snake_case pattern (e.g., list_*, analyze_*, recommend_*). However, there are a few exceptions like 'why_is_this_slow' (a phrase) and 'tune_vector_index' (verb_noun but with a less common verb). Overall, the pattern is predictable.
Tool Count1/5The tool count of 185 is extremely high for any server, far exceeding typical well-scoped servers (3-15). This indicates a lack of focus and likely many redundant or overly-specific tools that could be consolidated.
Completeness4/5The tool set covers a very broad range of PostgreSQL operations: schema introspection, query execution, performance analysis, vector search, replication, security, and more. There are few obvious gaps (e.g., no direct VACUUM tool, but advisors cover it). The domain is well-covered for a production-grade PostgreSQL server.
Average 4.2/5 across 180 of 185 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 2 community issues answered or closed in the last 6 months
- 241 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
Tools from this server were used 12 times in the last 30 days.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No contradiction with annotations (readOnlyHint=true). The description adds context about using brute-force ground truth and function-form distance, but does not disclose performance impact or side effects. It adequately describes the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the core purpose. No unnecessary words, though it could slightly expand parameter context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, low schema coverage, and an existing output schema, the description is insufficient. It omits details about how parameters affect behavior and does not mention return values or sampling methodology.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, yet the description adds no parameter explanations (e.g., meaning of k, sample_size, metric). It only mentions requiring the vector extension. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool measures recall@k of a pgvector index against brute-force ground truth, specifying the verb 'measure' and the resource 'existing pgvector index'. It distinguishes from sibling tools like vector_search or analyze_hnsw_recall by focusing on recall evaluation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as analyze_hnsw_recall or tune_vector_index. It only mentions a prerequisite (vector extension) but lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states 'feeds the RAG Reranker Pipeline category in audit_database,' which suggests a write operation, contradicting the readOnlyHint=true annotation. No disclosure of side effects or safety. The 'feeds' wording is ambiguous and potentially misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded with key purpose. However, the mention of 'four analytics' is inconsistent with the five listed components, reducing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Does not list the four analytics, mentions five components instead. Lacks guidance on when to use this tool vs. individual analyzers. Does not explain the output schema or how results are consumed. Incomplete for a roll-up advisor with 3 parameters and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (database param described). The description mentions 'days' but does not explain its meaning or default behavior. retrieval_index is not explained at all. The description fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a roll-up advisor over four analytics for one window, returns a summary and list of findings. Names specific components (reranker_idle, topk_stable, etc.). Distinguishes from sibling analytics tools by explicitly acting as a consolidator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage as a roll-up over analytics, but no explicit when-to-use or when-not-to-use guidance. Does not mention alternatives (e.g., using individual analyzers) or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states support for write queries (CREATE, SET, DELETE, MERGE, REMOVE), which contradicts the annotation readOnlyHint=true. This is a serious inconsistency. Additionally, no details about permissions, side effects, or error handling are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) and front-loaded with the key purpose and supported queries. It could be slightly more structured but is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with a write operation and an output schema (though not shown). The description explains the return format but fails to address parameter details and the contradiction with annotations, leaving gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must fully explain parameters. It only mentions 'on a specific graph database' for graph_name and lists allowed query types for cypher_query, lacking details on valid graph names, query syntax, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes an openCypher query on a specific graph database, listing supported query types (MATCH for read, CREATE/SET/DELETE/MERGE/REMOVE for write) and the return format (columns and rows). This distinguishes it from SQL-based siblings like run_select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the supported Cypher commands for read and write queries, giving clear usage context. However, it does not explicitly exclude alternatives or mention when to prefer a different tool (e.g., SQL queries).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and description adds that it returns a Mermaid string. This adds some context beyond annotations, but behavioral traits like potential performance impact or output size are not disclosed. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with verb and resource, no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and only 2 parameters, the description omits crucial detail about the 'limit' parameter and how the graph_name is used. The return format is stated, but the tool's behavior with different parameter values is not explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so parameters (limit, graph_name) have no descriptions. The description does not mention or explain any parameters, leaving their purpose unclear. The agent must rely solely on names, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the resource 'Mermaid flowchart diagram' for property graphs, with a specific purpose 'to visualize its schema and topology'. It distinguishes from siblings like describe_property_graph and generate_graph_projection by focusing on visual representation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: 'to visualize its schema and topology' suggests using it when a diagram is needed. However, no explicit when-to-use, when-not-to-use, or alternatives are provided. Among many sibling tools, guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior. The description adds details about the join with backend state, ordering, and returned columns, which provides moderate behavioral context beyond annotations. No information about permissions, side effects, or potential impact is disclosed, but the read-only annotation covers safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the core purpose. Each sentence adds value: listing, ordering, returned columns, and read-only nature. No unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown but indicated), the description adequately covers input parameters, behavior, and return composition. It mentions optional database filtering and limit. No critical gaps, though it could mention that it reads system views (implied by pg_stat_activity).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%—only the database parameter has a description. The description does not explain the limit parameter or its default behavior, nor does it clarify the effect of the database parameter beyond a terse schema note. The description could have compensated for the low schema coverage but did not, leaving parameter semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists currently-held and waiting locks joined with backend state. It specifies ordering and return fields, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like read_pg_stat_lock or list_active_queries, which may also provide lock information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the output ordering (waiting locks on top) which implies usage for monitoring blocking, and declares read-only. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., analyze_lock_hotspots for analysis, read_pg_stat_lock for raw stats). No when-not-to-use or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent. It adds behavioral detail beyond annotations: it preserves raw upstream payload in a 'raw' field and explicitly states the extension requirement. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action. Every sentence adds value: the first states the purpose, the second adds raw payload and requirement details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (so return values aren't needed in description), the description covers purpose and raw payload. However, it lacks usage context compared to siblings and does not explain 'heap row count' further. Adequate but not fully comprehensive for a tool with 3 parameters and a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 33% of parameters have descriptions in the schema (database). The description mentions 'single turboquant index (schema.index)' hinting at schema and index parameters but provides no additional semantic details like format, constraints, or examples. With low schema coverage, the description fails to compensate meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'exact heap row count' for a single turboquant index, using the specific function tq_index_heap_stats(). It distinguishes from siblings like get_turboquant_index_metadata or get_turboquant_last_scan_stats by focusing on heap row count and preserving raw upstream payload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_turboquant_index_metadata or list_turboquant_indexes. The only context is the requirement for the pg_turboquant extension, which is a prerequisite rather than usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'list' operation is consistent but adds no new behavioral context beyond return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, no redundant information, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema and annotations, the description adequately explains return format and purpose, though lacks mention of error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter; description adds no extra meaning beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List the extensions installed in the database' with a specific verb and resource, and distinguishes from sibling tools like list_available_extensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives; only describes what it does without providing context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by detailing the extension dependency, the empty list scenario when the extension is missing, and the specific output fields. This adds valuable behavioral context that the annotation alone does not provide. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences plus an example), front-loaded with the purpose, and contains no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality, extension requirement, and return fields (output schema exists, so returns need not be fully listed). It is fairly complete for a list tool, though it could mention the database parameter's role in multi-database setups more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the database parameter has a description in the schema. The main description only shows an example usage for schema and limit without explaining their semantics. With 33% schema description coverage, the description should compensate more but only partially does so via the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports 'current shared-buffer residency per relation, ranked by blocks-cached descending.' It specifically mentions the required extension and empty list behavior. However, it does not explicitly differentiate from similar sibling tools like read_pg_buffercache_relations, though the name 'prewarmed' and the extension requirement imply a distinct focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an example call (filtering by schema and limit) and notes the extension requirement, which gives some usage context. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., read_pg_buffercache_relations) and does not outline prerequisites or side effects beyond the extension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. Description adds that it flags partitioned tables and returns specific fields, providing mild additional context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example. Front-loaded with purpose and return info. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists (as per context), and description mentions return fields. For a list tool with annotations, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: the 'schema' parameter is explained via example and context, but the 'database' parameter's behavior is not elaborated in description (though schema includes description). Adds some meaning but not fully compensates for coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'List' and specific resource 'tables and views in a schema'. Returns structured objects with named fields. Distinguishes from siblings like list_views or list_partitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives. Among many list tools, no context is provided for choosing this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. The description adds context by detailing what the tool does (detect cycles, trace paths) and specifies the full structure of the returned object (cycles, paths, roots, nodes, mermaid). No contradiction 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the primary action then listing details. It is reasonably concise, though it could be slightly tighter without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 optional params) and the description fully explains the return value structure (cycles, paths, roots, nodes, mermaid). With an output schema (assumed), the description is complete and leaves no ambiguity about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'database' is described, but 'limit' is not). The description does not mention either parameter, so it adds no additional meaning beyond what the schema provides. Given the gap, the description should have compensated but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool walks and reconstructs the lock-wait graph, detects deadlocks, and traces blocking paths. It uses specific verbs and a distinct resource, but does not explicitly differentiate from the sibling tool 'find_blocking_chains', which likely has 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for analyzing blocking chains and deadlocks, and explicitly labels it as read-only. However, it does not specify when to use this tool versus alternatives like 'find_blocking_chains', nor does it provide 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable behavioral context: it reports available=false if the PostGIS extension is not installed, which is beyond what annotations provide. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The core action is front-loaded, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having 7 parameters (5 required) and an output schema, the description does not explain the output format, error conditions beyond extension missing, or any additional behavioral details. The low schema coverage combined with a terse description leaves it incomplete for a spatial search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only the 'database' parameter has a description). The tool description does not explain the meaning or constraints of the other required parameters (schema, table, column, longitude, latitude) nor does it clarify the 'limit' default. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Find the rows nearest to a lon/lat point by PostGIS distance.' It uses a specific verb ('Find') and resource ('rows nearest to a lon/lat point') and differentiates from sibling search tools by mentioning 'PostGIS distance' and the extension dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when nearest spatial search by PostGIS distance is needed, and notes that it reports available=false if the extension is missing. However, it does not explicitly state when to use this over other spatial or search tools, nor does it provide exclusion criteria or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds details about the return structure (fields like handler, validator) but does not disclose additional behavioral aspects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states the core purpose, and the second details the output format. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (simple list operation, one optional parameter) and the presence of annotations and output schema, the description fully covers the necessary information about what the tool does and what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'database' parameter is described in the schema). The description does not add extra meaning to the parameter beyond what is already in the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists foreign-data wrappers, using specific verb 'List' and resource 'foreign-data wrappers installed in the database'. It distinguishes from sibling tools like list_foreign_servers and list_foreign_tables by focusing on wrappers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. The description does not provide context for when to choose list_foreign_data_wrappers over related list tools such as list_foreign_servers or list_foreign_tables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds limited behavioral transparency. It does detail the return object structure (partitioned, strategy, partitions), which is helpful. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states purpose, second describes return format. It's efficient, front-loaded, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is described in detail, the description adequately covers the tool's behavior. It could mention behavior for non-partitioned tables (e.g., returns partitioned=false), but that is implied. The optional database parameter is well-documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only the database parameter has a description). The description does not explain the required 'table' and 'schema' parameters beyond their names, leaving ambiguity about possible values or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Describe how a table is partitioned (strategy and bounds) and list its partitions.' It specifies the verb (describe/list) and resource (table partitions), and distinguishes it from sibling tools like list_tables or list_indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The description implies it's for viewing partitioning info, but doesn't provide when-not or alternative recommendations. The database parameter has a usage hint ('omit for the primary'), but overall lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description confirms it only lists policies. The description adds the exact return structure but no additional behavioral traits like permission requirements or potential delays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the tool's purpose and return structure. It is front-loaded with the core function, though the detailed return object description could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return object in detail, which is sufficient for a read-only tool with annotations. It lacks information on error handling or empty results, but the context signals indicate no output schema is provided in the definition, so the description fills that gap adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'database' described). The description mentions 'schema' and 'table' but does not elaborate on their meaning or constraints beyond what the schema provides. It partially compensates by naming the parameters, but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Row-Level-Security policies on a table and whether row security is enabled, specifying the exact verb 'list' and resource 'policies on a table'. It distinguishes from sibling tools by its specific focus on RLS policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inspecting RLS policies but does not explicitly state when to use it versus alternatives or when not to use it. No guidance on prerequisites or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 specifying the return structure (name, function, definition) and clarifying it lists only user-defined triggers, not system triggers. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no extraneous information. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema, the description covers the key points: what it lists and the return fields. It does not address error cases or empty results, but is adequate given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only the optional database parameter has a description). The description does not explain the meaning or format of schema, table, or database parameters, leaving the agent with minimal guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'list' and the resource 'user-defined triggers on a table', specifying the return format with fields like name, function, and definition. This is a specific verb+resource combination that distinguishes it from sibling listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_constraints or list_indexes. The description assumes the user already knows the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by explaining the specific source (pg_blocking_pids), the row structure (blocked, blocking), and the possibility of cycles. It warns to 'render with care', adding practical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding essential information: the action and method, the row format, and a caution about cycles. It is concise without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and readOnlyHint annotation, the description covers the core functionality and potential pitfalls (cycles). It does not explain rendering in detail, but the context is sufficient for an AI agent to understand the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only database has a description). The description does not mention the limit parameter or its default, nor does it elaborate on the database parameter beyond the schema's own description. It adds no meaningful parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns (blocked, blocking) backend pairs using pg_blocking_pids. It specifies the resource (blocking chains) and the verb (return), and distinguishes from siblings like list_locks or walk_blocking_chains by focusing on pairs and cycles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like walk_blocking_chains or list_locks. It implies its use for identifying blocking pairs via a specific method, but no exclusion or comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and self-contained behavior. The description adds valuable behavioral details: it never raises errors (surfacing driver errors as available=false) and returns specific fields including a diagnostic string. This goes beyond annotations to clarify error handling and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the purpose stated upfront. The example at the end is slightly redundant but not harmful. Every sentence earns its place, and the length is appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description still covers essential aspects: purpose, error behavior, version-specific behavior, and return field names. For a simple status check tool, this is fully complete and leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'database' has 100% schema description coverage, so the description does not need to add meaning. The tool description does not mention the parameter at all, providing no additional semantic value beyond the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports whether PG 19's views are usable, with specific verb and resource. However, it does not explicitly differentiate from sibling tools like read_pg_stat_lock, which might lead to confusion about when to use this versus the read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by mentioning behavior on PG < 19 and pointing to alternatives like find_blocking_chains. However, it does not explicitly state when to use this tool (e.g., before calling read_pg_stat_lock) or provide clear exclusions, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds details about the return structure (fields like name, base_type, etc.) but does not disclose additional behavioral traits such as sorting or limitation behavior. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a clarifying sentence on return structure. Every word adds value, and it is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the presence of annotations and output schema, the description adequately explains what the tool does and what it returns. It could mention if there are any default behaviors, but it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage of parameters is 100% (both schema and database are documented in the schema). The description does not add new parameter meanings beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists domain types in a schema, with specific fields returned. The verb 'list' and resource 'domain types' are specific, and it distinguishes from sibling tools that list other database objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies usage for listing domain metadata but does not differentiate from similar list tools or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. The description adds context about the return structure but no additional behavioral traits (e.g., no mention of ordering, limits, or side effects). With annotations, the bar is lower, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description explicitly states what is returned (list of objects with name, kind, arguments, returns, language). Since output schema exists, the description could rely on it, but it adds clarity directly. Combined with annotations and schema, the tool is fully documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only the database parameter has a description in schema). The description does not elaborate on the required 'schema' parameter or provide any additional meaning beyond what the schema already states. It does not compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'list' and resource 'functions and procedures in a schema', and details the returned fields (name, kind, arguments, returns, language). This clearly distinguishes it from sibling list tools like list_tables, list_indexes, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description clearly states it lists functions and procedures in a schema, but does not provide explicit guidance on when to use this tool versus alternatives like list_tables or list_indexes. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: reports available=false if pg_trgm missing, describes return structure (object with available, matches, mode). Annotations already indicate readOnlyHint=true, so 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus example, no wasted words. Front-loaded with verb and resource. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains core functionality, modes, and gives example. However, missing parameter details for limit and threshold. Output schema exists but not shown. Adequate but with gaps for a tool with 8 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Defines mode parameter and provides an example covering schema, table, column, term, mode. However, limit and threshold are not explained despite low schema coverage (13%). Database parameter has schema description but missing from description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it ranks a text column by pg_trgm trigram similarity to a search term, with specific mode options ('word' vs 'full'). This distinguishes it from sibling search tools like full_text_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Agent can infer usage for fuzzy matching, but no contrast with sibling tools or mention of prerequisites beyond pg_trgm availability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by detailing the return format (JSON object with filename and source) and suggesting the agent write each file. This aligns with the readOnlyHint annotation (read operation) and provides actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that efficiently covers purpose, output, constraints, and action hint. No unnecessary information, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 key aspects: output format, file content details, and a known gap. Minor omissions include error handling and prerequisites, but overall sufficient for an agent with readOnlyHint context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema coverage, the description fails to explain the 'schema' parameter beyond what the schema provides (just its type). The 'database' parameter has a good description in the schema, but the description does not compensate for the lacking parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a PostgreSQL schema and emits Ent (Go) Schema struct files, one per table. It uses specific verbs (read, emit) and resource (PostgreSQL schema), and the output is distinct from sibling tools like generate_diesel_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. It implies usage when Ent schemas are needed, but lacks guidance on exclusions or comparisons with other schema generators. The mention of composite FK gap is useful but not enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only. The description adds value by noting 'In-process — no MCPG_ALLOW_SHELL needed' and detailing the DDL order, which informs agents about execution context and output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then order, then execution note and return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, order, execution mode, and return type. Lacks information on error handling or schema existence checks, but overall sufficient for a generation tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'database' has a description). The description does not compensate for the missing 'schema' parameter description, leaving ambiguity about what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads a PostgreSQL schema and emits a sqlc-friendly schema.sql, with a specific order. Distinguishes from siblings by being sqlc-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for sqlc schema generation but does not explicitly guide when to use this tool vs other schema generators (e.g., generate_diesel_schema). No when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by detailing the probe conditions (version string and catalog view), output fields (coordinator_role, segment_count, mirroring), and behavior ('never raises'). Annotations provide readOnlyHint and openWorldHint, which are consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the purpose. Every sentence adds value, and it includes an example call. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple probe behavior and existence of an output schema, the description sufficiently covers what the agent needs: purpose, conditions, return fields, and read-only nature. It also references sibling tools in the family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single optional parameter well-documented in the schema. The description adds no additional parameter information beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool probes for WarehousePG/Greenplum signature and explains conditions for available=true. It is specific to the resource, but does not explicitly distinguish from sibling status tools like get_aio_status or get_pgq_status, missing the highest tier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking WarehousePG availability and mentions read-only nature, but does not explicitly state when to use this tool vs alternatives or provide exclusions. The optional database parameter is explained with a reference to list_databases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's addition of return field details is useful but not essential. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and scope, second lists return fields. Concise, front-loaded, and no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's output and operation. For a simple list tool with one optional parameter, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'database' is well-described in the input schema (100% coverage). The tool description does not add parameter semantics, which is acceptable per baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists foreign servers with their FDW and options, and specifies the return fields. This differentiates it from sibling list tools like list_foreign_data_wrappers or list_foreign_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. However, the name and description implicitly indicate its purpose. With many sibling list tools, some context on when to choose this one would be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'List' aligns. It adds behavioral context by enumerating the returned fields (grantee, privilege, grantable, grantor), which helps the agent understand the output without needing to inspect the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence front-loaded with the purpose, followed by a concise list of return fields. Every part is necessary and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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's enumeration of return fields is a bonus. However, it could briefly explain the required parameters (table, schema) to compensate for the low schema coverage, but overall it sufficiently explains the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with only 33% description coverage (only 'database' has a description). The tool description does not mention any parameters, failing to add meaning beyond the schema for the two required parameters (table, schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('List the privileges granted on a table') and the resource ('a table'), distinguishing it from sibling list tools (e.g., list_indexes, list_roles) by focusing on privileges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via the tool name and purpose but does not explicitly state when to use it vs alternatives, nor does it provide exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's safety profile is clear. The description adds value by detailing the return fields (name, data_type, start_value, etc.) and scoping to a schema. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence stating the action followed by a list of return fields. It is front-loaded and contains no extraneous information. Every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the main purpose and return format. It could mention edge cases (e.g., behavior for non-existent schemas) or permissions, but for a read-only listing tool it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only database parameter has a description in the schema). The description only implicitly references the 'schema' parameter via 'in a schema', adding minimal meaning. It does not elaborate on the schema parameter's format or constraints, nor does it compensate for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists sequences in a schema with specific attributes (range, increment, last value). The verb 'list' and resource 'sequences' are precise, and the output format is described. It distinguishes from sibling list_* tools like list_tables or list_indexes by focusing on sequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining sequence details but does not explicitly state when to use this tool versus alternatives. No exclusions or comparisons to sibling tools are provided. The name and title give context, but explicit guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds significant detail beyond annotations: explains priority logic, output fields, and top-level overdue_count. Aligns with readOnlyHint. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise paragraph with front-loaded purpose and example. Efficiently covers purpose, logic, output, and usage example. Could be slightly more structured but no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description need not detail return format but still explains output fields and priority categories. Covers ranking logic and top-level aggregate. Lacks mention of error cases or pagination but adequate for the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only database described). Description compensates for limit by showing example usage, implying it limits rows. Database parameter details are not enhanced beyond schema. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states verb 'return' and resource 'tables most urgently needing autovacuum' with ranking method. Distinguishes from siblings by focusing on autovacuum priority rather than generic table listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for identifying urgent autovacuum candidates but does not explicitly state when to use vs alternatives (e.g., list_tables) or when not to use. Lacks direct usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm read-only behavior. Description adds extension requirement and return value when not installed, but does not detail performance or locking implications. Adequate 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, then requirements. No wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the specialized topic and existence of output schema, the description covers essential context. Could mention that output includes per-resource-manager stats, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema coverage, the description does not explain the parameters (start_lsn, end_lsn, per_record) beyond mentioning 'LSN range'. Fails to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads WAL statistics over an LSN range, grouped by resource manager or record type. Distinguishes from sibling 'read_pg_wal_records' which likely fetches raw records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions requirement of pg_walinspect extension and fallback behavior. Lacks explicit comparison to alternative tools but provides clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces by stating 'Advisory only — no writes'. It adds value by listing the specific types of rules checked (e.g., duplicate indexes, nullable timestamps), 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The first sentence front-loads the purpose and scope, and the second adds key behavioral details. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, 1 required, output schema exists), the description is adequate. It lists the rule categories and confirms read-only behavior. The output schema covers return value details, so the description does not need to explain them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description does not add significant detail beyond the schema. The first sentence mentions 'against a schema' but does not explain the database parameter semantics. The description does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs catalog-driven advisor rules against a schema and returns aggregated findings. It lists specific rules (missing primary keys, unindexed foreign keys, duplicate indexes, nullable timestamps), making it distinct from sibling tools like analyze_* or recommend_*.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Advisory only — no writes' which gives a usage hint but does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage context is implied but not fully clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false; the description confirms by stating it reads live row count and dimension. It also discloses that it returns parameters and a CREATE INDEX statement, implying no side effects. This adds useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and each sentence adds necessary detail without redundancy. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered. The description explains the tool's inputs (row count, dimension) and outputs (parameters, CREATE INDEX). It could mention the vector extension name explicitly, but overall it is adequately complete for a recommendation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description should compensate for undocumented parameters. However, it does not explain the meaning of metric or index_type, nor how they affect the recommendation. It only implicitly references schema, table, and column by mentioning row count and dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it recommends an ivfflat or hnsw configuration for a pgvector column, specifying the resource (pgvector column) and action (recommend configuration). It distinguishes itself from sibling tools like recommend_ivfflat_probes and recommend_hnsw_ef_search by focusing on full index configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (requires the vector extension) but does not explicitly state when to use this tool versus alternatives. It implies usage when configuring a new index, but lacks guidance on when not to use it or how it relates to sibling recommendation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds behavioral context: it explains the query syntax (web-search with quoted phrases, OR, -exclusion), output format (primary key columns + rank), and gives an example. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences of purpose and behavior, plus a clear example. Every sentence adds value, and the structure is well-organized with purpose, syntax, output, and example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers the return structure (primary key columns + rank). It mentions the query syntax and gives an example. Minor gaps: it does not explain the 'config' parameter options or default behavior for 'limit', but overall it is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (14%, only 'database' has a description). The description adds meaning to 'search_query' by explaining web-search syntax, and the example shows how to use 'schema', 'table', 'column', and 'search_query'. However, it does not explain 'limit', 'config', or the 'database' parameter beyond the schema's minimal note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks a text column's documents against a full-text query using PostgreSQL's tsvector/tsquery, with a specific verb ('Rank') and resource ('text column'). It also provides an example and distinguishes from sibling tools by focusing on native PostgreSQL full-text search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for full-text search with web-search syntax but does not explicitly state when to use this tool versus alternatives like fuzzy_search, hybrid_search, or vector_search. No exclusions or alternative guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, confirming safety. The description adds that caching is used and can be bypassed with fresh=true, disclosing behavioral traits beyond annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence conveys the core purpose, second sentence explains a key parameter. No wasted words, front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 signal), the description adequately covers what the tool returns (tables, columns, keys, relations) and the caching behavior. Could be slightly more explicit about the text format, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, but the description adds meaning to the fresh parameter ('bypass the cache and re-read live') which is helpful. The schema and database parameters are not further detailed, but fresh is the key conditional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a highly condensed text summary of schema metadata, specifying the verb (return), resource (schema summary), and purpose (save tokens). This distinguishes it from sibling tools like list_schemas or describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives guidance on when to use the fresh parameter (bypass cache after schema change) but does not explicitly differentiate this tool from alternatives or state when not to use it. Usage context is implied but not thorough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and closed world. The description adds valuable context: it uses PG 19's pg_get_databasedef function, returns a specific object structure, and handles missing databases by setting 'found=false'. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus an example, with no wasted words. It front-loads the main action and clearly explains behavior and return format. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return values but still summarizes them. It covers the not-found case and PG version requirement. For a simple DDL retrieval tool, this is comprehensive; it lacks only optional details like error handling or permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% because only the 'database' parameter has a description. The description provides an example using database_name but does not explain the 'database' parameter or add meaning to 'database_name' beyond the schema. The example helps but does not fully compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'CREATE DATABASE DDL for a named database', specifying the verb 'Return' and the resource 'DDL'. It distinguishes itself from sibling tools like get_role_ddl and get_tablespace_ddl by focusing on database DDL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it requires PG 19+ and returns 'found=false' for non-existent databases, but it does not explicitly compare to alternatives or provide when-to-use/when-not-to-use guidance. No exclusions or sibling comparisons are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; the description echoes 'Pure read' which adds no new behavioral insight. It does add useful context about detection logic and return fields, which provides moderate extra transparency 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph that front-loads the main purpose and then explains detection details and return structure. Every sentence adds value; no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers what the tool detects and returns. It might be missing limits on findings or performance notes, but for a naming lint tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the required 'schema' parameter (which lacks a description in the schema) by stating the tool lints naming in a schema. For the 'database' parameter, the schema already provides a thorough description. Overall, the description compensates for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lint') and clearly identifies the resource ('table / column / index naming in a schema'). It distinguishes itself from sibling tools like list_indexes or list_tables by focusing on naming convention analysis, not mere listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to check naming consistency) but does not explicitly state when not to use or mention alternative tools. No exclusion criteria or sibling comparisons are provided, so the guidance is merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description adds context by listing return fields (wait_event, duration, blocked_by) and noting that wait_event is null when not waiting. It does not contradict annotations and provides useful behavioral details beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately stating the tool's action and listing return fields. It is efficient with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, read-only, output schema exists), the description covers purpose, return fields, and parameter usage. However, it lacks guidance on when to use it, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the 'database' parameter. The description does not add any additional parameter-level information beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists currently running queries on the server, specifying the exact fields returned (wait event, duration, blocking PIDs). This differentiates it from sibling tools like 'list_locks' and 'read_pg_stat_lock' which focus on lock statistics rather than active queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The description implies it is for monitoring active queries, but it does not compare with similar tools (e.g., 'read_pg_stat_lock') or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavior beyond annotations: empty list edge case, ordering. Annotations already provide readOnlyHint and openWorldHint; description complements 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with main purpose. Each sentence provides distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior, edge case, and one parameter. Default limit and database parameter are omitted, but output schema likely documents return fields. Adequate for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning for the 'tool' parameter as a filter, which is not described in schema. However, 'limit' and 'database' parameters are not mentioned in description, and schema coverage is only 33%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action (list) and target resource (mcpg_audit.events), includes ordering (newest first) and optional filter. Clearly distinguishes from sibling listing tools by naming a unique table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for retrieving audit events, and mentions empty list condition when audit is not enabled. No explicit comparison to alternative tools or when not to use, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that it returns a list of objects with name and attributes, including nested structure. No contradictions. Adds context beyond annotations by specifying the response format and that it covers 'standalone' composite types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that efficiently convey the purpose and return format without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return value structure, and together with the existing output schema and readOnlyHint, provides adequate completeness. However, it lacks details on prerequisites (e.g., existence of schema) or error handling, which are minor gaps for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the required 'schema' parameter has no description in the schema, and the description does not elaborate on it. The 'database' parameter has a description in the schema. Description does not add significant semantics beyond what the schema provides, achieving baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists standalone composite types in a schema with their attributes, and specifies the return format. Distinguishes from other list_* tools by specifying 'composite types' and the return structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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. Mentions it lists 'standalone' composite types, but does not explain when to choose this over other list tools or how it differs from describe_composite_type or similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true, indicating safety. The description adds behavioral details: cache behavior with 'fresh' parameter, return format (list with name, type, definition). This exceeds annotation info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus an example. Front-loaded with action, no redundant text. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and an output schema, the description covers purpose, parameter details (partially), and output format. It lacks explicit usage guidelines but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (database has description). The description adds meaning for 'fresh' (bypass cache) and shows usage via example. However, required parameters 'schema' and 'table' lack additional explanation beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List a table's constraints' and enumerates types (primary/foreign keys, unique, check, exclusion). This distinguishes it from more specific sibling like 'list_foreign_keys'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description explains the 'fresh' parameter usage and provides an example, it does not explicitly state when to use this tool over alternatives or when not to use it. No exclusions or comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations: explains cache bypass with `fresh=true`, return format (list of objects with specified fields), and 'resolved to columns and referenced table.' Annotations already declare readOnlyHint=true, so the description adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences plus an example. Front-loaded with purpose, no filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple tool, annotations (readOnlyHint true), and implied output schema (return fields listed), the description covers essential behavior and parameters. Missing explicit description of all parameters, but example helps. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning for the `fresh` parameter (bypass cache) beyond the schema (which only has a default and type). The `schema` parameter is mentioned only in the example, and `database` is partially described in the schema. With 33% schema coverage, the description compensates somewhat but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List foreign keys in a schema, resolved to columns and referenced table.' The verb 'list' and specific resource 'foreign keys' make the purpose unambiguous, and it differentiates from sibling tools like list_constraints by focusing solely on foreign keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use the `fresh` parameter to bypass cache after schema changes, but does not explicitly state when to use this tool versus alternatives like list_constraints or list_indexes. Usage context is implied but not compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds the return format (list of objects with name, server, options), which is beyond annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, no unnecessary words. Efficiently conveys purpose and returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with output schema available, the description covers the core behavior: what it lists and the return fields. Annotations cover read safety, and no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'database' parameter has a description). The description does not add meaning for the 'schema' parameter beyond what the name implies. It mentions 'in a schema' but does not elaborate on valid values or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('foreign tables'), and specifies additional context ('with their server and options') and the return structure. It is distinct from sibling list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for listing foreign tables in a schema but does not explicitly state when to use this tool versus alternatives like list_tables or list_foreign_servers. No exclusions or when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds behavioral context: it requires superuser to see rows, implying non-superusers get empty results. This is useful transparency not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences, no wasted words, and the most critical information (purpose and privilege requirement) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one optional parameter and an output schema, the description provides necessary context about access restrictions. It is sufficiently complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'database' is fully described in the input schema with coverage at 100%. The tool description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists logical-replication subscriptions, using a specific verb and resource. It distinguishes from siblings like list_publications and list_replicas by focusing on subscriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that superuser privilege is required to see any rows, which is a usage condition. However, it does not provide guidance on when to use this tool versus alternatives, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, but the description adds value by specifying that an empty list is returned when the extension is not installed, and enumerates the exact metadata fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is thorough given the presence of annotations and output schema; it explains the return format and edge case (extension not installed), though an example could further improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional parameter; the description adds minimal extra context ('omit for the primary'), but baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every pg_turboquant ANN index with specific metadata fields, distinguishing it from general list_indexes and get_turboquant_index_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for the tool's purpose but does not explicitly guide when to use it versus alternatives like list_indexes or get_turboquant_index_metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behaviors beyond the readOnlyHint annotation: it explains the return format, the role of key_field and score, column search behavior, snippet parameters, and security implications of unsanitized tags. There is no contradiction 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the core action and return format, then parameter behaviors, then security notes. Every sentence adds value, though it is slightly long. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output format and key parameters, given the existence of an output schema. It does not address pagination or error handling, but for a search tool this is acceptable. Overall, it provides sufficient context for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 8% schema description coverage, the description adds significant meaning for parameters such as key_field, score, columns, return_snippets, snippet_field, and snippet tags (including XSS warning). It does not explain limit, schema, table, or database (though database has a schema description). Compensates well for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a BM25 keyword search against a pg_search-indexed table and specifies the return format (id, score, snippets). It distinguishes itself by mentioning pg_search-specific features and limitations, but does not explicitly differentiate from sibling search tools like fuzzy_search or full_text_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement for the pg_search extension and defers multi-column search to a follow-up phase, implying usage constraints. However, it does not explicitly state when to use this tool versus alternatives (e.g., hybrid_search, vector_search) or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the read-only nature is covered. The description adds value by disclosing the extension requirement and the 'available=false' response if the extension is not installed. This provides operational insight beyond the annotations, though more details about limit behavior or error conditions would strengthen transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that immediately convey purpose, prerequisite, and a key edge case. No redundant information. Front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema, the description covers the core purpose and an important prerequisite/failure scenario. However, it lacks details on parameter usage and expected result format. The output schema likely handles return values, but parameter documentation gaps reduce completeness. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only the 'database' parameter has a description). The tool description does not explain the meaning or format of key parameters like start_lsn, end_lsn, or limit. It mentions 'LSN range' but provides no details on valid formats or how parameters interact. With low schema coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads WAL records over an LSN range, using a specific verb ('Read') and resource ('WAL records'). It distinguishes from sibling tools like get_current_wal_lsn, which gets a single LSN, or read_pg_wal_stats, which reads aggregated stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: when to use this tool (to read WAL records over an LSN range), and it mentions a critical prerequisite (pg_walinspect extension) and a failure mode (returns available=false). However, it does not explicitly state when not to use this tool or list alternatives, though sibling tools are implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, which the description aligns with by describing a read-only search. It additionally discloses behavior when pgvector is not installed ('available=false'), adding useful context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and an example, front-loading the core purpose. Every sentence adds value, and the example provides immediate clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, metrics, availability check, and example usage. Given the tool complexity (7 parameters) and presence of an output schema, it is fairly complete but lacks usage guidelines against siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, but the description compensates partially with an example showing all key parameters. However, it does not individually describe each parameter's meaning or constraints, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds rows nearest to a query vector using pgvector distance metrics (l2, cosine, inner_product). It distinguishes from other search tools by specifying vector search and reporting extension availability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for vector similarity search but provides no explicit guidance on when to use this tool versus siblings like hybrid_search or fuzzy_search. No exclusion criteria or context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations by describing read-only operation and output generation, including file naming and module structure. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear first sentence. Slightly verbose but each sentence adds value. Could be slightly more concise but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: input, output, naming conventions, and configuration. Lacks error handling or prerequisites but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning for all three parameters despite low schema coverage: clarifies 'schema' as PostgreSQL schema, describes 'database' and 'app_module' defaults and behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads a PostgreSQL schema and emits Ecto modules, with specific details on naming, associations, and output format. Distinct from sibling schema generator tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for Elixir Ecto projects but does not explicitly state when to use versus other schema generators. No exclusionary guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds useful context: it details the fallback behavior for unmappable types (`Unsupported`) and lists which database objects are covered. This goes beyond the minimal safety annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the core function, the second details scope and behavior. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mapping many database features) and the existence of an output schema, the description covers the key aspects: what is included, what is excluded, and fallback behavior. It is sufficient for an agent to understand the tool's capabilities and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'database' has a description). The tool description does not explain the meaning of the required 'schema' parameter, nor does it provide additional guidance beyond what the schema already states for 'database'. With half the parameters undescribed and no compensation from the description, this dimension scores low.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read a PostgreSQL schema and emit a valid Prisma `.prisma` schema string (mirrors `prisma db pull`).' This is a specific verb and resource, clearly distinguishing it from siblings like generate_diesel_schema or generate_sqlalchemy_models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies what is covered (tables, columns, keys, constraints, enums) and what is out of scope (views, foreign tables, triggers, etc.), providing clear context for when to use this tool. However, it does not explicitly name alternative tools for out-of-scope items, which would have earned a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the readOnlyHint annotation: it returns SQL strings without executing, is deterministic with a seed, has a hard cap of 10000 rows, and does not resolve foreign keys. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences with no filler. It front-loads the core purpose, then adds usage context, behavioral details, and caveats. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool with 5 parameters and an output schema, the description covers the main purpose, usage environment, output format, deterministic behavior, row cap, and foreign key resolution. It is sufficiently complete for the agent to invoke correctly, though it could mention error handling or the exact output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description does not elaborate on most parameters. While it mentions 'rows' and 'seed', it does not explain their meanings, constraints, or types beyond what the schema provides. The 'database' parameter has a description in schema, but the tool description adds no parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates synthetic INSERT statements for a table, respecting column types and constraints. It distinguishes itself from siblings like 'generate_test_row_for' by generating multiple rows and not executing. The specific verb 'generate' and resource 'INSERT statements' provide clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is useful for seeding dev/staging environments and explicitly warns that foreign keys are not resolved, requiring the caller to pre-seed referenced rows. While it doesn't list alternatives, the context is clear and provides actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds detailed behavioral transparency by listing the exact return fields and explaining the significance of the autoprewarm worker requirement. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, includes an example, and uses formatting (backticks) for clarity. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fully covers the tool's behavior, return fields, and an example. It is complete enough for a simple status check tool with no nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description does not add any additional meaning beyond the schema; the parameter is well-documented in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports on installation status of pg_prewarm and pg_buffercache, and checks shared_preload_libraries. It distinguishes from siblings like list_prewarmed_relations which list actual prewarmed relations, not extension status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied from the description (check before using pg_prewarm), but there is no explicit guidance on when to use this vs alternatives, nor any when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=false. The description adds that it uses pg_get_roledef, returns found=false if role missing, requires PG 19+, and raises on older servers, exceeding what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded purpose, no filler. Two paragraphs are reasonable. Could be slightly more structured (e.g., bullet list of return fields) but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return structure, error scenarios (not found, older server), and example. With output schema present and annotations, the description is sufficiently complete for a simple DDL tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers database parameter with description, but role_name lacks description. Description only includes example to imply usage. With 50% schema coverage, the description could add more detail about role_name format or constraints, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the CREATE ROLE DDL for a named role using pg_get_roledef. It distinguishes from siblings by specifying the method (PG 19 function, no shell-out) and the exact return structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (need role DDL, PG 19+) and how to feature-detect with get_pg19_ddl_status. Warns about error on older servers. Does not explicitly list alternatives like list_roles, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only. Description adds behavioral details: it raises on missing conditions, preserves raw_metadata for unanticipated fields, and lists the returned typed attributes. No contradiction 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose, second adds behavioral context, third lists return fields. Front-loaded and efficient. Minor room for improvement in condensing the return field list, but overall concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and the tool's simplicity, the description covers purpose, error conditions, and return structure comprehensively. The mention of raw_metadata adds completeness for handling unanticipated fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%); only the 'database' parameter has a description. The description mentions schema and index names in the context of the index identifier but does not provide additional semantics, formatting, or examples for the parameters beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'fetch', the resource 'tq_index_metadata for a single turboquant index', and the scope 'by schema and index name'. Distinguishes from siblings like list_turboquant_indexes and get_turboquant_heap_stats by focusing on metadata retrieval for a single index.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when the tool raises errors (extension not installed or index not found). Implicitly guides use for metadata retrieval versus listing all indexes, but does not explicitly state 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds valuable behavioral context: returns null when extension absent or no scan has run, and lists specific fields returned. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and lists fields, second covers edge case (null). Front-loaded with essential information, no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, output schema exists), the description covers purpose, edge cases, and field listing comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter description. The tool's description does not add extra parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the backend-local JSON report of the most recent turboquant scan, listing specific fields (score_mode, simd_kernel, etc.), and distinguishes it from siblings by specifying 'last scan stats' versus other turboquant analysis tools like get_turboquant_heap_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for retrieving last scan stats and notes conditions when null is returned, but does not explicitly state when to use this vs other turboquant tools or provide alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by detailing the return format and the empty list behavior. No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a crucial edge case note and return format specification. It is front-loaded and every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format and the non-hypertable case, but lacks explanation of the 'available' bool flag. Overall, it is fairly complete for a list tool given the presence of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'database' parameter described). The description does not clarify the meaning or usage of 'table' and 'schema' parameters beyond their titles, failing to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'chunks of a TimescaleDB hypertable'. It specifies the return fields (range_start, range_end, is_compressed) and notes the empty list case for non-hypertables, effectively distinguishing it from sibling tools like list_hypertables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a boundary condition ('Empty list when the table is not a hypertable') which implicitly guides usage for hypertable inspection. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm readOnlyHint true. Description adds valuable context: returns empty list if pg_cron is not installed. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Action-first, efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with output schema, the description covers purpose and edge case. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes the only parameter thoroughly; description adds nothing beyond schema. Schema coverage is 100%, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists pg_cron jobs and adds behavior detail about empty list when pg_cron is missing. Distinct from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives among siblings. Only the empty list behavior is noted; no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds value by listing returned fields (SQL, rows, age, TTL) and mentioning auto-close behavior. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with all essential information. No extraneous words, purpose and output clearly stated up front.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description fully covers what the tool returns and its behavior. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. The description correctly notes there are no arguments, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('server-side cursors'), and details the exact fields returned. It clearly distinguishes from siblings like close_cursor and open_cursor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., fetch_cursor, close_cursor). The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds behavioral details: it can bypass cache via fresh=true, and it returns a structured list of index objects. This adds value beyond annotations by explaining the caching behavior and exact return fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with purpose, includes an illustrative example, and succinctly explains the return structure. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema (implied), the description covers return fields and caching behavior. It lacks parameter descriptions for schema and table, but the schema partially covers them. For a list tool with moderate complexity, it is mostly complete but could be slightly more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage, the description should compensate but only explains fresh in context; schema, table, and database are not described in the description. The database parameter has a schema description but is absent from the tool description. This leaves meaning unclear for three of four parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and the resource (indexes on a table), specifying required parameters schema and table. It distinguishes the tool from siblings by focusing on indexes, which is a unique purpose among many database introspection tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific usage scenario for the fresh parameter (bypass cache after schema change) and includes an example call. However, it does not explicitly compare with alternatives like describe_table or list_constraints, which might also expose index information, leaving some ambiguity about when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations: it reads from a specific system view, mentions version-dependent behavior, and notes that early Beta builds may lack the catalog view. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, covering purpose, source, edge cases, return structure, and an example. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional parameter, output schema exists), the description is complete: it explains the action, data source, edge cases, return format, and provides an example. The output schema handles return type details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the description already in the schema. The description restates the optionality of the database parameter but adds no new semantic information. Meets the baseline for covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists SQL/PGQ property graphs and specifies the source system view. However, it does not explicitly differentiate from the sibling tool 'list_graphs', which may list other graph types, so purpose is clear but not fully distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when results may be empty (PG<19, missing catalog view) and suggests using 'get_pgq_status' for disambiguation. It does not explicitly state when to use this tool versus alternatives, but the edge-case guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description's main contribution is detailing the return format (name, materialized, definition). This adds value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The key information is front-loaded with action and resource, followed by return type details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 sufficiently explains the return values. For a simple listing tool, no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (database param has description, schema param does not). The description reinforces the 'schema' parameter but adds no new details beyond 'in a schema'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list'), the resource ('views and materialized views'), and the scope ('in a schema'), along with the returned fields. This distinguishes it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when needing view definitions) but does not explicitly compare with alternatives like list_tables or list_functions. No exclusions or 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the algorithm (sampling, centroid, L2-norm, cosine distance), edge cases (insufficient_data, available if pgvector not installed), and the half-open interval behavior. Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds significant behavioral context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of ~150 words, efficient and front-loaded with the main action. Every sentence adds value: algorithm, default values, edge cases, example. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main return values (cosine distance, drift_detected, insufficient_data, available) and edge cases. Given the tool's complexity and 11 parameters, it is reasonably complete, though more detail on output schema would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With an input schema of 11 parameters and only 9% schema description coverage, the description should compensate. It mentions only sample_size and drift_threshold defaults, and timestamps implicitly. It does not explain schema, table, embedding_column, baseline/current start/end, or the database parameter. The example provides usage but no parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Compare two time windows of a pgvector column and flag distributional drift.' It identifies the specific resource (pgvector column) and action (compare and flag drift), and distinguishes it from sibling tools like detect_vector_outliers or 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: 'Useful for ops monitoring of embedding pipelines — an upstream model swap typically shows up as a large centroid cosine distance.' It implies when to use it but does not explicitly exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's read-only nature is established. The description adds important behavioral context: the extension requirement and the available=false fallback, which go 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the purpose and then add essential conditions. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter, clear annotations, and an output schema (implied by context), the description covers the return values, extension requirement, and failure mode. It provides enough information for the agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has one optional parameter (database) with schema coverage at 100% and a clear description in the schema. The tool description does not add any additional semantics about this parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as reading a high-level summary of the PostgreSQL shared buffer cache, specifying the exact metrics (total, free, used, dirty buffers, average usage count). It distinguishes from the sibling read_pg_buffercache_relations by focusing on summary rather than per-relation stats, though this is not explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement for the pg_buffercache extension and the behavior if not installed (returns available=false), providing some context. However, it does not explicitly state when to use this tool over its sibling read_pg_buffercache_relations, leaving the usage guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description is consistent, adding details like 'returns empty list when extension not installed' and 'feeds audit_database category'. This adds 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the main action. It efficiently lists rules and edge cases without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and presence of an output schema, the description covers all important aspects: what it does, rules surfaced, suggested actions, edge case for missing extension, and relation to audit_database. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'database' is fully described in the input schema (100% coverage). The description does not add any additional meaning or context about the parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'walk every pg_turboquant index and emit advisor findings', specifies the resource (pg_turboquant indexes), and lists specific rules surfaced. It distinguishes from siblings like recommend_indexes which likely deal with regular indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when TurboQuant extension is present (returns empty list if not installed) but does not explicitly state when to use this tool vs alternatives like recommend_turboquant_query_knobs. No exclusions or direct comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond the readOnlyHint annotation by stating that writes/DDL are rejected before execution. This helps the agent understand the safety mechanism. The example gives a practical sense of usage. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example: no wasted words. The purpose is stated first, followed by the key safety constraint, and then an illustrative example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description doesn't need to explain return values. Annotations cover read-only nature. The description explains the core behavior and safety, which is sufficient for a simple tool. Minor gap: no mention of error handling or bounds on max_rows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only indirectly explains the 'sql' parameter via the example. The 'database' parameter is described in the schema (but not in the description), and 'max_rows' has no description at all. With only 33% schema coverage, the description fails to add meaningful parameter guidance beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Validate and run a read-only SQL query' and explicitly distinguishes from unsafe operations. The tool name and description align perfectly, and it stands out among siblings with similar names (run_select_parallel, run_select_tuned) by specifying the core read-only SELECT functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says writes/DDL are rejected, implying this is for read-only queries. Provides a concrete example showing typical usage. However, it does not mention when to use alternatives like run_select_parallel or run_select_tuned, which could be valuable context for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals key behaviors: no exact rerank, half_precision toggle, optional knobs (probes/oversample_factor), and the format of returned candidates. This adds useful context that the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-structured sentences. The first sentence delivers the core purpose and constraint, the second explains key parameters, and the third covers prerequisites and return type. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, 7 required) and low schema coverage, the description partially compensates by explaining metric, half_precision, and optional knobs. However, it omits details on query_vector format, candidate_limit, and the meaning of table/schema/id_column/embedding_column. The return type is described, but the output schema is not fully leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 9% schema description coverage, the description adds semantic value for metric (enumerates valid values), half_precision (switch to halfvec), and optional knobs. However, many parameters like schema, table, id_column, embedding_column, query_vector, and candidate_limit lack added meaning beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Run tq_approx_candidates' and the resource 'turboquant index', specifying it performs approximate k-NN retrieval with no exact rerank. It distinguishes from sibling tools like turboquant_rerank_candidates by noting the absence of reranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises when to use this tool (approximate retrieval) and suggests using recommend_turboquant_query_knobs first for knob tuning. It also mentions the prerequisite pg_turboquant extension. However, it does not explicitly state when not to use this tool or contrast with alternatives like vector_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds behavioral context by explaining the two-step process (approximate retrieval then exact rerank) and the effect of half_precision. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and then add key details (half_precision, extension requirement). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations, the description covers the core workflow and a key parameter. It lacks discussion of defaults or edge cases but is generally sufficient for a well-documented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 8%, with only the database parameter described. The description adds meaning only for half_precision, leaving most parameters (e.g., query_vector, metric, limits) without additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs approximate retrieval followed by exact rerank, specifying the process and output. It distinguishes from related siblings like turboquant_approx_candidates by explicitly mentioning the rerank step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement for the pg_turboquant extension and the half_precision parameter behavior, but does not explicitly state when to use this tool versus alternatives like turboquant_approx_candidates or other rerank analysis tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior. The description adds valuable context: it walks the chain, reports coverage (first/last event ID), and details failure indicators (error, first_invalid_id). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and target, followed by concise return field details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter verification tool, the description fully covers purpose, return fields, and failure modes. Output schema exists but description compensates adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning beyond what the input schema provides for the single optional 'database' parameter. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies the HMAC-SHA256 signature chain of persisted audit events in a specific table, and specifies the return object with fields. This distinguishes it from sibling tools like list_audit_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying audit chain integrity but does not explicitly state when to use it versus alternatives, nor does it provide exclusions or usage contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description aligns with read-only behavior. It goes beyond by specifying the return shape (format, row_count, truncated, content) and the truncation condition. No destructive behavior is suggested, and the description adds value beyond annotations by detailing output fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long: the first sentence covers the core action and constraints, and the second sentence details the return object. It is front-loaded, concise, and contains no extraneous information. Every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is described in the description, it provides complete return value details. The description covers the main parameters and constraints. However, it could explicitly list the allowed values for 'format' (though implied by 'CSV or JSON') and mention that the tool may be resource-intensive for large tables. Overall, it is mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description compensates by explaining the meaning and constraints of key parameters: schema and table are required and must be plain identifiers, limit defaults to 10000, format defaults to 'csv', and database targets a secondary read-only database. This adds significant value beyond the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool serializes all rows in a specified schema.table to CSV or JSON, including constraints like limit and plain identifiers. This makes its purpose very specific and distinguishes it from sibling tools like export_query (which exports query results) and list_tables (which lists but doesn't export).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It provides constraints (e.g., plain identifiers, limit) but no guidance on when to choose export_table over export_query or other export-related tools. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description adds context such as excluding PK/unique indexes, returning stats vs. verdict, and the need for mature stats. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and well-structured, front-loading purpose and then providing details. It could be slightly more scannable, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately explains return structure (tables and indexes with stats). It covers exclusions, usage context, and false positives, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the 'database' parameter has a helpful description. The 'schema' parameter lacks description, but the tool's purpose implies it scans a schema. The description partially compensates by outlining returned fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds tables and indexes with zero scans since pg_stat reset, explicitly distinguishing it from being a verdict. It specifies what it returns and excludes primary key/unique indexes, providing a unique purpose among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises running after a meaningful period to avoid false positives, but does not explicitly mention when not to use or compare with alternatives like recommend_index_drops.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context beyond annotations: reveals exclusions (views, foreign tables) and default partition behavior. readOnlyHint already indicates safety, so extra detail on what is excluded is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences and an example. No wasted words; front-loaded with primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, exclusions, return format (Mermaid string), and parameter details. With output schema present, return value is documented. Missing potential performance notes for large schemas, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description explains include_partitions parameter default and effect, and gives an example for schema. Despite 33% schema coverage, it compensates by clarifying behavior for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a Mermaid ER diagram for a schema, specifying what is excluded (views, foreign tables, partitions by default). It distinguishes from siblings like generate_graph_diagram by focusing on schema diagrams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generating schema diagrams and includes an example, but lacks explicit guidance on when not to use or alternatives. It doesn't contrast with siblings like generate_schema_docs for documentation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds that it returns a string and optionally fetches sample values, which is consistent with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an example, no fluff. Front-loaded with purpose and key details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and good annotations, the description covers parameters and return type. Could mention output format or edge cases, but sufficient for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33%, so description must compensate. Explains include_samples and database (latter already in schema). But the required 'schema' parameter is only implied via example, lacking explicit description. Adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it generates a detailed Markdown reference of a schema's components, distinguishing it from similar tools like generate_schema_diagram or list_tables. Verb 'Generate' and resource 'schema docs' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for the database parameter (secondary databases) and example usage. Does not explicitly exclude alternatives or state when not to use, but usage is clear from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, indicating no modification. The description adds behavioral context: it generates SQL but does not execute, it uses column-name heuristics for realistic values. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet concise, front-loading the core purpose and then providing behavioral details and return structure. The example is included. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (2 required) and an output schema, the description covers the purpose, usage context, return object structure (insert_sql, columns, schema, table), and behavioral details. Minor gaps exist (seed, follow_foreign_keys details), but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (20%). The description adds meaning for the 'database' parameter (optional secondary DB) and implies 'follow_foreign_keys' by mentioning sampling FK columns. However, 'seed' is not explained, and 'follow_foreign_keys' behavior when false is not described. The example helps but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates one realistic test row for a table, is catalogue-aware, and distinguishes itself from the sibling 'generate_test_data' (bulk). It specifies the behavior: skipping identity/generated columns, sampling FK rows, and using heuristics for realistic values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions it is designed for the shadow-migration workflow where a single realistic row matters more than volume, and that it does not execute the INSERT (caller uses run_write). It distinguishes from the bulk sibling, but does not exclude other potential alternatives like manual SQL generation, but this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by detailing that it never raises, returns a structured object with specific fields, and describes version-dependent behavior (available=false for PG < 19).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the main purpose first, followed by behavioral details, return format, and an example. It is concise but could be slightly tighter, though it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers all necessary aspects: purpose, behavior, error handling, return values, and usage context. It is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single optional parameter (database) completely. The description does not add any additional meaning about the parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports whether SQL/PGQ is usable on the server, differentiating it from related tools like run_cypher and run_pgq by explaining it's a hint about which graph surface to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it's a precursor to using graph query tools (run_cypher for PG<19, run_pgq otherwise) and includes a diagnostic pointing to run_cypher when unavailable. It provides clear context but lacks explicit when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral context beyond the readOnlyHint annotation: error handling (available=false on error), version-dependent behavior (PG ≤ 18 fallback), and exact return fields. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the main purpose, and includes an example. Every sentence provides value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers behavior, return structure, error handling, and version dependencies. With an output schema present (assumed), the tool is well-documented. Minor omission: usage context relative to related recommendation tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the optional 'database' parameter with a clear description. The tool description does not add extra parameter semantics, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reporting whether B-tree skip-scan optimization is the planner default. It distinguishes from sibling tools (e.g., get_pg19_ddl_status) by focusing on skip-scan, and includes version-specific behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when checking skip-scan support and provides version guidance, but does not explicitly compare to related tools like recommend_skip_scan_indexes. Lacks 'when not to use' or direct alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, which description does not contradict. Description adds output behavior details (e.g., ranks, scores) and mentions tunables, but does not discuss rate limits or auth. Useful context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs: first explains purpose, second lists parameters with example. No wasted words, front-loaded with key information. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 11 parameters and output schema, the description explains the algorithm, return columns, and provides an example. Lacks explanation of 'database' parameter (though schema covers it) and mentions non-existent 'rrf_k', but overall complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (9%), so description should compensate. It lists key parameters and gives an example, but mentions 'rrf_k' which is not in the input schema, creating confusion. Example helps, but inaccuracy hurts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it combines vector and full-text ranking via RRF, and explicitly contrasts with pure vector and pure full-text search, distinguishing from sibling tools like vector_search and full_text_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by explaining it bridges gaps between vector and full-text search, but lacks explicit when-not-to-use or alternative comparison. It could more directly differentiate from hybrid_bm25_vector_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the tool is read-only (matching readOnlyHint annotation) and describes the return fields. It does not discuss edge cases or performance, but these are not critical for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first declares purpose, the second details return fields. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and presence of an output schema (assumed), the description is complete enough. It does not mention ordering or limits, but these are likely standard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description is adequate. The tool description does not add any additional meaning to the parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every extension available to the database, including installation status. This distinguishes it from the sibling 'list_extensions' which likely only lists installed extensions, though the description does not explicitly compare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests using this tool to see all extensions, but does not explicitly state when to use alternatives like 'list_extensions' or 'install_extension'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description reinforces read-only and adds specifics: reads from gp_toolkit.gp_resgroup_status, lists returned fields, and notes that on vanilla PG it returns available=false. This 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose and source, second adds context, third gives example. Front-loaded with core info, no redundant words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description doesn't need to detail return format. Covers source, fields, vanilla PG behavior, and pairing. Could mention permission requirements or error scenarios, but for a simple list tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one optional parameter 'database' with schema description. Description adds cross-reference hint to list_databases for configured ids, but does not elaborate on format or constraints. Schema coverage is 100%, so baseline is 3; this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists resource groups, specifies the source view (gp_toolkit.gp_resgroup_status), enumerates returned fields (concurrency, cpu_max_percent, etc.), and distinguishes behavior on vanilla PG. Differentiates from sibling tools by naming a complementary tool (analyze_workload).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for usage: pairs with analyze_workload for workload diagnosis. Mentions read-only nature and fallback on vanilla PG, implying when the tool is applicable. Could explicitly state when not to use, but the pairing and caveat provide good guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by explaining the method ('using EXPLAIN plan costs and index scans') and output nature ('returning an optimized version'). It aligns with readOnlyHint=true, indicating no destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that conveys all necessary information without redundancy. Every phrase carries weight, and the main action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema, the description adequately covers input, method, and output. However, it could mention limitations (e.g., only works for certain SQL dialects) or prerequisites, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description implicitly clarifies the 'sql' parameter's purpose (the query to analyze). The 'database' parameter already has a schema description. With 50% schema coverage, the tool description adds necessary context for the primary parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Analyze' and 'returning') and resource ('SQL query'), and specifies the exact outcomes ('syntax anti-patterns and performance issues' and 'optimized version'). It distinguishes itself from sibling tools like analyze_query_plan by promising an optimized version, not just analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for optimization but does not explicitly state when to prefer this tool over alternatives (e.g., explain_query or run_select_tuned). No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains that optional tuning args are omitted from the SQL if not provided, letting upstream defaults apply. It also requires the pg_search extension and specifies the return shape. Some details like performance implications are missing, but overall good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, front-loading the core purpose and following with necessary details. Every sentence adds value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 params, 5 required), the description covers essential aspects: mechanism, required params, optional tuning args, return shape, and extension requirement. It references the output shape from a sibling tool, which aids completeness. Missing error conditions or document existence handling, 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 7% schema description coverage, the description adds significant value by explaining the role of document_id, enumerating the nine tuning args, and clarifying that they are optional kwargs. It compensates well for the sparse schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds rows similar to a seed document using specific mechanisms (pdb.more_like_this + @@@). It distinguishes itself from sibling tool pg_search_run by noting it returns the same hit shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for text similarity based on a seed document, but does not explicitly state when to use this tool versus alternatives like pg_search_run, vector_search, or fuzzy_search. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readonly and non-open-world. Description adds version-dependent behavior (empty result on unsupported versions), revealing a critical edge case beyond annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core purpose and then add essential version behavior. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main purpose, version dependency, and counters reported. With output schema present, return format is handled. Minor gap: no mention of pagination or large result sets, but acceptable for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear description for the single optional parameter (database). Description does not add parameter-specific meaning beyond what the schema provides, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads the pg_stat_io view (PostgreSQL 16+), reports specific cumulative I/O counters, and is a read-only operation. The verb 'read' and resource 'pg_stat_io' are specific, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for use (spotting buffer-cache misses, write amplification) and explicitly mentions version dependency (returns available=false on PG 14/15). Lacks direct when-not or alternative tool references, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and openWorldHint=false. The description adds transparency by listing which thresholds are adapted, the fallback behavior with derived_from_corpus bool, and the fact that four thresholds stay at hardcoded defaults. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading the core purpose, then detailing thresholds, filtering, fallback, and return fields. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the existence of an output schema, the description covers the essential aspects: what it does, how to filter, fallback, and return structure. It could clarify the meaning of 'adapted' vs non-adapted thresholds, but is generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (20%), but the description compensates by explaining the purpose of days, backend, metric, and k for filtering corpus history. It does not detail default values or allowed ranges, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes corpus-percentile thresholds from efficiency observations history. It names specific thresholds and distinguishes itself from other recommend_* tools by focussing on efficiency thresholds adaptation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to filter by days, backend, metric, and k, with concrete examples like 'what's normal for HNSW+cosine+k=10'. It also describes fallback behavior when corpus is small. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description details behavioral aspects: sampling queries, building ground truth, sweeping ef values, excluding the query row from results, and verifying HNSW index. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and is informative, but includes some extra phrasing like 'the actionable companion to analyze_hnsw_recall' which could be trimmed. Still, it is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, procedural logic), the description covers purpose, behavior, prerequisites, and error handling. The output schema is explained in detail in the return object, making the description complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 13%, but the description explains defaults for sample_queries and target_recall, and provides an example call. However, it does not describe all 8 parameters, leaving gaps that the schema does not fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recommends an ef_search value for a target recall@k, with specific actions like sampling queries and sweeping ef values. It distinguishes itself from analyze_hnsw_recall by being the 'actionable companion'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool is positioned as the actionable companion to analyze_hnsw_recall, and it notes that it verifies HNSW index existence. It provides context on when to use and references prerequisites like the vector extension, but lacks explicit '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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Never raises,' a behavioral guarantee not covered by readOnlyHint annotation. It also details output fields and possible reasons, providing transparency on what the agent can expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences + example), front-loads the core purpose, and efficiently covers inputs, outputs, and behavioral guarantee. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, inputs, outputs, possible reasons, and a behavioral guarantee. With annotations specifying read-only and open-world hint, it is nearly complete. Could explicitly mention relation to sibling 'wait_for_lsn' to enhance completeness, but otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'database' is fully documented in the input schema. The description does not add new semantic information about the parameter beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies verb 'advise' and resource 'whether to use WAIT FOR LSN', clearly differentiating from sibling tools like 'wait_for_lsn' (executes wait) and 'get_current_wal_lsn' (retrieves LSN). It enumerates possible reasons and return fields, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool advises on using WAIT FOR LSN, implying it should be used before deciding to wait. It doesn't explicitly list when-not-to-use or alternatives, but the sibling structure and tool name make the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint annotation, detailing two operation modes and the specific output parameters. It includes a prerequisite (pg_turboquant). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two clear sentences and a bullet list. It front-loads the main purpose and efficiently conveys the two modes and output knobs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's functionality, modes, and output, and references related tools. It compensates for low schema coverage by explaining the parameter groupings. However, it lacks details on parameter constraints or ranges, and the output schema is only implied but not explicitly stated (though the output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to parameters by explaining the two modes and optional fields (final_limit, filter_selectivity). The database parameter is well-documented. However, it does not explain the purpose or typical values of candidate_limit and final_limit, nor what index_schema and index_name represent beyond their names. Given low schema coverage (17%), more parameter explanation would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs tq_recommended_query_knobs as a per-query knob advisor. It distinguishes two modes (plain and index-aware) and lists the returned knobs, making the purpose specific and distinct from sibling tools like recommend_hnsw_ef_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode: plain with just candidate_limit (and optional final_limit), index-aware with index_schema and index_name. It also instructs to pass returned knobs to related tools. However, it does not explicitly state when not to use this tool or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds beyond readOnlyHint annotation: describes output as Mermaid string, edge labels, cross-schema handling. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main action, no redundancy. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers default behavior, optional include_all, output format, and cross-schema handling. Output schema likely provides return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage low (33%) but description clarifies include_all default and purpose. Schema parameter not elaborated, but obvious from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it builds a Mermaid graph of FK cascade chains. Differentiates from sibling tools like generate_schema_diagram by focusing on cascade actions and blast radius.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains default behavior (only cascade actions) and when to use include_all. Provides context for write blast radius, but does not explicitly compare to alternative tools like list_foreign_keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation, as it only reads the schema and emits code. It adds detailed behavioral context beyond annotations, specifying which SQLAlchemy features are covered (Mapped[T], mapped_column, ForeignKey, etc.) and explicitly documenting the composite FK gap. This provides full transparency for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. The first sentence states the purpose, followed by details on coverage and a known gap, and ends with the output format. Every sentence earns its place; no unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generating code from a schema) and the presence of an output schema, the description is complete. It covers what the tool generates, what is supported, and what is not. The agent has enough information to decide whether this tool meets its needs without needing to invoke it blindly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'database' parameter well ('Optional: target a configured secondary...'). The tool description adds no further per-parameter guidance; it implicitly explains that 'schema' is the database schema to read. With 50% schema description coverage, the description does not compensate for the undocumented 'schema' parameter, so it adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a PostgreSQL schema and generates a SQLAlchemy 2.0 declarative models file. It specifies the output format and covers tables, columns, types, keys, constraints, defaults, and enums, while noting a known gap (composite FKs). This distinguishes it from sibling tools that generate other ORM schemas (e.g., Prisma, Drizzle, Ecto).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for generating SQLAlchemy models from a PostgreSQL schema but does not explicitly state when to use it vs. alternatives like generate_prisma_schema or generate_diesel_schema. It notes a limitation (composite FKs are a v1 gap) but provides no exclusion criteria or guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (safe read operation). The description adds value by specifying error conditions (extension not installed, index not found), return shape (schema, index, typed options, raw options), and that it raises errors, providing full 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the main action. The second sentence details returns, making it efficient. No wasted words, though it could be slightly more structured with bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 adequately covers returns (schema, index, typed options, index_options) and error conditions. It does not explain the 13 typed options individually, but the output schema and reference to list_pg_search_indexes fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only database has description). The description mentions 'schema.index' but does not detail each parameter's role beyond what the schema provides. It adds some context by tying schema and index together, but the gap in parameter documentation is not fully compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches parsed reloptions for a single BM25 index (schema.index), distinguishing it from sibling tools like list_pg_search_indexes (which lists all). It specifies the return shape and error conditions, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for a specific BM25 index) and contrasts with list_pg_search_indexes, but does not explicitly state when not to use or mention alternative tools for related tasks. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description confirms it's a read-only check. The description adds context beyond annotations by explaining the return object fields (available, server_version_num, etc.) and providing an example call. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it states the purpose upfront, then explains behavior, and ends with an example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and an output schema, the description covers all necessary aspects: purpose, behavior for different versions, return values, and an example. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'database' is well-documented in the input schema (100% description coverage). The description does not add further parameter semantics beyond what the schema provides, which is acceptable since the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Report whether PG 19's in-server REPACK command is usable.' It specifies the context (PG 19), what it checks, and the return values. It distinguishes from siblings by focusing on a specific PG 19 feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that for PG < 19, it returns available=false with a diagnostic pointing to the pg_repack extension fallback. It also highlights the significance of the in-server REPACK CONCURRENTLY as a PG 19 operational win, guiding agents on when to use this tool. It lacks explicit 'when not to use' but is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it uses a specific PG function (pg_get_tablespacedef), handles non-existent tablespaces by returning found=false, and requires PG 19+. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and includes an example in a single paragraph with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is complete: it covers required PG version, error handling, return structure, and an example. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the return fields and providing an example. The schema only describes the 'database' parameter; the description clarifies the 'tablespace_name' parameter through the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the CREATE TABLESPACE DDL for a named tablespace using a specific PG function. It specifies the return structure with object_type, object_name, found, and ddl, and distinguishes itself from siblings by being a specific DDL retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement for PG 19+ and provides an example, but does not explicitly state when to use this tool over alternatives like list_tables or other get_* tools. It implies usage but lacks clear when-not or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the sort order of labels and the return structure (name and values). Annotations already indicate read-only, so the description adds value beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose and return value without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema existence, the description adequately explains the return values and ordering, making it complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 50% description coverage (database parameter described). The tool description does not add extra meaning to parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists enum types in a schema, with labels in sort order. It uses a specific verb and resource, distinguishing it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing enum types. While no explicit alternatives are mentioned, the context makes it clear when to use this tool over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds context about the return structure and that only active graphs are listed, providing extra 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no fluff. All information is front-loaded and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and an output schema present, the description is complete. It specifies the return format adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description adds no parameter info because none exist, and the schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all active Apache AGE property graphs and specifies the return format with `name` and `oid`. This is a specific verb-resource combination that distinguishes it from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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, but the context of listing graphs is straightforward and the description implies its usage for retrieving graph metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 detailing what is returned (13 specific options, preserved full dict), and the edge case of an empty list when the extension is not installed. It does not disclose any required privileges or potential side effects, but the read-only nature is already clear from annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the core functionality, and the second adds important details about the options and edge case. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with an output schema, the description covers: the type of indexes listed, the configuration details included, accessibility of unsurfaced options, and behavior when the extension is missing. No gaps remain for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema coverage is 100% with a good description for the database parameter. The tool description does not add new semantics for the parameter; it repeats the concept of 'database' implicitly. Baseline score of 3 is appropriate as the schema already handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists pg_search BM25 indexes with parsed reloptions, specifying the exact resource and action. It distinguishes from siblings like list_indexes (general indexes) and get_pg_search_index_metadata (specific metadata) by focusing on BM25 indexes and their configuration details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: to list BM25 indexes and their options. While it does not explicitly compare with alternatives, the specificity ('pg_search BM25 index') makes it clear. No exclusion criteria or when-not-to-use guidance is provided, but the context from sibling names (e.g., list_indexes) helps fill the gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotation, the description discloses the output format (object fields and their meanings) and the special catch-all behavior (user='public'). This adds significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output structure, and special behavior. Combined with the output schema annotation, it provides complete context for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description is already in the schema. The tool description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists role-to-foreign-server mappings, with a specific detail about the catch-all entry. It clearly distinguishes from sibling tools like list_foreign_servers or list_foreign_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for viewing mappings but provides no explicit guidance on when to use this tool vs alternatives, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral details: scans schema, returns per-column recommendations with savings ratios, skips unsuitable columns. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and output specification. Every sentence adds essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, output fields, and edge cases (skipping non-vector or small tables). Annotations handle safety, and an output schema likely details the return structure, so no further info needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the description only mentions the 'schema' parameter implicitly ('Scan a schema') without adding meaning beyond the schema. The 'database' parameter is well described in the input schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Scan a schema') and clearly states the resource (vector columns) and outcome (recommendations for halfvec). It distinguishes from siblings like 'migrate_vector_to_halfvec' by focusing on analysis vs. action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and mentions skips (non-vector columns, small tables), providing implicit usage context. However, it does not explicitly state when not to use or list 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds substantial context beyond that: it confirms read-only transaction, no writes leak, and details the reporting behavior (RLS enabled, policies, row count, samples). No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence lists the tool's functions, the second emphasizes safety. It is front-loaded with purpose and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (testing RLS with multiple outputs), the description covers all key aspects: what it checks, that it runs as the target role, read-only guarantee, and what it reports. The presence of an output schema covers return values. The description is complete for an agent to understand when and what the tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only 'database' has a description). The description adds meaning for 'sample_size' by stating 'returns up to sample_size rows', but does not elaborate on 'role', 'table', 'schema' beyond their names. 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Test' with the resource 'RLS for role' and details what it does: reports RLS enabled, lists policies, counts rows, returns samples. It distinguishes itself from siblings like 'run_select' by specifying it runs as the target role in a read-only transaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Runs as the target role inside a READ ONLY transaction — no writes can leak. Pure read,' providing clear context for safe usage. It implies when to use (testing RLS without side effects) but does not explicitly state when not to use or name alternatives, though the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation (which indicates safety), the description adds that results are ordered by distance, capped at limit, and reports available=false if pgvector is missing. These are critical behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, minimal wasted words. Purpose is first, then use cases, then behavioral details. Well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered. The description explains threshold-based nature, ordering, capping, and a key precondition (pgvector extension). Could be more complete on supported metrics or parameter interactions, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, and the description mentions max_distance, query_vector, and limit only implicitly ('capped at limit'). No details on format, constraints, or defaults beyond schema. The metric parameter is not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns rows within max_distance of a query vector, distinguishing it from top-k searches. The verb 'return' and resource 'rows' are specific. Contrasts with top-k, aligning with sibling vector_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (de-dup, similarity gating, clustering pre-passes) and contrasts with top-k queries. However, it does not explicitly say when not to use this tool versus alternatives like vector_search or mmr_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and description states 'Read a PostgreSQL schema', consistent with read-only behavior. The description adds behavioral details: what is emitted (macros, enum module), the limitation ('Composite FKs are a documented v1 gap'), and enum handling, which are 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of four sentences, front-loaded with the core purpose, then efficient details on output structure, enum handling, and a known gap. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (code generation), the description covers the main purpose, output specifics, enum handling, and a known limitation. It assumes the tool reads from the live database via the schema name parameter, which is clear. Minor gap: no explicit mention of the return format, but the presence of an output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (database parameter has a description). The main parameter 'schema' lacks a description in the input schema, but the description states 'Read a PostgreSQL schema', implicitly indicating it refers to a schema name. No additional param-specific semantics are provided beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and resource 'PostgreSQL schema' to 'emit a Diesel ORM (Rust) schema.rs'. It details output components (table! macro, Nullable<T>, joinable!, allow_tables_to_appear_in_same_query!, enum handling), distinguishing it from sibling ORM generation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly identifies the tool as Diesel ORM specific ('Diesel ORM (Rust) schema.rs'), which strongly implies its use for Rust/Diesel projects. It does not explicitly state when not to use it, but the differentiation from siblings is clear from the name and content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details beyond the annotations: it lists every base table via a regex, excludes MCPg bookkeeping tables, and adds forcedType mappings for json/jsonb columns. It also mentions the default package and overridability. This fully informs the agent of the tool's behavior, and there is no contradiction with the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph, around 150 words, with the main action front-loaded. Every sentence adds value, distinguishing the tool, detailing the output, and noting configurable options. There is no redundancy or wasted words, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior and output details, including the XML structure. However, it does not specify how the output is delivered (e.g., as a file or text) or the file name. With an output schema present (though not shown), the description is mostly complete but could provide a bit more on the delivery mechanism.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%), with only the 'database' parameter having a description. The description adds meaning for 'target_package' by mentioning the default and override, but 'schema' and 'target_directory' are not explicitly explained. While the schema provides titles and defaults, the description does not fully compensate for the low coverage, earning a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a PostgreSQL schema and emits a jooq-codegen configuration XML. It distinguishes itself from other exporters by explaining that jOOQ generates Java code itself, and the artifact is the config file, not the code. This makes the purpose specific and distinct from sibling tools like generate_diesel_schema or generate_prisma_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: when the user needs a jOOQ configuration file for code generation, as opposed to other exporters that produce different outputs. However, it does not explicitly list alternative tools or state when not to use it, which would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Exceeds annotations by describing error handling behavior (never raises, errors surface as available=false) and listing return fields. Annotations already indicate read-only, so description adds useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: three sentences plus example. Front-loaded with purpose, then behavior and return fields. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of output schema implicit in description and high schema coverage, the description is complete for a status-check tool. It covers version behavior, error handling, and return fields. Could mention more about using the results, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema description already explains the parameter. Description does not add additional meaning beyond the example usage, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports whether PG 19's async-I/O subsystem is usable, uses specific verb 'report' and resource 'AIO status', and distinguishes from siblings by providing fallback alternatives for older versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says for PG < 19 returns available=false and points to alternative tools (read_pg_stat_io, run_maintenance). Also clarifies that errors are handled gracefully without raising.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by explaining the return empty list when pg_cron is missing and detailing the exact structure of returned objects (jobid, jobname, schedule, command). 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and front-loaded with purpose. The example is helpful, though could be considered slightly redundant; overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with complete schema, annotations, and output description in the text, the description is fully adequate. It covers behavior when pg_cron is missing and result fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the database parameter already described. The description provides an example call without arguments, but does not add new meaning 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists pg_cron jobs registered for autowarm with a specific filter condition (jobname LIKE 'mcpg_autowarm%'). It distinguishes from sibling list_cron_jobs by its scope, providing specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: it returns autowarm jobs and empty list if pg_cron not installed. However, it does not explicitly mention when not to use it or point to alternatives like list_cron_jobs for broader listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that the tool is read-only. It adds value by explaining the internal join logic, the behavior for different schema values, and the special case on vanilla PostgreSQL where it returns available=false with a diagnostic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3-4 sentences plus an example), front-loaded with the purpose, and every sentence adds value. It avoids redundancy and is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema (handling return format), the description covers the main aspects: what is listed, possible distribution policies, schema parameter behavior, and behavior on vanilla PG. It does not discuss error conditions or prerequisites (e.g., needing WarehousePG), but for a read-only list tool with an output schema, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only the 'database' parameter has a description in the input schema). The description compensates by explaining the 'schema' parameter: 'schema=None returns every non-system schema.' and provides an example with schema='public'. However, it could be more explicit about the 'database' parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and specifies the resource: 'data-distribution policy for each table in a WarehousePG schema', including the possible values (HASH, RANDOM, REPLICATED). It distinguishes this tool from sibling list tools by focusing on distribution policies and mentioning the join with system catalogs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that schema=None returns all non-system schemas and provides an example usage. However, it does not explicitly state when to use this tool versus other list tools or when it might not be appropriate, such as on vanilla PostgreSQL (it does note that on vanilla PG it returns available=false).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds value by detailing the exact return fields (e.g., name, owner, all_tables, publishes_* booleans, tables). This provides behavioral context beyond just the safety annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the action, the second enumerates the return fields. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and an output schema, the description fully covers the tool's capabilities and behavior. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter 'database' is explained with clear semantics: it targets a secondary read-only database, with guidance to call list_databases for id values. Schema coverage is 100%, and the description adds usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists logical-replication publications with their included tables and operations. The name and title match exactly, and the detail about return fields distinguishes it from other list tools, as none of the siblings list publications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly states its purpose (listing publications) but does not provide explicit guidance on when to use it vs alternatives or when not to use it. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details read-only behavior (nothing executed), catalog reading, index handling, and error conditions. It adds value beyond annotations (readOnlyHint) 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the main purpose. It's efficient but could benefit from slight structuring for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output (migration_sql, rollback_sql, already_halfvec) and error handling, which is comprehensive given the tool's complexity. The presence of an output schema further supports completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only database parameter documented). The description mentions the required parameters implicitly but doesn't elaborate on each. It provides some context but doesn't fully compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate a DDL plan that converts a pgvector vector(N) column to halfvec(N)', specifying the verb (generate) and resource (column conversion). It distinguishes from sibling tools by its migration-plan focus, contrasting with analysis or execution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the workflow: 'feed the plan through the shadow-migration workflow' and notes when the column is already halfvec. It doesn't explicitly state when not to use it, but the context of plan generation vs. execution is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: it reads the audit log, uses a capped lookback window (default 7, max 90), groups by capability bucket, and returns a diagnostic when the audit subsystem is off. The annotations already declare readOnlyHint=true, and the description reinforces this by describing a read-only operation. It adds value by detailing the exact return structure and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the first sentence captures the core purpose. Subsequent sentences detail behavior, output structure, and an example. It is moderately concise—every sentence adds information without redundancy. The example at the end is helpful and fits within the description length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the input schema is simple (3 optional parameters with defaults), annotations are present (readOnlyHint), and output schema is partially described in the description, the description is highly complete. It covers all necessary details: key parameters, default behaviors, edge cases (audit off), and the full return structure (including nested objects). No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 33% description coverage (only 'database' is described), but the description adds meaningful details for all parameters: it explains the purpose, default values, and constraints (e.g., lookback_days capped at 90, top_n default 6). This compensates for the schema's lack of parameter descriptions and provides clear semantics for agent invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Empirically curate describe_self's per-bucket headline_tools from the audit log.' It uses a precise verb+resource structure ('curate...headline_tools') and distinguishes itself from sibling tools by explicitly referencing the per-bucket headline tools context and the describe_self scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get a recommendation for updating headline tools) and what the output is (a reviewable recommendation, not auto-applied). It also covers the special case when the audit subsystem is off. However, it does not explicitly state when not to use it or provide alternatives among the many sibling recommend_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, but the description adds rich behavioral context: it reads pg_stat_database aggregates, maps workload signals, and emits a ready_to_run_sql snippet without altering the system. It also details conditions like insufficient_stats and current_setting_optimal. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly verbose, detailing the mapping logic and output object fields. It is well-structured, front-loading the purpose and then explaining behavior, but could be trimmed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mapping workload to method, handling multiple scenarios), the description is thorough: it explains the inputs, the mapping rules, the output structure, and an example. The output schema is described in detail, so no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage for the sole parameter (database), the baseline is 3. The description does not add additional meaning beyond what the schema provides, as the schema already includes a clear description. Thus the tool relies on the schema for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Recommend') and resource ('PG 19 io_method'), and clearly defines the possible outputs (e.g., high_concurrent_read_load -> io_uring, bursty_io_with_cache_pressure -> worker, low_io_pressure -> sync). This distinguishes it from sibling tools, none of which focus on io_method recommendation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is for recommending io_method based on current workload, and notes it is read-only (emitting SQL, not executing). It provides clear context but does not explicitly specify when not to use or list alternatives; however, given the niche purpose, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it confirms 'pure catalog read', 'no per-segment scans', 'diagnosis-only', and behavior on vanilla PG. No contradiction with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) with an example, front-loaded with the core concept, and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers return values and edge cases. However, it could mention the optional database parameter for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 33% of parameters have descriptions in the schema; the description provides an example call but does not detail each parameter's semantics, leaving the optional database parameter under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool is a distribution-skew advisor for hash-distributed tables, detailing its functionality (reads n_distinct, suggests better hash key) and distinguishing it from sibling tools like recommend_indexes or recommend_skip_scan_indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states it is diagnosis-only and never executes, and mentions behavior on vanilla PG, but does not explicitly contrast with alternative tools for distribution analysis or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral details: read-only, concurrent execution, safety allowlist validation, error isolation per statement, outcome correlation via index. Annotations already indicate read-only, but description enriches context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: main action, error handling, use case. No redundancy, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, error handling, and use case. Output schema exists so return format not needed. Minor omission: no mention of statement format requirements beyond validation, but overall sufficient given annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%), but description partially compensates by explaining parallel_limit and statements context (e.g., 'up to parallel_limit', 'each statement is validated'). However, max_rows and database lack additional meaning beyond schema defaults and descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it runs multiple read-only SELECTs concurrently, distinguishes from sibling run_select by parallel execution and error handling for individual statements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'useful for dashboard-style fan-out where round-trip latency dominates' and gives examples, but does not explicitly state when not to use it or contrast with alternatives beyond implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description's read-only nature is consistent. The description adds context about the broad scope of returned data and the optional sample rows behavior (including when to exclude them). It does not mention potential output size or performance implications, but the read-only annotation already assures safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus an example. The first sentence list the returned components, the second provides parameter guidance. Every sentence adds value with no redundancy. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and the read-only annotation, the description covers the main functional behavior and usage constraints. It mentions that it replaces multiple calls, setting expectations. Could add a note about potential large output for wide tables, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, but the description adds meaning for the sample_rows parameter (advising when to set it to 0). The schema and table parameters are clear from context, and the database parameter is described in the schema. The example demonstrates usage, compensating for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a comprehensive snapshot including columns, primary key, foreign keys, constraints, indexes, storage stats, row count, vacuum/analyze stats, and optional sample rows. It distinguishes itself from sibling tools by consolidating what would be 4-5 individual calls (e.g., list_constraints, describe_table, list_indexes) into one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use this tool (one-stop snapshot) and provides specific guidance on the sample_rows parameter: set to 0 for wide/jsonb-heavy tables where the sample isn't useful. An example call is given. However, it does not explicitly mention when to prefer individual sibling tools over this composite one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations (readOnlyHint, openWorldHint) by explaining the exhausted flag and batch size limits. It aligns with annotations (read operation) and informs the agent about polling termination conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences, no filler, and all information is essential. It is well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (cursor fetch with batch size and exhaustion signal), the description adequately covers all necessary points: what it does, when to stop, and batch constraints. The presence of an output schema (not shown) does not require additional description of return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the description covers semantics for batch_size (default and cap), it does not describe the required cursor_id parameter. With 0% schema coverage, the description partially compensates but leaves a gap for cursor_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool fetches the next batch from an open server-side cursor, using specific verb 'fetch' and resource 'next batch'. It distinguishes itself from siblings like open_cursor and close_cursor by focusing on the incremental fetch operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage, including when to stop polling (exhausted=true) and the batch size defaults/cap. It does not explicitly compare to alternatives, but the guidance is sufficient for an agent to decide when 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.
- Behavior5/5
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 the heuristic nature (no row sampling, no value introspection), listing categories, and detailing confidence levels (high/medium/low). This provides behavioral context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core verb and resource, followed by key details (categories, confidence, caveat). Every sentence adds value with no redundancy, using proper punctuation and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains the tool's behavior, output structure (findings list with fields and summary counts), and caveats. Given the output schema exists (as per context signals), the description need not repeat return types, and it complements the schema with clear purpose and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: the 'database' parameter has a description in the schema, but 'schema' does not. The description does not elaborate on either parameter beyond what the schema provides. The inherent context of the tool's purpose indirectly clarifies the 'schema' parameter, but the description adds no explicit parameter guidance, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool flags columns that look like sensitive data (passwords, tokens, PII, etc.), specifying it is a pure heuristic without row sampling. This clearly distinguishes it from sibling tools which are mostly analysis or audit operations, providing a unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises treating the output as a signal, not a verdict, and gives a concrete example (email_template_id). It implies usage for a first pass review, but does not explicitly state when not to use or mention alternatives. This is clear guidance but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond the readOnlyHint=true annotation. It details exactly which database objects are covered, which are not, documents a known gap (composite FKs), and clarifies that the output is a single string. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the main action, followed by specific coverage details, limitations, and out-of-scope items. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, simple input) and the existence of an output schema, the description is complete. It covers what the tool does, what it covers, its limitations, and what is excluded. No additional context is needed for an AI agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; only the 'database' parameter has a description in the schema. The description mentions 'Read a PostgreSQL schema' which clarifies the intent of the first parameter but does not specify its format or meaning (e.g., schema name like 'public'). While it adds some value, it could better explain the required 'schema' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a PostgreSQL schema and emits a Drizzle ORM TypeScript schema string. It specifies the exact scope (tables, columns, keys, constraints) and explicitly lists what is out of scope (views, foreign tables, etc.). This distinguishes it from sibling tools like generate_diesel_schema or generate_ecto_schemas, which target different ORMs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for generating Drizzle schemas but does not explicitly compare to alternative schema generators or provide when-not-to-use guidance. It does document a known limitation (composite FKs are a v1 gap), which helps set expectations. Missing explicit exclusion or alternative references prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description reinforces no side effects. Importantly, the description adds behavioral details beyond annotations: it explains primary vs standby behavior, version support, and the exact return format. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an example, front-loaded with core functionality. Every sentence adds value: primary/standby behavior, workflow context, version support, return structure. Concise and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, clear return object), the description is complete. It explains primary/standby behavior, version compatibility, and the role/lsn return structure. With annotations and output schema present, no further details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single optional parameter 'database', specifying it targets a secondary read-only database. The description does not add additional meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The tool name and title clearly indicate it returns the current WAL LSN. The description specifies it returns pg_current_wal_lsn on a primary and pg_last_wal_replay_lsn on a standby, distinguishes it from sibling tools like wait_for_lsn, and explains the return structure (role and lsn). This is specific and action-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a usage workflow: capture LSN on primary after write, pass to wait_for_lsn on standby before read. This gives clear context for when to use the tool. It does not explicitly state when not to use it or list alternatives, but the workflow guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says 'Never raises', which complements the readOnlyHint annotation. It also explains the behavioral trait that divergence between configured and effective wal_level indicates a pending reload, adding behavioral nuance 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence stating purpose, a list of fields, a behavioral note, and an example call. No extraneous text. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With both annotations and output schema present, the description is more than adequate. It explains key return fields, how to interpret them, and provides a usage example. It covers all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description in the schema already provides adequate meaning. The tool description adds no additional semantic value beyond what the schema already says about the database parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Report') and the resource ('PG 19's on-demand wal_level flip usability'), and lists specific fields returned. It distinguishes itself from sibling tools like get_current_wal_lsn or get_wal_archive_status by targeting the logical replication status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to check wal_level flip usability, detect pending ALTER SYSTEM reload) and provides interpretation guidance. While it doesn't explicitly mention alternatives, the context is specific enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds significant behavioral context: it never raises, reports standby status, and describes fallback behavior on PG ≤ 18. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, front-loads the main purpose, includes an example, and every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers behavior across PG versions, error handling, and return fields. Since an output schema exists, the description need not elaborate on return values; it lists them briefly. 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate description for the database parameter. The description does not add new information beyond the schema; it includes an example showing parameter omission. Baseline score of 3 applies as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports whether PG 19's WAIT FOR LSN is usable, and also reports standby status. It uses specific verbs and explicitly distinguishes from sibling tools like wait_for_lsn (which performs the wait) and get_current_wal_lsn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (to check usability), mentions behavior on older PG versions (available=false with fallback), and notes it never raises. It lacks explicit comparison to sibling tools but implies usage context well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, never raises, and security-sensitive omission of archive_command string (only boolean returned). Annotations already provide readOnlyHint=true, but description adds important behavioral details about error handling and data sensitivity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence is necessary: purpose, companion tool, security note, list of returned fields. Front-loaded with the core purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simplicity (1 optional param, read-only, output schema exists), description fully covers behavior, return fields, and use case. Lists all fields returned, including the health boolean logic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description mentions the optional database parameter implicitly ('omit for the primary') and references list_databases, but the schema already provides a clear description (target secondary, omit for primary). With 100% schema coverage, the description adds no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Report' and resource 'WAL-archiving health' with clear scope: early-warning signal for failing archive_command/archive_library. Explicitly differentiates from sibling read_pg_wal_records by stating it covers WAL archive, not records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States it's a 'Companion to read_pg_wal_records' and explains the distinction (records vs. archive). Provides context for when to use (early-warning for failing archive) but does not explicitly list 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces that this is a read-only operation. It adds transparency about secondaries being read-only (PostgreSQL-enforced) and describes the return object structure. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences covering purpose, usage context, and return format. No redundant information; every sentence adds value. Well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema (though not shown in input, context says true), the description fully explains the tool's behavior, return structure, and how it relates to other tools. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters (schema coverage 100%), so the baseline is elevated. The description adds meaning by explaining the role of primary and secondary databases and describes the return object (primary_id, database_ids, databases list with fields). This provides context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every database this MCPg server is configured to serve', specifying the verb 'list' and resource 'databases'. It distinguishes from sibling tools by detailing the primary and secondary database concept, which is unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to see available databases and understand which database is targeted by default. It provides context that read-capable tools accept an optional `database` argument and that writes target the primary. No explicit exclusions or alternatives are given, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable behavioral context: explains the 'kind' field's purpose (forward compatibility), notes PG limitations, and details the exact output shape. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no wasted words. The first sentence front-loads the purpose and output fields, the second adds PG-specific context, and the third clarifies the response shape. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (2 parameters, 1 required) and explicit output schema described in the description, the tool is fully specified. No missing details about return values or behavior; output schema is described in prose. No prerequisites or edge cases are needed for this straightforward listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions the 'schema' parameter implicitly but does not describe the 'database' parameter at all. Schema description coverage is 50%, and the description adds minimal value beyond the input schema's own descriptions. The schema param context is clear, but the database param relies solely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists generated columns with specific fields (schema, table, column, data_type, expression, kind). It uses a specific verb ('List every ... STORED column') and resource, and distinguishes from sibling list_* tools by targeting a narrow subset of columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what the tool returns and notes that PostgreSQL only supports stored form, with forward compatibility. It does not explicitly state when not to use or name alternatives, but the specificity makes usage clear. Lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. The description adds value by disclosing behavior when the extension is not installed ('available=false') and confirming visibility to the current role. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and includes precise detail on output structure. Every sentence earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single optional parameter, rich output description, and annotations, the description covers edge cases (extension not installed) and return format completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-documented parameter. The tool description does not add extra parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all TimescaleDB hypertables visible to the current role, specifying the returned fields (chunk count, compression flag, total size) and behavior when the extension is missing. It distinguishes itself from sibling list_* tools through explicit reference to hypertables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys usage (for hypertable metadata), but lacks explicit comparisons to sibling tools like list_tables or when not to use this tool. The context is clear, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds value by specifying that PostgreSQL's own roles are excluded unless include_system is true, which is a key behavioral trait 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with purpose and key details. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters (2 optional) and output schema described, the description covers purpose, parameters, return format, and a key behavioral distinction. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage (database parameter documented, include_system not), the description compensates by explaining the effect of include_system. It also lists return fields, adding meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the database roles and their attributes,' specifying the verb and resource. It distinguishes from sibling list tools by noting the exclusion of system roles and the include_system parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on use: list roles, with optional targeting of secondary databases via 'database' parameter and control over system roles via 'include_system'. However, it does not explicitly state when not to use this tool versus alternatives among the many list_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation, such as the default exclusion of system schemas and the return structure. It does not contradict 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a relevant example. Every sentence adds value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description covers essential behaviors (exclusion logic, parameter usage) and is complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the include_system parameter lacks a description in the schema, the description explains its effect through the example and main text, compensating for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists database schemas, specifies exclusion of system schemas by default, and mentions the output format (list with 'name'). This distinguishes it from other list tools like list_tables or list_databases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an example and explains the include_system parameter, giving clear context on when to include system schemas. However, it does not explicitly state when not to use this tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which matches the tool's read-only nature. The description adds valuable behavior details: the available=false flag when pgvector is missing, and that relevance/diversity use cosine similarity independent of the retrieval metric. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a summary sentence, explanation of core parameters, output fields, error condition, and an explicit example. Every sentence adds value and the most critical information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (which describes return fields), the description still adds algorithmic context, explains the output (relevance, mmr_score, selection rank), notes the pgvector dependency, and provides a concrete example. It is fully adequate for an 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11% (only 'database' has a raw description). The description compensates by explaining the key parameters lambda_mult and fetch_k (their roles, ranges, defaults) and includes an example call that illustrates many parameters. However, it does not detail schema, table, column, or query_vector beyond self-evident semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a diversity-aware vector search using Maximal Marginal Relevance, explicitly distinguishing it from raw top-k and implying its advantage for LLM context. Among many sibling search tools, it uniquely highlights MMR re-ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool (when diverse results are preferred for LLM context) and implies that raw top-k is a simpler alternative. It does not explicitly list alternative tools or when not to use, but provides sufficient context for an AI agent to make a choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral details beyond annotations: it explains the computed progress_pct logic (blocks first, tuples as fallback, null when no denominator) and that it returns one row per build. Annotations already declare readOnlyHint=true, and the description aligns with a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four well-structured sentences. It front-loads the main purpose, details output fields, and adds usage guidance, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity monitoring tool, the description fully covers the return value semantics, including computed fields and edge cases (null progress). The output schema is described in detail, making the tool self-contained for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter `database`, and the description does not add significant meaning beyond what the schema provides ('Optional: target a configured secondary database'). It meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it surfaces active CREATE INDEX progress from pg_stat_progress_create_index, specifying the data source (PG12+, no extension) and output fields. It distinguishes itself from sibling tools like list_active_queries by mentioning when it's useful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Useful next to list_active_queries when an HNSW / IVFFlat build on a big table is taking longer than expected.' This gives clear context, though it doesn't explicitly exclude alternatives or state prerequisites beyond the PG version requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotation contradiction (readOnlyHint=true aligns with read-only cursor). Description adds behavioral details beyond annotations: TTL of 5 minutes, hard cap of 16 concurrent cursors, and server-side result set holding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, efficient coverage of key points without waste. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description doesn't need return details. Covers all necessary context: what it does, how to use, constraints, and relationship to sibling tools. Complete for a read-only cursor tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only database described). Description doesn't add much parameter detail beyond schema; it mentions SQL validation and purpose but no specific syntax or constraints. Adequate but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Open a server-side cursor') and the resource ('for a SELECT query'), explaining the purpose of paging through large result sets. It distinguishes from sibling tools like fetch_cursor and close_cursor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides good guidance: SQL validation from run_select, how to fetch and close, TTL and concurrency cap. Lacks explicit when-not-to-use but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds details about lenient and conjunction_mode behaviors and the extension requirement, providing context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two front-loaded sentences, efficiently covering purpose, parameter behavior, and prerequisites without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description fully covers what an agent needs: purpose, parameter effects, and extension requirement. No major gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema coverage, the description adds meaning for lenient and conjunction_mode parameters by explaining their effects. It compensates for low coverage, though database parameter is not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'parse' and resource 'query string', and explains its purpose for debugging. It differentiates from sibling search tools like pg_search_run by emphasizing parsing over execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is useful for confirming parser interpretation and mentions the dependency on pg_search extension. It does not explicitly list when not to use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the extension must be installed and that it returns available=false if not, adding significant behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding crucial information: purpose, filtering, and requirements. No wasted words, front-loaded with primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description covers purpose, filtering capability, required extension, and behavior when extension is missing. No gaps for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage, the description adds meaning for the 'schema' parameter by stating it allows filtering. However, it does not describe 'limit' or add to 'database' beyond the schema description. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the list of relations in the PostgreSQL shared buffer cache with specific fields (buffered size, percentage, etc.), distinguishing it from the sibling 'read_pg_buffercache_summary' which likely provides aggregate statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering by schema and the requirement for the pg_buffercache extension, but does not explicitly compare to sibling tools or state when not to use. It provides clear context on prerequisites and fallback behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds key behaviors: empty results on PG < 19, the fields returned, and an example call. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) with front-loaded purpose, clear structure, and no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, return format, version constraints, and usage example, leaving no gaps given the output schema exists and parameters are simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (database) is fully documented in the schema with description and default; the tool description adds no extra parameter meaning beyond the example call, but schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every row from PG 19's pg_stat_lock view with specific counters, distinguishes itself from sibling tools by its focus on PostgreSQL lock statistics, and provides explicit output structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the version dependency (PG < 19 yields empty list) and the optional database parameter, but lacks explicit guidance on when to use this tool versus alternatives like analyze_lock_hotspots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description's additional details—return format with nullable fields, empty list conditions—add significant behavioral context without contradiction. The description fully discloses edge cases and data structure, exceeding what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an example—extremely concise. Every sentence adds value: first explains purpose, second covers edge cases, example shows invocation. No wasted words, and the structure is front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but implied), the description adequately covers the tool's behavior, including nullability of fields and empty result scenarios. It also mentions the PG version requirement. For a simple read tool, this is sufficient for an agent to understand when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a detailed description of the `database` parameter. The tool description only mentions the parameter in passing, adding no new semantic meaning beyond the schema. Baseline 3 is appropriate as the schema carries the full parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns rows from PG 19's `pg_stat_recovery` view, detailing the specific information (replay progress, lag, startup state). It distinguishes from siblings by focusing on recovery statistics for a standby server, which is a specialized function not covered by other list/read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions when the tool returns empty results (PG <19, view absent, not in recovery) and mentions the optional database parameter for targeting a secondary. However, it does not explicitly compare to other related tools like `get_wal_archive_status` or `read_pg_wal_stats`, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations: it explains that fresh=true bypasses the cache and re-reads live data, and describes the output format (list of objects with specific fields). Annotations (readOnlyHint=true) align with the description, and no contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs plus an example, which is clear but slightly verbose. It front-loads the purpose and then adds details. Every sentence adds value, but it could be more concise without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no required parameters, output schema described), the description adequately covers usage and behavior. With many sibling tools, it provides enough context for an agent to select and invoke it correctly, though missing explicit comparison to recommend_index_drops.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only database parameter has a description in schema). The description compensates by explaining fresh (bypass cache) and giving an example with min_live_tuples, adding meaning beyond the schema's default values and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recommends tables that may benefit from indexing, specifically large tables read mostly by sequential scan. It uses a specific verb ('recommend') and resource ('tables') and distinguishes from sibling tool 'recommend_index_drops' by focusing on indexes to add, not drop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the fresh parameter (bypass cache after schema change) and includes an example usage. However, it does not explicitly state when not to use this tool or compare it to alternatives like recommend_index_drops, though the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals that the tool returns an empty list when the extension is not installed and that each finding carries a ready-to-run suggested_action SQL statement. This adds valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (several sentences) but packed with essential information: purpose, rule details with severity, action format, edge case, and integration context. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's narrow purpose and the presence of an output schema, the description covers all necessary aspects: what it does, what findings it produces, what each finding contains, and the edge case of missing extension. It is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents the optional database parameter. The tool description adds no additional meaning beyond what the schema provides, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool walks every pg_search BM25 index and emits advisor findings, listing specific rules and their severities. It distinguishes itself from siblings by focusing on pg_search index maintenance, with no other sibling having this exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use the tool (to get maintenance advice for pg_search BM25 indexes) and mentions it feeds into audit_database. However, it does not explicitly state when not to use it or name alternative tools, so it lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states it never invokes pg_prewarm and is read-only, aligning with readOnlyHint=true. It details the algorithm and budget capping, adding value beyond annotations with 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and well-structured, front-loading the purpose and then explaining algorithm and output. While informative, it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a recommendation tool with 5 optional parameters, the description covers functionality, algorithm, and output structure comprehensively. Missing details on prewarm_mode behavior, but otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema coverage, the description compensates by explaining shared_buffers_budget_pct and limit via example, but does not cover prewarm_mode or min_heap_blks_read. The output schema is described in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool recommends relations for pg_prewarm based on cold-miss rates and seq_scan dominance, using specific system tables. It clearly distinguishes from sibling tools like list_prewarmed_relations and get_prewarm_extension_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is for advisory purposes and is read-only, but does not explicitly state when not to use it or mention alternatives. The sibling tools exist, but the description could provide clearer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value beyond that by detailing behavior: returns an empty list on version/driver failure, the effect of the `max_leading_ndv` parameter, and the structure of the return list. No contradiction with annotations. Could be improved by noting that it only queries metadata and has no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 6 sentences) and front-loaded with the primary purpose. It includes an example call, and each sentence adds necessary information without excess. No redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (PG version dependency, output structure, parameter meaning, related tools), the description covers all aspects: what it does, when it returns empty, what the output contains (including field names and types), and how to interpret parameters. The output schema is described in sufficient detail, so no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only `database` has a schema description). The description compensates by explaining `max_leading_ndv`: 'caps the leading-column NDV that's considered low enough for skip-scan to be profitable.' This adds semantic meaning beyond the schema's type and default. The `database` parameter is already described in the schema, so no extra value needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find composite B-tree indexes whose leading column has low NDV — these are the ones PG 19's skip-scan optimisation unlocks.' It identifies the specific verb 'Find' and resource 'composite B-tree indexes', and distinguishes itself from siblings by mentioning how its output feeds into `recommend_index_drops` and pairs with `get_skip_scan_status`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it explains that the tool returns an empty list on PG ≤ 18 or driver failure, and suggests pairing with `get_skip_scan_status` for diagnostics. It also connects the output to `recommend_index_drops`, indicating a workflow. However, it does not explicitly contrast with other recommendation tools like `recommend_indexes`, but the intent is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already marking readOnlyHint=true, the description adds substantial behavioral detail: LLM provider sees a compact schema brief, returns JSON with sql/explanation, SQL passes through a safety allowlist rejecting writes/DDL/multi-statement, and return values include SQL, model rationale, and rows/columns/row_count. It also explains provider routing and default order.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense paragraph with an example, front-loaded with the core purpose and followed by specific behavior, parameter details, and a usage example. It is longer than ideal but every sentence adds value, and the structure is logical despite the lack of bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 parameters and an output schema, the description covers the main purpose, safety constraints, provider routing, table_filter, return values, and a concrete example. It does not explain max_rows or explain_preflight, but the overall picture is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, but the description compensates by explaining `question`, `schema`, `execute`, `table_filter`, and `provider` (including default selection order). It does not cover `max_rows` or `explain_preflight`, but the added detail for the most important parameters is significant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool translates a natural-language question into a read-only PostgreSQL query against a schema, with a specific verb ('Translate') and resource ('schema'). It distinguishes itself from sibling query tools by noting it uses LLM providers and the same safety allowlist as run_select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 (natural-language-to-SQL translation) and mentions using get_server_info to check configured providers. It also explains the execute flag and table_filter scoping, but does not explicitly exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds detail about querying pg_stat_ssl, returning specific encryption parameters, and notes a privilege-related caveat (lower bound under non-superuser). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action and details. No redundant information; every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 annotations, the description covers the tool's behavior, return contents, and a limitation (non-superuser lower bound). It is complete for a specific diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema fully describes the optional 'database' parameter. The description does not elaborate on the parameter beyond what's in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports whether the connection is TLS-encrypted, including protocol version, cipher, key bits, and a cluster-wide tally. It uniquely identifies its function among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it complements the startup TLS-enforcement check, implying a post-startup use case. It lacks explicit when-not-to-use or direct comparisons to siblings, but the purpose is specific enough to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint annotation, description adds blocking behavior, timeout handling, validation, and server version requirements. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences including example, front-loaded with SQL command, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description explains return fields. All parameter behaviors and edge cases covered. 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning to lsn (hex/hex validation) and timeout_ms (default 0, behavior). Database parameter is covered by schema. Schema coverage is 33%, so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool issues a WAIT FOR LSN command and blocks until WAL replay catches up. It uses specific verb and resource, distinguishing it from siblings like get_current_wal_lsn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions requirements (PG 19+) and behavior on timeout (timed_out=true) and error on older servers. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only behavior, non-execution of the query, and details the internal actions (EXPLAIN, plan walking, snapshotting locks, cache hit ratio). Annotations already indicate readOnlyHint=true, and the description adds significant behavioral context beyond that, with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two paragraphs, first explains functionality, second shows an example. Every sentence adds value, no fluff. It is well-structured and easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (signal indicates yes) and annotations, the description covers the main functionality comprehensively: it lists the diagnostic components (plan, contention, cache, maintenance) and mentions the output is categorized suggestions. This is complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: the 'sql' parameter has no description in the schema, and the description does not describe it either (only shows an example). The 'database' parameter is well-described in the schema. The description adds little beyond the example for the missing parameter, so it does not fully compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool diagnoses SQL query slowness in one call, specifying it runs EXPLAIN without executing, walks the plan tree, snapshots concurrent queries, and produces categorized suggestions. This distinguishes it from sibling tools like explain_query (which just runs EXPLAIN) and analyze_query_plan (which may focus on plan details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is safe to run on a statement not yet materialized, implying use before execution. It gives an example. However, it does not explicitly state when not to use this tool or mention alternatives among siblings (e.g., when to use analyze_query_plan instead). The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), the description adds that the tool never raises errors (driver-level errors surface as available=false) and details behavior across PostgreSQL versions. This provides transparency about error handling and version-dependent responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with clear front-loading of core purpose and an example call. Some details (like exact return fields) could be streamlined, but it remains well-structured and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (context signals), the description explains all return fields and covers version-specific behavior. It is complete in describing what the tool returns and under what conditions, leaving no gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single optional database parameter. The description adds context that omitting targets the primary, and explicitly references list_databases for discovering secondary database names, which is helpful beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports whether PG 19's online data_checksums toggle is usable and the current setting, adding version-specific behavior. It distinguishes itself from sibling tools by focusing on the data_checksums toggle status, 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use it (checking online toggle status) and explains behavior on PG ≤18, including pointing to the offline pg_checksums fallback. It does not explicitly name alternative tools or state when not to use it, but the version guidance aids in appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, so no mutation. The description adds significant value: it reveals that the tool returns an empty list when the redis_fdw extension is not installed, which is not encoded in annotations. It also lists the exact return fields and clarifies the output structure. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus an example. The purpose is front-loaded, every sentence adds value, and the structure is easy to read. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary context: it explains what the tool does, how to use the optional parameter, what the output contains, and handles the edge case of missing extension. With an output schema present (implied by the field list), the description is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 1 parameter with 100% description coverage. The description adds further context: it explains that the parameter is optional, targets a secondary read-only database, and advises calling list_databases to see configured IDs. This enriches the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists foreign servers backed by redis_fdw. It specifies the exact fields reported (address, port, database, TLS posture, password_configured, options). The verb 'list' and resource 'Redis foreign servers' are precise, and the tool is distinguished from the generic sibling 'list_foreign_servers' by specifying the FDW type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it: when you need info about Redis foreign servers. It also mentions the optional 'database' parameter for targeting secondary databases and directs users to call 'list_databases' to see configured IDs. However, it does not explicitly state when not to use it or name alternative tools (e.g., list_foreign_servers for other FDWs), though the context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes internal logic: walks `pg_stat_user_indexes` and `pg_stat_user_tables`, uses three reason codes. States it is read-only. Does not contradict 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Detailed with example, but slightly lengthy. Every sentence adds value. Good structure: purpose, logic, exclusions, return, example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers the tool's purpose, behavior, and return type adequately. Provides enough information for an AI agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to `low_scan_ratio` and `min_index_size_bytes` in context, with an example usage. However, the `schema` parameter is not described, and schema coverage is low (25%). Overall helpful but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a sibling of `recommend_indexes` for index removal, explaining it walks system catalogs to find large, rarely-scanned indexes. This distinguishes it from the sibling by focusing on drops.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use: to identify drop candidates. Exclusions are listed (PK/unique, small indexes). Read-only nature noted. Could be more explicit about when not to use, but the reason codes guide the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details internal behavior: sampling queries, building ground truth, sweeping probes, measuring recall and latency, and verifying index existence. It aligns with readOnlyHint=true, adding context beyond annotations. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose, detailed algorithm, and an example. It is informative without excessive verbosity, though slightly longer than minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema existence and the tool's complexity, the description fully covers algorithm, validation, return fields (including sweep details), and requirements. It integrates well with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite low schema description coverage (13%), the description explains key parameters (k, target_recall, sample_queries) and their defaults. It clarifies the algorithm's approach, compensating for the schema's lack of context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recommends an ivfflat.probes value for target recall@k, explicitly distinguishing itself as the IVFFlat analogue of recommend_hnsw_ef_search. Verb 'recommend' and resource 'IVFFlat probes' are 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the sampling, sweeping, and recommendation process, including validation for index existence. It provides an example and mentions requirements (vector extension). However, it does not explicitly exclude scenarios where it should not be used, though the analogue reference helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals behaviors beyond annotations (readOnlyHint, openWorldHint): it explains the one-hop expansion logic, default parameter behaviors, the dropping of the embedding column, and the requirement for the vector extension. This is thorough and adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with a clear summary, but it is somewhat lengthy. Every sentence adds value, though minor pruning could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 10 parameters and a rich output schema, the description covers the algorithm, parameter behaviors, limitations, dependency, and return structure. It provides an example and is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 10% schema description coverage, the description compensates well by explaining key parameters (query_vector, include_parents, include_children, max_related) and their defaults. It also provides an example. However, it does not explain optional parameters like metric or the meaning of k in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states its function as 'Context-packed k-NN retrieval (a one-shot RAG building block)' that runs vector search and expands results one hop along foreign keys. This distinguishes it from sibling tools like vector_search which likely perform plain vector search without context expansion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description frames usage as a RAG building block and lists limitations ('1 hop only', 'inbound expansion same-schema only'), helping an agent decide when to use it. However, it does not explicitly name alternative tools or state when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, but description adds significant behavioral details: SET LOCAL scoping so memory setting doesn't leak, hard cap at 2GB to prevent OOM, regex validation for memory units, and read-only validation via same allowlist as run_select. These go well 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise yet comprehensive. First sentence states purpose, then usage context, then constraints, and ends with an example. Every sentence adds value; no fluff. Suitable length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, memory tuning, read-only validation) and presence of an output schema, the description covers the key aspects: purpose, parameter semantics, scoping, and constraints. It does not detail return values (handled by output schema) or error cases, but remains complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description compensates well by explaining work_mem and maintenance_work_mem: bounded, local scope, regex pattern, cap. It does not detail sql, max_rows, or database (database has its own schema description). Adds significant meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it runs a read-only SELECT with tuned work_mem for heavy analytical queries. It distinguishes itself from run_select by explicitly mentioning the memory tuning and scoping via SET LOCAL. Verb 'run' + resource 'read-only SELECT with tuned work_mem' 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it's 'useful for heavy analytical SELECTs... that spill to disk under default work_mem.' It also mentions what is out of scope (non-transactional maintenance). However, it does not explicitly state when not to use it (e.g., simple queries where default work_mem suffices should use run_select instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds critical behavioral details: it never raises exceptions, driver errors are surfaced as available=false, and exact behavior on older PG versions. It also lists all return fields, providing complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences and an example. The first sentence states the purpose, the second covers error behavior, and the third explains fallback and lists return fields. No redundant information, clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description still usefully enumerates the return fields. It covers all important aspects: purpose, behavior on errors, behavioral differences across PG versions, and fallback guidance. The tool is simple, and the description fully covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one optional parameter (database) with 100% schema description coverage. The description does not add extra semantics beyond what the schema provides, which is adequate. The schema already explains its purpose and how to list databases. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports whether specific PG19 DDL-dump functions are usable. It names the functions (pg_get_roledef(), etc.) and distinguishes from other status tools in the sibling list, such as get_pg19_partitions_status and get_pg19_stats_status, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that on PG≤18 it reports available=false and provides fallback commands (pg_dumpall with options). It also clarifies error behavior: driver-level errors surface as available=false, guiding the agent on how to handle failures. This provides clear when-to-use and fallback guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral details beyond annotations: it never raises, driver errors surface as available=false, and on PG≤18 it reports available=false with fallback guidance. This is consistent with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the primary purpose. It includes an example and covers edge cases without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the description is fully complete: it covers purpose, behavior, return fields, and edge cases. The existence of output schema further reduces the need to document return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter has 100% schema coverage and is well-described in the schema. The description adds an example call without parameters, implying default behavior, which provides extra context without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports whether PG19 partition operations are usable. It specifies the verb (report), resource (partition operations status), and distinguishes it from siblings by focusing on a specific version feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly covers when to use (to check partition operation usability) and provides guidance for PG≤18 fallback. It does not explicitly mention when not to use, but the niche purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds significant behavioral context: the tool is best-effort due to version-dependent SQL surface, validates server existence, and returns an object with specific fields including available, key_count, etc. It also mentions the return format and provides a diagnostic note. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, then explains behavior, lists return fields, and provides an example. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 parameters, simple output schema), the description is complete. It covers the best-effort nature, validation, return fields, and even references list_databases for the optional parameter. The output schema exists, so return values are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only database has a description). The description provides an example showing the server parameter but does not elaborate on its meaning beyond the name. The database parameter's description in the schema is sufficient, but the tool description adds no extra semantics for server. The description is adequate but not compensatory beyond baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets best-effort cache metrics for a redis_fdw server, with specific verb and resource. It distinguishes from live Redis queries by noting that operators should query Redis directly for live metrics, and it appears among siblings like list_redis_foreign_servers and describe_redis_cache_table, providing enough differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use (for cache metrics via redis_fdw) and when not to use (for live metrics, query Redis directly). It also explains the best-effort nature and the validation behavior (checks server existence, reports available=false with diagnostic). Provides an example and references list_databases for the optional parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds valuable behavioral details: handling of effective_wal_level for PG 18 vs 19+, and that divergence indicates pending reload. This goes beyond annotations and clarifies edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficiently structured, front-loaded with the main action. Every clause adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema (assumed), the description completely covers what the tool returns, including version-specific nuance. No gaps remain for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description does not need to add parameter info, but it does explain what the return values include. Baseline for zero parameters is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return the MCPg server version, access mode, transport, database connection status, and PostgreSQL wal_level / effective_wal_level'. This uses a specific verb and defines the resource exactly. No sibling tool offers the same output, so differentiation is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Although not explicitly stating when to use or not, the tool's unique purpose among siblings (none other returns server info) makes it obvious. The description implies it is the go-to for server metadata. Slight deduction for lack of explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses detailed behavioral traits beyond annotations: the RRF formula, score calculation, handling of per-leg ranks (including NULL cases), and defaults. This adds significant value beyond the readOnlyHint annotation, confirming safe read operations and explaining output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, starting with the core purpose, then output details, parameter explanations, defaults, and requirements. Each sentence adds value without redundancy, making it appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (14 parameters, 7 required) and the presence of an output schema, the description covers the algorithm, output format, parameter semantics for key fields, and constraints (extensions, defaults). It is sufficiently complete for an agent to understand invocation and expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 7%, but the description explains the function of many parameters (e.g., distance_op, bm25_columns, k, weights, per_leg_limit) and their defaults. It does not describe every parameter exhaustively (e.g., vector_weight is mentioned but not explained), but compensates well for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it combines BM25 and pgvector search via Reciprocal Rank Fusion, citing a specific blog post. It uses specific verbs and resources, distinguishing itself from other search tools in the sibling list like full_text_search and fuzzy_search by detailing its methodology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (combining BM25 and vector search) and lists required extensions, but does not explicitly state when to use this tool over alternatives like hybrid_search or pg_search_run. It provides clear context without exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds detailed behavioral context: entry fields (index, obfuscated DSN, degradation flag, last error, reprobe seconds) and empty list return for no replicas. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, first stating purpose, second detailing outputs. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a zero-parameter tool with output schema. Covers what each entry contains and the edge case of empty list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%. Description adds value by explaining output fields, which is more than the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'report the health of every configured read replica' and enumerates the fields in each entry. Distinguishes from other list_* sibling tools by focusing on replica health status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly clear when to use: to check read replica health. No explicit alternatives or when-not, but the tool's specificity makes it unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavior: it checks for framework-specific tables, returns null when absent, and details the return shape per framework. Annotations (readOnlyHint) are reinforced, and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph with no wasted words. It lists frameworks, explains filtering, and describes the return structure clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the description explains the return format in detail, it is contextually complete. All essential aspects are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema parameter's purpose (filtering by schema) is added in the description, and the database parameter is described in the input schema. With 50% coverage, the description compensates well for the undocumented schema parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries and summarizes historical migrations by popular frameworks. It lists specific frameworks and distinguishes from sibling tools that analyze performance, audit, or schema details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that it allows filtering by schema, which guides use. However, it does not explicitly state when not to use or alternatives, though the narrow domain makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=true and openWorldHint=false, and the description reinforces that it is a pure calculator with no database side effects. It also lists all output fields, providing full transparency without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative and front-loaded with the main purpose, but the list of output fields is somewhat dense. The example adds clarity. Overall well-structured, though slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers purpose, parameters, output, usage context (pairing), and provides an example. It is complete for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains each parameter: total_ram_mb is required, cpu_count defaults to 4, workload enum values, storage enum values, and optional max_connections override. This adds significant meaning beyond the schema's default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool computes pgtune-style postgresql.conf recommendations, specifying it's a pure calculator that touches no database. It distinguishes itself from siblings by its calculator nature and mentions pairing with audit_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that it's a read-only calculator safe to call anytime, and explicitly advises pairing with audit_settings (audit first, then size). It does not list when not to use it or alternatives, but the context is clear enough for usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Advisor is read-only — never touches Redis itself,' which aligns with the readOnlyHint annotation. It also details the internal logic (inspects pg_stat_user_tables) and output structure, providing full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it starts with the purpose, explains the algorithm, server behavior, safety, output format, and includes an example. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the six parameters and present output schema, the description adequately covers the core logic, criteria, output fields, and safety. The output schema is described in detail, and the example provides concrete usage. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to parameters by explaining default thresholds (read/write ratio ≥10, ≥1000 reads, ≤1M rows) and the server's role in the output SQL stub. However, it does not describe the limit or max_rows parameters beyond defaults, and the schema coverage is low (17%).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: recommending tables for Redis caching. It specifies the resource (tables) and action (recommend), and outlines the criteria (read/write ratio, reads, row count). This distinguishes it from other recommendation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to identify caching candidates) and provides an example with a server parameter. It also notes that the advisor is read-only. However, it does not explicitly contrast with alternatives like describe_redis_cache_table or list_redis_foreign_servers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: dedicated connection pool, elevated timeout, primary database. Annotations already mark read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded purpose, efficient sentences covering all key aspects without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers behavior, connection isolation, timeout behavior, return shape (known from output schema), and distinguishes from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Describes timeout_ms clamping and work_mem usage. Example clarifies usage. Compensates for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it runs read-only analytical SELECT queries requiring longer time, distinguishing from standard queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer run_select for ordinary queries and use this only when more time is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds behavioral context by stating it returns 'in-process' metrics (snapshot at call time) and describes the series structure (counter with tool/status labels, histogram with sum/count). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three well-structured sentences. The first sentence states the core purpose, the second lists the series (adding detail), and the third provides usage guidance. Every sentence is informative and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, annotations indicating read-only, and an output schema, the description is complete: it explains what the tool returns and when to use it, covering all needed information for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and the description adds value by explaining the output structure, which is helpful since the input schema is empty and the output schema provides structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns Prometheus-format metrics for the MCPg server, listing specific series (counter and histogram) and their fields. It distinguishes itself from siblings by mentioning when it's useful (when HTTP /metrics endpoint is unreachable or via MCP protocol).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: when the HTTP /metrics endpoint is unreachable (e.g., over stdio) or to fetch via MCP protocol. While it doesn't mention when not to use, it provides clear context that makes the usage scenario obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description does not contradict annotations (readOnlyHint: true, openWorldHint: false). It clarifies the tool only generates and never executes Cypher (consistent with read-only), and explains the two modes (schema-level vs. concrete statements) and side-effect of reading data but not modifying.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured and front-loaded with purpose, but slightly lengthy. However, every sentence adds value, covering behavior, notes, and return object fields. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generating graph projections), the description is complete. It covers both modes, edge cases (no PK), execution order, materialization warning, and lists all return object fields. Output schema exists but description still adds context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains all parameters: schema, tables (optional), database (optional secondary), row_limit (0 for template, >0 for concrete rows), graph_name. It adds meaning beyond the schema (e.g., default values, effect of row_limit). Schema coverage is low but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates openCypher statements to project a relational schema into an Apache AGE property graph, with specific verb 'generate', resource 'graph projection', and distinguishes from siblings by noting it never executes (like generate_test_data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use (e.g., to project schemas, with row_limit behavior), and when not (tables without PK), plus notes on execution order and materialization. Also mentions alternatives implicitly by referencing generate_test_data behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details query validation, row cap behavior (truncated=true), PG version requirement, return structure, and example. This adds context beyond the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with a clear lead sentence, constraints, return format, and an illustrative example. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential aspects: purpose, constraints, return format, and an example. Given the output schema exists and the description already details the return object, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), but the description compensates by explaining max_rows constraints and provides an example showing query usage. However, it does not describe the database parameter beyond what schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it executes a PGQ SELECT with GRAPH_TABLE, distinguishing it from run_select for non-graph queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use this tool vs. alternatives: 'use run_select for non-graph reads', and specifies that only single SELECT with GRAPH_TABLE is accepted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/devopam/MCPg'
If you have feedback or need assistance with the MCP directory API, please join our Discord server