analyze_sql_queries

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

With no annotations, the description carries the burden: it does disclose the full scope of inspection and hints at output (it 'lists navigation-style SQL queries'), which is more than most. It never states that it is read-only/non-mutating, what it needs from the target model, or whether it can run against a live vs. offline file — meaningful gaps for a tool with zero annotation coverage.

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 action, and the enumerated checks do earn their space by letting the agent judge relevance. But the second half is a breathless comma-run of a dozen items that reads as generated list-dump rather than structured prose, impairing scanability.

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 shape needn't be described, and the analytical scope is well covered. The missing pieces are the sole required parameter and any statement of read-only behavior — for a diagnostic tool with no annotations, that leaves a gap an agent must resolve by trial.

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?

There is one required parameter, 'instance', with 0% schema description coverage, and the description never mentions it — not what an instance is (Power BI Desktop? AS server? PBIX path?), not its format, not how to discover valid values. With a single undocumented param the agent is left to guess at invocation.

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 (review hand-written SQL embedded in M code, citing [Query=...] and Value.NativeQuery) and enumerates the exact anti-patterns it flags, so the agent knows precisely what class of problem it surfaces. It stops short of explicitly naming how it differs from nearby tools like find_query_diagnostics or analyze_folding_risk, though the 'can fold' note gestures at the latter.

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

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

Usage is only implied: an agent can infer 'call this when auditing native SQL in Power Query/M code,' but there is no statement of when to prefer it over analyze_folding_risk, diagnose_power_query, or find_query_diagnostics, and no prerequisites or exclusions. The check list helps the agent decide relevance but not selection.

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