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

Annotations declare readOnlyHint=true, which already establishes that the tool is non-mutating. The description adds useful context about what the analysis returns, but it does not clarify whether the query is executed or only statically parsed, nor does it mention failure modes, dialect support, or performance implications.

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

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

The description is a single, dense sentence that efficiently summarizes the tool's output categories without excess wording. It is front-loaded with the key idea, and every word contributes meaning.

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 tool with one parameter and no output schema, the description gives enough detail about what results the agent should expect. It could be more complete by explicitly stating that this is static analysis and not query execution, but the core invocation decision is well supported.

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%, so the description carries the burden of explaining the 'sql' parameter. It does this only implicitly by calling it 'a query.' Since there is just one parameter and its name and type make its role fairly obvious, this is minimally adequate, but it lacks detail about accepted formats, dialect, or whether it can analyze incomplete SQL.

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 what the tool reports: tables/views, columns per table, CTEs, parameters, and output columns for a SQL query. Though it lacks an explicit verb like 'analyzes' and could better distinguish itself from explain_query, the resource and content are specific enough for an agent to understand its 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 provides no guidance on when to use this tool versus alternatives such as explain_query, lint_sql, or describe_table. There are no stated conditions, exclusions, or sibling comparisons, so the agent must infer usage from the tool name alone.

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 provide readOnlyHint: true, which the description aligns with by stating it never runs DDL. Beyond that, the description adds valuable behavior: it checks against cached schema, validates FK constraints, returns undo_sql, and wraps in IF OBJECT_ID(...) IS NULL. This goes beyond the annotation.

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

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

The description is informative without being excessive. The key point (text-only script) is front-loaded, followed by checks and an example. The example is compact yet illustrates the expected structure. It is well-organized, though slightly long due to the example.

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 (7 parameters, no output schema), the description covers the essential context: it returns sql + undo_sql + notes, it validates schema constraints, and it mentions naming conventions. It doesn't detail the return structure beyond that, but the agent can infer from the mention of sql/undo_sql/notes.

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%, so the description must compensate. It provides a detailed example for name, columns, primary_key, foreign_keys, and indexes, including defaults (e.g., ref_columns default to parent's primary key). This gives concrete meaning to the otherwise loosely typed 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 states a clear verb and resource: 'Generate a CREATE TABLE script'. It also specifies 'TEXT ONLY' and that the server never runs DDL, which distinguishes it from tools that execute (e.g., run_query). It is unambiguous about what the tool produces.

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

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

The description implicitly defines usage: when you need to create a table. However, it does not explicitly mention alternatives like build_view or build_procedure, nor any exclusions. The context is clear but lacks explicit routing 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?

The description adds significant behavioral detail beyond the readOnlyHint annotation: it explicitly says 'TEXT ONLY -- never executed', and describes the return format ('Returns sql + undo_sql + notes (including an EXEC example)') and the parameter auto-generation behavior. No contradiction with annotations 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 concise and front-loaded with the core purpose. It includes a helpful params example and return info, but is a single dense paragraph without clear separation of sections. Still, every sentence adds value, so it's efficient.

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

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

Given the tool's complexity (5 params, no output schema), the description is fairly complete: it explains inputs, output structure, constraints, and an example. It lacks explicit details on the 'name' and 'description' parameters, but these are likely self-evident. Overall, it covers what an agent needs to call 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 0%, so the description must compensate. It explains sql and query inputs and gives a concrete params example with name/type/default, but does not elaborate on the 'name' (required) or 'description' parameters. It partially clarifies parameter usage but not fully.

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

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

The description clearly states the tool's function: 'Generate a CREATE OR ALTER PROCEDURE script (TEXT ONLY -- never executed here) around a query.' It names the specific resource (procedure) and action (generate script), and distinguishes itself from siblings like build_view and build_create_table by focusing on procedures.

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 input-format guidance ('Give inline sql, or a library query') and a constraint ('Every @variable in the body must be a typed parameter'), but does not explicitly state when to use this tool over alternatives like build_view or build_select. It does note 'TEXT ONLY -- never executed here', which implies it's not for execution, but lacks explicit exclusions or comparison 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: names are validated, joins are inferred from foreign keys, bridge tables are added automatically, aliases are assigned, and GROUP BY is derived. It also reiterates that nothing is executed, reinforcing the 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?

The description is dense but well-structured: a one-sentence purpose statement followed by compact parameter examples. Every line adds useful information, and the front-loaded definition makes the tool's behavior immediately clear.

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 with nine parameters and no output schema, the description states the return contract ('Returns SQL text only') and covers most parameter semantics. It is slightly incomplete because `distinct` and `connection` are not addressed, though their schema defaults and titles offer some self-evident meaning.

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 0% schema description coverage, the description compensates well by documenting tables, columns, aggregates, filters, order_by, top, and join_type with concrete examples and rules. However, it does not explain the `distinct` or `connection` parameters, leaving two of nine parameters without added semantic 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?

The description opens with a specific verb and resource: 'Generate a SELECT from the cached schema,' and immediately clarifies scope with 'Returns SQL text only; nothing is executed.' This clearly distinguishes it from sibling builders like build_create_table, build_procedure, and build_view, as well as from run_query.

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 provides clear context: use this when you need a SELECT generated from the cached schema and want SQL text rather than execution. It does not explicitly name alternatives or list exclusions, but the 'nothing is executed' statement effectively separates it from query-execution tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral detail: output is text-only, the script is never executed, and the tool refuses unsupported constructs like parameters, DECLARE, and ORDER BY without TOP. This goes well beyond the annotation without contradicting it.

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 filler, with the most important constraints front-loaded: the core action, the text-only/no-execution guarantee, and the refusal rules. 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 main behavior, input sources, and key constraints, which is strong for a read-only script generator. Minor gaps remain around the exact roles of the name and description parameters and the precise return shape, but the required name is already visible in the schema.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It indirectly maps 'SELECT' to sql and 'library query' to query, but it does not explain the purpose of name or description, nor clarify how the two input sources relate. This leaves several parameters under-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 and resource: 'Generate a CREATE OR ALTER VIEW script', which clearly identifies the tool's function. It also distinguishes itself from siblings such as run_query by stating 'TEXT ONLY -- never executed here', and from build_create_table/build_procedure by specifying VIEW.

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 when to use the tool ('from a SELECT or a library query') and excludes execution via 'never executed here', but it does not explicitly name alternative tools or state when not to use it. Usage context is inferable 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?

The description goes beyond the destructiveHint annotation by explaining the deletion is non-permanent ('text is kept in a snapshot') and how to recover it. This gives the agent meaningful behavioral context about the consequences of calling the 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?

Two sentences, front-loaded with the primary action followed by the recovery caveat. No wasted words; every sentence adds essential 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?

The description covers the main action and recovery behavior, but omits the `dry_run` parameter, which is likely important for safe previews of a destructive operation. Without output schema or parameter explanations, this is a notable gap for an agent to call the tool correctly in all modes.

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

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

Schema description coverage is 0%, and the description does not explain either parameter. The `query` parameter is inferable from the tool's purpose, but `dry_run` is completely unexplained; with no schema descriptions, the agent must guess its meaning.

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

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

States a specific verb ('Remove') and resource ('a query from the library'), and clarifies the deletion is recoverable via snapshot. The mention of restore_snapshot differentiates it from a permanent deletion tool, leaving no ambiguity about what the tool does relative to 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?

Provides clear context: use this to remove a query while retaining recoverability, and points to restore_snapshot as the way to bring it back. While it doesn't explicitly state exclusions or alternatives, the context is sufficient for an agent to know when this tool is appropriate.

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 readOnlyHint=true, the safety profile is already covered by annotations. The description adds a useful scope constraint (one table or view) and output detail, but it does not disclose any potential costs, errors, or limitations such as row-count performance on large tables.

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 compact sentences: the first front-loads the exact result contents, the second gives a high-value workflow rule. 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?

Despite lacking an output schema, the description specifies the returned metadata well and includes a usage directive. It is slightly incomplete because it does not clarify how table names should be qualified or when the connection parameter is needed, but it is adequate for a simple 2-parameter 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 0%, so the description should explain what table/connection mean; it does not. The 'table' parameter is inferable from the tool name and 'one table or view,' but the optional connection parameter is never addressed.

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 enumerates exactly what is returned (columns with type/nullability/identity/computed, primary key, indexes, foreign keys, row count), so an agent knows this is a schema-introspection tool for a single table or view. It does not name a sibling alternative, but the concreteness separates it from list_tables or profile_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?

'Always do this before writing SQL against a table' is an explicit when-to-use rule tied to the SQL-writing workflow. It does not state when not to use it or name alternatives, but the rule is strong enough to guide 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 mark readOnlyHint=true, and the description reinforces this by stating the query is NOT executed and safe on heavy queries. It adds the SHOWPLAN permission requirement, which is not in annotations, providing valuable behavioral context beyond structured fields.

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 fluff. The primary purpose and key constraints are front-loaded, and the list of plan elements is compact yet informative. 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 gives a good overview of the tool's behavior and safety, and lists the kind of plan output. However, it lacks any parameter guidance (especially the distinction between sql and query, and the connection field) and does not describe the output format. For a tool with 4 params and no output schema, this is a moderate gap.

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

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

Schema description coverage is 0% and the description makes no mention of the four parameters (sql, query, params, connection). It provides zero guidance on what each parameter is for, how they interact, or which are required. The agent is left entirely to guess parameter semantics.

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 produces an estimated execution plan summary, enumerating specific elements (expensive operators, scans, key lookups, sorts, implicit conversions, warnings, missing-index suggestions). This is a distinct, concrete purpose that differentiates it from siblings like run_query (executes) or lint_sql (static 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 notes the query is compiled, not executed, and calls out safety on heavy queries, which implies a use case for performance analysis without side effects. However, it does not explicitly contrast with alternative tools (e.g., run_query, analyze_sql) or state when not to use it, leaving some inference to the agent.

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

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

No annotations are present, so the description must carry the full behavioral burden. It does disclose the edit mechanics, but it never says whether the saved query is actually modified in place, whether dry_run prevents a write, or what the return/output is — critical for a tool that changes a saved artifact.

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, front-loaded with the core operation, and the substitution rule plus header-line behavior are packed in without filler. The example is compact and 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?

For a tool with no annotations, no output schema, and five undocumented parameters, this description leaves too much unspecified: persistence/side effects, dry_run semantics, query identity, and success result shape. It is adequate as a purpose statement but not as a complete call contract.

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%, so the description is the only source for all five parameters. It clarifies 'literal' and 'param' indirectly and mentions the old value becomes the default, but it does not explain what 'query' refers to (SQL text vs saved query ID), nor the roles of 'dry_run' and 'description'.

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

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

Opens with a specific verb and resource ('Turn a hard-coded value in a saved query into a parameter') and then defines the exact transformation behavior: every occurrence of the literal becomes @param, and a '-- param:' header is added with the old value as default. This clearly distinguishes it from query-building, linting, and library-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 parameterizing hard-coded literals in saved queries and gives the exact substitution semantics, but it never states when not to use it or names an alternative. An agent must infer that this is the right tool from the transformation description alone.

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

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

The description discloses that only declared foreign keys are considered, that the result is the shortest chain, and that the output is ready-to-use JOIN lines. This adds behavioral meaning beyond the readOnlyHint annotation. It does not cover edge cases like missing relationships or multiple paths, 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, tightly worded sentence that front-loads the core concept and then provides the key detail about foreign keys and JOIN output. Every phrase earns its place and there is no filler.

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

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

For a simple two-required-parameter tool with no output schema, the description covers the essential behavior: shortest FK chain and JOIN-line output. However, it omits the optional connection parameter, does not mention what happens when no join path exists, and provides only a high-level sense of the return format.

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 has 0% description coverage, so the description must compensate. It references 'two tables' and 'between them,' which loosely maps to from_table and to_table, but it never explains the connection parameter or how the parameters interact. The names are somewhat self-explanatory, but the description leaves a key parameter undocumented.

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

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

The description clearly states that the tool finds the shortest chain of declared foreign keys between two tables and returns ready-to-use JOIN lines. This distinguishes it from query-building or schema-inspection siblings. It lacks a direct imperative verb, but the resource and output are specific enough for an agent to understand the tool's purpose.

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

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

The description implies a use case—understanding how two tables relate via foreign keys—but gives no explicit guidance on when to choose this tool over siblings like describe_table, build_select, or find_usage. There are no exclusions, prerequisites, or alternative tool recommendations.

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, so the read-only nature is already known. The description adds that it analyzes 'saved queries,' which clarifies scope, but does not disclose details like result format, performance implications, or limitations. Given the annotation, a 3 is appropriate.

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

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

Two concise sentences with no filler. The primary purpose is stated first, and the usage guidance is front-loaded. Every word 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?

For a simple read-only tool with two parameters, the description covers purpose, parameters, and when to use. It doesn't describe the output, but no output schema exists, and the result type (list of queries) is implicitly understood. Adequate 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 coverage is 0%, so the description must explain parameters. It maps 'given table/view' to the table parameter and 'optionally a given column' to the column parameter, clarifying that column is optional. This compensates for the missing schema descriptions, though it doesn't specify input formats.

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: impact analysis for saved queries referencing a table/column. It distinguishes from siblings like describe_table (schema details), search_schema (object search), and find_join_path (join discovery) by focusing on usage dependency.

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 when to use it: 'Ask this before a table or column is changed, renamed or retired.' It does not name alternatives or exclusions, but the trigger 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?

The description discloses that the tool normalizes cosmetics and explicitly warns that 'comments inside expressions may move', a behavioral nuance beyond the readOnlyHint annotation. It also states that meaning is unchanged, providing clarity on side effects. This adds value beyond the annotation, though it does not cover all potential edge cases.

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

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

The description is two sentences with zero filler. The main purpose is front-loaded, followed by concise details on cosmetic changes and a caveat. 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 single-parameter tool with no output schema, the description covers the operation, the side effect on comments, and semantic preservation. It does not explicitly mention the return value (formatted SQL), but that is implied. Given sibling tools like lint_sql, a brief note that it does not validate syntax could improve completeness, but the description is still sufficient 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?

With 0% schema description coverage, the description must compensate. It identifies the parameter as 'T-SQL' to be pretty-printed, adding meaning beyond the bare string type. However, it does not specify input format details, constraints, or examples, so the compensation is partial. A 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 clearly states the verb 'pretty-print' and the resource 'T-SQL', with a specific scope ('one canonical style'). It provides concrete examples of the cosmetic normalizations, distinguishing it from sibling tools like lint_sql or analyze_sql. The purpose is unambiguous and not a tautology.

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 no explicit guidance on when to use this tool versus alternatives. It implies usage for formatting T-SQL, but does not mention exclusions (e.g., 'not for syntax validation') or name any sibling tool. An agent might confuse it with lint_sql or translate_sql without additional context.

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

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

The annotation already declares readOnlyHint=true, so the read-only safety profile is covered. The description adds useful behavioral context beyond that by specifying the result contents: header fields, parameters, SQL, tables touched, and lint findings. It does not mention behavior for a missing saved query, but that is minor for a read-only retrieval 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?

One concise, front-loaded sentence; every element adds useful information about the returned object. There is no repetition of schema fields or annotation content.

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?

Complexity is low: one required parameter, a read-only annotation, and no output schema. The description gives a helpful output summary, but it omits the meaning of the query parameter, not-found behavior, and any relationship to sibling tools like list_queries. It is minimally viable but has clear 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 0% and the only parameter is a bare string named 'query'. The description never clarifies whether query is a saved-query name, ID, or SQL text, so the agent must guess what value to pass. The phrase 'One saved query' only implies the result type, not the parameter format.

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

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

The description names the resource (a single saved query) and enumerates its contents, so it is clear what the tool returns and is not a tautology. However, it uses a noun phrase rather than an explicit verb like 'retrieves', and it only implicitly differentiates from list_queries via 'One'.

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 given for when to use get_query versus list_queries, save_query, delete_query, or other siblings. The singular 'One saved query' hints at retrieving one item, but there is no explicit context, prerequisite, or exclusion.

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

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

Annotations already mark the tool as read-only, and the description consistently supports that. It adds valuable behavioral nuance: linting runs against each query's cached connection schema when available, which affects result reliability. This goes beyond what annotations alone convey.

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

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

The description is two tight sentences with no filler. The core action is front-loaded, and the useful 'after refresh_schema' guidance appears at the end. 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?

The description covers what the tool does and when to run it, making it callable. However, there is no output schema and no description of what results are returned, and the only parameter is undocumented. For a simple one-argument tool this is a moderate gap, not a fatal one.

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

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

Schema description coverage is 0%, and the description does not mention the min_severity parameter. An agent cannot tell what values are valid (e.g., 'error', 'warning', 'info') or how severity affects lint output. The default 'warning' is the only hint, which is insufficient.

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

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

The description states a specific action ('lint every saved query') and resource ('the saved query library'), and distinguishes it from individual linting tools like lint_sql by targeting the entire library. It also states the purpose: catching queries broken by schema changes.

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 an explicit trigger condition: 'run it after refresh_schema.' This clearly tells an agent when the tool is appropriate. It does not mention alternatives or when not to use it, but the context is strong.

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

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

The annotations already declare readOnlyHint=true, and the description adds useful context by enumerating the specific checks and stating that schema verification only happens when a connection with a cached schema is provided. It does not describe output behavior or error handling, but the safety profile is covered by annotations.

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

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

The description is front-loaded and every clause carries behavioral information. The first sentence is dense with examples, but these examples are useful for an agent deciding what the tool checks. There is no filler, though the enumeration could be slightly trimmed.

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

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

The description covers the tool's main function, the conditional schema-verification behavior, and enough detail for an agent to invoke it correctly with sql and optionally connection. It does not describe the return format, but given the lint-oriented behavior and absence of an output schema, the core calling context is largely 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 description coverage is 0%, so the description must add meaning to the parameters. It gives semantic weight to 'connection' by explaining that it enables table/column existence verification, and implicitly treats 'sql' as the query to lint. It does not elaborate on expected formats or connection value sources, leaving some 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 that the tool checks SQL for correctness traps, performance problems, and style, with concrete examples. It is easy to tell this is a linting tool, though it does not explicitly differentiate itself from sibling tools like analyze_sql or explain_query.

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

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

There is no explicit guidance about when to use this tool versus analyze_sql, explain_query, or other siblings. The description implies it is for linting SQL, but does not state when to choose an alternative, leaving the agent to infer based on sibling names.

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

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

Annotations already convey readOnlyHint=true, so the description doesn't need to restate safety. It adds useful behavioral detail: connections come from sqlglass.toml, the default config also holds the query library location, and the result reports cached-schema presence per connection.

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

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

The description is compact and single-sentence, front-loading the main purpose. The phrasing 'which is the default, where the query library lives' is slightly awkward, but still packs relevant detail into a small space.

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 listing tool, the description is sufficiently complete. It names the source, the default config relationship, the query library location, and the cached-schema status included in results, which is enough given the tool's simplicity.

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 100% schema coverage of an empty schema, so there is little to explain. Per the baseline for parameterless tools, this is handled well; the description confirms the tool requires no configuration arguments.

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 action ('List') and the resource ('configured database connections'), and adds specificity about the source file and output details. It distinguishes itself from sibling list tools by focusing on connection configuration rather than tables, snapshots, or 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?

Usage context is implied: an agent would call this to inspect configured database connections and their cached-schema status. However, there is no explicit when-to-use guidance, no mention of when not to use it, and no naming of alternative tools for related needs.

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

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

Annotations already provide readOnlyHint: true, so the safety profile is covered. The description adds behavioral context by describing what the search parameter matches and that tag filters, but it does not disclose return format, ordering, pagination, or what happens with no filters. With annotations present, the bar is lower, but the description adds limited behavioral detail beyond the schema–appropriate but not rich.

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: the first states the primary purpose ('Browse the saved-query library'), and the second explains parameters. It is front-loaded with the core intent, has zero filler, and every word adds value. This is an exemplary model of concise, 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 is simple with two optional parameters and no required fields. The description explains both parameters and implies the action. It does not describe return structure or pagination, but for a read-only list operation, these are relatively minor gaps. Given the low complexity and existing annotations, the description is nearly complete, missing only explicit output format and pagination behavior.

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

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

The schema has 0% description coverage, so the description must fully explain the parameters. It does: 'search' matches id, name, description, and SQL text; 'tag' filters by tag. This adds meaningful semantics that are not inferable from the parameter names alone. It could be more precise (e.g., exact vs substring matching), but it covers both parameters adequately, warranting a strong score.

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

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

The description states a clear verb and resource: 'Browse the saved-query library.' It also explains the two filters (search and tag) with specifics on what search matches. However, it does not explicitly distinguish from sibling tools like get_query or search_schema, though the verb 'browse' implies a listing operation. This is clear but not fully differentiated from siblings.

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

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

The description conveys when to use this tool by saying it browses the saved-query library and explains how search and tag work. It does not mention alternatives, such as using get_query to retrieve a single query, or search_schema for schema-level search. Usage context is implied but no explicit exclusions or comparisons are given, so it earns a mid-range 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?

The description adds value beyond the readOnlyHint annotation by explaining the nature of snapshots ('Before-images taken automatically ahead of every library write') and their ordering ('newest first'). This gives the agent useful context about what the tool returns and how it's sorted. 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, efficient sentence that conveys the core concept and ordering. No wasted words, and the key information (what snapshots are) is front-loaded. It is concise without being under-specified.

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 simplicity of the tool (no parameters, no output schema, read-only annotation), the description is mostly complete. It tells what the tool returns (list of before-images) and the ordering. It could mention the relationship to restore_snapshot or what snapshots contain, but that's not critical for calling 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 and the schema covers 100% of them (none). Per the rubric, baseline is 4 when there are no parameters. The description doesn't need to add parameter semantics since there are none.

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 resource ('Before-images taken automatically ahead of every library write') and the action (implied 'list' through the tool name and context). It distinguishes itself from siblings like restore_snapshot (which restores) and list_queries (which lists queries), so the purpose is clear enough, though it does not explicitly state 'list' as a 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that it's the read-only counterpart to restore_snapshot, nor does it suggest any use case or context. The only clue is the word 'list' in the tool name, which is not elaborated.

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 useful behavioral context: it returns row counts and descriptions, supports two kinds of filters, and hints at cost characteristics by redirecting large databases to search_schema. It does not detail limit, ordering, or pagination, but the read-only safety profile is already covered by the annotation.

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

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

The description is two short sentences with no filler. It front-loads the core behavior, then adds filter semantics and a routing hint, making every sentence earn 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 read-only listing tool, the description covers purpose, return content, filtering, and performance-aware routing. It omits only limit and connection semantics, which are partially self-evident from their defaults and sibling context, so it is slightly above adequate but not exhaustive.

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%, so the description must compensate. It usefully explains 'schema' and 'pattern', including wildcard syntax, but says nothing about 'limit' or 'connection', leaving two of the four parameters underspecified.

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

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

The description states a concrete verb ('List') and a precise resource ('tables and views') with the included payload ('row counts and descriptions'). It also clarifies the filtering dimensions, and the final sentence orients it against search_schema, so an agent can distinguish it from sibling 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?

It gives an explicit alternative (search_schema) and a triggering condition ('big database'), which is exactly the when-to-use guidance needed to select between two enumeration tools. The filter hints ('schema name and/or a name pattern') also clarify the intended use case.

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, but the description adds significant behavioral detail: it converts the write to a SELECT, never sends the write, explains how each statement type (UPDATE/DELETE/INSERT) is represented, and clarifies the run=true behavior (executes the preview, read-only, row-capped, returns affected count and first rows). This goes well beyond the annotation and is fully consistent with it.

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 somewhat long but each sentence carries specific value. The core purpose is front-loaded, followed by detailed breakdowns for each statement type and the run flag. It avoids repetition and is structured clearly with line breaks. It could be slightly trimmed but remains efficient for the complexity it covers.

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 thorough for a complex tool that handles three statement types and two flags. It explains the transformation, the read-only nature, the return values (affected-row count and first rows when run=true), and the server's inability to apply writes. It does not cover potential errors or edge cases, but given no output schema, it sufficiently covers what the agent needs to call 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 0%, so the description must compensate. It does explain 'run' (default false, if true executes preview) and 'changed_only' (hides no-op rows) clearly. It also implicitly defines 'sql' as the write statement. However, it does not explain 'params' (bind parameters) or 'connection' (target connection), which are left to schema defaults. Given the tool's core parameters are covered, a 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: dry-run a write (UPDATE/DELETE/INSERT) by converting it to a read-only SELECT and returning affected row counts. It distinguishes itself from siblings like run_query (which actually executes) and explain_query (which explains plans) by emphasizing that the write is never sent to the database.

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

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

The description implicitly tells when to use it: when you want to preview the effect of a write without applying it. It also explicitly states a limitation ('This server cannot apply the write; hand the reviewed statement to the user to run themselves'), which guides the agent to not attempt actual execution. However, it does not explicitly name alternative tools or exclusions (e.g., use run_query for actual execution), so a clear alternative comparison is missing.

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

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

The readOnlyHint annotation already signals safety. The description adds useful behavioral constraints: it runs 'one aggregate query' and is limited to 'Up to 15 columns per call.' It does not cover error or edge-case behavior, but the annotation lowers the bar.

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 economical sentences: the first states outputs and mechanism, the second states the use case and the column limit. Every clause 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?

Covers the essential contract: what is computed, when to use it, and the column limit. Since there is no output schema, the listed metrics serve as the output contract. Minor ambiguity about omitted columns and the connection parameter prevents a perfect score.

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%, so the description must compensate. It does clarify the columns parameter via the 15-column limit and per-column metrics, and 'table' is obvious from context. However, it provides no semantics for the connection parameter or for what a null columns value means.

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

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

States the exact aggregate metrics returned (row count, NULLs, distinct values, min/max) and ties them to a specific resource: columns of a table. This differentiates it from siblings like describe_table (schema metadata) and sample_table (row sampling) even though no sibling is named.

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 frames the use case: 'learn a column's grain and range before filtering or joining on it.' This gives clear context for when to call the tool, though it does not mention alternatives or when not to use it.

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

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

With no annotations, the description carries the full burden of behavior disclosure. It does explain that the tool re-reads from the database into a local cache, which is useful. However, it omits details like permission requirements, potential performance cost, or what happens if the database is unreachable – notable for a refresh 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?

Two sentences with no filler. The action and scope are front-loaded, and the trigger conditions are given concisely. 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?

For a simple refresh utility with one optional parameter and no output schema, the description is complete: it says what is reloaded, where it is loaded, and when to run it. The low complexity means nothing essential is missing.

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

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

Schema description coverage is 0%, and the description never mentions the 'connection' parameter. The parameter name and default value are somewhat self-explanatory, but the description adds zero value on parameter semantics and does not compensate for the missing 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 uses a specific verb ('re-read') and a precise resource (tables, views, columns, keys, indexes, foreign keys) with a clear destination (local cache). This clearly distinguishes it from sibling tools like list_tables, describe_table, or search_schema, which operate on the cached state rather than refreshing it.

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

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

It gives explicit triggers: run when a table or column seems to be missing, or after the database changed. It does not name alternatives or exclusions, but the context is clear enough for an agent to know when refresh_schema is the right choice versus the lookup 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses token-aware rewriting, that strings/comments are untouched, that alias-qualified and bare references are handled, and that ambiguous bare references are reported rather than changed. It also exposes the dry-run safety 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?

The description is compact and front-loaded: the essential behavior comes first, followed by distilled examples and the dry-run workflow. Every line earns its place 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 mutation tool with no output schema and minimal param metadata, the description covers invocation, edge cases, and the dry-run workflow well. The main gap is that table is marked optional in the schema while the example implies it is required for kind='column'; the description does not explicitly settle that constraint.

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%, but the description compensates with concrete examples for kind='table' and kind='column', showing how old, new, and table relate. It also explains dry_run's meaning and default. All five parameters gain practical semantics beyond the bare schema titles.

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 opening sentence states a specific operation: following a database rename through every saved query with token-aware rewriting. The table/column examples clarify exactly what resource is being acted on, and the sibling list confirms this is the only library-rewrite tool, so there is no ambiguity.

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 workflow: dry_run defaults to true so the agent can review the diff, then invoke again with dry_run=false. It does not explicitly name alternative tools or state when not to use this tool, but the examples and the unique rename purpose set the context well.

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 adds meaningful behavioral context beyond the destructiveHint annotation by stating that the restore is itself snapshotted and can be undone. This usefully tempers the destructive nature of the tool. It does not mention authorization or effects on other snapshots, but the annotation plus added context cover the key behavioral risk.

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 no filler. The core action and the important 'latest' behavior come first, followed by the undoable-restore trait. 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 core restore semantics and reversibility are clear, but the tool has no output schema and the description does not mention what a call returns or how dry_run=true behaves. An agent cannot fully predict the outcome of the dry-run parameter or the response format, leaving a meaningful gap.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It explains the 'latest' default for snapshot_id but does not explain dry_run at all, nor does it clarify what a snapshot_id is or how to obtain one. This is incomplete compensation for an otherwise undocumented parameter set.

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 what the tool does: it reverts queries in a snapshot to their state before a write, with 'latest' explicitly meaning 'undo the last write.' This is specific and distinct from sibling tools like list_snapshots or save_query, and it gives actionable meaning to the default parameter value.

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 practical context by explaining that 'latest' means undo the last write, which tells an agent when to invoke this tool. It does not explicitly enumerate alternatives or exclusions, but no sibling tool appears to compete with this restore behavior, so the guidance is 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?

Annotations only declare readOnlyHint=true, but the description adds valuable behavior: refusal of non-SELECT/WITH statements before reaching the database, capping rows by connection max_rows, library query fallback behavior, and guidance to aggregate in SQL for large data. This goes well beyond the annotation.

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

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

Four dense, purposeful sentences with no filler. The primary action is front-loaded, followed by parameter guidance, safety restrictions, and row-limit behavior. 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 is self-sufficient for selecting and invoking the tool: it explains the query source, parameters, safety gate, row limits, and how to handle large datasets. Even without an output schema, 'return the first rows' plus the cap explanation gives enough expectation for the return behavior.

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

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

Schema description coverage is 0%, but the description compensates well. It clarifies the sql/query mutual exclusivity, the params object with an example, max_rows purpose, and connection context. All five parameters receive meaningful explanation despite the empty 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 states a specific verb and resource: 'Run a read-only query and return the first rows.' It clearly differentiates this from siblings like lint_sql, explain_query, or sample_table by emphasizing read-only execution and inline or library query sources.

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 usage context: choose either inline 'sql' or a library 'query', pass params, and use max_rows to control row count. It also states the SELECT/WITH restriction. It does not explicitly name alternatives or say when not to use the tool, but the guidance is concrete 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?

The readOnlyHint annotation already establishes the tool is read-only, and the description adds that it returns actual row values, which is useful context. However, it does not disclose behavioral details such as row ordering, sampling method, or performance implications on large tables. It does not contradict the annotation.

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

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

The description is a single, efficient sentence with no filler. It front-loads the resource ('table or view') and the action ('a few rows') before the purpose, making it easy to scan.

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

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

The tool has four parameters, one required, and no output schema, yet the description only covers the core purpose. It does not explain the effect of the 'columns' parameter, the 'connection' parameter, or the format of the returned rows. For an agent to use it correctly, more detail is needed.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It clarifies 'rows' as 'a few rows' and 'table' as 'table or view', but it does not explain 'columns' (whether it filters or selects columns) or 'connection' at all. Given the zero coverage, this is insufficient.

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 the tool returns a few rows of a table or view to inspect actual values, which clearly identifies the resource and intent. It lacks an explicit verb like 'sample' or 'retrieve', and does not explicitly differentiate from siblings like describe_table or profile_table, but the purpose is evident.

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 purpose ('to see what the values actually look like') implies when to use the tool, but there is no explicit guidance on when not to use it or which alternative to prefer. Sibling tools such as describe_table and profile_table are not mentioned, 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.

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

With no annotations, the description carries the full burden. It discloses that sql is body-only, that empty header fields keep current values during updates, and that script-type queries are never linted or executed. It does not mention permissions or error behavior, but the disclosed behaviors are significant and go beyond the schema.

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

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

The description is dense but well-organized with line breaks and an example. It front-loads the primary purpose and then details special cases. Every sentence contributes, though it is longer than average; the structure supports readability without excess.

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 with 10 parameters and no output schema, the description covers the most complex aspects (params format, overwrite, kind) but omits several parameters and does not describe return values or error conditions. Given the complexity, the description is partially complete but leaves gaps that an agent might need to resolve.

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 has 0% description coverage, so the description must compensate. It explains id, sql, params (with a JSON example), overwrite, and kind. However, it leaves name, tags, dry_run, connection, and description unexplained, which is a notable gap for a 10-parameter tool. The partial coverage earns a mid score.

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

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

The description clearly states the tool saves a query to the library as <id>.sql, distinguishing it from siblings like get_query, delete_query, and run_query by its write-to-library action. The inclusion of folder paths and special handling for kind='script' further clarifies its specific 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 provides concrete usage rules: how to format the params array, that overwrite=true is required for updates, and that kind='script' is for DDL text. It does not explicitly compare against sibling tools or state when to use save_query over others, but the operational guidance is strong 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?

The readOnlyHint annotation already declares the tool is read-only, so the description does not need to repeat that. The description adds that it searches name and description fields and supports wildcards, which is useful behavioral detail. However, it does not disclose the return format (e.g., whether results are grouped by table vs. column) or any pagination/limitations. Given the annotation covers the safety profile, the description adds some value but not extensive behavioral context, warranting a 3.

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 redundant wording. The core function is front-loaded in the first sentence, and the second sentence provides situational context. Every word contributes to understanding the tool's purpose and use case, making it highly concise 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?

For a read-only search tool with two parameters and no output schema, the description is fairly complete. It covers what is searched (tables, columns, descriptions) and the pattern syntax. The connection parameter is not explained, but its purpose is likely evident from the context. The description does not specify the exact result format, but given the tool's simplicity and the annotation coverage, it meets most agent needs. A small gap around result structure prevents a 5.

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%, so the description must compensate. It explains the pattern parameter well: 'whose name contains the text (or matches a * ? wildcard pattern), plus tables whose description mentions it' – this gives semantic meaning to the pattern. However, the connection parameter is not explained at all; the schema only shows a default empty string. The description partially compensates for the coverage gap but leaves one parameter unexplained, so a 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 searches tables and columns by name pattern and description mentions, which is a specific verb+resource action. It distinguishes itself from siblings like list_tables (which lists all tables) and describe_table (which describes a specific table) by emphasizing the search/filter aspect, making its 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?

The description provides clear usage context: 'The way to locate data in an unfamiliar database.' This tells the agent when to use it (when exploring unknown schema). However, it does not explicitly mention alternatives or when not to use it, such as recommending list_tables for a full listing or describe_table for specific details. The context is clear but exclusions are absent, so it earns a 4.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds context about the scope of translation (specific conversions), but it does not disclose limitations (e.g., unsupported syntax handling) or output format. This is adequate but not rich, given the annotation baseline.

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 states the purpose and lists key conversions without waste. It is compact and efficient, with 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 translation tool with no output schema, the description should clarify the output format and error behavior for unsupported constructs. It lists specific conversions but does not state whether the translation is lossless or what happens for unlisted SQL features. This leaves some ambiguity for an agent invoking 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 description coverage is 0%, but the schema provides property names (sql, to_dialect, from_dialect) and a default for from_dialect. The description adds a list of valid dialects, which clarifies possible values, but it does not explain the meaning of each parameter beyond the names. This partially compensates for the coverage gap.

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

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

The description clearly states the verb 'Translate' and the resource 'query', and enumerates the supported dialects and specific conversion patterns (TOP<->LIMIT, ISNULL/COALESCE, etc.). This distinguishes it from sibling tools like lint_sql or format_sql, which serve different purposes.

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 when to use the tool by naming its function, but it does not explicitly state when to prefer it over alternatives like analyze_sql or build_select. There is no exclusion or routing guidance, though the purpose is clear enough for an agent to infer applicability.

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