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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: deletion may cascade to related records, nothing takes effect until a human approves the exact request in Settings > MCP, and execute_approved_action must then be called. It also notes that org-configurable MCP approval rules and business workflow approvals both apply, which is exactly the kind of operational behavior an agent cannot infer from structured fields.

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?

The core action is buried in the second sentence behind a generic opening clause, and the approval theme is restated three times ("subject to configured MCP approval rules", "no change occurs until a human approves", "MCP approval requirements are configurable by the organization administrator"). Trimming the boilerplate and the repeated approval phrasing would make the destructive/cascade warning lead.

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?

An output schema exists, so return values need no explanation; safety is covered by annotations plus the cascade and two-step approval description. What is missing is whether the deletion is reversible or permanent after approval, and what state the deal is in while awaiting approval — meaningful for an irreversible destructive 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?

There is one required parameter (id) with 0% schema description coverage, so the description carries the burden — yet it never mentions the identifier at all. The uuid format and pattern make the type obvious from the schema, so the practical gap is small, but an explicit "pass the deal UUID" statement is missing.

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 states the verb and resource plainly ("Delete deal") and scopes it to RetailHardHat deals in the connected organization. Among the many delete_* siblings, the resource name is the only differentiator needed and it is present. The leading sentence ("Use this when working with RetailHardHat deals records") is boilerplate that restates the resource rather than refining the purpose.

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?

It gives a real precondition for invocation (must go through approval, then execute_approved_action), which is useful routing guidance. However, there is no guidance on when NOT to delete — e.g. archiving vs deleting, or checking whether related records should be removed first — and no mention of alternatives such as update_deal or any soft-delete path.

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