delete_candidate

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

With no annotations provided, the description carries the full disclosure burden and does well: it states the operation is permanent, cannot be undone, and cascades to all applications. It does not mention permission requirements or any guardrails (e.g. candidates with active offers), which keeps it short of a 5.

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, front-loaded segments: the destructive action first, then ID acquisition, then the compliant alternative. No filler sentences and nothing buried.

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. For a single-parameter destructive tool with no annotations, the description covers the action, its irreversibility, cascade scope, prerequisite lookup, and a safer alternative — everything needed to call it correctly.

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% and the schema already documents candidate_id, so the baseline would be 3. The description adds real value by explaining how the ID is acquired via search_candidates_by_name and get_candidate, which is meaning the schema cannot convey.

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 (delete), resource (candidate) and scope (and all their applications), plus the irreversible nature. It also distinguishes itself from the sibling anonymize_candidate by naming it explicitly, so an agent can route correctly without opening either 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?

Gives an explicit prerequisite chain for obtaining the required ID (search_candidates_by_name then get_candidate) and an explicit when-to-use-the-alternative condition ('For GDPR compliance, consider anonymize_candidate instead'). This is exactly the routing guidance an agent needs.

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