Validate Sql

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

The annotations already declare a safe, non-destructive read with open-world access, so the safety profile is covered. The description adds meaningful behavior beyond that: it performs a dry run and reports Term certification status, which tells the agent the tool may execute against the datasource and returns governance metadata. It does not disclose cost, latency, or whether failures block execution.

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?

Purpose is front-loaded in the first clause, followed by a compact enumeration of checks. It is a single dense sentence but every clause names a distinct capability, so there is little waste, though it would scan better as a list.

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 values need not be explained, and the description covers the full set of validations an agent would want to know about. The only gap is operational context: whether validation is cheap, whether a dry run touches the datasource, and whether a failing check prevents execution.

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 both parameters, including the read-only SELECT constraint and the optional datasource default, so the schema carries the parameter burden. The description adds no parameter-level detail and does not mention the datasource parameter at all; baseline 3 applies.

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

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

States a specific verb and resource ('Check a query') and then enumerates the exact checks performed: read-only guard, unknown tables/columns, non-ontology joins, near-miss literals, fan-out under aggregates, dry run, and Term certification. That level of specificity clearly distinguishes it from run_sql and check_answerable.

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?

'Check a query before running it' establishes the workflow position relative to run_sql without naming the sibling. There is no explicit exclusion (e.g., when validation is unnecessary or when it should be skipped for trivial queries), so it falls short of a full when/when-not statement.

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