Retrieve a PostgreSQL execution plan for a SQL query. Set analyze to true for actual execution results (requires server permission); false returns cost estimates to identify performance bottlenecks.
获取 JSON 执行计划。analyze=false 只估算，true 会执行且需服务端许可。
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| analyze | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description usefully discloses that analyze=false only estimates while analyze=true executes and requires server-side permission. However, this contradicts the readOnlyHint=true annotation: if analyze=true actually executes the provided SQL and the tool does not restrict sql to SELECT statements, it may modify state. This is an annotation contradiction.
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 short sentences with no filler. The core function is front-loaded, and the second sentence efficiently adds the parameter behavior and permission caveat. Every clause earns its place.
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?
The description covers the critical execute/permission caveat and the JSON output type, and annotations address read-only/destructive concerns. However, with no output schema and no description of sql semantics, an agent lacks enough detail to confidently call the tool, especially for analyze=true cases.
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 explains the analyze parameter well (false=estimate, true=execute+permission) but says nothing about the sql parameter—its format, constraints, or whether only SELECT statements are allowed. Compensation is only partial.
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 states a specific function—getting a JSON execution plan—using a clear verb and resource. It is distinguishable from siblings like query or diagnose, though the phrase 'true 会执行' introduces some ambiguity about whether the tool actually runs the SQL statement.
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?
No guidance is provided on when to use explain instead of query, diagnose, list_tables, or describe_table. The description explains analyze modes but does not state prerequisites, exclusions, or decision criteria for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.