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

Annotations already establish the read-only, idempotent, non-destructive profile, so the bar is lower, but the description adds real value: the six analyses run concurrently and results are merged into a single composite report. The MCP Apps interactive-rendering note is useful host-dependent behavior. It does not mention latency/cost of fanning out six analyses, so not a 5.

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, zero waste: the usage trigger is front-loaded, followed by the mechanical behavior. No restatement of the tool name or filler.

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

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

With no output schema, the description carries the burden of describing returns, and 'one composite report' plus the list of constituent analyses covers that adequately. The only gap is the report's internal structure, which is implied but not specified.

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?

Single parameter with 100% schema description coverage, so the schema already documents 'sql' fully. The description adds no syntax, dialect, or size guidance beyond what the schema provides; baseline 3 is correct.

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 and resource ('complete review of a SQL query') and enumerates exactly which six sibling capabilities it composes (validate, parse, metadata, security, lint, format). An agent can instantly tell this apart from the single-purpose siblings without opening any schema.

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?

'Use this when the user wants a complete review' gives a clear triggering condition, and the enumeration of the six sub-analyses implicitly signals that the individual sibling tools exist for narrower needs. It stops short of explicitly saying when to prefer validate_sql or lint_sql alone, so no true exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the return contract {tables, columns, functions}, which is the only place the agent learns output shape since there is no output schema. It does not say what happens with unparseable or dialect-specific SQL.

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, zero filler: the trigger condition comes first and the return shape second. Nothing is repeated from the schema or annotations.

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 one-parameter, read-only, idempotent extraction tool this is nearly sufficient: usage trigger, output keys, and a fully documented parameter. The only missing element is failure behavior for invalid SQL, which is minor given the low complexity and full annotation coverage.

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

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

Schema description coverage is 100%, so the single "sql" parameter is already fully documented as "The SQL string to analyze." The description adds no syntax, dialect, or size guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: it extracts the tables, columns, and functions a SQL query references. The output-key enumeration makes it distinguishable from siblings like format_sql or lint_sql, though it never explicitly contrasts itself with parse_sql or analyze_sql, which could sound similar to an agent.

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?

"Use this when the user wants ... (e.g. for lineage or impact analysis)" gives a clear triggering condition plus concrete scenarios. It does not, however, name an alternative tool or state when NOT to use this one versus parse_sql/analyze_sql.

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 this as a safe, read-only, idempotent, non-destructive operation. The description adds meaningful behavior beyond annotations: comments are preserved, unplaceable optimizer hints are refused, and the return shape is {formatted_sql, options}. It does not contradict annotations.

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

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

The description is compact and front-loaded with the usage trigger, followed by key formatting behavior, edge cases, and return shape. Every sentence contributes useful information without repetition.

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

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

Given the fully specified input schema and annotations, the description covers the purpose, main options, edge-case behavior, and return keys. It is nearly complete, though the returned 'options' object is not expanded and there is no output schema to rely on for that detail.

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

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

Schema description coverage is 100%, so all four parameters are already well documented in the schema. The description reinforces optional uppercase keywords and trailing semicolon behavior, but it does not mention indent_size or add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: pretty-printing/reformatting SQL, with concrete formatting behavior. It is clearly distinguishable from siblings like lint_sql, validate_sql, and analyze_sql by being purely cosmetic, though it does not explicitly name those alternatives.

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 trigger: 'Use this when the user wants SQL pretty-printed or reformatted.' That is strong usage guidance, but it does not state when not to use it or explicitly route to validation/linting alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds value by enumerating the exact rule set applied and by specifying the return shape '{violation_count, violations}', which is otherwise undocumented since no output schema 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?

Front-loaded with the usage trigger, followed by scope (the rule set) and then the return contract in a compact form. The L001-L010 enumeration is long but each entry is terse and genuinely informative, so it earns its 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 single-input, read-only lint tool with no output schema, the description supplies the missing return shape and the rule scope, which is most of what an agent needs. It omits only minor items such as SQL dialect handling and output ordering.

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

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

Schema description coverage is 100% for the single `sql` parameter, so the schema already carries the semantics and the baseline is 3. The description adds no syntax, size, or dialect constraints beyond what the schema states.

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 operation (SQL style linting) with an explicit rule inventory (L001-L010) and scoping to the `gosqlx lint` rule set. This clearly separates it from siblings like validate_sql (correctness), security_scan (vulnerabilities), and format_sql (mutation of the SQL), so an agent can route without opening schemas.

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?

Opens with a clear trigger condition, 'Use this when the user wants SQL style feedback,' which is a genuine when-to-use statement. It does not, however, explicitly name the alternatives (format_sql/validate_sql) or state when not to use it, so the agent must infer the boundary from the 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description rightly focuses on behavior beyond that: what the response contains and the non-obvious quirk that GO batch separators are excluded from the statement count. No mention of size limits or dialect fallback behavior, which keeps it off a 5.

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 usage trigger front-loaded and the return semantics immediately after. The clause about GO separators is a worthwhile edge case rather than padding.

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

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

With no output schema, the description must convey return shape, and it does (AST summary, count, statement types). Combined with full schema coverage and read-only annotations, an agent has what it needs; only the default-dialect behavior is left implicit.

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

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

Schema coverage is 100% and the dialect enum lists every accepted value, so the schema carries the load. The description only adds "optionally for a specific dialect" on top of that, which restates rather than enriches parameter meaning (e.g., what happens when dialect is omitted).

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 and resource (parse SQL) and, unusually, spells out the return payload: an AST summary with statement count and per-statement type. That output shape implicitly separates it from validate_sql/lint_sql/format_sql, though no sibling is named explicitly.

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?

"Use this when the user wants to know how SQL parses" gives a clear trigger condition, and the listed return fields (statement count, statement types) reinforce which questions it answers. It stops short of naming analyze_sql as the alternative or saying 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by naming the detection categories and stating the response shape (findings with severity counts), which annotations cannot express.

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 tight sentences, with the use condition front-loaded and the return summary appended. 'and more' is mildly vague filler, but overall nothing is wasted.

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

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

For a single-parameter, read-only, closed-world scan with full annotation coverage and a stated return summary, the description is nearly complete. The only gap is the absence of any dialect/input-size caveat or a note on how it differs from the lint/validate siblings.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents 'sql'. The description adds no syntax, size, or dialect constraints (e.g. whether multi-statement input is allowed), leaving the baseline 3 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?

States a specific verb+resource ('SQL checked for injection patterns') and enumerates the detection classes (tautologies, UNION attacks, stacked queries, comment bypasses). It is clearly distinct from format_sql/parse_sql, though it doesn't explicitly draw the boundary against the closest siblings lint_sql, validate_sql, and analyze_sql.

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

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

'Use this when the user wants SQL checked for injection patterns' gives a concrete trigger condition tied to user intent. It offers no when-not guidance and never names the adjacent siblings (validate_sql, lint_sql), so an agent must infer that security scanning is separate from correctness linting.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes further by disclosing the return shape {valid, error?, dialect?}, which is genuinely useful behavioral context given there is no output schema.

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

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

Two tight sentences: the usage condition comes first and the return contract second, with no filler or repetition. Every clause 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 two-parameter read-only tool with no output schema, the description supplies the missing piece: the response structure and its optional fields. Nothing essential for correct invocation is absent, though a note on how invalid SQL is reported (vs. an error thrown) would close the last 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 100% and the enum for dialect is fully enumerated in the schema, so the parameters are already documented. The description only echoes that the dialect is optional ('optionally for a specific dialect'), adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('validate' a 'SQL statement') plus the scoping detail 'syntactically valid' and optional dialect targeting. It clearly differs in intent from siblings like format_sql or parse_sql, though it never names an alternative to sharpen the boundary.

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?

Gives an explicit trigger: 'Use this when the user wants to know whether a SQL statement is syntactically valid.' This is a clear context for invocation. It stops short of exclusions or naming the neighboring tools (lint_sql, parse_sql) that an agent might otherwise confuse it with.

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