PostgreSQL-Performance-Tuner-Mcp

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

The description adds valuable behavioral context beyond annotations. While annotations indicate idempotentHint=true and destructiveHint=false, the description clarifies that 'This actually executes the query!' and provides specific warnings about data modification queries. It also explains the tool's approach (EXPLAIN ANALYZE) and what analysis it provides, which annotations don't cover.

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 well-structured and front-loaded with the core purpose, followed by implementation details, analysis components, and critical warnings. Every sentence adds value: the first states purpose, second explains method, third lists analysis areas, fourth provides crucial safety guidance. No wasted words.

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 (executes queries, provides performance analysis) and rich annotations, the description is mostly complete. It explains what the tool does, how it works, what it analyzes, and critical safety considerations. The main gap is lack of output format details (no output schema exists), but the description compensates somewhat by listing analysis components.

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 100% schema description coverage, the input schema already documents all 6 parameters thoroughly. The description doesn't add significant parameter-specific information beyond what's in the schema, though it implies the 'query' parameter is central and mentions 'analyze_only=false' (referring to the 'analyze' parameter). Baseline 3 is appropriate when schema does the heavy lifting.

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 the tool's purpose: 'Analyze a SQL query's execution plan and performance characteristics' with specific details about what it provides (execution plan analysis, timing breakdown, buffer usage, performance issues). It distinguishes from siblings like 'explain_with_indexes' by emphasizing actual execution with EXPLAIN ANALYZE and comprehensive performance analysis.

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 provides explicit usage guidance: 'For SELECT queries this is safe, but be careful with INSERT/UPDATE/DELETE - use analyze_only=false for those.' This clearly indicates when to use caution and mentions an alternative approach (setting analyze=false) for non-SELECT queries, helping distinguish from read-only analysis tools.

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