analyze_db_health

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

Annotations already declare readOnlyHint=true, so the tool is known to be read-only. The description adds behavioral context by listing specific read-only health checks, indicating no destructive actions. It does not mention potential performance impacts of running all checks, but the read-only nature is well-covered.

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 with a clear opening sentence, a bulleted list of health checks, and a concluding usage note. It is appropriately sized for the complexity of the tool, though a slightly more concise formulation could reduce redundancy.

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 simplicity (one parameter, no required fields, read-only), the description is fairly complete. It covers the purpose, available checks, and usage of the parameter. The existence of an output schema further reduces the need to describe return values, so the description adequately supports agent decision-making.

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?

The input schema provides 100% coverage with a description of valid values and default. The tool description adds extra semantic value by explaining that multiple checks can be specified as a comma-separated list and that the default runs all checks, which is not in the schema description.

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 'Analyzes database health' and enumerates specific health checks (index, connection, vacuum, etc.), providing a specific verb and resource. It distinguishes from sibling tools focused on query analysis, object details, and execution, making its purpose 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?

The description explains how to specify health checks (single or comma-separated list) and that default is 'all', but it does not explicitly state when to use this tool versus sibling tools like 'analyze_query_indexes' or 'get_top_queries'. Usage context is implied rather than explicit.

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