run_query

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

With no annotations, the description fully discloses behavior: read-only, only SELECT statements, restricted SQL subset (no JOIN, GROUP BY, OR, aggregates), and that the server cannot modify data. These are critical limitations an agent must know, and they are clearly stated upfront.

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 front-loaded with the main purpose, followed by essential constraints and an example. Every sentence adds value with no filler. The structure is logical: purpose, restrictions, guidance, example, parameter description.

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?

The output schema exists, so return value details aren't required. The description covers purpose, usage, prerequisites, constraints, and parameter semantics — everything an agent needs to invoke the tool correctly in context. It is complete without being verbose.

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%, but the description fully compensates by explaining 'query' as a QuickBooks SELECT statement, detailing the allowed subset, and providing a concrete example. This adds substantial meaning beyond the bare schema type of 'string'.

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 'Run a read-only QuickBooks query' with a specific verb and resource. It explicitly positions itself as a catch-all for 'anything the other tools miss', distinguishing it from the purpose-built siblings. The scope and restrictions are immediately clear.

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 instructs to 'call describe_schema first' and to 'prefer the purpose-built tools where one fits' — providing clear when-to-use and when-not-to-use guidance. This goes beyond minimal naming of alternatives by explaining why (they do arithmetic this cannot).

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