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

Annotations only declare the mutation/safety profile (destructiveHint, idempotentHint, readOnlyHint=false); the description goes well beyond by disclosing the exact side effects (account links and touch/note/task history return intact because delete retains them; contacts/opportunities/subscriptions re-link via retained account_id), the refusal path for non-deleted or unknown ids ('refused with the reason and nothing changes'), and the auth scope.

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?

Front-loaded with the core action and well-sectioned, but the 'When to use' paragraph substantially restates the opening paragraph (restorable objects, undo semantics), which is mild redundancy rather than waste.

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?

Output schema exists, so return-shape detail is not required; the description nonetheless names the restored:true marker. With error semantics, side effects, id source, object restriction and permission scope all covered, nothing material is missing for correct invocation.

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 100%, so both parameters are already documented in the schema, including that object_type is one of contact|account and that id is a uuid. The description reinforces the id source (delete result or get_record with include_archived) but adds no new syntax or format detail, so the baseline 3 applies.

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?

Names a specific verb and resource ('bring back a soft-deleted contact or account') and positions itself explicitly as 'the undo of delete_record', which cleanly separates it from delete_record, get_record and create_record in the sibling list. Scope is bounded to two object types.

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 when-to-use ('Undo a delete'), names when NOT to use it ('the other objects have no undo (re-create them)'), and routes the agent to the prerequisite tool ('Find a deleted record with get_record(include_archived:true)'). It also states the permission scope is the same as delete_record.

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