Skip to main content
Glama
Sign In

Osome

by com.osome.mcp
OverviewDiscussionsAdmin

update-invoice-draft

Destructive

Change fields on a draft invoice and return the updated invoice. Fields you send in invoice overwrite the stored values and the rest stay. An array for lineItems or paymentMethods replaces the whole list, so send every line to keep; null keeps the stored list. Totals are recalculated and the recipient is refreshed from the customer. It works on drafts only and doesn't submit or email the invoice. Finalize with submit-invoice, which needs lineItems set here first; for an issued invoice, use create-credit-note. Requires the invoice:write scope.

Input Schema

NameRequiredDescriptionDefault
idYesID of the draft invoice, as returned by create-invoice-draft, duplicate-invoice or list-invoices
invoiceYesFields to change on the draft. Fields you leave out keep their stored values. An array for lineItems or paymentMethods replaces the whole list; null keeps the stored list.
companyIdYesID of the company that owns the invoice, as returned by list-companies

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changed
    • changedInput schema / properties / companyId / description
      Previous value: -"Company ID"New value: +"ID of the company that owns the invoice, as returned by list-companies"
    • changedInput schema / properties / id / description
      Previous value: -"Invoice ID"New value: +"ID of the draft invoice, as returned by create-invoice-draft, duplicate-invoice or list-invoices"
    • addedInput schema / properties / invoice / description
      Added value: +"Fields to change on the draft. Fields you leave out keep their stored values. An array for lineItems or paymentMethods replaces the whole list; null keeps the stored list."
    • changedInput schema / properties / invoice / properties / currency / description
      Previous value: -"Currency code (e.g., SGD, USD)"New value: +"Currency code, such as SGD or USD."
    • changedInput schema / properties / invoice / properties / customerId / description
      Previous value: -"Customer ID. Recipient data is auto-populated from the customer."New value: +"ID of the invoice customer, from list-customers or create-customer. The recipient is filled from that customer's current details."
    • changedInput schema / properties / invoice / properties / dueDate / description
      Previous value: -"Due date in YYYY-MM-DD format"New value: +"Due date (YYYY-MM-DD)."
    • changedInput schema / properties / invoice / properties / includeTaxIntoPrice / description
      Previous value: -"Whether tax is included in line item prices"New value: +"Whether line item prices already include tax. If true, tax is taken out of each line amount instead of added on top."
    • changedInput schema / properties / invoice / properties / invoiceNumber / description
      Previous value: -"Custom invoice number (auto-generated if not set)"New value: +"Custom invoice number, unique within the company. Leave unset to have one generated when the invoice is submitted."
    • changedInput schema / properties / invoice / properties / issueDate / description
      Previous value: -"Issue date in YYYY-MM-DD format"New value: +"Issue date (YYYY-MM-DD)."
    • changedInput schema / properties / invoice / properties / lineItems / anyOf
      Previous value: -[
-  {
-    "items": {
-      "properties": {
-        "description": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "discount": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "discountAmount": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "discountUnit": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "grandTotal": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "name": {
-          "type": "string"
-        },
-        "order": {
-          "maximum": 9007199254740991,
-          "minimum": -9007199254740991,
-          "type": "integer"
-        },
-        "price": {
-          "type": "number"
-        },
-        "quantity": {
-          "type": "number"
-        },
-        "subTotal": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "taxAmount": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "taxCategory": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "taxRate": {
-          "anyOf": [
-            {
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "unit": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "name",
-        "price",
-        "unit",
-        "order",
-        "quantity"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "description": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional description of the line."
+        },
+        "discount": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Discount on the line: a percentage of price times quantity, or a fixed amount for the whole line, depending on discountUnit."
+        },
+        "discountAmount": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Leave unset: calculated from discount."
+        },
+        "discountUnit": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "percent (the default) or amount."
+        },
+        "grandTotal": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Leave unset: calculated as the line amount with tax."
+        },
+        "name": {
+          "description": "Name of the product or service.",
+          "type": "string"
+        },
+        "order": {
+          "description": "Position of the line on the invoice; lines are sorted by it.",
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "price": {
+          "description": "Unit price before discount. It includes tax when includeTaxIntoPrice is true.",
+          "type": "number"
+        },
+        "quantity": {
+          "description": "Number of units.",
+          "type": "number"
+        },
+        "subTotal": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Leave unset: calculated as the line amount without tax."
+        },
+        "taxAmount": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Leave unset: calculated from taxRate."
+        },
+        "taxCategory": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Tax category for GST- or VAT-registered companies, such as SR or ZR in Singapore, or standardRate or zeroRate elsewhere."
+        },
+        "taxRate": {
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Tax rate as a percentage, such as 9 for 9%."
+        },
+        "unit": {
+          "description": "Unit of measure, such as pcs, unit, item, hour, day or month.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "price",
+        "unit",
+        "order",
+        "quantity"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / invoice / properties / lineItems / description
      Previous value: -"Line items. Only name, price, unit, quantity, order are required; totals are calculated automatically."New value: +"The complete list of line items, replacing the stored list; send [] to remove every line, or null to keep the stored lines. Each line's discountAmount, taxAmount, subTotal and grandTotal and the invoice totals are recalculated."
    • changedInput schema / properties / invoice / properties / notes / description
      Previous value: -"Invoice notes"New value: +"Free-text notes on the invoice."
    • changedInput schema / properties / invoice / properties / paymentMethods / anyOf
      Previous value: -[
-  {
-    "items": {
-      "properties": {
-        "id": {
-          "type": "number"
-        },
-        "type": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "id"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "id": {
+          "description": "ID of a company payment method, as in the paymentMethods that preview-invoice returns.",
+          "type": "number"
+        },
+        "type": {
+          "description": "Optional; the stored payment method's type is used.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / invoice / properties / paymentMethods / description
      Previous value: -"Payment methods to include"New value: +"Payment methods to show on the invoice, replacing the stored list; send [] to remove them all, or null to keep the stored ones. Each is reloaded by id, and any that no longer exist are dropped."
    • changedInput schema / properties / invoice / properties / supplyEndDate / description
      Previous value: -"Supply period end date"New value: +"Last day of the supply period (YYYY-MM-DD), not before supplyStartDate."
    • changedInput schema / properties / invoice / properties / supplyStartDate / description
      Previous value: -"Supply period start date"New value: +"First day of the supply period (YYYY-MM-DD)."
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the annotations, the description explains overwrite semantics, array replacement versus null preservation for lineItems and paymentMethods, recalculation and customer refresh behavior, draft-only scope, and the invoice:write requirement. These details are highly relevant for a destructive update tool.

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?

The description is front-loaded with the core action and then covers overwrite behavior, alternatives, and authorization in compact sentences. Every sentence adds useful operational context without repetition.

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 nested destructive update tool with no output schema, it provides enough context to call correctly: draft constraint, replacement semantics, recalculation behavior, dependency on submit-invoice, alternative for issued invoices, and required scope.

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 100%, so the baseline is 3, but the description adds important meaning: fields omitted keep stored values, arrays replace whole lists, and null preserves stored lists. It also notes that lineItems must be set here before submit-invoice can finalize.

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 description states a specific verb and resource — changing fields on a draft invoice and returning the updated invoice. It also distinguishes the operation from submit-invoice and create-credit-note, so an agent can select it confidently among siblings.

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 explicitly limits use to drafts, says it does not submit or email, and names the correct alternatives: submit-invoice for finalization and create-credit-note for issued invoices. The required scope is also stated.

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

All Osome toolsInspect
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