query

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

Annotations already declare readOnlyHint/idempotentHint, and the description goes well beyond them: it lists refused statement types (including PRAGMA assignments and load_extension), the row and ~200 KB result caps, the timeout interruption behavior, BLOB rendering as size plus hex prefix, and text truncation with length. These are exactly the runtime behaviors an agent must anticipate to avoid misreading results or issuing rejected SQL.

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 action and the hard constraint, followed by output-shaping behavior and a compact parameter block; every sentence carries information an agent needs, with no restatement of the name or redundant framing.

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 and the description still usefully explains result truncation and cell rendering, so return-value behavior is well covered. The remaining gap is the undocumented required `path` argument and no hint about how to page past the max_rows cap.

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 carries the full burden, and it does document format options with the markdown default, max_rows (1-5000) and timeout_seconds (0.1-60) ranges. However, the required `path` parameter is never explained in either schema or description — an agent cannot tell whether it is a database file, an alias, or a directory — and the sql parameter is only characterized indirectly through the allowed-statement sentence.

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?

Opens with a specific verb and resource: 'Run one read-only SELECT / WITH / VALUES statement', and enumerates the statement classes that are refused, so an agent knows exactly the operation class covered. It stops short of naming sibling tools (explain_query, find_in_db) that handle adjacent tasks, so the boundary is only inferable from knowing those 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?

'Prefer aggregates (COUNT, GROUP BY) over pulling raw rows' gives concrete positive guidance on how to use it well, and the read-only refusal list effectively defines when the tool will not work. There is no explicit routing statement such as 'use explain_query to inspect a plan' or 'use find_in_db to locate an entity', leaving sibling selection to inference.

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