explain

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

No annotations are provided, so the description carries full burden. It discloses that the tool returns a query plan in JSON format and that it does not execute the SQL, implying a read-only, non-destructive operation. It also reveals that connection and schema routing mirror run_select, which is helpful. However, it does not explicitly state that it is read-only or safe, nor does it discuss error behavior.

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 concise with two sentences. The first sentence front-loads the core purpose (EXPLAIN FORMAT=JSON for SELECT, query plan, no execution). The second adds routing context. Every sentence adds value, and there is no fluff.

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 complexity of an EXPLAIN tool with no output schema, the description adequately covers the output contents (indexes, join order, estimated rows) and the JSON format. It ties routing to run_select, which leverages existing knowledge. However, it omits details like whether only SELECT is supported, error handling, or how the JSON is returned (string vs parsed). Still, it is fairly complete for an experienced database user.

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 description coverage is 0%, so the description must compensate. It only mentions that schema and connection follow the same routing as run_select, but does not explain their individual roles or constraints. The sql parameter is implied to be a SELECT statement, but no validation or format details are given. This lack of parameter guidance makes it difficult for the agent to use parameters correctly.

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 that the tool executes an EXPLAIN FORMAT=JSON for a SELECT statement to show the query plan (indexes, join order, estimated rows) without executing it. It distinguishes itself from run_select by explicitly noting it does not execute, and from other siblings like describe_table by focusing on query planning.

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 contrasts with run_select by stating 'without executing it,' which implies use when you want the plan without execution. It also mentions 'Same connection/schema routing as run_select,' providing context for parameter usage. However, it does not explicitly state when not to use or list alternative tools for other EXPLAIN formats.

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