ThinAir Data

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

The description reveals behavioral traits beyond the annotations: the tool generates a one-time link, does not transmit the connection string via chat, and returns dialect-specific instructions. The mssql caveat about Entra authentication and the prohibition on constructing mssql:// URLs are non-obvious behaviors. This goes well beyond the basic readOnly/destructive hints.

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

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

The description is four sentences and covers purpose, input caveat, response handling, and an important dialect-specific warning. It is front-loaded with the core purpose and avoids any redundant or filler content. Every sentence contributes necessary information, though the mssql section is somewhat lengthy.

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

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

Given the tool's complexity (two-step registration, dialect-specific auth, output fields to surface), the description is thorough. It explains the workflow, the security property, the response fields, and the mssql edge case. The presence of an output schema and clear annotations further fills in any remaining details, making the description complete enough 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?

The schema already documents both parameters thoroughly (name with example, dialect as enum with description), giving 100% coverage. The description adds some parameter-specific behavior for mssql (Azure SQL uses Entra, so the connection string excludes credentials), which is extra semantic context beyond the schema. However, most of the description focuses on the response and workflow rather than defining parameters.

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

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

The description clearly states the tool's function: obtaining a secure one-time link to register a new database connection, and lists supported dialects (postgres, mysql, mssql). It also explicitly distinguishes from siblings by clarifying that it does not accept a connection string, making its scope 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?

The description provides strong usage guidance: it explains the two-step flow (get link, then paste connection string in a web form), warns that the connection string is never sent through chat, and instructs the agent to surface specific response fields verbatim. It also includes a critical warning for mssql to avoid constructing an mssql:// URL. While it doesn't explicitly name alternative tools, the guidance is sufficient for an agent to know when to use this tool.

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

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

Annotations declare read-only and idempotent; description adds the 'quick' performance characteristic and optional column drill-down, going beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the core purpose, and each sentence serves a distinct role (what it does, when to use alternative).

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

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

Given the output schema and annotations, the description sufficiently covers usage context, distinguishes the tool from siblings, and omits unnecessary repetition of return values.

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 all three parameters with detailed descriptions, so the description adds little new semantic value; 'optionally drill into a specific column' rephrases the schema's column parameter.

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 a quick statistical snapshot for one table, enumerates specific outputs (row count, null rates, cardinality, numeric min/max/avg, date ranges) and explicitly contrasts with data_profile.

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 to use for fast at-a-glance reads and to use data_profile for full quality reports with PII detection and health score, naming the alternative.

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

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

Beyond the destructiveHint annotation, the description discloses that set_tables replaces the allowlist, remove_allowlist disables it, and masking is 'a heuristic policy aid (not a compliance guarantee) and one-way per execution.' It also explains enforcement at the AST level across subqueries/CTEs/JOINs, adding meaningful behavioral context that annotations do not provide.

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

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

The description is dense but well-structured, front-loading the tool's core purpose ('Manage HARD SQL guardrails') and then enumerating actions with concise clarifications. It includes important caveats like the enterprise tier and heuristic limitation. While slightly long, every sentence adds value and there is no redundant fluff.

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

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

Given the tool's complexity (5 parameters, 4 actions, destructive operations, enterprise tier), the description covers all key aspects: what each action does, how to lock down tables, PII masking defaults, the heuristic/non-compliance warning, and the enterprise requirement. An output schema exists, so return values need not be described. The description is sufficient for correct tool selection and invocation.

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 provides 100% coverage of parameter descriptions, including 'Empty array = lock down' and the default behavior for mask_patterns. The description adds some extra context (e.g., 'across subqueries/CTEs/JOINs') but does not significantly redefine or clarify parameters beyond the schema. Baseline 3 is appropriate given the rich 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 defines the tool's purpose: managing SQL guardrails (table allowlist and PII masking). It specifies the concrete actions (view, set_tables, remove_allowlist, set_pii_policy) and distinguishes it from sibling tools like query_firewall and pii_scan by focusing on the allowlist/PII configuration for an enterprise connection.

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

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

The description provides clear context for when to use each action (e.g., 'set_tables replaces the allowlist (use [] to lock down everything)'), and notes both policies 'opt-out by default.' It does not explicitly name alternative sibling tools, but the action-by-action guidance is sufficient for an agent to know when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, but the description adds significant behavioral context: parallel execution, per-connection rows + errors, dialect-specific failure modes, the 4-connection cap, and the requirement to resolve names beforehand. This goes well beyond what annotations convey and gives the agent a realistic behavioral model.

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 dense and front-loaded with the critical dialect warning, then the core behavior, use cases, and constraints. Every sentence serves a purpose, though the emoji and repeated canonical examples could be trimmed. It remains well-structured and efficient for its complexity.

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

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

For a tool that executes SQL across multiple heterogeneous connections, the description covers the key operational aspects: dialect compatibility, connection naming/resolution, parallel execution, per-connection error reporting, and usage limits. The presence of an output schema means return values need no further explanation. This is highly complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the schema's parameter explanations (2-4 connections, dialect-valid SQL, use list_connections). It adds the ARCHITECT-tier cap and a URL, but these are not new parameter semantics beyond what the schema already states. Thus no meaningful extra value is contributed.

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

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

The description states precisely: 'Run the same query across 2-4 connections in parallel; returns per-connection rows + errors for diffing.' This clearly identifies the verb (run), resource (connections), and output, and distinguishes it from single-connection tools like query_sql by emphasizing parallel cross-connection 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?

It explicitly lists canonical use cases (regional compare, cross-dialect sync check, 3-env drift, 4-region compare), warns about dialect incompatibilities (MSSQL TOP vs LIMIT), and instructs to resolve connection names via list_connections first. It thus provides clear when-to-use and prerequisite guidance, even if it doesn't name a specific alternative 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?

Beyond annotations (readOnly/openWorld/idempotent), the description discloses performance characteristics ('Slower than `analyze_table`'), output composition ('full data quality + compliance report'), and specific detection modes ('type-gated PII detection'). No contradiction with annotations.

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

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

Three sentences: one for content, one for trade-off, one for usage triggers. No filler and each sentence carries distinct value. The [BUILD tier] tag is extra but informative.

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

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

Given the output schema, comprehensive annotations, and clear sibling context, the description covers purpose, usage, performance, and alternatives. It provides enough information for an agent to decide when to invoke the tool and 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 covers 100% of parameters with descriptions, including detailed guidance for `connection`. The description focuses on the tool's purpose and does not add parameter-specific semantics, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('returns'), names the resource (a table), and enumerates the components (per-column stats, health score, PII detection, insight warnings). It distinguishes itself from sibling `analyze_table` by noting it is slower but more complete.

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 when to use: 'Use this when the user says "profile" or "quality report" or mentions PII/compliance.' It also names an alternative (`analyze_table`) and contrasts them, giving clear conditions for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, establishing the safety profile. The description adds worthwhile behavioral context by disclosing the 1-hour cache and the refresh mechanism, which are not captured in annotations. No contradictions found.

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, both dense with value. The first sentence states the core purpose; the second delivers caching and refresh guidance. No filler or redundancy.

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

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

Given the tool has an output schema, it need not describe return values. The description covers what the tool returns (schema components), its caching behavior, and when to refresh. The connection parameter is fully specified in the schema, so the combined picture is complete for a read-only introspection 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 input schema provides detailed descriptions for both parameters (refresh and connection), giving 100% coverage. The tool description only reinforces the refresh parameter in prose without adding new meaning. Per the rubric, baseline 3 is appropriate when schema description coverage is high and the description does not compensate further.

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 a specific verb ('Discover') and resource ('full database schema') and enumerates concrete components (tables, columns, types, primary keys, foreign keys, indexes), which clearly distinguishes it from sibling tools like query_sql or analyze_table. The purpose is immediately understandable and unambiguous.

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

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

The description provides a clear usage context: results are cached for 1 hour, and callers should set refresh=true after schema changes. This implies when to use the tool (schema discovery) and gives a practical condition for refreshing, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description adds critical behavioral details: tables >100k rows are sampled at ~5%, results may carry 'sampled:true', and the exact sampling mechanism varies by SQL dialect. This goes well beyond what annotations convey and helps the agent set user expectations correctly.

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 and well-structured: it opens with purpose and anomaly types, mentions severity-ranked alerts, then explains sampling and dialect behavior. Every sentence carries useful information 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?

Given an output schema exists and parameter descriptions are comprehensive, the description completes the picture by covering sampling caveats, dialect-specific behavior, and how to present sampled results. It is sufficiently complete for correct invocation and result interpretation.

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 already provides full descriptions for all three parameters, including rich guidance for the 'connection' parameter. The description adds no additional parameter-level meaning beyond what the schema covers, so the baseline score of 3 applies.

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

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

The description clearly states the tool scans a table for unusual patterns and enumerates specific anomaly types (volume drops/spikes, data gaps, value concentration, high null rates, stale data). This specific verb+resource combination differentiates it from generic analysis tools like data_profile or analyze_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 gives strong usage context by describing the sampling behavior for large tables and how to report sampled results, plus dialect-specific SQL methods. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds specific behavioral detail by revealing that it runs EXPLAIN ANALYZE or EXPLAIN FORMAT=JSON depending on dialect, which explains how the analysis is performed without contradicting annotations.

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

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

The description is two sentences with no wasted words, leading with the primary purpose and then adding implementation details. It is tightly structured and easy to parse.

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

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

Given the simple two-parameter tool, an output schema, and annotations covering safety, the description provides sufficient operational context including the dialect-specific EXPLAIN behavior. The [BUILD tier] marker adds minor context but doesn't hinder 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?

Input schema documents both parameters with full descriptions, including detailed guidance for resolving the connection parameter from list_connections output. The tool description itself does not elaborate on parameters, but schema coverage is 100%, so the baseline 3 applies.

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

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

The description clearly identifies the tool's function: analyzing SQL execution plans and producing plain-English performance recommendations. The verb 'analyze' and resource 'SQL query's execution plan' distinguish it from sibling tools like optimize_query (which likely modifies queries) and query_sql (which executes 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 query performance diagnosis and mentions dialect-specific behavior (EXPLAIN ANALYZE for Postgres, EXPLAIN FORMAT=JSON for MySQL), but does not explicitly state when to choose this over alternatives like optimize_query. It provides clear context but no exclusions or alternative references.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds behavioral context by explaining the detection method: 'Fingerprints queries and flags repeated patterns.' It also discloses the tier restriction '[ARCHITECT tier]', which is useful context beyond the annotations.

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

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

The description is extremely concise: two sentences with no filler. The first sentence states the purpose and scope ('recent query history'), the second adds the method and tier. Every word is informative.

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

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

Given the presence of a rich output schema and detailed parameter descriptions in the schema, the description sufficiently covers the tool's core behavior. It does not specify a time window for 'recent', but that is a minor gap. Overall, the information is complete enough for correct invocation.

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

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

Schema description coverage is 100%, with both parameters (connection and min_executions) thoroughly documented in the schema, including how to resolve connection names and the default execution threshold. The description does not add extra parameter meaning, so the 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 it 'Detect[s] N+1 query patterns from recent query history', using a specific verb+resource. This distinguishes it from sibling tools like detect_anomalies (general anomalies), explain_query (explaining single queries), and optimize_query (general optimization).

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 N+1 detection from query history, but does not explicitly state when to choose this tool over alternatives or when not to use it. It lacks exclusions or alternative tool references, making the guidance only implied rather than explicit.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description explicitly states 'Never executes' and details dialect-specific behaviors (pg `USING`, mssql `sp_rename`, mysql `MODIFY COLUMN`). It also advises checking the response `dialect` field before manual edits, adding valuable post-invocation guidance that annotations do not convey.

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

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

The description is dense but every clause contributes: purpose, dialect coverage, safety note, and a concrete warning against hand-translation. The enumeration of dialect specifics is slightly long but useful, making it efficient for a tool with this complexity.

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

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

Combined with a rich input schema, output schema, and safety annotations, the description covers the core purpose, dialect behavior, non-execution safety, and post-invocation guidance. There are no obvious gaps that would prevent an agent from using 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 100%: both `intent` and `connection` have descriptive text, with connection even explaining how to resolve names via `list_connections`. The tool description adds high-level dialect context but does not add parameter-specific meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with 'Generate dialect-correct ALTER TABLE migration SQL + rollback from a plain-English intent', which clearly identifies the verb (generate), resource (migration SQL + rollback), and input (plain-English intent). No sibling tool focuses on generating migrations, so it is well-distinguished.

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 practical context: it never executes, so an agent knows to treat it as a code-generation step. It warns about dialect mismatches and checking the `dialect` field, which guides safe usage. While it does not name explicit alternatives, the sibling list contains no other migration-generation tool, so this is adequate.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds that the tool 'Never executes', which clarifies it only generates statements without running them. It also mentions it 'Respects types, constraints, and FK relationships', adding behavioral detail not implied by annotations. Significant added context.

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

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

The description is very concise, using only two sentences plus a tier tag, with no wasted words. It front-loads the core purpose ('Generate realistic, schema-aware INSERT statements'), then adds key behavioral constraints. Every clause adds value.

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

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

Given that an output schema exists and annotations provide safety hints, the description is complete enough. It explains the tool's role in development/testing, its non-executing nature, and schema awareness. It doesn't need to explain return values because the output schema exists. Minor gaps exist around parameter selection, but these are covered by the detailed schema descriptions.

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 every parameter has a detailed description, including a comprehensive explanation for the 'connection' parameter. The tool description adds no parameter-specific information, so it doesn't exceed the baseline of 3. It fully relies on the schema, which is 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 generates INSERT statements, with a specific verb ('Generate') and resource ('schema-aware INSERT statements'). It distinguishes itself from sibling query tools by adding 'Never executes' and by focusing on development/testing. This is a specific and unambiguous purpose.

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

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

The description gives clear context for when to use the tool ('for development and testing') and emphasizes safety ('Never executes'). However, it does not explicitly name alternative tools or state when not to use it. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare read-only and idempotent behavior. The description adds the ARCHITECT tier access restriction and clarifies that the analysis is for a proposed change, not an applied one. No contradiction with annotations.

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

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

The description is a single sentence with a front-loaded verb and a concise list of outputs. The tier marker is extra but valuable. Every word earns its place, with zero 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 a full parameter schema, an output schema, and annotations covering safety, the description completes the picture by stating the analysis scope and access tier. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions, including guidance on resolving the 'connection' parameter via list_connections. The tool description does not add parameter semantics, but it is not needed because the schema fully handles it. Baseline 3 applies.

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

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

The description uses a specific verb ('Analyze') and resource ('blast radius of a proposed schema change'), and enumerates concrete outputs (FK dependencies, affected views, row count, risk score). This clearly distinguishes it from siblings like describe_schema, analyze_table, and generate_migration.

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 phrase 'proposed schema change' clearly implies use during planning before a change is applied. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to guide an agent.

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

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

Beyond the annotations, the description explains the key rotation effect: previous keys keep working for one hour then stop, the response reports retiring keys and retirement time, the new key is tied to the existing plan tier, and issuance is rate-limited to 5 per tenant per day. This fully discloses the behavioral consequences without contradicting the annotations.

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

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

Three sentences carry the full behavioral contract: what happens, when to use it, and the rate limit. The most important detail is front-loaded and there is no filler or repetition.

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

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

For a zero-parameter tool with an output schema, the description covers everything an agent needs: the action, rotation impact, response fields, tenant scope, plan-tier linkage, and rate limiting. Nothing important is missing.

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

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

The tool has zero parameters and schema coverage is vacuously 100%, so the baseline for parameter semantics is 4. The description adds no parameter documentation because none is needed. It instead focuses on relevant operational context, which is appropriate here.

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

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

The description opens with a specific verb and resource: 'Issue a fresh ta_data_* API key'. It clearly states the operation is for the current tenant and includes rotation semantics, so an agent knows exactly what the tool does and how it differs from ordinary key creation.

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 explicit use cases: 'Use it to rotate, or when an integration needs a key and can't reach the console.' This makes the intended context clear. It does not explicitly state when not to use it, but the rate limit and rotation behavior provide enough boundary for 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?

The annotations already indicate readOnlyHint and idempotentHint. The description adds valuable disclosure: duplicate name handling (only the first-added is reachable by name) and a security guarantee (no DSN or credentials returned). This goes beyond the annotations and helps the agent understand the tool's behavior and safety profile.

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

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

Three short sentences, front-loaded with the action and resource, then two specific behavioral notes. No fluff, every sentence 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?

The description covers the tool's purpose, output fields, duplicate behavior, and security bounds. With an output schema also present, the agent has everything needed to use it 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?

The tool has zero parameters, so the schema is empty. The description doesn't need to explain parameters, and the baseline for 0 params is 4. It adds value by describing the output fields, which is relevant.

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 the specific verb 'List' with the resource 'database connection' and specifies the scope 'for your tenant' and the exact fields returned (name, id, dbType, createdAt). This clearly distinguishes it from sibling tools like add_connection or test_connection.

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?

While the description doesn't name alternatives, it clearly implies the use case of inspecting registered connections. It provides context (every connection, no filtering) but doesn't explicitly exclude edge cases or mention when another tool would be more appropriate. Given the tool's simplicity, this is adequate but not fully explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by detailing the types of optimizations it performs (sequential scans, missing indexes, etc.) and that it suggests index DDL. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by supporting details. Every sentence earns its place with no redundancy or fluff. It efficiently conveys main function, typical findings, and output.

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

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

Given the tool's moderate complexity (two params, output schema, read-only), the description covers the core behavior, what it identifies, and output. The output schema likely documents return values, so no need to repeat. Minor gaps include not explicitly stating that it does not execute the query, but the word 'Suggest' implies this. It lacks explicit mentions of permissions or limitations, but annotations cover safety.

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

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

Schema description coverage is 100%, with both parameters fully described: 'query' as 'SQL query to optimize' and 'connection' with detailed guidance on resolving names. The tool description itself adds no extra parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Suggest a rewritten, optimized version of a SQL query with explanations.' It specifies the verb (suggest), resource (SQL query), and adds specific details about what it identifies (sequential scans, missing indexes, sort spills, join inefficiencies) and what it provides (index DDL). This distinguishes it from siblings like explain_query and query_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 implies usage for optimizing SQL queries but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The mention of identifying specific query issues suggests a use case, but it fails to state exclusions or direct users to other tools like explain_query for execution plans.

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

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context by explicitly stating 'Heuristic-only — not a compliance guarantee', which qualifies the reliability of results. This goes beyond the annotations and helps set expectations.

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 concise sentences, front-loaded with the action and purpose. Every clause is informative, including the heuristic caveat. The '[BUILD tier]' tag is minor but not distracting.

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

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

With rich annotations, full parameter documentation, and an output schema, the description is sufficient for the agent to understand the tool's purpose and limitations. It could benefit from mentioning sampling behavior, but that is already captured in parameter descriptions (max_tables, sample_rows).

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 all three parameters are well-documented in the schema. The description does not add parameter-specific meaning, but the baseline of 3 is appropriate given the schema handles the heavy lifting.

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 identifies the tool's function with a specific verb ('sweep') and resource ('string columns across tables'), and enumerates common PII patterns (email, SSN, credit card, phone, JWT, bearer tokens). This distinguishes it from sibling tools like analyze_table or data_profile, which are more general.

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

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

The description implies the tool is for scanning PII patterns across tables, but does not explicitly state when to use it over alternatives or mention any exclusions. The heuristic-only caveat gives some context, but there is no clear 'use this when...' guidance or reference to sibling tools.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. However, the description does not clarify which actions are read-only (list_rules, test_query) versus destructive (add_rule, remove_rule), nor the side effects of modifications. This is a significant gap for a tool with mixed safety profiles across actions.

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 one sentence with a clear structure, front-loaded with the verb and resource, and includes a tier tag. It is concise and free of 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?

The description is too high-level for a tool with four actions; it does not enumerate them or mention that connection resolution is required. The rich schema covers parameter details, but the description omits the action taxonomy, making it slightly incomplete for a new agent to understand the full scope of the tool.

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

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

Schema coverage is 100%, with every parameter including a description, so the baseline is 3. The description adds no parameter-specific information; the schema carries the full burden, which it handles well (e.g., connection resolution guidance).

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 manages per-connection SQL rules, with concrete examples (block dangerous patterns, require WHERE, log PII). This distinguishes it from query execution tools like query_sql and explain_query, and the resource is 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?

The description implies usage for enforcing SQL security policies via the examples, but it provides no explicit comparison to alternatives or exclusions. It does not say when to use this instead of query_sql, pii_scan, or other related tools.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds beyond-annotation context by specifying the response contents (timing, row counts, status) and the '[BUILD tier]' qualifier, which may signal environment availability. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that directly states the tool's function without any waste. It is concise and structurally ideal.

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 read-only history query, the description is complete: it states the returned data fields, and the schema covers all parameters. An output schema exists, so return-value details are not required from the description. The overall information is sufficient for correct tool usage.

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

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

Schema description coverage is 100%, with both 'limit' and 'connection' thoroughly documented, including detailed guidance on resolving connection names. The tool description itself adds no parameter semantics beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states a specific verb ('Return') and resource ('recent queries executed through ThinAir') with detail on the returned data (timing, row counts, status). It distinguishes itself from siblings like query_sql (execution) and saved_queries (saved queries) by focusing on historical execution records.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contrast with sibling tools such as saved_queries or cross_db_query. The only hint is the tool name, which is insufficient for usage 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?

Beyond the readOnlyHint annotation, the description discloses allowed statement types, dialect-specific syntax requirements, a default row limit of 100, and that response meta includes connection and dialect for follow-up calls. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is four sentences, each densely packed with operational detail and no redundancy. It front-loads the core action first and every sentence contributes essential guidance.

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

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

Given the tool's moderate complexity, the description covers all necessary operational aspects: permissible SQL, dialect handling, connection lookup, default limits, and response meta. The existence of an output schema means return values need no further explanation.

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?

Even though the schema covers all parameters, the description adds meaningful guidance: how to resolve the connection parameter semantically using list_connections output, the default limit behavior, and the permitted SQL forms. This goes well beyond the schema's field 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 'Execute a read-only SQL query against the target connection' with a specific verb and resource, and further specifies allowed statement types (SELECT / WITH / EXPLAIN), making its scope unambiguous and distinguishing it from write-oriented or analysis tools.

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

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

The description provides extensive usage context: dialect-specific syntax for Postgres, T-SQL, MySQL; connection resolution via list_connections; and default limit behavior. However, it does not explicitly mention alternative tools or enumerate when not to use this tool beyond the read-only restriction, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Check' is consistent. The description goes beyond the schema by specifying the returned information: API usage, daily limit, plan name, and upgrade options. It does not mention whether the check itself affects quota or requires authentication, but the read-only nature and output schema mitigate this.

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: 'Check current API usage, daily limit, plan name, and upgrade options.' Every word adds value, and there is no redundancy or filler.

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

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

For a zero-parameter read-only tool with an output schema, the description fully covers the purpose and expected results. It clearly enumerates the returned quota details, making the tool self-explanatory within its context.

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

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

The tool has zero parameters, and schema coverage is 100% (vacuously). Per guidelines, a zero-parameter tool gets a baseline of 4. The description correctly adds no parameter information because there is nothing to add.

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 the specific verb 'Check' and identifies exact resources: API usage, daily limit, plan name, and upgrade options. This clearly distinguishes the tool from the data-analysis and connection-management siblings.

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

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

The description implies the tool is for monitoring current quota status. Although it does not explicitly mention alternatives, no sibling tool appears to cover quota, so the usage context is clear. It lacks an explicit 'when not to use' statement, but that is not critical for a zero-parameter status tool.

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

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

Annotations already declare destructiveHint=true, but description goes further by clarifying 'deletes ONLY ThinAir's saved connection record... your actual database is never touched'. This is critical behavioral context beyond the annotation, disclosing exactly what gets destroyed.

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, each earns its place: action, non-destructive scope, and usage tip. Front-loaded with the primary purpose, no redundant phrasing.

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 single-parameter destructive tool with output schema and annotations, the description is complete. It covers what is removed, what is untouched, and how to ensure correct input, making it safe for an agent to invoke without ambiguity.

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% with parameter description 'Exact name of the connection to remove, as shown by list_connections'. Tool description repeats 'by name' and advises calling list_connections, but adds little beyond schema. Baseline 3 applies.

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

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

Clearly states 'Remove a stored database connection from ThinAir Data by name' – specific verb, resource, and scope. Distinguishes from siblings like add_connection and list_connections by focusing on removal of saved record only.

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 explicit guidance to 'Call list_connections first if you're unsure of the exact name', which is a direct when-to-use alternative. The context implies removal is for stored connections, and no exclusions 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description confirms the delete action. However, the description adds little beyond the annotations—it does not mention whether run returns data, whether delete is irreversible, or any other side effects. No contradiction exists.

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

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

The description is two sentences, front-loaded with the purpose and followed by a compact enumeration of actions. It wastes no words, and the [BUILD tier] tag is minor but not confusing. Excellent conciseness.

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 8 parameters and an output schema, but the schema's parameter descriptions are highly detailed (especially the connection guidance). The description adequately covers the four actions and the overall purpose. It does not discuss edge cases like overwriting existing names or missing IDs, but the overall package is complete for a CRUD-style tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of the action parameter (e.g., 'action=save stores a query by name; action=run executes a saved query'), which goes beyond the simple enum values in the schema. Other parameters are already well documented.

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

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

The description opens with a specific verb+resource ('Manage your personal library of reusable SELECT queries') and then enumerates the four distinct actions (save, run, list, delete). This clearly distinguishes it from sibling tools like query_sql (ad-hoc execution) and suggest_queries (suggestions).

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 by listing the actions and the concept of a personal library, but it does not explicitly state when to use this tool versus alternatives (e.g., 'for ad-hoc SQL, use query_sql'). No exclusions or alternative tool references are 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?

The description goes well beyond annotations by disclosing per-dialect system views, required privileges (pg_read_all_stats, PROCESS, VIEW SERVER STATE), and the clean 'Query blocked by security policy' error instead of partial data. This level of disclosure is exceptional.

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

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

The description is front-loaded with the core purpose, then efficiently structured into dialect details, privileges, and error behavior. Each sentence carries meaningful information; the only minor extra is the '[BUILD tier]' tag.

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 multi-dialect complexity, the description covers the essential behavioral aspects: which system views are used, privilege requirements per dialect, error behavior, and the managed PostgreSQL caveat. An output schema exists, so return values needn't be described.

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

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

The tool's description text itself adds no parameter details, but the input schema provides 100% coverage with a rich description of the `connection` parameter, including resolution via `list_connections`. Therefore 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 opens with 'List active sessions + blocking locks,' a specific verb+resource statement that clearly distinguishes it from sibling query tools like query_sql or explain_query. It also specifies dialect-specific system views, leaving no ambiguity about scope.

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

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

The description provides clear context for when to use the tool—whenever session or blocking lock information is needed—and notes that no dialect argument is required. It lacks explicit exclusions or direct alternative references, but the prerequisites and error handling give adequate usage guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering safety and repeatability. The description adds behavioral context by stating the tool is 'schema-aware' and produces 'ready-to-run SQL', implying it reads schema information and returns SQL rather than executing it. This goes beyond the annotations by clarifying the read-only, suggestion-generating nature.

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, front-loaded with the core action and outcome. It contains no redundant phrases and each sentence adds value: the first states what it does, the second indicates when it's most useful. This is a model of concise, well-structured tool documentation.

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 an output schema (not shown) and rich parameter descriptions, so return format and parameter semantics are covered. The description clearly explains purpose and use cases, and annotations handle safety. It does not explicitly discuss output quantity or limitations, but the output schema compensates for any return-value details. Overall, the definition is complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with both parameters having detailed descriptions, especially 'connection' which instructs to call list_connections and resolve names semantically. The tool description itself does not add parameter-specific meaning beyond high-level phrasing like 'schema-aware'. Since the schema already carries the full param burden, the baseline 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 uses a specific verb 'generate' and resource 'schema-aware query suggestions' with a clear deliverable ('ready-to-run SQL'). It distinguishes this from siblings like query_sql (executes) or explain_query (explains) by focusing on suggestion generation. The stated use cases ('exploring unfamiliar databases or finding useful queries') reinforce its unique role.

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 when to use the tool: 'Great for exploring unfamiliar databases or finding useful queries.' This gives clear contextual guidance, though it does not mention alternatives or exclusions. The guidance is clear enough for an agent to select it appropriately among 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?

The description discloses the exact SQL operation (SELECT 1), what it returns (server version + latency), and frames it as a lightweight alternative to describe_schema. Given readOnlyHint=true already in annotations, the description adds meaningful context about the tool's behavior without contradiction.

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

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

The description is a single sentence that is front-loaded with the core action and result. No redundant words; every phrase adds value, earning a top score.

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

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

With one optional parameter, no required fields, and an output schema present, the description is complete enough. It describes the action, the use case, the alternative tool, and the return type (server version + latency), while the output schema handles detailed 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 description coverage is 100%, so the parameter 'connection' is already well-documented with guidance on resolution. The main description does not add additional parameter semantics beyond referencing 'a connection', thus a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Ping a connection (SELECT 1) and return server version + latency.' It uses a specific verb ('Ping') and resource ('connection') and distinguishes itself from describe_schema by positioning as a faster credential/network 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?

The description explicitly indicates when to use this tool: 'Fast way to confirm credentials and network path without running describe_schema.' It also provides guidance in the schema to use list_connections for resolving the connection parameter, offering clear context and an explicit alternative.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable context about snapshot comparison and a built-in scheduler, which are not captured by the annotations. It does not mention permissions or scheduler configuration, but for a read-only monitoring tool with annotations covering safety, the additional context is useful.

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 only two sentences plus a tier tag, directly stating the core purpose, snapshot comparison, and scheduler. It is front-loaded and every word earns its place, making it highly concise and scannable.

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

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

Given the tool has an output schema and annotations, the description sufficiently covers the monitoring behavior and scheduler. It does not explain return values (covered by output schema) or prerequisites, but the complexity is moderate and the description provides enough for an agent to invoke it 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 100%, so the baseline is 3. The description itself does not mention parameters, but the schema fully documents table, column, condition, and connection, including detailed guidance for connection resolution. Thus the description adds no extra parameter semantics, but the schema handles it adequately.

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

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

The description clearly states a specific action: monitor a table's row count and latest record, and compare snapshots to show changes. This distinguishes it from siblings like analyze_table or detect_anomalies, which focus on profiling or anomaly detection rather than time-based change monitoring.

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 ongoing monitoring with a built-in scheduler, but does not explicitly state when to use this tool versus alternatives such as analyze_table or data_profile. No exclusions or alternative names are provided, leaving the agent to infer the appropriate context.

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