run_audit_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. It implies a read-only audit operation via 'audit query' and reveals the allowlist constraint, but says nothing about required permissions, behavior on an invalid or non-allowlisted query_id, cost/runtime, or side effects.

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 front-loaded sentence with no filler; the scope constraint is stated immediately. It is efficient, though its brevity leaves real gaps that are penalized under other dimensions rather than here.

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?

Because an output schema exists, return values need not be described. However, for a single-parameter tool whose only parameter is unconstrained in schema, the definition should have enumerated or referenced the accepted query_id values more concretely, and given at least a hint of usage context relative to the other tools.

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% and query_id has no title/description beyond its name, so the schema contributes nothing. The description partially compensates by pointing to Q1..Q20 in audit-queries.md, but it does not state the accepted literal format (e.g. 'Q1' vs '1') or that the values form an enumerable set, leaving the agent to guess valid values.

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?

States a specific verb (run) and resource (audit query) with an explicit scope constraint: allowlisted queries Q1..Q20. An agent immediately knows this executes a predefined audit query rather than an arbitrary one. It does not explicitly differentiate from the sibling tools, but those (get_schema, probe_as_anon, scan_repo) share no surface ambiguity.

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 constrains inputs to the allowlist but never says when this tool should be chosen over siblings like scan_repo or get_schema, nor when an audit query is the right approach versus a direct schema read. No exclusions or prerequisites are stated.

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