Simpler.Asia

invoice_item_delete

DestructiveIdempotent

Soft-deletes a line item — it leaves the invoice and its derived total immediately, but the row is retired for audit history, never removed. expected_updated_at is required: the line's updated_at from your read (invoice_item_read); without it the removal is refused and the refusal names the current value. Refuses when the parent invoice is 'paid' (ledger-locked: retire the payment first) or 'cancelled' (terminal: its lines stay as issued), and with CONFLICT when the line changed since that read (read it again). If retiring the line settles the remaining balance on a partially-paid invoice, the parent re-derives to 'paid' by itself. NEXT: invoice_read to see the updated total.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "expected_updated_at": "<expected_updated_at>"
    },
    "name": "invoice_item_delete"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	The invoice_item id (invoice_item_list shows them).
`unit`	No
`position`	No
`quantity`	No
`tax_code`	No
`invoice_id`	No
`description`	No
`discount_bps`	No
`unit_price_cents`	No
`expected_updated_at`	Yes	Required: the line's updated_at from your last read (invoice_item_read, invoice_item_list or the create answer). Left out, the call is refused and names the current value; a line changed since then returns CONFLICT with the current value and stays as it is.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations: destructiveHint=true is qualified as a soft delete with audit retention rather than a hard removal, the required optimistic-concurrency token and its refusal/CONFLICT semantics are spelled out, the parent-invoice state guards are enumerated, and the auto-transition of a partially-paid parent to 'paid' is disclosed. This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core behavior and keeps every sentence functional — no restatement of the name. It is dense and long-ish, but the density is justified by the amount of refusal and side-effect behavior conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description covers error behavior and the follow-up read (invoice_read) so the agent knows what to do next and what refusals look like. It does not state what a successful response contains, which is the only meaningful gap for a mutation of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 20%, but the description fully explains both required parameters: id (pointing at invoice_item_list/read for discovery) and expected_updated_at with its refusal and CONFLICT behavior. The eight optional properties are undocumented in both schema and description, though they appear to be irrelevant carry-over fields for a delete call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Soft-deletes a line item') and immediately explains the mechanism: the line leaves the invoice and total but the row is retired for audit, never removed. That distinguishes it from invoice_item_update or a hypothetical hard delete without the agent needing to open any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-not conditions (refused when the parent invoice is 'paid' or 'cancelled') and a required precondition (expected_updated_at from a prior read), plus the recovery path on CONFLICT ('read it again'). It stops short of naming a sibling to use instead when the removal is refused, so a 4 rather than a 5.

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

All Simpler.Asia tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?