Skip to main content
Glama

Change a draft invoice

update_draft_invoice
DestructiveIdempotent

Use this when the user asks to change a draft invoice: its lines, prices, date, currency or notes. Changes a draft invoice: only the fields passed change; items replaces all lines. Issued invoices, drafts made by the Shopify app, and supplementary or advance invoice drafts cannot be changed here. Line descriptions are printed on the tax invoice: write them in English, translating when the user writes in another language (for example "Консультация" becomes "Consultation"). Keep names, brands and model numbers exactly as written. Use another language only when the user explicitly asks for it or quotes the exact text. Lines are priced by Fatura Go as in the app (each line rounded, header = sum of lines; with prices_include_vat the entered price includes VAT, e.g. 26.95 = 25.67 + 1.28 VAT). Returns the stored lines and totals and app_url. Nothing is issued, numbered as a tax invoice or sent: the user reviews and issues it in Fatura Go ("Review and issue in Fatura Go"). Do not use it for a new invoice (create_draft_invoice) or for an issued invoice, which is changed with a credit note in Fatura Go.

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": {
      "invoice_id": "<invoice_id>"
    },
    "name": "update_draft_invoice"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateNoYYYY-MM-DD. Default today (UAE).
itemsNoThe lines, 1 to 100. On an update they replace every line.
notesNo
fx_rateNoAED per 1 unit of a foreign currency.
currencyNoOne of AED, SAR, USD, EUR, GBP, KWD, QAR, BHD, OMR, INR. Default the client's preferred currency, else the business currency.
due_dateNoYYYY-MM-DD, on or after date.
client_idNoFrom list_clients or create_client.
invoice_idYesFrom create_draft_invoice or list_invoices (status draft).
business_idNoFrom list_businesses. May be left out when the connection shares exactly one business.
client_nameNoOnly when the client_id is not known: nothing is written, and the matching clients are returned to pick from.
idempotency_keyNoOptional. A unique string (for example a UUID) for this request: a retry with the same key returns the first result instead of writing again.
prices_include_vatNoWhether unit_price includes the 5% VAT. Default the business setting.
document_language_overrideNoLanguage this document prints in: en, ar or bilingual. Left out: a new draft follows the business setting and an update keeps the current choice; null goes back to the business setting. Only for a document the user asked to print in another language.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / document_language_override
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 20,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Language this document prints in: en, ar or bilingual. Left out: a new draft follows the business setting and an update keeps the current choice; null goes back to the business setting. Only for a document the user asked to print in another language."
      +}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare destructiveHint=true and idempotentHint=true; the description supplies the context those flags cannot, namely that only fields passed change and that items replaces every line (which is what makes it destructive). It also discloses that nothing is issued, numbered or sent, that the user issues in Fatura Go, and that the response carries stored lines, totals and app_url.

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-loaded with the trigger condition and exclusions, and most sentences carry a rule that changes agent behaviour (language, pricing, review-then-issue). The line-description language guidance is duplicated verbatim from the schema, which is a sizeable block of redundant text for an otherwise tight description.

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

Completeness5/5

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

For a 13-parameter mutation tool with no output schema, the description covers the essentials an agent needs: which fields mutate and how, what is forbidden, that nothing is issued or sent, and what the response contains (lines, totals, app_url). Combined with 92% schema coverage, no significant decision-relevant information is missing.

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 92%, so the baseline is 3; the description still adds update semantics the schema does not state, notably that omitted fields are preserved and that an items array is a full replacement. It also explains Fatura Go's line-level rounding and VAT-inclusive pricing. It loses a point for restating the line-description language rule almost verbatim from the schema rather than adding to it, and for not clarifying ordering or the client_name/client_id trade-off.

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 ('change a draft invoice') and enumerates the mutable fields (lines, prices, date, currency, notes). It explicitly names the sibling it is not (create_draft_invoice) and rules out issued invoices, so an agent can separate it from every neighbour listed.

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

Usage Guidelines5/5

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

Gives explicit when-to-use ('user asks to change a draft invoice'), explicit when-not (issued invoices, drafts made by the Shopify app, supplementary/advance drafts), and names the correct alternative in each excluded case: create_draft_invoice for new drafts and a credit note in Fatura Go for issued ones. Nothing is left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources