get_table_bloat_analysis

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

With no annotations provided, the description carries full burden for behavioral disclosure. It effectively describes what the tool does (analysis, not modification), output characteristics (bloat ratios, sizes, maintenance recommendations), and operational constraints (filtering via SQL LIKE/ILIKE, sorting by severity). It doesn't mention rate limits, authentication needs, or performance characteristics, but provides substantial behavioral context beyond basic functionality.

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 clear sections ([Tool Purpose], [Exact Functionality], etc.) that make it easy to parse. While comprehensive, some sections could be more concise - the [Exact Functionality] uses 6 bullet points where 3-4 might suffice. However, every sentence adds value and the structure helps with quick scanning.

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 analytical complexity, 5 parameters with 0% schema coverage, no annotations, but with an output schema, the description is remarkably complete. It covers purpose, functionality, usage guidelines, parameter semantics, and return value description. The output schema existence means the description doesn't need to detail return structure, allowing it to focus on operational context, which it does thoroughly.

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 0% schema description coverage and 5 parameters, the description provides excellent parameter semantics. The Args section clearly explains each parameter's purpose, default values, constraints (e.g., '1-100' for limit), and usage examples (e.g., SQL LIKE pattern examples). This fully compensates for the lack of schema descriptions and adds meaningful context beyond what the bare schema provides.

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 explicitly states the tool's purpose as 'Analyze table bloat based on dead tuple statistics and size information' in the [Tool Purpose] section, which is a specific verb+resource combination. It clearly distinguishes this from sibling tools like get_database_bloat_overview (database-level vs table-level analysis) and get_vacuum_effectiveness_analysis (different analytical focus).

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 comprehensive usage guidance with dedicated sections: [Required Use Cases] lists five specific scenarios when to use this tool, and [Strictly Prohibited Use Cases] explicitly states three scenarios when NOT to use it (e.g., 'Requests for automatic VACUUM execution'). This gives clear alternatives (use other tools for those prohibited actions) and context for appropriate application.

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