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

Annotations already declare destructiveHint=true and non-idempotency, so the safety profile is covered. The description adds the human-approval gate and the version precondition, which are useful, but the most consequential behavior — that the record is only soft-deleted, with deleted_at set — appears only in the schema's confirm description, not in the tool description itself.

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?

Three short sentences, front-loaded with the action, then the workflow, then the scope exclusion. Nothing is repeated from the annotations and no sentence is filler.

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 five-parameter destructive tool with full schema coverage and no output schema, the description covers action, precondition sourcing, approval gating, and boundary versus the model-deletion sibling. It could say more about what a successful delete returns or whether it is reversible, but the schema fills most of that gap.

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 100%, so the baseline is 3, but the description goes beyond it by binding the version parameter to its source (crm_query) and the confirm parameter to a human approval event, which the schema does not state. It omits the id/record_id alias choice, which the schema already documents.

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 (deletes) and scope (one record), and explicitly contrasts with crm_delete_model by saying 'It does not delete the list.' The noun 'stored thing' is imprecise, though the title 'Delete a CRM record' and the model parameter make the resource recoverable.

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 a concrete workflow: get the version from crm_query, then call with confirm true only after the person approves. It also carves out one alternative (list/model deletion). It stops short of routing among other destructive siblings such as crm_person_erase or crm_update.

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