Run SELECT tuned

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

Annotations already set readOnlyHint=true, but description adds significant behavioral details: SET LOCAL scoping so memory setting doesn't leak, hard cap at 2GB to prevent OOM, regex validation for memory units, and read-only validation via same allowlist as run_select. These go well beyond annotations.

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?

Description is concise yet comprehensive. First sentence states purpose, then usage context, then constraints, and ends with an example. Every sentence adds value; no fluff. Suitable length for the tool's complexity.

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 complexity (5 parameters, memory tuning, read-only validation) and presence of an output schema, the description covers the key aspects: purpose, parameter semantics, scoping, and constraints. It does not detail return values (handled by output schema) or error cases, but remains complete enough for correct invocation.

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?

With only 20% schema description coverage, the description compensates well by explaining work_mem and maintenance_work_mem: bounded, local scope, regex pattern, cap. It does not detail sql, max_rows, or database (database has its own schema description). Adds significant meaning beyond bare schema.

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?

Description clearly states it runs a read-only SELECT with tuned work_mem for heavy analytical queries. It distinguishes itself from run_select by explicitly mentioning the memory tuning and scoping via SET LOCAL. Verb 'run' + resource 'read-only SELECT with tuned work_mem' is specific and unambiguous.

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 says it's 'useful for heavy analytical SELECTs... that spill to disk under default work_mem.' It also mentions what is out of scope (non-transactional maintenance). However, it does not explicitly state when not to use it (e.g., simple queries where default work_mem suffices should use run_select instead).

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