job_card_deleteDelete a job card entered by mistake. One with labor or materials logged is refused, naming what it holds, because deleting it would lose the record of work done: archive it instead. The JC number is never reissued.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | The job card id, e.g. JC-2026-0003, or the client name when only one card has it |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already flags mutating behavior, but the description adds crucial context beyond that: non-empty cards are refused and the refusal names what the card holds, deletion would lose work records, and the JC number is never reissued. This is exactly the kind of behavioral nuance annotations cannot convey.
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, each earning its place: purpose first, then the critical refusal and archival guidance, then the irreversible consequence. There is no filler or repetition of schema details, and the most decision-relevant information is front-loaded.
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 simple one-parameter destructive tool with no output schema and no nested objects, the description covers the operation, the boundary condition, the alternative action, and the long-term consequence. An agent has everything needed to invoke it correctly and to avoid destructive misuse.
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 the single 'card' parameter is fully documented in the schema. The description adds no new parameter-level meaning beyond reinforcing that JC numbers are involved and that deletion is permanent, which does not materially improve on the existing 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 clearly states the specific action: deleting a job card entered by mistake, with the scope constraint implied by the title ('empty'). It also distinguishes the refusal case (labor/materials logged) from the intended use, making the tool's purpose unambiguous relative to siblings like job_card_update_status or job_card_log_labor.
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 explicitly tells the agent when to use this tool: for a job card entered by mistake and therefore empty. It also gives a clear exclusion rule—cards with logged labor or materials are refused—and directs the agent to archive instead, providing actionable guidance for the alternative path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.