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

No annotations exist, so the description carries the full behavioral burden. It discloses a 15-second query timeout, a silent failure mode (all-null rows with no error), and the data-boundary behavior: market_* tables are not queryable here and will instead be recomputed from dispatch_prices, which is slower and easy to phrase incorrectly. This level of candid failure disclosure is exceptional.

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 dense but every clause earns its place: purpose and returns first, then scope and timeout rationale, then the silent-failure SQL trap, then the reachable/unreachable table boundary with fallback behavior. There is zero filler and the highest-risk information (scope/timeout) is front-loaded.

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 tool with no output schema and no annotations, the description covers the major operational realities: what it returns, timeout limits, silent-failure traps, and reachable data. The gaps are a concrete example of a well-phrased question and a more explicit shape of the returned result rows, which would push it to a 5.

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

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

Schema coverage is 100% and the single 'question' parameter is already documented ('Plain-English question max 500 chars'), so the baseline is 3. The description meaningfully raises it by telling the agent how to phrase questions appropriately scoped, which patterns trigger the correct SQL (window function) and which trigger silent failures, going beyond the schema without being redundant.

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 first sentence states a specific verb and resource ('Ask a natural-language question about NEM BESS data') and enumerates the returns (generated SQL, result rows, plain-English explanation). This clearly distinguishes it from the sibling getter/list tools, so an agent can tell them apart 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?

The description gives explicit usage constraints: scope questions to roughly one region-month or less to avoid the 15s timeout, and for per-day top-N/bottom-N queries it names the correct construction (window function ROW_NUMBER/RANK) and warns against the dangerous alternative (per-day correlated subquery returning all-null rows without error). It also explicitly lists which tables are reachable and which are not, and what happens if the agent asks about the unreachable ones.

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