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

Lists checks performed and mentions outputs issues with severity levels, but does not disclose behavioral traits beyond that (e.g., whether it's safe to run frequently, required permissions, or if any side effects occur). With no annotations, description carries the burden, and fails to fully address safety or impact.

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

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

Single sentence with bullet-like listing of checks; no wasted words, front-loaded with purpose. Highly efficient.

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

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

For a comprehensive health check with no input parameters and no output schema, the description could elaborate on the output format or scope (e.g., which database/table scope). It lists checks but omits any detail on how results are structured, leaving the agent to infer. Adequate but incomplete.

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

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

No parameters exist, so schema coverage is trivially 100%. Description adds value by explaining what the tool does, meeting baseline for zero-parameter tools. No further param context needed.

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

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

Description clearly states 'Run comprehensive database health checks' and enumerates specific checks (cache hit rates, connection usage, index health, etc.), differentiating from sibling tools like analyze_query_indexes which focus on specific index analysis.

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

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

No guidance on when to use this tool versus alternative analysis tools (e.g., analyze_query_indexes, analyze_workload_indexes). Does not specify prerequisites or exclusion criteria.

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

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

No annotations are provided, so the description must fully disclose behavior. It states the tool 'recommends' indexes, suggesting it is read-only, but it does not confirm whether recommendations are only advisory or if any side effects occur. Missing details on required permissions, handling of invalid queries, or response structure.

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

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

The description is two sentences with no wasted words. The first sentence states the core purpose, and the second provides a usage instruction. It is front-loaded and concise.

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

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

Given one well-documented parameter and no output schema, the description is minimally complete. It explains what input to provide and what to expect (recommendations), but lacks information about output format, limitations, or when not to use. Adequate but not rich.

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

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

The single parameter 'queries' is fully described in the input schema as 'SQL SELECT queries to analyze (max 10)'. The description adds 'Provide up to 10 SELECT queries' which repeats the schema, adding no new semantic information. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool recommends indexes for specific SQL queries, using a specific verb ('Recommend') and resource ('indexes'). It distinguishes from siblings like 'analyze_workload_indexes' (workload-level) and 'explain_query' (execution plan), as it focuses on individual SELECT queries.

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

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

The description implies use when you have specific SELECT queries needing index recommendations, but it does not explicitly state when to use this tool versus alternatives like 'analyze_workload_indexes' or 'explain_query'. 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.

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

No annotations are provided, so the description carries full burden. It states 'recommend indexes' implying read-only, but does not explicitly confirm no mutation, required permissions, or potential side effects. The mechanism (pg_stat_statements) is disclosed, but safety profile is vague.

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

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

Two sentences, no redundant information. First sentence states core purpose, second adds technical mechanism. Efficient and front-loaded.

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

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

Given no output schema or annotations, the description adequately explains purpose and mechanism but lacks details on return format, error handling (e.g., missing hypopg), and behavioral traits like read-only nature. Sibling tools like analyze_query_indexes create ambiguity that could be clarified.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by explaining that includeHypothetical requires hypopg extension, which is not in the schema. This extra context helps correct usage.

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

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

The description uses specific verb 'Analyze' and 'recommend', clearly identifies the resource (database workload and indexes), and distinguishes from siblings like analyze_db_health and analyze_query_indexes by mentioning pg_stat_statements and slow queries.

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

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

The description implies usage for index recommendations but does not explicitly state when to use this tool vs alternatives like analyze_query_indexes. No exclusions or prerequisites are mentioned, 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.

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

No annotations are provided, so the description must disclose behavioral traits. It mentions parallel execution and one-time overrides, but does not discuss rate limits, resource impact, or error behavior beyond the stopOnError parameter. Adequate but not comprehensive.

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

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

The description is concise with three sentences, front-loading the key purpose. It avoids redundancy and is easy to parse. Could be slightly more structured but effective.

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

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

Given no output schema, the description explains that results are keyed by query name. It covers the main use case and overrides. Missing details about result format or pagination, but sufficient for a batching tool.

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

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

Schema description coverage is 100%, so parameters are well-documented structurally. The description adds context like 'keyed by query name' and 'max 20' which adds value, but does not significantly exceed what the schema already provides.

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

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

The description clearly states the tool executes multiple SQL queries in parallel and returns results keyed by query name. It distinguishes from siblings like execute_sql by emphasizing parallelism and batching.

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

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

The description explicitly says it is efficient for fetching multiple independent pieces of data in one call, and mentions optional server/database/schema overrides for one-time execution. This provides clear guidance on when to use it.

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

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

With no annotations, the description adds minimal behavioral context beyond the basic function. It does not disclose potential side effects like lock acquisition or transaction timeout, which could affect agent decision-making.

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

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

Two sentences that are front-loaded with the primary action and immediately useful. No unnecessary words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the essentials: action, return value, and related tools. A mention of the scope or implications of a transaction would improve completeness.

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

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

Schema coverage is 100% for the single optional parameter, and the description does not add further meaning 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.

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

The description clearly states 'Start a new database transaction' and specifies the return value and associated tools. It distinguishes itself from sibling transaction tools like commit_transaction and rollback_transaction.

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

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

The description indicates usage with execute_sql, commit_transaction, and rollback_transaction, and mentions atomic execution. However, it lacks explicit guidance on when not to use or alternatives beyond the transaction lifecycle.

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

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

With no annotations, the description carries full burden. It discloses use of TABLESAMPLE BERNOULLI for large tables, single-pass computation, and latency bounding. It does not cover permissions, locking, or sampling accuracy trade-offs, but the core behavior is transparent.

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

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

The description is a single paragraph of three sentences, concise and front-loaded with key functionality. It could be slightly more structured with bullet points, but it is efficient and free of fluff.

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

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

Given no output schema and 9 parameters, the description omits crucial details like return format, default column limit (30), and full parameter roles. While it explains the algorithm, it is not complete enough for an agent to use it without guessing return structure.

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

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

Schema coverage is only 22%, and the description adds limited parameter explanation. It mentions sample_threshold and sample_percent implicitly via sampling algorithm, but parameters like server, database, override_schema are undocumented. The description does not sufficiently compensate for the schema gaps.

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

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

The description clearly states the tool profiles columns in a table, listing specific statistics (null %, distinct count, top-K, etc.) and explains it replaces multiple exploratory queries, making the purpose unambiguous and distinct from tools like describe_table.

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

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

The description implies usage for understanding column shape efficiently, stating it replaces a dozen separate exploratory queries. However, it doesn't explicitly mention when not to use or compare to specific sibling tools, 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.

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

With no annotations, the description carries the full burden. It discloses the key behavior (committing makes changes permanent) but does not address failure cases (e.g., invalid transaction ID, already committed transaction) or side effects. This is adequate but minimal.

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

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

A single, well-structured sentence that explains both the action and result concisely. No wasteful words.

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

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

For a simple commit operation with one parameter and no output schema, the description is minimally complete. It covers the primary purpose but misses edge cases or error conditions, which would improve completeness.

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

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

The input schema has 100% coverage, with the only parameter (transactionId) described as 'The transaction ID returned by begin_transaction'. The description adds no additional meaning beyond this, 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.

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

The description clearly states the action ('Commit an active transaction') and the outcome ('making all changes permanent'). It pairs with siblings like begin_transaction and rollback_transaction, so the purpose is clear, though it does not explicitly differentiate from these siblings beyond the verb.

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

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

No guidance is provided on when to use this tool versus alternatives like rollback_transaction. There is no mention of prerequisites (e.g., requires an active transaction started by begin_transaction) or conditions for use.

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

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

No annotations provided, so the description carries full burden. It describes the rich read output and parameter behaviors (sample_size can skip, profile_columns default up to 20). It does not explicitly state it is read-only, but that is strongly implied by the listing nature. Slight room to mention non-destructiveness.

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

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

Two sentences, front-loaded with the core proposition ('replaces ~5 separate calls'). Every piece of information earns its place; no fluff.

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

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

Given 7 parameters and no output schema, the description covers the tool's purpose, output, and parameter behaviors well. It does not detail the return format, but the listing of returned fields provides adequate context for an agent. Minor gap: no mention of error handling or prerequisites.

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

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

Schema coverage is 57%, and the description adds meaning to key parameters: table is unqualified, schema is separate from override_schema, sample_size and profile_columns have defaults explained. Server and database lack schema descriptions, but the description does not compensate; still, overall adds value beyond schema.

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

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

Description clearly states it's a single call describing a table, enumerating all returned elements (columns, PKs, FKs, indexes, size, row count, sample rows). It also explicitly contrasts with alternatives, making the tool's unique value unmistakable.

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

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

Explicitly states that this tool replaces ~5 separate calls (get_object_details + LIMIT 5 + COUNT(*) + pg_stats), providing clear when-to-use guidance. No ambiguity about its purpose versus sibling tools.

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

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

The description indicates a read-only probe ('probe', 'returns'), but without annotations, it does not explicitly state that the tool has no side effects, requires no special permissions, or has any performance impact. The description is adequate but not fully transparent.

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

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

The description is concise, with two sentences conveying the core functionality and usage context. No redundant information is present, though it could be slightly more streamlined.

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

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

The description explains the return values (detected tools, schema/table, count, latest version) reasonably well, compensating for the lack of an output schema. Given the tool's complexity and no output schema, the description provides enough context for an AI 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.

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

Schema description coverage is only 25%, with only the 'schemas' parameter documented in the schema. The tool description adds value for 'schemas' (default: all non-system) but provides no additional meaning for 'server', 'database', and 'schema' parameters. With low coverage, the description should compensate more.

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

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

The description clearly states the tool probes for migration tool tracker tables and returns specific details (tools detected, schema/table, count, latest version). It also explicitly explains the AI agent use case, distinguishing it from sibling tools that analyze database health or indexes.

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

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

The description implies usage before suggesting changes, providing clear context for when to use. However, it lacks explicit exclusions or alternatives, such as when not to use it or what to use instead if migration state is not needed.

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

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

No annotations provided, so description carries full burden. It discloses transaction rollback, real result capture, and warnings about non-rollbackable operations. Does not mention behavior on connection loss or transaction abort, but covers key behavioral aspects.

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

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

Description is well-structured with front-loaded action and behavior. Slightly long but each sentence adds value; no redundancy.

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

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

No output schema, so description explains return values (row counts, errors with line numbers) and warns about non-rollbackable operations. Comprehensive for a dry-run testing tool.

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

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

Schema description coverage is 100%; description adds some context (e.g., example for stripPatterns, one-time execution for server/database/schema). Adds value beyond schema but not extensively.

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

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

The description clearly states it executes a SQL file in dry-run mode, runs statements within a transaction, captures real results, then rolls back. It distinguishes from siblings like execute_sql_file (which commits) and preview_sql_file (likely just shows statements).

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

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

Explicitly says 'Perfect for testing migrations before deploying' and mentions optional server/database/schema overrides. Does not explicitly state when not to use it, but context implies it's for testing; alternatives like execute_sql_file are implied but not named.

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

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

No annotations are provided, so the description carries the full burden. It discloses support for different SQL types, parameterization, multiple statements, transactions, and query budget controls. However, it does not describe return format (e.g., array of objects for SELECT, affected rows for DML), error behavior, or the 100KB limit for large scripts, which are important for agent decision-making.

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

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

The description is a single paragraph that is front-loaded with the core purpose and then expands on key details. It is concise but packed with information. Could benefit from bullet points or sectioning for clarity, but remains efficient.

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

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

Given 13 parameters and no output schema, the description covers most behavioral aspects: parameterization, multiple statements, transactions, overrides, query budgets. It lacks explanation of return types or error handling, and could mention restrictions like server/database not usable with transactionId. Fairly complete for a complex tool.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema: explains $1, $2 placeholders, incompatibility of params with allowMultipleStatements, default/max for maxRows, bypass for allowLargeScript, schema info via includeSchemaHint, SP-7 query budget for maxEstimatedRows/Cost, and one-time overrides for server/database/schema. This enriches the agent's understanding.

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

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

Description clearly states it executes SQL queries with support for SELECT, INSERT, UPDATE, DELETE, parameterized queries, multiple statements, transactions, and one-time overrides. It differentiates from sibling tools like analyze, explain, and file-based executors by focusing on raw SQL execution.

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

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

Provides guidance on using $1, $2 placeholders with params array to prevent SQL injection, allowMultipleStatements for multiple semicolon-separated statements, transactionId for transactional execution, and one-time server/database/schema overrides. Does not explicitly exclude alternatives but implicitly distinguishes from sibling tools.

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

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

No annotations provided, so description carries full burden. Discloses file size limit, transaction mode, validateOnly, stripPatterns, and server/database/schema overrides. Missing details on permissions or exact 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.

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

Concise multi-sentence description with front-loaded main action and succint additional details. No wasted words.

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

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

Given no output schema, description covers key aspects (size limit, transaction, preview, stripping, overrides). Lacks return value explanation but sufficient for most agents.

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

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

Schema coverage 100%, but description adds value with examples for stripPatterns ('/','GO') and clarifies validateOnly and server/database/schema usage. Baseline 3, bonus for extra context.

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

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

Clearly states 'Execute a .sql file from the filesystem' with specific use cases (migration scripts, schema changes, data imports). Distinguishes from siblings like dry_run_sql_file and preview_sql_file.

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

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

Describes when to use (migration scripts, etc.) and mentions one-time overrides. Lacks explicit contrast with execute_sql for inline SQL, but still clear.

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

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

Since no annotations are provided, the description carries the full burden. It discloses behavioral traits: analyze executes the query for real timings (SELECT only, blocked for writes), hypothetical indexes require the hypopg extension, and server/database/schema are one-time overrides. It does not explicitly state that the tool is read-only, but the description implies safety.

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

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

The description is concise: three sentences covering purpose, usage, and key parameters. Every sentence adds value without redundancy. It is well-structured and front-loaded with the main purpose.

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

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

Given 8 parameters, no output schema, and many sibling tools, the description covers the essential aspects: purpose, key parameters, and behavioral notes. It could mention that the output is the execution plan itself, but that is implied. Overall, it is sufficiently complete 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.

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

Schema coverage is 100% with descriptions for all parameters. The description adds significant meaning beyond the schema: it explains that analyze gives actual timings (SELECT only), buffers includes cache statistics, format outputs in various formats, hypothetical indexes need hypopg, and server/database/schema are for one-time execution. This enhances the agent's understanding.

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

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

The description clearly states the tool's purpose: 'Show PostgreSQL's execution plan for a query.' It specifies the action (show execution plan) and the resource (PostgreSQL query), and distinguishes its use case from sibling tools by mentioning performance analysis and missing indexes.

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

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

The description provides usage context: 'Use this to understand query performance and identify missing indexes.' It also gives specific guidance on the analyze parameter: 'analyze=true runs the query to get actual timings (SELECT only).' However, it does not explicitly contrast with sibling tools like analyze_query_indexes, which slightly reduces clarity.

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

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

Details file modes (append/overwrite with banner), header banner recording timestamp and server alias (host/port hidden), and foot-gun guard for confirm_overwrite. No annotations, so description carries burden; covers key 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.

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

Front-loaded with purpose, then organized by content kinds, modes, and usage note. Slightly lengthy but appropriate for complexity; no wasted sentences.

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

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

Given 8 parameters, no output schema, and no annotations, the description covers all content kinds, modes, header, and usage guidance. It is comprehensive and leaves no major gaps.

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

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

Schema coverage is 75%, but the description adds value by explaining the four 'what' kinds, mode behavior, and header banner. It clarifies complex union schema and enhances understanding.

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

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

The description clearly states it exports schema and/or data to a .sql file, then details four content kinds. It differentiates from siblings by mentioning use before transfer_objects.

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

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

Explicitly says 'Use this before transfer_objects or for migration script generation.' Provides context on modes and content kinds, but no exclusions or alternatives beyond that.

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

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

Describes the output fields (pid, user, database, etc.) and the join operation, but does not explicitly state that the tool is read-only or non-destructive. With no annotations, more explicit behavioral disclosure would be beneficial.

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

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

The description is concise (2-3 sentences), front-loaded with the main purpose, and avoids redundancy. Minor improvement could be adding structure for parameter explanations.

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

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

Despite no output schema and 0% parameter coverage, the description explains outputs well but completely ignores input parameters. This leaves significant gaps for the 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.

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

Schema description coverage is 0%, and the description provides no explanation of the 5 parameters (include_idle, limit, server, database, schema). The agent receives no guidance on how to use these inputs.

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

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

The description clearly states it shows blocking sessions in a tree format using pg_stat_activity and pg_blocking_pids, with a specific purpose of diagnosing slowdowns. It distinguishes itself from siblings like kill_query and lock_check.

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

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

Explicitly says 'Use to diagnose slowdowns and pick a candidate for kill_query,' providing clear context and a downstream action. However, it does not specify when not to use or compare to alternatives like lock_check.

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

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

With no annotations, the description carries full burden. It discloses recursive walking of pg_depend, classification of dependents, and depth reporting. Missing details like error handling or performance but covers core behavior well.

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

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

Concise four-sentence description with front-loaded purpose. No redundant text, though could be slightly more compact.

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

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

No output schema exists, so description should detail return format. It mentions depth but not other fields. For a complex tool with 7 params, it covers purpose well but leaves parameter and output details incomplete.

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

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

Schema coverage is only 29%, yet the description does not explain parameters like server, database, or override_schema. It adds no value beyond the schema for most parameters, leaving gaps.

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

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

The description clearly states the action (find), resource (dependents of a database object), and context (before dropping). It differentiates from sibling tools by specifying recursive dependency analysis via pg_depend.

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

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

Explicitly states 'Use this BEFORE running DROP CASCADE to understand the blast radius,' providing clear when-to-use guidance. However, no explicit alternatives are given for when not to use.

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

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

No annotations provided, so description carries full burden. It discloses many behaviors: respecting constraints, handling types, per-column overrides, and execution mode. Lacks details on permissions or error handling, but covers the main traits.

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

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

Single well-structured sentence with bullet-like enumeration. Front-loaded with purpose. No redundancy, though breaking into clearer sections could improve readability.

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

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

Given 9 parameters and no output schema, description covers inputs, core behaviors, and output mode. Missing details on return value when apply is false and error scenarios, but overall complete for most use cases.

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

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

Schema coverage is low (22%), and description adds meaning for key parameters (table, count, column_values, skip_fks, apply) but does not explain server, database, override_schema, or schema beyond their names. Partial compensation.

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

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

Description clearly states it generates schema-aware fake seed data for a table, listing many features that distinguish it from sibling tools (analyze, execute, etc.). The verb 'generate' and resource 'seed data' are specific.

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

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

Implies when to use (need seed data) and mentions apply vs SQL-only via `apply: false`. Does not explicitly state when not to use or compare to alternatives, but the shared 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.

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

With no annotations, the description fully carries the burden. It is transparent about the output (returned fields and access mode) and implies no side effects. Missing permission requirements but acceptable for a read-only status check.

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

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

Two sentences: first clearly states purpose and output, second provides usage guidance. No extraneous words; every sentence adds value.

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

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

Despite no output schema, the description lists all returned fields. The tool is simple enough that no additional context (e.g., error handling, permissions) is critical. Complete for its function.

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

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

The tool has no parameters and schema coverage is 100%, so the description needs to add nothing. Baseline of 4 is appropriate.

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

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

The description clearly states 'Get current connection status' and explicitly lists the returned fields (server name, database, schema, access mode). This uniquely identifies the tool among siblings like list_databases and list_servers.

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

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

The description advises 'Call this to verify your connection before running queries,' providing a clear use case. While it doesn't mention when not to use or alternatives, the simplicity of the tool makes this sufficient.

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

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

No annotations were provided, so the description carries full burden. It describes the operation as retrieving info but does not explicitly state it is read-only, non-destructive, or free of side effects. It lacks details on authorization or rate limits.

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

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

Two concise sentences: first states purpose and outputs, second adds optional usage. No redundancy, efficiently front-loaded.

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

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

Given no output schema, the description lists key return categories (columns, data types, constraints, indexes, size, row count) but does not specify the exact structure. This is largely sufficient for an agent to understand the tool's value.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the one-time override parameters ('Optionally use server/database/targetSchema params for one-time execution on a different server'), reinforcing the schema descriptions.

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

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

The description clearly states the action ('Get detailed info') and the resources ('table/view/sequence'), listing specific outputs (columns, data types, constraints, etc.). It distinguishes from siblings like 'describe_table' by implying a more comprehensive analysis.

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

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

The description explicitly advises 'Use this to understand table structure before writing queries,' providing clear context for when to use. It also mentions optional overrides for one-time execution but does not explicitly exclude alternatives like 'describe_table'.

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

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

No annotations are provided, so the description carries the full burden. It discloses a critical prerequisite ('Requires pg_stat_statements extension enabled'), which aids safe usage. However, it does not explicitly state whether the tool is read-only (though implied) or describe any side effects or output structure. This leaves some behavioral ambiguity.

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

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

The description is extremely concise (two sentences) and front-loaded: first sentence states the action, second adds a requirement and use case. Every word earns its place with no redundancy.

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

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

The tool has 3 parameters and no annotations or output schema. The description covers the prerequisite and high-level purpose but does not describe the return values (e.g., columns returned, pagination). For a diagnostic tool, this gap could affect an agent's ability to interpret results correctly.

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

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

Schema coverage is 100%, so the input schema adequately documents each parameter (limit, orderBy, minCalls). The description does not add additional parameter-level meaning beyond the schema (e.g., it doesn't explain what 'total_time' means). Baseline 3 is appropriate since the schema is self-sufficient.

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

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

The description clearly states the tool's function: 'Find slowest queries from pg_stat_statements.' It uses a specific verb ('find') and resource ('slowest queries'), and the context 'identify performance bottlenecks' distinguishes it from sibling tools like analyze_query_indexes or find_blocking_queries.

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

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

The description gives a clear usage context: 'Use this to identify performance bottlenecks.' However, it does not explicitly state when not to use this tool or suggest alternatives from the sibling list. The instruction is helpful but lacks exclusion guidance, which would improve decision-making.

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

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

No annotations are provided, so the description carries the full burden. It correctly indicates the operation is a read ('Get information'), but does not disclose potential failure cases (e.g., invalid or completed transaction ID) or any safe behavioral traits beyond the basic purpose.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, followed by specifics. Every word earns its place with no redundancy or fluff.

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

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

For a simple single-parameter tool with no output schema, the description adequately outlines the returned information. It is missing error-handling or edge-case context, but overall completeness is high given the low complexity.

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

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

The schema already describes the 'transactionId' parameter as 'The transaction ID returned by begin_transaction' (100% coverage). The tool description adds no additional meaning or context beyond that, so it meets the baseline without enhancement.

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

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

The description clearly states the tool's purpose with a specific verb ('Get information') and resource ('active transaction'), and lists the included fields (name, server, database, started). It effectively distinguishes from sibling tools like list_transactions (list) and transactional action tools.

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

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

The description implies usage when a transaction ID is available, but does not explicitly guide when to use this tool over alternatives like 'list_transactions' or other transaction-related tools. No exclusions or when-not-to-use guidance is provided.

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

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

No annotations provided, so description fully covers behavior: cancel interrupts statement, terminate kills backend, requires confirm, refused in readonly mode, returns snapshot before signaling. This is comprehensive for a kill operation.

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

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

Three sentences, front-loaded with purpose, then mode details, then conditions and return. No wasted words.

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

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

Without annotations or output schema, description covers core functionality and return value. Missing details on error handling or invalid PID, but adequate for a kill tool with clear required params.

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

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

Description adds meaning for pid, mode, and confirm beyond schema (e.g., soft/hard, foot-gun guard). However, it does not explain the optional server, database, and schema parameters, which are only in schema without descriptions. Given 50% schema coverage, description only partially compensates.

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

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

Description clearly states the tool cancels or terminates a backend session by PID, distinguishing between soft cancel and hard terminate. It uses specific verb+resource and is distinct from siblings like 'find_blocking_queries' or 'lock_check'.

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

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

Description explains when to use cancel vs terminate, and mentions the confirm requirement and readonly restriction. However, it does not explicitly state when not to use this tool or suggest alternatives.

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

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

No annotations provided, so description must carry behavioral info. It discloses the required parameter and workflow but omits details like read-only nature, default exclusions of system databases, or maxResults limit, which are only in 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.

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

Two concise sentences, front-loaded with purpose, no redundancy. Every word earns its place.

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

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

Appropriately complete for a simple list tool with well-described parameters in schema. Could mention default exclusions or output format, but not essential given schema coverage.

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

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

Schema covers 100% of parameters with descriptions, including the serverName requirement and exclusion of database names. The description repeats this without adding new semantic value beyond the schema.

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

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

The description clearly states the verb 'list' and resource 'databases', with specific context (PostgreSQL server). It distinguishes from sibling tools like list_servers by emphasizing the serverName requirement and directing users to list_servers first.

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

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

Explicitly instructs to obtain serverName from list_servers and warns against guessing, providing clear when-to-use and when-not-to-use guidance relative to siblings.

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

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

No annotations provided, so description carries full burden. Discloses need for active connection and one-time nature of override params, but lacks detail on error cases or output behavior.

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

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

Two sentences, no redundancy. First sentence states purpose, second adds usage guidance. Efficient and well-structured.

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

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

Covers main purpose, prerequisites, and optional overrides. Missing output format or return value description, which would be helpful given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description mostly restates parameter purposes (e.g., 'one-time execution'), adding minimal new meaning beyond schema descriptions.

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

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

Description clearly states it lists specific object types (tables, views, etc.) in a schema, with a clear verb and resource. It distinguishes from sibling list tools by focusing on schema-level objects.

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

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

Mentions prerequisite 'Requires active connection' and explains when to use optional overrides. Does not explicitly list alternatives but context makes differentiation clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool lists schemas, requires a connection, and allows temporary overrides. It does not mention security or performance, but for a read-only listing these are less critical. The inclusion of the includeSystemSchemas parameter downstream adds transparency.

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

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

Two sentences with front-loaded purpose and key usage conditions. No extraneous information. Every sentence contributes to understanding.

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

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

Given the schema covers params and there is no output schema, the description is fairly complete. It could mention the default filtering of system schemas or the return format, but the presence of the includeSystemSchemas param and the listing nature makes it adequate.

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

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

The input schema has 100% description coverage. The description adds value by explaining that server, database, and schema params are for one-time overrides without changing the main connection, which is not evident from schema descriptions alone.

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

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

The description clearly states the verb 'List' and the resource 'schemas in the current database'. It differentiates from sibling tools like list_databases and list_objects by specifying the target is schemas, and mentions the one-time override params that are 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.

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

The description explicitly states the prerequisite 'Requires active connection (use switch_server_db first)' and explains when to use the optional override params for one-time execution. It does not explicitly list alternatives or when not to use, but the context is clear and actionable.

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

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

While no annotations are provided, the description reveals that the tool returns server names and connection status, implying it checks connectivity. It does not explicitly state it is read-only, but 'List' implies 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.

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

Three concise sentences: purpose, usage guidance, output. No extraneous words, front-loaded with the most important information.

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

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

Given no output schema, the description mentions the return values (server names and connection status). It does not cover potential edge cases like empty lists, but it is adequate for this simple tool.

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

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

The description adds no information about the 'filter' parameter beyond what is already in the input schema (which has a comprehensive description). Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List all configured PostgreSQL servers.' It distinguishes from sibling tools like list_databases and switch_server_db by instructing to call this first to discover server names.

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

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

Explicit guidance is given: 'Call this FIRST to discover available server names before using list_databases or switch_server_db.' This tells the agent when and in what order to use the tool.

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

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

No annotations provided, so description bears full burden. It only states the basic operation and returned fields, without disclosing performance impact, permission requirements, or potential 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.

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

Single sentence that is front-loaded with the action and efficiently conveys the purpose and output. No extraneous words.

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

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

For a simple list tool with no parameters and no output schema, the description is adequate. It could mention potential ordering or filtering, but not essential. Missing annotations reduce completeness slightly.

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

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

No parameters exist, so schema coverage is 100%. Description adds no parameter info, but none is needed. Baseline 4 for zero-parameter tools.

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

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

The description clearly states the verb 'list' and the resource 'active transactions', and specifies the returned details (name, server, database, start time). It distinguishes from siblings like get_transaction_info, which likely targets a specific transaction.

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

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

No guidance on when to use this tool vs alternatives like get_transaction_info. No explicit context on appropriate scenarios or prerequisites.

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

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

No annotations exist, so description carries full burden. It describes outputs (warnings, recommendations) and scope of knowledge, but does not explicitly state it is read-only or handle edge cases. Adequate but not exhaustive.

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

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

The description is a single paragraph, front-loads the key action, and contains no fluff. Could be slightly more structured but is efficient.

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

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

For a complex lock analysis tool with no output schema and low parameter coverage, the description covers the main purpose and outputs but lacks specifics on return format, permissions, and limitations. Adequate for basic understanding.

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

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

Schema description coverage is low (40%). The description does not explain the server, database, or schema parameters, failing to compensate. Only sql and estimate_duration are described in schema, and description adds no further detail.

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

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

The description clearly states the tool performs static analysis of SQL statements to determine PostgreSQL lock level, table rewrite, duration, and provides warnings/recommendations. It differentiates from sibling tools which are about database health, query indexes, etc.

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

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

Explicitly advises 'Use BEFORE running DDL on production' and lists known SQL variants. While no explicit exclusions or alternatives are given, the usage context is clear.

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

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

Since no annotations are provided, the description fully bears the disclosure burden. It thoroughly explains the transactional behavior, rollback, result details, error info, and optional overrides, leaving no ambiguity.

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

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

The description is compact yet comprehensive, with no superfluous words. It front-loads the core function and efficiently conveys all necessary details.

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

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

Given the complexity (5 parameters, no output schema), the description covers behavior, error information, and optional overrides adequately. It hints at the output format (row counts, errors, before/after data) but lacks a structured return description, though acceptable.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the one-time execution nature of server/database/schema params and specifying the default and max for sampleSize, going beyond the schema.

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

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

Description clearly states the tool executes INSERT/UPDATE/DELETE in dry-run mode, runs SQL in a transaction, captures real results, and rolls back. It distinguishes itself from mutation_preview, 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.

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

Explicitly advises to use this tool to verify mutations before committing and notes it is more accurate than mutation_preview. However, it does not mention when not to use it or provide alternatives.

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

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

No annotations present, but the description clearly states the tool is non-executing, shows estimates and samples, and mentions parameter limits (sampleSize max 20). Does not detail error handling but adequate for a preview tool.

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

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

Three concise sentences that front-load purpose, then provide usage guidance and parameter hints. No fluff or repetition.

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

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

All five parameters are covered by schema and description. Output behavior (estimated rows and samples) is described. Lacks description of error cases, but tool complexity is low and no output schema is expected.

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

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

Schema description coverage is 100%, so baseline 3. The description adds minor reinforcement for optional overrides, but no significant extra meaning beyond the schema.

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

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

Clearly states 'preview the effect of INSERT/UPDATE/DELETE without executing' with specific verb and resource, and distinguishes from siblings like execute_sql which actually run queries.

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

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

Explicitly advises using this 'before running destructive queries to verify the impact', and describes optional server/database/schema overrides. Lacks explicit 'when not to use' but context implies distinction from actual execution.

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

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

With no annotations, the description carries the transparency burden. It clearly states it does NOT execute the SQL, and describes the output (statement count, types, warnings). It doesn't mention file access or error handling, but the core behavior is transparent.

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

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

Three concise sentences: what it does, comparison, and usage recommendation. No wasted words, information front-loaded.

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

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

Given no output schema and no annotations, the description gives a solid overview. It explains what the tool does, what output to expect, and when to use it. Could mention return format or error scenarios, but sufficient for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add much beyond the schema; it briefly mentions 'warnings for dangerous operations' but that's more about output than parameters. The schema descriptions are clear enough.

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

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

The description clearly states 'Preview a SQL file without executing it' and lists what it shows (statement count, types breakdown, warnings). It also distinguishes from sibling mutation_preview by specifying 'for SQL files'.

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

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

Explicitly says 'Use this before execute_sql_file to understand what a migration will do.' Also provides context by comparing to mutation_preview, helping the agent decide when to use this tool instead of others.

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

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

With no annotations provided, the description bears full burden. It discloses the core behavioral trait of undoing all changes, which is sufficient for a simple rollback. Could mention that the transaction is closed afterward, but overall transparent.

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

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

The description is a single, front-loaded sentence that concisely conveys the purpose and effect. Every word is earned; no fluff.

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

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

Given low complexity (one simple parameter, no output schema, no nested objects), the description adequately covers what the tool does and the parameter meaning. Sibling tools provide context for differentiation.

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

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

Schema description coverage is 100% for the sole parameter 'transactionId', with a clear schema description. The tool description adds no further meaning, meeting the baseline of 3.

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

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

The description clearly states the verb 'rollback', the resource 'active transaction', and the effect 'undoing all changes'. It distinguishes from sibling tools like 'commit_transaction' and 'begin_transaction'.

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

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

The description implies usage for undoing changes within a transaction, but provides no explicit guidance on when to use this versus alternatives like 'commit_transaction' or 'rollback_transaction' itself. No when-not-to-use or context is given.

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

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

Since no annotations are provided, the description carries full burden. It discloses that the output contains scriptSql, lock levels, and notes, and mentions transaction constraints. It lacks details on error handling or validation, but covers key behaviors.

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

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

The description is two sentences plus a brief instruction, front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

Given high complexity and no output schema, the description adequately explains the recipe output (SQL, lock level, notes) and usage workflow. It could be more detailed on return structure, but is sufficient for most use cases.

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

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

Schema coverage is 0%, so description compensates by explaining the 'intent' parameter's kinds (e.g., 'add NOT NULL column with default'). This adds meaning beyond the bare schema structure, though it does not detail each sub-field.

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

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

The description clearly states the tool converts a high-level intent into a multi-step zero-downtime DDL recipe. It lists specific intent types (e.g., 'add NOT NULL column with default') and explains the output format (SQL, lock level, notes), distinguishing it from siblings like execute_sql.

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

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

The description provides explicit workflow: use the recipe output with dry_run_sql_file then executeSqlFile. It warns about CONCURRENTLY operations outside transactions. However, it does not explicitly state when to use this versus direct ALTER TABLE or other mutation tools.

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

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

The description discloses behavioral traits: it uses CREATE OR REPLACE for views/functions/procedures and DROP+CREATE for others. It also specifies the migration script direction (apply to target to converge with source). However, it lacks information on performance constraints or large schema handling.

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

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

The description is concise (under 80 words), front-loads the main action, and efficiently conveys key details about output and behavioral rules without redundancy.

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

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

The description explains the output types (CREATE, DROP, MODIFY, migrationSql) and the migration strategy. However, it does not provide details on the exact output structure (e.g., whether migrationSql is a string or array) or pagination. Given the complexity and lack of output schema, it is fairly complete but has minor gaps.

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

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

The input schema parameters are self-explanatory (source and target objects with server, database, schema). The description adds no further detail about each parameter, and schema coverage is 0%. It merely references the endpoints without elaborating on required fields or defaults.

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

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

The description clearly states the tool computes the DDL delta between two endpoints, specifying the output (CREATE, DROP, MODIFY, migrationSql). It distinguishes from siblings like detect_migration_state by focusing on delta generation.

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

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

The description implies usage for schema migration planning but does not explicitly state when to use it over alternatives such as detect_migration_state or dry_run_sql_file. The phrase 'Source is the source of truth' provides some context but no exclusions.

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

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

No annotations are present, so the description must convey behavioral traits. It mentions connection and prerequisite calls but lacks details on side effects (e.g., connection persistence, error handling, or state changes).

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

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

Two concise sentences, front-loaded with the primary action, and no extraneous information. Every word earns its place.

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

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

For a simple connection tool with three parameters and no output schema, the description adequately covers purpose, prerequisites, and defaults. It lacks details on return values or connection lifecycle, but these are minor gaps.

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

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

Schema description coverage is 100% and already includes explanatory descriptions. The main description adds minor reinforcement (e.g., using list_servers) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Connect to a PostgreSQL server and database.' It distinguishes from siblings as a prerequisite for queries and references specific discovery tools (list_servers, list_databases).

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

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

Explicitly states 'MUST be called before executing queries' and directs the user to list_servers and list_databases for parameter values, providing clear when-to-use guidance.

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

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

With no annotations, the description fully discloses behavior: modes, if_exists handling, dry_run SQL generation, FK constraint ordering, and security/readonly checks, leaving no ambiguity.

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

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

The description is slightly verbose but well-structured with front-loaded main purpose and detailed specifics; every sentence adds value, though some redundancy exists (e.g., 'both endpoints must be configured servers' repeated).

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

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

Given complexity (8 params, no output schema), the description covers all key aspects: modes, conflict resolution, dry run, security, readonly enforcement, and FK handling, making it self-contained and complete.

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

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

Schema coverage is 75%; the description explains the purpose of 'include', 'if_exists', 'dry_run', and 'output_file' beyond the schema, clarifying their interaction and constraints.

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

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

The description clearly states the tool transfers DDL and/or data between servers/databases, specifying modes ('ddl', 'data', 'both'), which distinguishes it from sibling tools like 'export_to_sql_file' or 'execute_sql'.

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

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

Provides conditions: endpoints must be configured servers, refuses if target is readonly, and mentions security (no ad-hoc connection strings). However, it lacks explicit comparison to alternatives or 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.