Fawtar

Issue an invoice

fawtar_create_invoice

Issue a tax or ordinary invoice. This is a real financial document: it takes the next sequential number, computes VAT, generates the ZATCA QR code and posts to the general ledger. It cannot be edited afterwards — correct it with a credit note. Confirm the amounts with the user before calling.

Use taxTreatment "tax" for a VAT-registered business, "ordinary" for one that is not registered. Use type "simplified" for individuals, "standard" for businesses (which requires the buyer's VAT number).

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": {
      "taxTreatment": "<taxTreatment>",
      "type": "<type>",
      "lines": "<lines>"
    },
    "name": "fawtar_create_invoice"
  }
}

Input Schema

Name	Required	Description
`type`	Yes	ZATCA document type: "simplified" for a sale to an individual (B2C), "standard" for a sale to a business (B2B), which requires the buyer's name and VAT number.
`buyer`	No	Who the invoice is for. Required for a standard (B2B) invoice, where name and vatNumber must both be present.
`lines`	Yes	The invoice lines. At least one. Amounts are in Saudi riyals unless the org bills in another currency.
`notes`	No	Free text printed on the invoice, visible to the buyer.
`dueDate`	No	YYYY-MM-DD
`taxTreatment`	Yes	"tax" for a VAT invoice from a VAT-registered seller, "ordinary" when the seller is not VAT registered. An ordinary invoice carries no VAT and no QR code.
`pricesIncludeVat`	No	True when each line unitPrice already contains VAT, so it is divided out rather than added on.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedNov 6, 2026

addedInput schema / properties / buyer / description

Added value: +"Who the invoice is for. Required for a standard (B2B) invoice, where name and vatNumber must both be present."

addedInput schema / properties / buyer / properties / address / description
```
Added value: +"Buyer's address as it should appear on the invoice."
```
addedInput schema / properties / buyer / properties / email / description
```
Added value: +"Buyer's email, used if the invoice is sent."
```
addedInput schema / properties / buyer / properties / name / description
```
Added value: +"Buyer's registered name."
```
addedInput schema / properties / buyer / properties / phone / description
```
Added value: +"Buyer's phone number."
```

addedInput schema / properties / buyer / properties / vatNumber / description

Added value: +"Buyer's 15-digit Saudi VAT number, required on a standard (B2B) invoice."

addedInput schema / properties / lines / description

Added value: +"The invoice lines. At least one. Amounts are in Saudi riyals unless the org bills in another currency."

addedInput schema / properties / lines / items / properties / description / description
```
Added value: +"What is being charged for, as it should read on the invoice."
```
addedInput schema / properties / lines / items / properties / quantity / description
```
Added value: +"How many units."
```
addedInput schema / properties / lines / items / properties / unitPrice / description
```
Added value: +"Price for one unit, before VAT unless pricesIncludeVat is true."
```

addedInput schema / properties / notes / description

Added value: +"Free text printed on the invoice, visible to the buyer."

addedInput schema / properties / pricesIncludeVat / description

Added value: +"True when each line unitPrice already contains VAT, so it is divided out rather than added on."

addedInput schema / properties / taxTreatment / description

Added value: +"\"tax\" for a VAT invoice from a VAT-registered seller, \"ordinary\" when the seller is not VAT registered. An ordinary invoice carries no VAT and no QR code."

addedInput schema / properties / type / description

Added value: +"ZATCA document type: \"simplified\" for a sale to an individual (B2C), \"standard\" for a sale to a business (B2B), which requires the buyer's name and VAT number."

First observedSep 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description supplies the substantive consequences the annotations cannot: it consumes the next sequential number, computes VAT, generates a ZATCA QR code, posts to the general ledger, and is permanently uneditable. That irreversibility and the credit-note remediation path are exactly the behavioral context an agent needs before committing a financial record.

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

Conciseness5/5

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

Two short paragraphs, front-loaded with the identity and the irreversible-commitment warning before the enum guidance. Every sentence carries decision-relevant content; there is no filler or repetition of the schema beyond what the routing rules require.

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?

For a seven-parameter nested mutation with no output schema, the description covers the important risk surface: immutability, GL posting, sequential numbering, and the confirmation step. The remaining gap is that it never indicates what the agent receives back (invoice ID, assigned number, QR payload), which matters somewhat given there is no output schema.

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

Parameters3/5

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

Schema description coverage is 100%, so all seven parameters are already documented, which sets the baseline at 3. The description restates the taxTreatment and type semantics in decision-rule form but adds no genuinely new field-level detail, and it says nothing about pricesIncludeVat, dueDate, notes, or the line-level vatRate/unitPrice interaction.

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?

The opening sentence names a specific verb and resource ("Issue a tax or ordinary invoice") and immediately scopes it to the two document variants, which separates it from the generic fawtar_create sibling. An agent can tell from the first sentence that this is the invoice-issuing tool and not a draft or generic document creator.

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?

It gives explicit selection rules: taxTreatment "tax" vs "ordinary" depending on VAT registration, and type "simplified" vs "standard" depending on B2C vs B2B. It also states a pre-call discipline ("Confirm the amounts with the user before calling") and an alternative for correcting a mistake ("correct it with a credit note"), so both when-to-use and when-not-to-use are covered.

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

All Fawtar 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?