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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by disclosing that output is 'compact structured findings' rather than a full textual plan and enumerates the diagnostic categories. It does not contradict annotations, though it doesn't discuss the runtime-execution implications of the analyze parameter, which is covered in the schema.

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

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

The description is compact and front-loaded: first the purpose, then the alternative tool, then the binding rule with a concrete example. Every sentence earns its place with no filler or redundancy.

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

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

With an output schema present, detailed return structure is unnecessary. The description covers the key routing decision, the parameter binding convention, and the diagnostic scope, while remaining fields like connection and analyze are already documented in the schema. This is complete for the tool's complexity.

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

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

Schema coverage is already high, but the description adds critical binding semantics beyond the schema: '?' maps to params, ':name' maps to namedParams, never mix, and the example clarifies that the object key should be the bare name without the colon. This directly helps an agent construct valid calls.

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 explicitly states the tool diagnoses query-plan performance and lists concrete findings it returns: expensive nodes, large-table full scans, estimation errors, risky nested loops, and disk-sort spills. It uses a specific verb ('Diagnose') with a clear resource ('query-plan performance') and differentiates itself from explainQuery in the next sentence.

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

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

The description gives explicit selection guidance: 'Use explainQuery when the full textual plan is required.' This directly tells the agent when not to use analyzePlan and which sibling tool is appropriate instead. It also includes binding instructions that guide correct invocation.

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 readOnly/idempotent/destructive annotations, the description discloses key behavior: it returns only the size of the last result (rows, columns, truncated) rather than the rows themselves. It also explains the binding model ('?' vs ':name') and warns against mixing them. These are meaningful behavioral details not visible in the annotations alone.

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

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

Three sentences deliver purpose, usage guidance, binding rules, and return behavior without filler. Information is front-loaded: the core purpose appears first, then usage alternatives, then parameter and return semantics. 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 an 8-parameter tool with an output schema, the description covers the critical invocation context: when to use it, how to bind parameters, what it returns, and why it differs from timedQuery. Remaining details like default run counts, timeout, and valid connection names are already present in the parameter schema, so nothing necessary for correct use is missing.

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

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

The schema already documents 88% of parameters, including descriptions for 'params' and 'namedParams', so the baseline is 3. The description adds a concrete example (':status -> namedParams={status:'PAID'}'), clarifies that the key is the bare name, and warns never to mix binding styles. This adds value but is not essential given the schema's coverage.

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

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

The description states a specific verb ('Measure') on a specific resource ('repeatable query latency') and defines the output as cold runs plus min/median/max warm-run timings. It also distinguishes itself from the sibling timedQuery by noting that timedQuery is the one-run alternative that returns rows. This makes the tool's purpose unambiguous and separable 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?

It explicitly says 'Use for comparing query rewrites, not retrieving data' and names timedQuery as the alternative that returns rows. This gives the agent both a positive and negative usage condition, which is strong guidance for tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds value beyond annotations by disclosing that execution performs GROUP BY + COUNT and may be expensive on large tables. This is useful behavioral context.

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

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

The description is two sentences with no fluff. It front-loads the core purpose, immediately gives the sibling distinction, and ends with a concise performance warning. Every sentence contributes useful information.

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

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

Given the output schema exists, the description does not need to explain return values. It covers purpose, usage distinction, and cost. The only minor gap is that it doesn't mention that schema is optional, but required parameters and the connection hint largely compensate.

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

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

The description adds some meaning beyond the schema by clarifying that column must be a single known column and by referencing top-N values, which maps to the topN parameter. However, with only 40% schema description coverage, the description does not fully compensate for the lack of documentation on schema and table 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 uses a specific verb ('Measure') with a clear resource ('value frequency and skew for one known column') and states the output shape ('top-N values, counts and row shares'). It also distinguishes itself from a sibling tool, columnStats, by naming what that tool is for.

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

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

The description explicitly says when to use columnStats instead ('for only cardinality/extremes'), which implies when to use this tool (i.e., when distribution and skew are needed). It also warns that the tool runs GROUP BY + COUNT and may be expensive, giving practical usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the accepted column types (numeric, date, timestamp, text), the requirement that the column be orderable, and the precise set of statistics returned including null counts.

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 filler: the first front-loads the purpose and exact output statistics, and the second gives a clear alternative. Every word contributes to selecting or invoking the tool correctly.

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

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

Given the presence of a full output schema, the description does not need to explain return values. Combined with annotations for read-only behavior and the explicit sibling routing, it covers the essential information an agent needs. A minor gap is the lack of guidance on how to specify tables/schemas, but the schema's standard parameter names make this largely self-evident.

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

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

Schema description coverage is only 25%; the connection parameter is well-documented in the schema itself. The description partially compensates for the undocumented column parameter by specifying that it must be an orderable numeric, date, timestamp, or text column. However, the table and schema parameters receive no added meaning, and the description does not clarify how to qualify the table or handle the optional schema parameter.

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

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

The description states a specific verb ('Measure') and resource ('percentile distribution for one orderable numeric, date, timestamp or text column') and enumerates exact outputs (min/max, P25/P50/P75/P90/P95/P99, null counts). It also distinguishes itself from columnDistribution by explicitly naming that sibling as the alternative for top frequent values.

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

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

The description gives clear context for when to use this tool: when percentile distribution for a single orderable column is needed. It explicitly instructs to use columnDistribution for top frequent values instead, providing a direct exclusion and routing the agent to a sibling tool.

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

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

Annotations already mark it read-only and idempotent, and the description adds behavioral scope: it operates on a single known column rather than scanning all columns, and it specifies exactly which statistics are computed. It does not mention return shape, but an output schema exists and the annotations cover safety.

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

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

Two clauses in a single sentence: the first states purpose and outputs, the second gives routing to siblings. Every word earns its place, with no redundancy.

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

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

For a simple read-only statistics tool with an output schema, the description covers what it computes and how it differs from related tools. Remaining gaps, such as how schema is selected or null handling, are minor given the output schema and annotation set.

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

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

Schema description coverage is only 25% (only connection is described). The description clarifies that the column parameter targets one known column, but it does not explain table/schema semantics, the optionality of schema, or naming conventions. This insufficiently compensates for the low coverage.

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

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

The description uses 'Measure' as a specific verb, identifies the resource as 'one known column', and enumerates the exact outputs (total/non-null rows, distinct count, min/max). It also names sibling tools columnDistribution and columnHistogram, distinguishing this from them.

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 this tool – for basic extremes and cardinality on one column – and when to use alternatives: columnDistribution for frequent values, columnHistogram for percentiles. The connection parameter guidance in the schema also directs the agent to listConnections for valid 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 declare readOnlyHint, idempotentHint, and non-destructive behavior Mend, so the description mainly adds scope context. It discloses that it works on one known object, returns metadata for that object only, and that full metadata is the output. No contradiction with annotations.

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

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

Two sentences with strong front-loading: the first states the primary action and benefits, the second clarifies scope and the sibling alternative. Every phrase earns its place and there is 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?

For a metadata inspection tool with rich annotations and an output schema, the description is largely complete. It provides scope, alternative routing, and behavior. The only meaningful gap is the undocumented 'schema' parameter, which 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 only 33%: only 'connection' is described in the schema. The tool description does not compensate by explaining what 'table' and 'schema' mean, whether schema is optional, or how the table identifier should be qualified. This leaves a gap for an agent selecting 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 opens with a specific verb and resource: 'Inspect one known table or view.' It clarifies the scope and lists concrete metadata facets (fields, columns, types, nullability, defaults, comments, keys, indexes, constraints, triggers), making it distinct from sibling tools like tableContext.

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 states when to use this tool ('Inspect one known table or view') and explicitly names the alternative for related needs: 'use tableContext when nearby relationships or joins are also needed.' This gives clear routing 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 and destructiveHint=false, and the description adds the important behavior that no query is executed and that results are planner estimates rather than actual row counts. It also discloses the output shape (rows, baseline, ratio) beyond what the input schema provides, though it does not address error behavior or limits.

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

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

Two tightly packed sentences lead with the core action, then state the return values and usage context without repetition or filler. 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 read-only estimation tool with idempotence annotations and an output schema present, the description provides the essential behavioral distinction (no execution), the output semantics, and the two primary use cases. Nothing critical is missing for an agent to decide whether and how to call it.

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 schema description coverage at 50%, the schema already documents predicate and connection. The description clarifies that the predicate is a proposed table filter and that the baseline is the unfiltered count, but table and schema parameters remain mostly implicit and are not described in the text, so the description only 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 opening verb 'Estimate' plus the object 'selectivity of one proposed table predicate' states exactly what the tool computes, and 'without executing the query' sets it apart from execution-oriented siblings such as executeQuery and timedQuery. The return values and intended use cases further clarify the resource being analyzed.

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 when evaluating filters or composite-index column order' gives explicit context for choosing this tool. It does not name alternatives or explicit when-not-to-use conditions, but the 'proposed... without executing' wording makes the boundary versus query execution clear enough.

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 read-only and non-destructive behavior, and the description adds meaningful behavioral context: 'Sets truncated when the row cap is hit.' The binding rule 'never mix' also discloses a constraint not present in the annotations. No contradiction.

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

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

Three dense sentences cover purpose, alternatives, binding semantics, example, and truncation behavior. The most important usage guidance is front-loaded, and 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 complete for an agent invoking the tool: it states the query types allowed, the sibling tools for timing, parameter binding rules, and the truncation signal. The output schema and annotations cover return values and safety, so 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 coverage is 83%, but the description adds real value by explaining the relationship between '?' placeholders and params, ':name' placeholders and namedParams, and gives a concrete example with the bare-name rule. This goes beyond the schema's short 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 SQL SELECT / WITH / EXPLAIN when actual result rows are needed.' It also distinguishes the tool from timedQuery and benchmarkQuery, making it clear this is the general row-returning query tool.

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

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

It explicitly says 'Use timedQuery for one timed execution or benchmarkQuery for repeated latency measurements,' giving an agent concrete alternative-selection criteria. The phrase 'when actual result rows are needed' further clarifies 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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond that: the return is a full engine-specific textual plan, and parameter binding follows strict '?' vs ':name' conventions that must not be mixed. This is meaningful operational transparency for an agent.

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 three sentences with no filler. It front-loads the core purpose, then gives usage guidance, then explains parameter binding with an example. Every sentence contributes 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?

Despite having no output schema, the description tells the agent the return kind ('textual execution plan') and the tool's scope. Combined with the schema's parameter descriptions and the annotations' safety profile, the agent has enough information to select and invoke the tool correctly. The explicit binding rule and sibling alternative complete the picture.

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 80%, so the schema already documents most parameters. The description adds value by clarifying the binding model: '?' maps to params, ':name' maps to namedParams, and the example shows that the key is the bare name without the colon. This goes beyond the schema descriptions and reduces ambiguity.

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: 'Return the full engine-specific textual execution plan for a SELECT / WITH statement.' It also distinguishes itself from analyzePlan by contrasting raw plan detail with compact performance findings, making sibling differentiation clear.

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

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

It explicitly states when to use the tool ('Use when raw plan detail is needed') and names the preferred alternative for compact performance findings ('prefer analyzePlan'). This gives an agent concrete routing guidance rather than leaving the choice implied.

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 destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it traverses 'declared FK and optional observed join edges in both directions,' which clarifies the search mechanics and the includeObserved parameter intent.

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 purpose is front-loaded, the traversal behavior is summarized, and the sibling routing is delivered in a compact closing clause.

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

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

Given the tool has a rich output schema and annotations covering read-only, idempotent, and non-destructive behavior, the description provides the needed selection and invocation context without forcing the agent to infer usage. It explains when to use it, what it traverses, and how it differs from a key sibling.

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 56%, so several parameters (fromTable, toTable, fromSchema, toSchema) lack schema-level descriptions. The description compensates by framing these as 'endpoint tables' and clarifying the task involves unknown 'intermediate relationships,' which directly informs how to set fromTable and toTable. It does not elaborate schema parameters, but the core ambiguity is 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 names a specific action and resource: 'Find join paths when both endpoint tables are known but the intermediate relationships are not.' It clearly distinguishes the tool from tableContext by stating that the immediate neighborhood case belongs to that sibling, so an agent can tell them apart without inspecting 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?

It states the precise condition to use the tool ('when both endpoint tables are known but the intermediate relationships are not') and explicitly points to the alternative ('for one table's immediate neighborhood, use tableContext'). This gives actionable selection 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 indicate read-only, idempotent, non-destructive behavior. The description adds meaningful details beyond that: it searches stored queries rather than live data, checks specific SQL clauses, and emphasizes that column references are 'actual' rather than merely declared. This aligns with annotations and enriches the agent's expectations.

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

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

The description is two sentences, front-loads the core behavior in the first sentence, and uses the second sentence for actionable guidance. Every phrase earns its place with no repetition of schema or annotation details.

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

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

Given the presence of an output schema, return-value details are not required. The description covers scope, filtering behavior, and a discovery workflow. It is slightly incomplete in not explicitly steering the agent away from sibling tools like findQueriesByTable, but the core calling context is sufficiently covered.

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

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

Schema description coverage is only 25%, so the description must compensate. It clarifies that 'column' is the search target and that schema/table act as optional, case-insensitive filters. The connection parameter is already documented in the schema, but the description could still say more about how table/schema values are matched.

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: find stored application/report queries that reference one column and show where the column appears (SELECT, WHERE, JOIN, ORDER BY, HAVING). This specific verb+resource combination distinguishes it from sibling tools like findQueriesByTable and searchObjects.

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 useful context: use describeTable to discover declared columns, and schema/table filters are optional and case-insensitive. It does not explicitly name alternatives or exclusions, but the workflow and filter behavior are clear enough for an agent to call it appropriately.

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 non-destructive. The description adds meaningful behavioral details beyond that: results are based on 'actually reference[d]' tables, names are matched case-insensitively, and the focus is on observed query usage rather than declared schema. This gives the agent useful runtime expectations.

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

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

Two focused sentences deliver the core purpose, usage guidance, and a key matching rule without redundancy. The main action is front-loaded alerting an agent immediately what the tool is for.

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

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

Given the output schema exists and annotations cover safety, the description is largely complete for invoking the tool correctly. It covers purpose, usage boundary, matching behavior, and required input intent. The only minor gap is not naming a sibling alternative for declared table structure, but this is not essential to making a correct call.

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

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

Schema description coverage is only 33%, so the description must carry parameter meaning. It partially does by explaining that the tool resolves a 'known table' and matches names case-insensitively, but it does not clarify the optional 'schema' parameter or how it constrains the search. The connection parameter is already documented in the schema.

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

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

The description opens with a specific verb and resource: 'Find stored application/report queries that actually reference one known table.' It also clarifies the intended purpose ('observe filters, joins and business usage') and explicitly contrasts with table structure inspection, making it easy to distinguish from schema-focused siblings like describeTable.

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 states when to use the tool: to learn observed filters, joins, and business usage. It also gives a when-not: 'not to inspect declared table structure.' However, it does not explicitly name the alternative tool for inspecting structure, so it falls just short of fully explicit routing.

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, idempotent, and non-destructive. The description adds the specific output behavior (only returns uncovF FKs, includes suggested index columns), which is useful beyond annotations. It does not mention edge cases or side effects, but for a read-only audit tool this is adequate.

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 the core purpose first and the alternative second. No redundant wording, every sentence 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?

An output schema exists, so return-value details are covered. The description explains behavior, output filtering, and an alternative tool. The only notable gap is the undocumented schema parameter, which 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 67%, with table and connection documented in the schema but the schema parameter is undocumented. The tool description adds no additional parameter semantics beyond the schema, leaving the schema parameter ambiguous. A score of 3 reflects the adequate but not complete parameter guidance.

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

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

The description states a specific audit task (child-side foreign keys), the precise filter (FKs not covered by an index starting with FK columns in order), and the output (suggested index columns). It also distinguishes itself from describeTable by noting what describeTable is for, making its purpose unambiguous relative to at least one sibling.

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 ('use describeTable to inspect all keys and indexes of one table') and a usage condition for the table parameter ('Omit to scan the schema'). It does not enumerate when-not conditions for other sibling tools like redundantIndexes, but the context for when to use this tool is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what the returned record contains (SQL, parameters, parsed components, outputs, field usages), which is behavioral detail beyond the annotations. It does not contradict annotations and does not discuss edge cases like pagination, 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?

Two sentences with zero waste: the first states purpose and return content, the second gives routing to sibling tools. The most important info is front-loaded, and 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 read-only retrieval tool with a full output schema and complete parameter documentation, the description is complete. It covers purpose, what is returned, and how to discover the required identity. The existence of an output schema means return-value details need not be repeated, and annotations cover safety. Nothing an agent needs to call it correctly 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 100%, with each parameter (connection, sourceKind, sourcePath, sourceUnit) having a description. The description adds the concept of 'source identity' and that these parameters identify the query, but it does not add syntax or format details beyond what the schema already provides. Since the schema carries the heavy lifting, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Retrieve') with a clear resource ('the complete stored record for one query') and explicitly enumerates the returned content (SQL, parameters, parsed tables/columns/joins, outputs, field usages). It also names sibling tools (listQueries, findQueriesByTable, findQueriesByColumn) as the discovery path, distinguishing this retrieval tool from search tools.

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

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

The description explicitly tells the agent when to use this tool: when the source identity is already known, and instructs to use listQueries, findQueriesByTable, or findQueriesByColumn to discover matching records first. This provides clear context and exclusions, leaving no ambiguity about when to select this tool over its 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds one useful behavioral nuance: the body is included 'where available', implying some routines may have no body. It does not contradict annotations, though it does not discuss error behavior or permissions.

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 primary behavior is front-loaded and the discovery pointer is a single clear clause. 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 core return value (source code, body where available) and directs agents to listRoutines for discovery, while annotations cover the safety profile. The main gap is the undocumented optional schema parameter and absence of not-found/error behavior, but for a simple read-only getter this is nearly 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 only 33%, with only connection documented. The description adds meaning for name by calling it a known routine and pointing to listRoutines, but the optional schema parameter is never explained and name lacks format details. With low schema coverage, the description only partially compensates.

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

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

The description states a specific action ('Return the source code') on a defined resource ('one known function, procedure or package') and clarifies scope with 'including its body where available.' It also points to listRoutines for discovery, which helps differentiate it from search-oriented 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?

It explicitly tells agents to use listRoutines to discover routine names, which provides clear context for when to use that sibling first. It does not spell out exclusions like triggers/views, but the 'known' routine requirement implies this tool is for direct retrieval, not discovery.

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 convey read-only, idempotent, and non-destructive behavior. The description adds a small amount of context: it returns the 'full definition/body' and requires a 'known' trigger. It does not contradict annotations, nor does it provide extra detail on errors or missing-trigger behavior.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the routing guidance is placed second. Every clause adds value.

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

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

For a read-only lookup by identifier, the description is sufficient: it tells the agent what to retrieve and directs it to find identifiers when absent. Gaps are minor: it does not explicitly describe return format, missing-trigger behavior, or whether schema is optional, but the simple nature of the tool and the annotations reduce the burden.

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

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

Schema description coverage is only 25% (connection only). The description partially compensates by saying 'one known table trigger' and routing to describeTable for trigger names, which implies what table and trigger mean. However, it leaves schema semantics, the optional nature of schema, and trigger/table formatting details to be inferred.

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-resource pair: 'Return the full definition/body of one known table trigger.' It is clearly distinct from the metadata-focused describeTable, and the phrase 'table trigger' differentiates it from sibling tools like getRoutineDefinition or getViewDefinition.

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 second sentence gives an explicit precondition: use describeTable first when you need trigger names or compact metadata. It makes clear the tool expects a known, specific trigger, which is exactly the guidance an agent needs to decide between this tool and its sibling metadata 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'known view' constraint and the return type (SQL text), which is useful but not deeply behavioral; it does not describe error cases or catalog assumptions.

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 behavior is front-loaded, and the alternative tool is mentioned immediately after the main statement. 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 read-only metadata tool with rich annotations, the description is mostly complete: it states what is returned, scopes the operation to known views, and names the sibling for metadata. The main gap is the lack of parameter-level guidance for name/schema, but the overall shape is adequate.

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

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

Schema description coverage is only 33%, with only 'connection' described in the schema. The description does not explain the 'name' or 'schema' parameters or how they relate to the 'known view' concept, so it fails to compensate for the low coverage.

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

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

The description uses a specific verb ('Return') and resource ('SQL text that defines one known view or materialized view'), making the tool's function immediately clear. It also distinguishes itself from describeTable by explicitly routing metadata needs elsewhere.

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: use this when you need the defining SQL of a known view/materialized view. It also names describeTable as the alternative when exposed fields, keys, or object metadata are needed, which is an explicit when-not condition.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds context about the nature of the returned data (live counters) but does not describe pagination, empty-result behavior, or permission requirements. Given the annotation coverage, a 3 is appropriate – it adds some value but not extensive behavioral detail.

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 zero redundancy: the first states the core purpose and scope, the second provides the key alternative. The most important information (what it does and its scope) is front-loaded, and 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 read-only inspection tool with an output schema present, the description covers the essential use case and scope (table or schema), and explicitly points to the alternative when live stats are not needed. It omits any mention of performance implications or result size, but these are not critical for a tool of this type, and the annotations cover safety. The definition is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 67% (connection and table have descriptions, schema does not). The description clarifies that table is optional ('Omit to scan the schema') and that the tool works for 'one table or a schema', giving meaning to the schema parameter beyond the schema field. However, it does not explicitly document the schema parameter's format or interplay with table, so the compensation is partial. Baseline 3 is fair.

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 ('Inspect'), a clear resource ('index definitions'), and the precise data returned (operational size, usage, cardinality counters) for a table or schema. It explicitly differentiates itself from describeTable by contrasting 'live index statistics' with structural metadata, so an agent can distinguish it from a sibling 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?

Gives explicit when-to-use context (inspecting index stats) and names describeTable as the alternative for structural metadata without live stats. It does not address other index-focused siblings like unusedIndexes or redundantIndexes, but the primary differentiation is clear and the usage scenario is unambiguous.

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 adds the significant behavioral detail that the tool does not access a database and that the result is parser-derived. It also lists what the AST summary contains, giving the agent accurate expectations of the tool's 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: purpose, behavioral claim, output, and alternatives all appear in one efficient sentence. Every clause earns its place, with no redundant elaboration.

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 parser tool with an output schema and read-only annotations, this description is complete. It covers the tool's scope, output nature, and sibling alternatives, and the remaining connection nuance is at least partially handled by the schema's instructions.

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

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

The description explains what the SQL input is used for, but the connection parameter remains ambiguous: the schema says 'Database to run against' while the description says 'without accessing a database.' With only 50% schema description coverage, the description should clarify why the connection is needed despite no database access.

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 a specific action ('Inspect SQL syntax and structure') and a clear resource (SQL), and immediately distinguishes the tool from close siblings by listing what it returns and by naming validateQuery and queryLint as alternatives. An agent can tell exactly what this tool does without inspecting 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?

The description explicitly tells the agent when not to use this tool: 'use validateQuery for driver validation or queryLint for metadata-aware advice.' This provides concrete routing among siblings and enough context to select inspectQuery for syntax/structure inspection.

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 destructiveHint=false; the description reinforces this with 'no inspected database data is modified' and adds specifics about synchronous rebuild on next lookup, which is beyond the annotations.

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

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

Two sentences, front-loaded with purpose, no fluff. Every sentence contributes 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?

With one parameter, an output schema present, and annotations covering safety, the description fully covers purpose, trigger, scope, and behavior. Nothing an agent needs to call it correctly is missing.

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

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

The schema description already fully documents the single parameter at 100% coverage ('Call listConnections for valid names; do not guess'). The tool description adds no additional parameter context, so 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+resource ('Force the server-local usage index to be rebuilt') and distinguishes the scope ('runtime/local index' only). Clearly differentiates from a full rebuild by noting it invalidates and rebuilds on next lookup.

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 a clear trigger ('after its configured sources change') and clarifies that it only affects the runtime/local index, implying when to use it over a full rebuild. However, it does not explicitly name alternative tools like rebuildCatalog.

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, destructiveHint, and idempotentHint. The description adds behavioral value by stating it returns planner estimates (not actual results) and compares against the Cartesian product, which goes beyond the annotation. No contradiction with annotations.

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

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

Two sentences, no filler, purpose front-loaded, and the alternative is stated succinctly. Every word contributes.

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 cardinality estimation tool, it covers the core behavior (what it estimates, that it doesn't execute, what it returns) and the key alternative. It does not mention error conditions or catalog prerequisites, but given the output schema is provided separately, it is sufficiently complete for an agent to use correctly in most cases.

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

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

Schema description coverage is 50%; the schema describes joinType, connection, leftColumn, and rightColumn, but not the table/schema parameters. The description mentions 'known tables' and 'equi-join' but does not clarify the meaning or relationship of parameters beyond what the schema already offers. It adds minimal value for parameter understanding.

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

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

The description states a specific verb ('estimate'), a specific resource ('output size and selectivity of a proposed equi-join between two known tables'), and explicitly notes it does not execute. It distinguishes itself from findJoinPaths by naming the alternative, making the purpose unambiguous.

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

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

It provides an explicit when-not condition ('use findJoinPaths when the join route itself is unknown'), giving clear usage context. However, it doesn't address other potential siblings like estimateSelectivity or analyzePlan, leaving some routing ambiguity for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context beyond annotations by stating it returns purpose, engine, default schema, and local-catalog availability, and notably that it works 'without opening a database 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?

Two sentences with no filler: the first states the core capability and output, the second gives a usage condition and return details. Information is front-loaded and 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 parameterless discovery tool with rich annotations and an output schema, the description fully explains what the tool does, when to call it, what behavior to expect, and what the results contain. 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?

The tool has zero parameters, so the baseline is 4. The description still adds useful semantic context by explaining that the output provides the valid name to pass as 'connection' to other tools.

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

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

The description states a specific verb ('Discover') and resource ('databases served here' and valid 'connection' names), clearly differentiating this discovery tool from siblings like listSchemas or listTables. It also specifies the exact output purpose: returning a valid name to pass as the 'connection' parameter.

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 condition: 'Call when the target connection is not already established.' This implies the inverse case clearly, but it does not name alternative sibling tools or explicitly state when not to call beyond that condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral value by disclosing that the result contains existing vocabulary and query counts, which is useful beyond the annotation-only picture.

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 sentence carries the purpose, the resource, and the intended reuse without any filler. Every word contributes, and the key discriminator ('for reuse in listQueries filters') appears at the end for natural reading.

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 documented parameter, an output schema, and safety annotations, the description is complete enough. An agent can infer what it returns, why to call it, and that it is non-destructive without needing additional context.

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

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

Schema description coverage is 100% for the single required parameter, and the schema already documents that 'connection' is a database name and instructs agents to call listConnections rather than guess. The tool description itself adds no parameter-level detail, so the baseline 3 applies.

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

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

The description states a specific verb ('Discover') and a precise resource: 'existing business-domain vocabulary and query counts.' It also names the downstream use ('reuse in listQueries filters'), which clearly distinguishes it from plain enumeration tools like listKnownKinds or listKnownTags.

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

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

The description gives clear context by saying the output is meant for reuse in listQueries filters, so an agent knows when it is relevant. It does not explicitly say when not to use alternatives like listKnownKinds or listKnownTags, but the intended use case is specific enough to route selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context by mentioning query counts and the usage-catalog source, but it does not disclose potential caveats like cache freshness or open-world value variability, which would have added more value.

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

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

A single, front-loaded sentence with no filler. Every phrase earns its place: what is discovered, what is included, and why the result matters.

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 tool with a rich output schema and strong annotations, the description is complete. The agent knows when to call it, what it returns, and how the result should be used.

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 single connection parameter is well documented, including guidance to call listConnections for valid names. The description itself does not add new parameter-level meaning, but the schema already carries the full burden.

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

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

The description uses a specific verb ('Discover') with a specific resource ('valid usage-catalog source-kind values and their query counts') and states the intended downstream use ('for reuse in listQueries filters'). This clearly differentiates it from sibling tools like listKnownDomains, listKnownTags, and listQueries.

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 clearly indicates when to use this tool: when valid source-kind values are needed for listQueries filters. It provides clear context but does not explicitly name alternatives or state when not to use it, so it stops short of the strongest 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, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral traits such as performance expectations, cache dependence, or return volume, but it doesn't contradict the annotations either.

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 sentence of 14 words, with the core action and resource front-loaded and the context at the end. There is zero filler; every word contributes to explaining what the tool does or why it should be used.

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 discovery tool with a rich output schema and full annotation coverage, the description is complete. It tells the agent what will be returned (tag vocabulary and counts) and how to use it (for listQueries filters), leaving no critical gap 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?

The only parameter, connection, is fully documented in the schema with a description that even points to listConnections for valid values. The tool description adds no additional meaning beyond the schema, which has 100% coverage, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Discover') and resource ('business-tag vocabulary and query counts') and immediately states its integration purpose ('for reuse in listQueries filters'). This clearly distinguishes it from siblings like listKnownDomains and listKnownKinds, which handle other vocabularies.

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

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

The description gives a clear context for when to use the tool: when building filters for listQueries. However, it does not explicitly mention alternatives or when not to use it (e.g., when domains/kinds are needed), so it stops short of full 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, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by specifying that results are 'summaries newest-ingest first' and that the complete SQL and evidence require a follow-up getQuery call. This informs ordering and return granularity without contradicting the annotations.

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

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

The description is two sentences with no filler. The first sentence states the tool's purpose and filter dimensions; the second explains result ordering and directs the agent to getQuery for deeper detail. This is efficient, front-loaded, and every clause adds useful 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?

For a read-only browsing/search tool, the description is complete: it explains the resource, the search dimensions, the result type ('summaries'), the sort order ('newest-ingest first'), and the relationship to getQuery for full detail. An output schema exists, so return-value details are not required in the description. Combined with the schema's thorough parameter documentation and the non-destructive annotations, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents all nine parameters. The description does add a light conceptual grouping ('source, business metadata, parse status or free text'), but this mostly mirrors parameter names like sourceKind, sourcePath, businessDomain, parseStatus, and searchText. It does not introduce new semantic detail such as value formats, LIKE patterns, or interaction between filters beyond the schema.

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

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

The description states a specific verb ('Browse or search') on a specific resource ('stored usage-catalog queries') and lists the filtering dimensions: source, business metadata, parse status, and free text. It also distinguishes itself from getQuery by noting that listQueries returns summaries while getQuery provides complete SQL and evidence. This makes the tool's purpose immediately clear and separable from its 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 gives clear context for when to use the tool versus getQuery: use listQueries for browsing/searching summaries, then getQuery for full SQL and evidence of a selected record. It does not explicitly mention exclusions against searchObjects or other sibling search-like tools, but the emphasis on 'usage-catalog queries' implies the intended scope. The guidance is clear enough for an agent to make a sound initial selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the resource types (functions, procedures, packages) and optional pattern filtering, which goes beyond annotations. It doesn't describe pagination or ordering, but 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?

Two sentences, zero waste. Purpose is front-loaded, and the alternative is given immediately after. Very efficient.

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

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

For a listing tool with an output schema and read-only annotations, the description covers key decision points: what is listed, optional pattern, and when to use the alternative. It doesn't mention pagination or limits, but those are likely in the output schema. It's sufficiently complete for an agent to call correctly.

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

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

Schema coverage is 67%, so the baseline is 3. The description mentions 'in a schema' and 'by name pattern' which adds meaning to the schema and namePattern parameters. The connection parameter is documented in-schema with a directive to call listConnections. The schema parameter lacks in-schema documentation but is implied in the description, though not explicitly detailed.

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 'Discover function, procedure and package names in a schema' – a clear verb, resource, and scope. It also explicitly distinguishes from getRoutineDefinition, making it easy to select the right tool.

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

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

Explicitly states when to use the alternative getRoutineDefinition ('when the source of one known routine is needed') and mentions the optional name pattern, which implies when to use it. Doesn't exhaustively cover all sibling listings but gives the primary decision.

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 destructiveHint=false, covering the safety profile. The description adds a small behavioral detail: it lists schemas 'visible to the current user,' which is helpful. It does not describe pagination, ordering, or potential system schema inclusion (though that is covered in the parameter). Given the annotations carry the main burden, a 3 is appropriate – the description adds some context but not rich behavioral detail.

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 redundancy. The primary purpose is stated first, and the follow-up action is provided succinctly. Every word earns its place, and it is appropriately short for a simple discovery tool.

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 low-complexity tool with an output schema (not shown but indicated), the description covers when to use it, what it returns, and the next step. It lacks explicit mention of error handling or permissions, but the annotations cover safety. The only minor gap is not stating what happens if the schema is already known, but that is implicit in the phrase 'when the target schema is unknown.' Overall, it is complete enough for correct usage.

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

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

The input schema covers 100% of parameters with descriptions, including guidance to call listConnections for valid names and the default for includeSystem. The tool description itself does not add parameter-level information beyond the purpose. Since the schema already provides the needed semantics, the baseline of 3 applies without additional value from the 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?

The description states a specific verb ('Discover') and resource ('schema names'), and clearly scopes the use case: 'when the target schema is unknown.' It also distinguishes itself from a sibling tool by mentioning listTables for the next step, making it unambiguous which tool to use for schema discovery versus object enumeration.

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 condition for use ('when the target schema is unknown') and suggests a follow-up action ('Use listTables next'). It also indirectly references listConnections in the parameter description for valid connection names. However, it does not explicitly mention when not to use this tool or alternatives like searchObjects, though the context is fairly clear.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar for the description is lower. The description adds the one non-obvious behavioral trait beyond those hints: the schema parameter is optional, and omitting it changes the result scope to 'across all schemas.' No contradiction with the 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?

A single 17-word sentence with the verb and resource front-loaded, followed by the scoping conditional. Every word earns its place — no filler and no repetition of what the schema or annotations already state.

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 2-parameter, read-only discovery tool, the description plus an output schema and safety annotations cover everything an agent needs: connection-parameter behavior is in the schema, schema-omission behavior is in the description, and return values are covered by the output schema. Nothing required for correct invocation 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 only 50% — the schema parameter has no schema-level documentation. The description compensates by explaining the schema parameter's semantics ('in one schema, or across all schemas when schema is omitted'), telling the agent that omission is valid and changes the scope. The connection parameter is already documented in the schema, so the description need not repeat it.

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 pairs a specific verb ('Discover') with a precise resource ('sequence names and metadata') and states the scoping behavior ('in one schema, or across all schemas when schema is omitted'). This is a specific verb+resource that distinguishes it from sibling list tools like listSchemas, listTables, and listRoutines by its unique resource type.

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 schema-scoping statement ('across all schemas when schema is omitted') gives useful context on how to invoke the tool for different result sets, and the resource name clarifies its niche relative to list* siblings. However, it never explicitly names alternatives or states when NOT to use it, leaving tool selection among the 50+ siblings to inference.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds useful behavioral context beyond that: it returns only names, not columns, and supports optional filtering by name or type. This is modest but meaningful added disclosure.

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, and the core purpose is front-loaded in the first phrase. Every word contributes to clarifying scope or routing to an alternative.

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

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

For a read-only listing tool, the description covers purpose, filter options, and the key limitation (no columns). The output schema exists, and the parameter schema covers all inputs, so nothing essential for correct invocation 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 100%, so all four parameters are fully documented in the schema itself. The description's phrase 'filtered by name or type' roughly maps to namePattern and types, but it adds no new semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Enumerate') and names the resource ('table and view names'), with a clear scope ('in a known schema'). It also explicitly distinguishes itself from describeTable by stating it does not return fields/columns, which prevents confusion with a close sibling.

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

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

The description gives explicit when-not guidance ('Does not return fields/columns') and names the specific alternative to use ('use describeTable for one object's structure'). This tells the agent exactly which tool to select for a different need.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral detail beyond that: it performs a single scan, scans every column, returns null/non-null counts and ratios, and sorts by sparsity. These are meaningful execution traits that help an agent anticipate behavior and cost. No contradiction with annotations.

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

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

The description is a single, dense sentence that front-loads the core purpose, then specifies the output, then gives the routing alternative. There is zero fluff; every clause earns its place. It is highly efficient and easy to parse.

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

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

Given the tool's simplicity (3 parameters, 2 required), the description covers purpose, output shape (counts, ratios, sorting), scope (every column, one table), and usage routing. An output schema exists, so return details are already structured. Nothing an agent needs to correctly invoke this tool 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 only 33% (only the connection parameter has a description). The tool description does not add parameter-level semantics, but the parameter names (table, schema, connection) are self-explanatory, and the connection parameter has a useful schema description ('Call listConnections for valid names; do not guess'). The description implies that table and schema identify the target table, so the agent can infer usage. This is adequate but not enhanced beyond the schema.

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

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

The description uses a specific verb ('Find') and resource ('sparse or mostly-null fields across every column of one table'), clearly stating what the tool does. It also differentiates from a sibling by naming describeTable as the alternative when only declared nullability is needed, so an agent can distinguish it without inspecting 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?

It explicitly tells the agent when to use this tool (when actual null counts/ratios are needed) and when to use the alternative ('use describeTable when only declared nullability is needed'). This is direct routing guidance that leaves no ambiguity about selection among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it is 'empirically observed' from stored queries and that non-equi joins are excluded, which is useful context. However, it doesn't disclose details like whether results are paginated, how support counts are computed, or whether the catalog must be fresh. With annotations covering the safety profile, 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 sentences with zero waste. The core purpose is front-loaded, and the alternative tool is named in the second sentence. 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 tool has an output schema, so the description needn't explain return values. The description covers purpose, scope, exclusions, and the alternative tool. The only minor gap is that it doesn't mention whether the results are limited to the current catalog or whether the catalog needs to be populated, but given the output schema and annotations, this is nearly 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 100%, so the schema already documents all four parameters. The description adds the context that the tool returns support counts and contributing query IDs, which helps understand the minSupport parameter's meaning, but it doesn't add syntax or format details beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('Discover'), a specific resource ('empirically observed equi-join column pairs from stored queries'), and the output includes support counts and contributing query IDs. It also explicitly distinguishes itself from findJoinPaths, which is a sibling tool, by noting that findJoinPaths is for declared/combined paths and that non-equi joins are excluded. This makes the tool's purpose unambiguous and differentiates it 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 explicitly says 'Use findJoinPaths for declared/combined paths between endpoints; non-equi joins are excluded.' This provides clear when-to-use and when-not-to-use guidance, naming the alternative tool and the condition that selects it. The connection parameter also instructs to call listConnections for valid names, which is a usage guideline.

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 establish readOnly/idempotent/non-destructive behavior, so the description need not repeat safety information. It adds behavioral context that this is a context-building/selection operation rather than a query or analysis operation, and clarifies the multi-table scope. It does not detail all internal behavior, but that is not required given the rich 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?

Two sentences with no filler, and the core operation plus the primary usage condition appear first. Every sentence earns its place by either defining the tool or guiding routing.

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 schema-introspection tool with an output schema, six parameters, and strong annotations, the description plus input schema fully cover selection and invocation. The only required parameter (connection) is marked required and referenced in its own schema description with a pointer to listConnections.

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 83%, and the schema already documents terms, tables, maxTables, connection, and includeSamples. The description adds only a high-level mapping from terms/tables to the purpose, which is useful but not materially beyond the schema; baseline 3 is appropriate.

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

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

Description opens with a specific verb and object ('Build multi-table SQL-authoring context') and specifies two input modes (natural-language terms, explicit table list). It names describeTable as the alternative, so the tool is distinguishable from its closest sibling without opening the 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 when relevant tables are unknown or a request spans several tables' gives explicit trigger conditions, and 'for one known table's fields or structure, use describeTable' gives an explicit exclusion and alternative. No inference is required.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds valuable behavioral detail by listing the specific problem categories it reports (unknown objects, SELECT *, conditionless joins, etc.) and reiterates that it does not execute the SQL, which is consistent with the annotations.

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

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

The description is a single, dense sentence that front-loads the purpose and then enumerates the checks. It is efficient and well-structured, though the long list of issue types adds length without being verbose.

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