Billy MCP

Overview Schema Source Related Servers Discussions Admin

billy_prepare

Destructive

Validate and persist a bookkeeping write proposal without altering records. Review the returned operation, reason, ID, and hash to confirm.

Instructions

Validate and persist a concrete write proposal without modifying Billy. Review the returned operation, reason, ID and hash. Receipts must be uploaded before preparing a booking. Reconciliation is restricted to matching existing bank-account postings.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`reason`	Yes
`verbose`	No
`operation`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.2.1Sep 25, 2026

changedInput schema / properties / operation / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "contactId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "currencyId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "entryDate": {
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "create_bill",
-        "type": "string"
-      },
-      "lines": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "accountId": {
-              "pattern": "^[A-Za-z0-9_-]{1,160}$",
-              "type": "string"
-            },
-            "amount": {
-              "maximum": 10000000000,
-              "minimum": 0,
-              "type": "number"
-            },
-            "description": {
-              "maxLength": 1000,
-              "minLength": 1,
-              "type": "string"
-            },
-            "taxRateId": {
-              "pattern": "^[A-Za-z0-9_-]{1,160}$",
-              "type": "string"
-            }
-          },
-          "required": [
-            "accountId",
-            "taxRateId",
-            "description",
-            "amount"
-          ],
-          "type": "object"
-        },
-        "maxItems": 100,
-        "minItems": 1,
-        "type": "array"
-      },
-      "receiptId": {
-        "pattern": "^[a-f0-9]{64}$",
-        "type": "string"
-      },
-      "suppliersInvoiceNo": {
-        "maxLength": 160,
-        "minLength": 1,
-        "type": "string"
-      },
-      "taxMode": {
-        "enum": [
-          "incl",
-          "excl"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "receiptId",
-      "contactId",
-      "entryDate",
-      "currencyId",
-      "suppliersInvoiceNo",
-      "taxMode",
-      "lines"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "bankLineId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "daybookId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "description": {
-        "maxLength": 1000,
-        "minLength": 1,
-        "type": "string"
-      },
-      "entryDate": {
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "create_journal",
-        "type": "string"
-      },
-      "lines": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "accountId": {
-              "pattern": "^[A-Za-z0-9_-]{1,160}$",
-              "type": "string"
-            },
-            "amount": {
-              "maximum": 10000000000,
-              "minimum": 0,
-              "type": "number"
-            },
-            "currencyId": {
-              "pattern": "^[A-Za-z0-9_-]{1,160}$",
-              "type": "string"
-            },
-            "side": {
-              "enum": [
-                "debit",
-                "credit"
-              ],
-              "type": "string"
-            },
-            "taxRateId": {
-              "pattern": "^[A-Za-z0-9_-]{1,160}$",
-              "type": "string"
-            },
-            "text": {
-              "maxLength": 500,
-              "minLength": 1,
-              "type": "string"
-            }
-          },
-          "required": [
-            "accountId",
-            "text",
-            "amount",
-            "side",
-            "currencyId"
-          ],
-          "type": "object"
-        },
-        "maxItems": 100,
-        "minItems": 2,
-        "type": "array"
-      },
-      "noReceiptReason": {
-        "maxLength": 1000,
-        "minLength": 10,
-        "type": "string"
-      },
-      "receiptId": {
-        "pattern": "^[a-f0-9]{64}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "daybookId",
-      "entryDate",
-      "description",
-      "lines"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "bankLineId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "cashAccountId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "cashAmount": {
-        "maximum": 10000000000,
-        "minimum": 0,
-        "type": "number"
-      },
-      "cashExchangeRate": {
-        "exclusiveMinimum": 0,
-        "maximum": 100000000,
-        "type": "number"
-      },
-      "cashSide": {
-        "enum": [
-          "debit",
-          "credit"
-        ],
-        "type": "string"
-      },
-      "entryDate": {
-        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "create_payment",
-        "type": "string"
-      },
-      "subjectAmount": {
-        "maximum": 10000000000,
-        "minimum": 0,
-        "type": "number"
-      },
-      "subjectCurrencyId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "subjectReference": {
-        "pattern": "^(bill|invoice):[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "entryDate",
-      "cashAmount",
-      "cashSide",
-      "cashAccountId",
-      "bankLineId",
-      "subjectReference"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "approve",
-        "type": "string"
-      },
-      "resource": {
-        "enum": [
-          "bills",
-          "invoices",
-          "daybookTransactions"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "resource",
-      "id"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "upload_receipt",
-        "type": "string"
-      },
-      "receiptId": {
-        "pattern": "^[a-f0-9]{64}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "receiptId"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "countryId": {
-        "pattern": "^[A-Z]{2}$",
-        "type": "string"
-      },
-      "email": {
-        "format": "email",
-        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
-        "type": "string"
-      },
-      "isCustomer": {
-        "type": "boolean"
-      },
-      "isSupplier": {
-        "type": "boolean"
-      },
-      "kind": {
-        "const": "create_contact",
-        "type": "string"
-      },
-      "name": {
-        "maxLength": 200,
-        "minLength": 1,
-        "type": "string"
-      },
-      "registrationNo": {
-        "maxLength": 100,
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "name",
-      "countryId",
-      "isSupplier",
-      "isCustomer"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "bankLineId": {
-        "pattern": "^[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "reconcile",
-        "type": "string"
-      },
-      "subjectReference": {
-        "pattern": "^(invoice|bill|posting|daybookTransaction|bankPayment):[A-Za-z0-9_-]{1,160}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "bankLineId",
-      "subjectReference"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "contactId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "currencyId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "create_bill",
+        "type": "string"
+      },
+      "lines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "accountId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "amount": {
+              "maximum": 10000000000,
+              "minimum": 0,
+              "type": "number"
+            },
+            "description": {
+              "maxLength": 1000,
+              "minLength": 1,
+              "type": "string"
+            },
+            "taxRateId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "accountId",
+            "taxRateId",
+            "description",
+            "amount"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "receiptId": {
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      },
+      "suppliersInvoiceNo": {
+        "maxLength": 160,
+        "minLength": 1,
+        "type": "string"
+      },
+      "taxMode": {
+        "enum": [
+          "incl",
+          "excl"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "receiptId",
+      "contactId",
+      "entryDate",
+      "currencyId",
+      "suppliersInvoiceNo",
+      "taxMode",
+      "lines"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "bankLineId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "daybookId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "description": {
+        "maxLength": 1000,
+        "minLength": 1,
+        "type": "string"
+      },
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "create_journal",
+        "type": "string"
+      },
+      "lines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "accountId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "amount": {
+              "maximum": 10000000000,
+              "minimum": 0,
+              "type": "number"
+            },
+            "currencyId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "side": {
+              "enum": [
+                "debit",
+                "credit"
+              ],
+              "type": "string"
+            },
+            "taxRateId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "text": {
+              "maxLength": 500,
+              "minLength": 1,
+              "type": "string"
+            }
+          },
+          "required": [
+            "accountId",
+            "text",
+            "amount",
+            "side",
+            "currencyId"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 2,
+        "type": "array"
+      },
+      "noReceiptReason": {
+        "maxLength": 1000,
+        "minLength": 10,
+        "type": "string"
+      },
+      "receiptId": {
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "daybookId",
+      "entryDate",
+      "description",
+      "lines"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "bankLineId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "cashAccountId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "cashAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "cashExchangeRate": {
+        "exclusiveMinimum": 0,
+        "maximum": 100000000,
+        "type": "number"
+      },
+      "cashSide": {
+        "enum": [
+          "debit",
+          "credit"
+        ],
+        "type": "string"
+      },
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "feeAccountId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "feeAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "kind": {
+        "const": "create_payment",
+        "type": "string"
+      },
+      "subjectAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "subjectCurrencyId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "subjectReference": {
+        "pattern": "^(bill|invoice):[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "entryDate",
+      "cashAmount",
+      "cashSide",
+      "cashAccountId",
+      "bankLineId",
+      "subjectReference"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "approve",
+        "type": "string"
+      },
+      "resource": {
+        "enum": [
+          "bills",
+          "invoices",
+          "daybookTransactions"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "resource",
+      "id"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "upload_receipt",
+        "type": "string"
+      },
+      "receiptId": {
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "receiptId"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "countryId": {
+        "pattern": "^[A-Z]{2}$",
+        "type": "string"
+      },
+      "email": {
+        "format": "email",
+        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+        "type": "string"
+      },
+      "isCustomer": {
+        "type": "boolean"
+      },
+      "isSupplier": {
+        "type": "boolean"
+      },
+      "kind": {
+        "const": "create_contact",
+        "type": "string"
+      },
+      "name": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "registrationNo": {
+        "maxLength": 100,
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "name",
+      "countryId",
+      "isSupplier",
+      "isCustomer"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "bankLineId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "reconcile",
+        "type": "string"
+      },
+      "subjectReference": {
+        "pattern": "^(invoice|bill|posting|daybookTransaction|bankPayment):[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "bankLineId",
+      "subjectReference"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "contactId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "contactMessage": {
+        "maxLength": 2000,
+        "type": "string"
+      },
+      "currencyId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "expectedNetAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTaxAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTotalAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "kind": {
+        "const": "create_sales_invoice",
+        "type": "string"
+      },
+      "lines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "maxLength": 1000,
+              "minLength": 1,
+              "type": "string"
+            },
+            "expectedTaxRateId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "productId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "quantity": {
+              "exclusiveMinimum": 0,
+              "maximum": 100000000,
+              "type": "number"
+            },
+            "salesTaxRulesetId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "unitPrice": {
+              "maximum": 10000000000,
+              "minimum": 0,
+              "type": "number"
+            }
+          },
+          "required": [
+            "productId",
+            "salesTaxRulesetId",
+            "expectedTaxRateId",
+            "quantity",
+            "unitPrice"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "taxMode": {
+        "enum": [
+          "incl",
+          "excl"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "contactId",
+      "entryDate",
+      "currencyId",
+      "taxMode",
+      "lines",
+      "expectedNetAmount",
+      "expectedTaxAmount",
+      "expectedTotalAmount"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "contactMessage": {
+        "maxLength": 2000,
+        "type": "string"
+      },
+      "expectedNetAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTaxAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTotalAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "id": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "update_draft_invoice",
+        "type": "string"
+      },
+      "paymentTermsDays": {
+        "description": "Net days from invoice entryDate; sets paymentTermsMode to net and verifies the computed dueDate",
+        "maximum": 3650,
+        "minimum": -365,
+        "type": "integer"
+      },
+      "taxMode": {
+        "enum": [
+          "incl",
+          "excl"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "id",
+      "expectedNetAmount",
+      "expectedTaxAmount",
+      "expectedTotalAmount"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "contactPersonId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "emailBody": {
+        "maxLength": 10000,
+        "minLength": 1,
+        "type": "string"
+      },
+      "emailSubject": {
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      "id": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "send_invoice",
+        "type": "string"
+      },
+      "recipientEmail": {
+        "format": "email",
+        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "id",
+      "contactPersonId",
+      "recipientEmail",
+      "emailSubject",
+      "emailBody"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "expectedNetAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTaxAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTotalAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "kind": {
+        "const": "create_customer_credit_note",
+        "type": "string"
+      },
+      "lines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "maxLength": 1000,
+              "minLength": 1,
+              "type": "string"
+            },
+            "expectedTaxRateId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "originalLineId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "productId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "quantity": {
+              "exclusiveMinimum": 0,
+              "maximum": 100000000,
+              "type": "number"
+            },
+            "salesTaxRulesetId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "unitPrice": {
+              "maximum": 10000000000,
+              "minimum": 0,
+              "type": "number"
+            }
+          },
+          "required": [
+            "productId",
+            "salesTaxRulesetId",
+            "expectedTaxRateId",
+            "quantity",
+            "unitPrice",
+            "originalLineId"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "originalInvoiceId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "originalInvoiceId",
+      "entryDate",
+      "lines",
+      "expectedNetAmount",
+      "expectedTaxAmount",
+      "expectedTotalAmount"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "entryDate": {
+        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+        "type": "string"
+      },
+      "expectedNetAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTaxAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "expectedTotalAmount": {
+        "maximum": 10000000000,
+        "minimum": 0,
+        "type": "number"
+      },
+      "kind": {
+        "const": "create_supplier_credit_note",
+        "type": "string"
+      },
+      "lines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "accountId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "amount": {
+              "maximum": 10000000000,
+              "minimum": 0,
+              "type": "number"
+            },
+            "description": {
+              "maxLength": 1000,
+              "minLength": 1,
+              "type": "string"
+            },
+            "originalLineId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            },
+            "taxRateId": {
+              "pattern": "^[A-Za-z0-9_-]{1,160}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "originalLineId",
+            "accountId",
+            "taxRateId",
+            "description",
+            "amount"
+          ],
+          "type": "object"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      },
+      "originalBillId": {
+        "pattern": "^[A-Za-z0-9_-]{1,160}$",
+        "type": "string"
+      },
+      "receiptId": {
+        "pattern": "^[a-f0-9]{64}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "receiptId",
+      "originalBillId",
+      "entryDate",
+      "lines",
+      "expectedNetAmount",
+      "expectedTaxAmount",
+      "expectedTotalAmount"
+    ],
+    "type": "object"
+  }
+]

addedInput schema / properties / verbose

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

First observedv0.1.0Sep 22, 2026

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already indicate non-read-only, destructive, and open-world behavior. The description adds meaningful behavioral context by stating that the tool does not modify Billy, that it returns an operation/reason/ID/hash for review, and that receipts must be uploaded first. These go beyond the annotations and help set expectations. No contradiction with the annotations.

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 three tight sentences. The first front-loads the core purpose, the second tells the agent what to review, and the third gives key constraints. No filler or redundancy.

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

Completeness2/5

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

Given the enormous polymorphic input schema, no output schema, and annotations that flag destructive behavior, the description is far too sparse. It does not explain how to construct the `operation` object, what the returned hash/ID are for, whether execution is required afterward, or how errors are surfaced. An agent would be left guessing about most of the tool's behavior.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate by explaining the `operation`, `reason`, and `verbose` parameters. It does not: the mention of 'operation, reason, ID and hash' refers to the returned values, not the input. The only parameter-related hints are indirect constraints about receipts and reconciliation. This is far below what the complex polymorphic operation schema requires.

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

Purpose4/5

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

The description clearly states a specific action ('Validate and persist a concrete write proposal') with a resource and a key constraint ('without modifying Billy'). It distinguishes the tool as a prepare step, though it does not explicitly name alternatives like billy_batch_prepare or billy_execute, so it falls just short of a 5.

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

Usage Guidelines3/5

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

The description implies a preparatory role and gives preconditions ('Receipts must be uploaded before preparing a booking', 'Reconciliation is restricted to matching existing bank-account postings'), but it never states when to use this tool versus siblings such as billy_batch_prepare or billy_execute. No alternatives or exclusions are mentioned, so usage guidance is only implicit.

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

billy_prepare

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools