SQL Query Plan EXPLAIN Optimizer & Bottleneck Diagnostics

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real operational context: stateless edge call, 32 KB payload cap, 60 RPM rate limit, L402 payment of 15 sats, demo mode, and HTTP 400 on invalid input. The only gap is that payment/demo mechanics are described as query-string behavior not reflected anywhere in the input schema, which could confuse an agent about how to supply them.

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?

Two sentences, front-loaded with purpose before the alternative and the operational constraints. The second sentence is a dense run-on cramming size limit, rate limit, parameter default, payment scheme, and error code together, which costs some scannability but no sentence is wasteful.

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?

With an output schema present, return values need not be explained. The description covers purpose, routing to the sibling, parameter default, resource limits, auth/payment, and error behavior — everything an agent needs to call it correctly. Only the demo/payment mechanism lacks a corresponding schema field.

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 100%, so baseline is 3; however the description adds a fact the schema omits — that 'optimization_target' defaults to 'eliminate_seq_scans' — which is genuinely useful for deciding whether to pass the argument. It adds no meaning for 'explain_plan_or_query' or 'database_engine' beyond the 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?

Specific verb + resource: 'Analyzes SQL EXPLAIN execution plans to detect sequential table scans, high-cost cartesian joins, and buffer memory bottlenecks.' This names the exact artifacts it detects, so an agent can distinguish it from siblings like audit_sql_injection_ast or validate_sql_query_ast without opening any schema.

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?

Gives explicit triggering conditions ('diagnosing slow queries, optimizing database performance, or evaluating query cost') and names the alternative with the condition that selects it ('for getting index recommendations, use recommend_database_indexes instead'). Nothing about routing is left to inference.

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