Soft-deletes a tax declaration by UUID, with an optional company ID override. Use it to remove declarations that are no longer needed; accepted declarations cannot be deleted.
Soft-delete a tax declaration. Cannot delete accepted declarations.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Declaration UUID to delete | |
| companyId | No | Company UUID (overrides STORNO_COMPANY_ID env var) |
Changes observed during successful MCP inspections.
v1.0.17Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, which alone would suggest permanent removal; the description adds the crucial correction that this is a soft delete, plus a state-based precondition. That is genuine context beyond the structured fields, though it omits whether a restore path exists and any permission/company-scoping implications.
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?
Two short sentences, the core action and its nature first, then the blocking condition. No filler or repetition of the title.
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 two-parameter destructive tool with full schema coverage and annotations, the description covers what is deleted, the soft-delete nature, and the key precondition. A note on recoverability or the company-scoping effect of companyId would close the remaining gap.
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% with both parameters described, including the env-var override behavior for companyId, so the description need not compensate. It adds no meaning about the id parameter beyond what the schema already states; 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?
"Soft-delete a tax declaration" gives a specific verb plus resource, and "soft-delete" is more precise than the tool name alone since it signals the record is not physically removed. It does not explicitly contrast with other deletion siblings (e.g., dosare_delete, invoices_delete), so it stops short of full sibling differentiation.
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?
"Cannot delete accepted declarations" is an explicit when-not condition that prevents a predictable failed call. It names no alternative route (e.g., what to do instead with an accepted declaration), so context is clear but exclusions-to-alternatives mapping is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.