run_query

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state read-only and that it returns results, but doesn't document behaviors like whether multiple statements are allowed, statement timeouts, row-count limits, or error behavior for invalid SQL. With zero annotation coverage, this is a notable gap.

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?

A single sentence, zero wasted words. Every element earns its place: the action, the nature (read-only), the resource (business database), and the output (returns results). Optimal length for the information conveyed.

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?

There is an output schema present, so return-value documentation isn't required from the description. With 1 simple parameter and clear sibling context, the core task is adequately described. However, given zero annotations, some additional guidance about error handling or result-set behavior (e.g., max rows) would improve completeness for a database query tool.

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's only 1 parameter (sql) with 0% schema description coverage. The description mentions 'SQL SELECT query' which tells the agent the sql parameter should contain a SELECT statement, adding some value over the bare schema. However, it doesn't clarify format nuances (e.g., semicolons, parameterization, quoting) beyond what a user would naturally infer.

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 verb (run), resource (SQL SELECT query), and scope (read-only, business database). It distinguishes from siblings by specifying it's a SELECT query that returns results, while siblings list/describe tables. However, it could more explicitly note it differs from the schema-related 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?

The 'read-only' qualifier gives some usage guidance (safe to call, won't mutate data), and returning "results" implies it's for data retrieval. However, it doesn't explicitly state when to use this vs describe_table or list_tables, nor does it disclose any limits (large queries, timeouts, multi-statement restrictions).

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