delete_message

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

With no annotations provided the description carries the full burden, and it does: destructive and irreversible, a separate permission that is disabled by default, error behavior when the entity is missing, and the atomic validation rule that every ID is checked against the named chat and the whole batch is refused if any ID belongs elsewhere. That last detail is exactly the kind of non-obvious behavior an agent cannot infer.

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?

Well front-loaded with the destructive/security warning and the fallback tools called out before the arguments. The opening two lines say the same thing twice ('Delete messages from a specific entity.' / 'Deletes messages from a specific entity.'), which is pure waste, and the Returns block duplicates the output schema.

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 two-parameter tool with no annotations, the description supplies the safety profile, the permission precondition, the error case, the recovery path via sibling tools, and the batch-validation guarantee. An output schema exists, so return values are already covered, and nothing an agent needs in order to call this safely is missing.

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 coverage is 0%, so the description must document both parameters, and it does: entity as the entity identifier and message_ids as a list of message IDs. It also adds a cross-parameter constraint (IDs are validated against the named entity, batch refused on mismatch) that the schema does not express, though it never says what form the entity identifier takes (ID vs username vs title).

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?

States a specific verb and resource ('Delete messages from a specific entity') and names the scope. It doesn't distinguish itself from the adjacent edit_message/send_message siblings, but it does route to search_dialogs and get_messages for the prerequisite lookups.

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?

Gives explicit preconditions: call search_dialogs when the entity is uncertain and get_messages when the message IDs are uncertain, plus a requirement to confirm with the user and an explicit prohibition on deleting because message content asked for it. No guidance on when to delete versus edit or archive, so no exclusion against sibling mutations.

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