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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the deletion is irreversible, it cascades to a stored file and derived Brain knowledge, it needs workspace settings permission, and it is retry-safe with the same idempotency_key. That is exactly the behavioral detail an agent needs before firing a destructive call.

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?

Four short sentences, front-loaded with the action and its blast radius, then irreversibility, permission requirement, and retry semantics. No filler and nothing important buried at the end.

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, no-output-schema mutation the description covers the essentials: permanence, cascade scope, permission prerequisite, and idempotency. The remaining gap is ambiguity around the `id` (implicitly the document id) and whether workspace_id applies to a delete, given the schema's note that it is optional for reads and required for creates.

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 only 40% (id, brand_id and idempotency_key have no schema description), so the description has some compensating work to do. It usefully explains idempotency_key's retry semantics, which the schema's pattern/example alone does not convey, but leaves `id` and `brand_id` uninterpreted and does not clarify whether workspace_id is required for this delete.

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 ('Permanently delete a workspace Brain document') and goes further by naming the collateral scope: 'its stored file and the Brain knowledge derived from it'. The word 'Permanently' cleanly separates it from the archive-style sibling aidelly_archive_brain_entry without needing the schema.

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?

Usage is implied by 'Permanently delete' plus the prerequisite 'Requires workspace settings permission', which tells the agent a permission gate exists. However, it never explicitly routes the agent away from aidelly_archive_brain_entry when archival would suffice, nor states when-not to delete, so it stops at implied guidance.

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