ecp_postgres_truncate_table

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

No annotations are provided, so description carries full burden. It does mention irreversible data loss, which is important. However, it fails to disclose other behavioral aspects like locking behavior, whether it resets identity sequences (auto-increment counters), or whether it requires special permissions. Also, the tool requires a 'confirm' parameter set to true, which is a safety mechanism, but the description does not explain its presence or the need for explicit confirmation. This is a significant gap for a destructive operation.

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, no filler. 'Delete all rows from a table. Irreversible.' Front-loads the core action and immediately follows with the critical warning. Well-structured for the content it includes, though it could include a touch more detail without becoming verbose.

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?

For a destructive operation on a database table, the description is thin. It does not mention the confirm parameter, which is effectively a safety gate, nor does it suggest any recovery options or mention transactionality. Given the tool's irreversible nature, an agent needs to know that calling it will permanently wipe data and that there is no undo. While the 'irreversible' warning covers that, the absence of any mention of the confirm parameter or impact on identity sequences leaves gaps. The output schema is absent, so the description should explain what happens after execution – it does not. This is below minimum viable for such a critical operation.

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 description must compensate. It doesn't explain that db_name identifies the target database, table_name the target table, and that confirm is a boolean that must be exactly true as an explicit consent. It implies the table name via 'table' and the irreversible nature via the warning, but does not name any parameters. With 3 required parameters and no description, an agent gets no help in understanding what values are suitable. Score 3 because at least it's clear the tool operates on a table, but the confirm parameter is unexplained.

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?

Description: 'Delete all rows from a table. Irreversible.' States a specific verb+resource (delete rows from a table) and is clear. It does not explicitly differentiate from sibling tools like ecp_postgres_drop_table, which deletes the entire table, but for an agent familiar with the distinction, the purpose is unambiguous. With no title, the description provides the only purpose text.

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 on when to use this tool versus alternatives like ecp_postgres_drop_table (which removes the table entirely) or ecp_postgres_delete_row (which deletes selective rows). Implied usage: when you need to remove all data but keep the table structure.SaveChanges are permanent. No explicit exclusions or prerequisites, but the 'irreversible' warning implicitly suggests caution. This is adequate but lacks explicit routing.

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