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

With no annotations, the description carries the full load and does well: it declares READ-ONLY catalog access, states it never reads data rows, and discloses the failure mode (returns `need_from_user` naming what to ask). It stops short of permissions, rate limits, or latency characteristics, so it is strong but not exhaustive.

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

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

Front-loaded with the purpose and the FIRST-call directive before the rationale, and each sentence adds a distinct fact (content, trigger, safety, failure mode, targeting). The dense em-dash enumeration is slightly heavy but still 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 single-parameter read tool with an output schema already covering return shape, this covers purpose, trigger, safety, failure handling, and multi-DB targeting. The only notable omission is how it differs from the similarly named preflight_schema_only 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 coverage is 0% (the lone `target` property has no description), so the description must compensate, and it does: it explains that target=<name> is used in a multi-DB setup and how to discover the right value via list_targets. That is meaningful guidance beyond the bare 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?

States a specific verb and resource ('Read a database's REAL schema') and enumerates exactly what is returned (tables/collections, columns/fields, indexes, row counts). It also implicitly separates itself from data-returning siblings by emphasizing catalog-only content.

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

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

Gives an explicit trigger ('Call this FIRST when a user asks for data and you don't already know the schema') and names the complementary sibling ('combine with list_targets to find which DB has the data'). The condition for the target parameter is stated as well ('in a multi-DB setup').

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the output (two layers, bottom-up physical plan) and the multi-DB targeting rule, but never states whether the query is actually executed, its read-only/cost profile, or any permission requirements — meaningful gaps for an unannotated 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?

Front-loads the two output layers, then usage, then a one-word role marker, then the targeting note — each sentence carries information. It is slightly dense with parentheticals but nothing is redundant.

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 needn't be spelled out, and the description still usefully previews the two layers. Given no annotations, the only real omissions are side-effect/execution semantics and error behavior — minor for a read-only explain tool.

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

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

Schema coverage is 0%, so the description must compensate. It adds real meaning for 'target' ('Pass target=<name> in a multi-DB setup'), but says nothing about 'sql' beyond the obvious, and gives no format/syntax hints for either 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?

Names a precise verb+resource (explain how a query behaves) and breaks the deliverable into two concrete layers: logical gather order and the engine's physical plan. This is unmistakably a teaching/diagnostic tool, cleanly separable from siblings like preflight_query (validation) or rewrite_query (rewriting), even without naming 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?

Gives an explicit trigger: 'Call when a user asks why a query is slow or how it runs,' which tells the agent when this tool fits. It stops short of when-not-to-use guidance or naming the sibling alternatives (preflight_query, suggest_query) an agent might otherwise pick.

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

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

With no annotations, the description carries the full burden and does well: it discloses the policy object shape (name, scope, condition, action), the possible actions (block/warn/allow), and the important default that no configured policies means nothing is blocked. It does not explicitly state read-only/non-mutating behavior, but the verdict-attachment and default semantics are non-obvious context an agent needs.

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 compact sentences, front-loaded with the resource identity before the fields and the usage routing. Every clause adds information — definition, structure, default behavior, and the sibling relationship — with no filler.

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

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

An output schema exists, so return values need not be documented, yet the description still usefully summarizes the fields. For a no-param read tool it covers purpose, behavior defaults, and cross-tool routing, leaving an agent nothing essential 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 takes zero parameters, so there is no per-parameter semantics to convey; the baseline for a parameterless tool is 4. Nothing in the description is needed to call it correctly, and it introduces no misleading parameter hints.

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 ('List the operator's standing enforcement policies') and immediately characterizes what a policy is: name, scope, condition, action. It distinguishes itself from preflight_query and suggest_query by explaining those already apply policies while this one only enumerates 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?

Gives an explicit trigger ('call this to explain to a user WHY a query was blocked') and implicitly rules out using it as a check step by noting that preflight_query and suggest_query already apply the policies and attach the verdict. The when and the alternatives are both present.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses what the call returns (name, engine, diagnosability) and proactively rules out sensitive output ('Never returns connection strings or secrets'). It stops short of stating auth requirements or whether the target list is cached/live, which keeps it from a 5.

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

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

Three short sentences, front-loaded with what is listed, followed by when to call it and the security caveat. No filler or redundancy; every clause adds decision-relevant 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 zero-parameter discovery tool with an output schema, the description covers purpose, ordering, downstream usage, and output sensitivity. Nothing an agent needs to invoke 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 tool takes zero parameters, so the baseline is 4. The description usefully explains the target=<name> convention used by sibling tools, giving context for the values this call exposes, but there are no parameters of its own to document further.

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

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

States a specific verb and resource ('List the databases Anumana is configured to analyse') and enumerates returned attributes (name, engine, diagnosability). It also implicitly distinguishes itself from siblings like list_policies and the preflight_* tools by being the inventory/discovery call.

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 sequencing ('Call this FIRST in a multi-DB setup'), the downstream handoff ('then pass target=<name> to the other tools'), and the single-DB alternative ('you can omit target and the one database is used'). An agent knows exactly when to call it and what to do with the result.

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

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

With no annotations, the description carries the full burden and does so: it declares the tool never executes the query, describes the risk tiering, rows scanned vs returned, scan strategy, and the specific overhead flags it detects. That is exactly the behavioral context an agent needs before committing to a costly query.

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

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

Front-loaded with the primary directive, then returns, then the safety guarantee, then routing. Every sentence earns its place with no filler.

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

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

An output schema exists, so return-value enumeration is not strictly required, yet the description still previews the payload. Combined with the sibling routing and target guidance, nothing an agent needs to invoke this 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 0%, so the description must compensate. It explains target fully ('in a multi-DB setup pass target=<name>', pointing to list_targets), but leaves sql undocumented beyond the obvious name. Adequate but not complete.

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 (preflight/check cost), resource (SQL query against the real schema), and scope (EXPLAIN only, never executes). It explicitly distinguishes itself from preflight_vector_search and preflight_schema_only, so an agent can route without opening either 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?

Gives explicit when-to-use ('before running ANY SQL query you just wrote'), when-not-to-use (similarity search, no DB), and names the exact alternatives with the condition that selects each. The multi-DB case is covered with the target=<name> instruction.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that results are HEURISTIC only, that there are no live counts, and that it 'says so' in output. It also enumerates the specific classes of issues caught (SELECT *, missing LIMIT, un-indexed filters, LIKE '%...', functions on filtered columns).

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

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

Front-loads the differentiating capability (offline, zero-trust) and stays compact. The parenthetical 'the zero-trust, offline front door' is slightly marketing-flavored but earns space by signaling the routing distinction.

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 detail is not required. The description covers what the tool examines and its heuristic limitation, which is enough for correct invocation; only parameter-shape guidance is thin.

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

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

Schema coverage is 0% for 2 required params, so the description must compensate. It implies ddl = pasted CREATE TABLE DDL and sql = the query, but adds no format, sizing, or multi-statement guidance for either. Some meaning, but incomplete.

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 (analyse) plus resource (query vs CREATE TABLE DDL) and the defining constraint (NO database connection). It clearly distinguishes itself from preflight_query by scoping to the offline case where no target/credentials exist.

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

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

Gives an explicit trigger: 'Call when the user gave you their schema (DDL) but not DB credentials.' The 'No target needed' line reinforces when this applies versus a connection-requiring sibling, though it never names preflight_query as the alternative.

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

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

No annotations are provided, so the description carries the full burden, and it does well: 'EXPLAIN only' discloses that nothing is executed, and it enumerates the exact findings the agent can expect (FULL_VECTOR_SCAN, TOP_K_TOO_LARGE, UNBOUNDED_VECTOR_SEARCH, VECTOR_FILTER_INTERACTION). It doesn't state permissions or target-connection requirements beyond the multi-DB note.

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

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

Front-loads the core instruction ('check its cost WITHOUT running it') before the operator examples and trap list. Dense but nearly every clause carries information; the parenthetical operator enumeration is the only slightly heavy part.

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 detail is unnecessary, yet the description still names the warning categories the agent will see. For a two-parameter read-only diagnostic tool, nothing material is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for 'target' (name in a multi-DB setup, should be a pgvector engine) but says nothing about the required 'sql' parameter beyond contextual implication that it is the query to preflight.

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 (check cost) and resource (vector similarity search) and explicitly frames the scope as pre-execution 'WITHOUT running it'. The pgvector operator examples (ORDER BY embedding <-> $1, <=>, <#>) make the target workload unmistakable and distinguish it from generic SQL preflight 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?

Clearly says when to use it: before running any RAG / semantic-search / nearest-neighbour query, and contrasts it with 'a plain SQL check' which implicitly points to preflight_query. It stops short of naming that sibling explicitly or stating when NOT to use this tool (e.g. non-pgvector targets).

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

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

With no annotations, the description carries the full burden and does well: it discloses the equivalence-caveat output, the btree-vs-HNSW index heuristic, and that improvement is proven by comparing planner cost rather than asserted. It never states whether the rewrite is applied or merely returned, and says nothing about required permissions or whether execution touches the target DB.

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

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

Front-loaded with the core purpose and the trigger condition, then the return contents. Dense and mostly waste-free, though the long multi-clause middle sentence about index suggestions is information-dense enough to slow 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?

An output schema exists, so enumerating return fields (rewritten query, changes, before/after cost, index suggestions) is arguably redundant, yet the description still adds the equivalence-caveat and indexing-rule context. What remains missing is the read-only/apply question, which matters for a tool that inspects and rewrites SQL.

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

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

Schema description coverage is 0% with 2 parameters, so the description is the only source of meaning. It explains target adequately ('Pass target=<name> in a multi-DB setup'), but sql is left entirely implicit — no hint that it expects a concrete statement or what dialect/normalization is assumed.

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 (rewrite a slow query into a cheaper equivalent) plus the verification method (EXPLAIN both, compare planner cost). It is clearly distinguishable from siblings like preflight_query, suggest_query, and explain_query_working. An agent can tell exactly what this tool produces 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?

Explicitly states the trigger condition: 'Call after a preflight flags a query expensive/dangerous,' which links it to preflight_query/preflight_vector_search. It also scopes the multi-DB case via target=<name>. It stops short of naming when NOT to use it or explicitly contrasting with suggest_query as the lighter-weight alternative.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the return contract's semantics ('accept' = cheap/moderate, run it; 'refine' = expensive/dangerous with high-severity flags and a verified cheaper rewrite) and clarifies the division of labor ('You write the SQL; Anumana owns cost truth'). It omits error/auth conditions and whether the rewrite is applied automatically, keeping it short of a 5.

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

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

Front-loads the purpose, then the workflow, then the return semantics, with no filler sentences. It is dense with parentheticals and dash clauses, but each element (loop bound, multi-DB target, cost ownership) carries actionable 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?

An output schema exists, so the description need not enumerate return fields, and it still explains the meaning of next_action values. Given a 3-param tool with no annotations, the coverage of workflow, loop limits, and cost-ownership is nearly complete; only edge cases like malformed SQL or target resolution failures are unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: candidate_sql is framed as the query the agent wrote, intent as the user's data request, and target is given real meaning ('in a multi-DB setup'). It adds context the raw schema lacks, though it never states intent's expected format (natural language vs. structured).

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 ('grade a query ... whether to RUN it or REFINE it') and positions the tool as the check step of a generate->check->refine loop. The agent can distinguish it from write-side siblings like rewrite_query and from schema-side siblings like describe_schema_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?

Gives an explicit numbered workflow (describe_schema_tool -> write candidate -> call this), states the alternative branch ('refine' means fix and call again), bounds the loop to ~3 rounds, and tells the agent to pass target=<name> in a multi-DB setup. When-to-use and when-to-refine are both spelled out.

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