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

Even though destructiveHint=true already flags destructiveness, the description adds substantial behavior beyond the annotations: the 30-day recycle-bin retention window, the restore path via crm_restore_deal, the admin-only permission requirement, and the no-confirmation/inform-user expectation. These details are not derivable from the annotations and meaningfully shape how an agent invokes and reports the action. The description is consistent with readOnlyHint=false and destructiveHint=true, so there is no contradiction.

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 sentences totaling about 50 words, with the core purpose front-loaded in the first sentence. Every clause carries information: definition, retention/restore, permissions, and reply guidance. There is no redundancy or 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 single-parameter tool with no output schema, the description covers the essentials: effect, duration, undo path, permission gate, and expected reporting behavior. Minor gaps remain, such as behavior when the deal is already in the trash (which idempotentHint=false hints matters) and any cascade to related records like followups or contacts.

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% for deal_id and the description does not explicitly document the parameter's format or source. The parameter name is largely self-explanatory and the description grounds it as 'a CRM deal,' so the gap is tolerable; however, a note that the ID comes from crm_get_deals or list_trash would have fully compensated for the missing schema documentation.

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 opens with a specific verb+resource pair, 'Soft-delete a CRM deal,' which precisely names the action and object. The soft-delete qualifier and the explicit mention of crm_restore_deal set it apart from the other crm_delete_* siblings that target different entities (contact, lead, followup) and from any permanent-delete operation.

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 gives clear operational context: it is admin-only, so agents know who may invoke it, and it specifies the conversational behavior ('no confirmation phrase is required - but still tell the user what you removed'). It does not, however, explicitly state when to prefer this over alternatives such as list_trash or a permanent delete, so it falls just short of a 5.

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