query

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the tool executes SQL queries, returns formatted tables, and is 'Read-only by default' (implying safety and restrictions). However, it could add more context, such as error handling, performance implications, or specific limitations beyond the default read-only mode.

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 appropriately sized and front-loaded, consisting of two concise sentences that directly convey the tool's purpose and key behavior. Every sentence earns its place by providing essential information without redundancy or unnecessary details.

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?

Given the tool's moderate complexity (SQL execution), no annotations, and no output schema, the description is mostly complete. It covers the core functionality, default behavior, and output format. However, it could improve by addressing error cases, result limitations (e.g., large datasets), or more details on the 'readonly' parameter's enforcement, which would enhance completeness for a tool with no structured output documentation.

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%, so the schema already documents all parameters ('db', 'sql', 'readonly') with descriptions. The description adds minimal value beyond the schema, as it doesn't provide additional syntax, format details, or usage examples for parameters. The baseline score of 3 is appropriate since the schema handles most of the parameter documentation.

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 description clearly states the specific action ('Execute a SQL query'), target resource ('against a SQLite database'), and output format ('Returns results as a formatted table'). It distinguishes from siblings like 'explain' (query analysis), 'list_databases' (database enumeration), 'schema' (structure overview), and 'table_info' (table metadata) by focusing on direct query execution.

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 provides clear context for when to use this tool ('Execute a SQL query against a SQLite database') and implicitly suggests alternatives through sibling tool names (e.g., use 'explain' for query analysis, 'schema' for structure). However, it lacks explicit guidance on when NOT to use it or detailed comparisons with alternatives, such as when to prefer 'explain' over 'query' for debugging.

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