Update to Essentio

{
  "description": "Draft, check, issue and send an Invoice in Essentio through the Essentio connector's tools, in that order, stopping at a refusal. Use this whenever the person asks to invoice or bill a Client, charge someone for work or products, prepare or send an Invoice, Proforma Invoice, Quote or Credit Note, or says things like \"invoice ACME 500 euros and send it\" — even when they do not name Essentio or say \"draft\".",
  "included_files": [],
  "name": "draft-and-send-invoice",
  "skill_md_contents": "---\nname: draft-and-send-invoice\ndescription: Draft, check, issue and send an Invoice in Essentio through the Essentio connector's tools, in that order, stopping at a refusal. Use this whenever the person asks to invoice or bill a Client, charge someone for work or products, prepare or send an Invoice, Proforma Invoice, Quote or Credit Note, or says things like \"invoice ACME 500 euros and send it\" — even when they do not name Essentio or say \"draft\".\n---\n\n# Draft, check, issue and send an Invoice\n\nThe Essentio connector (`essentio_*` tools) acts for one Business, the one the person chose when they\nconnected it, with the Role they gave it there. Every figure on a document is computed by Essentio when\nthe Draft is saved: your job is to put the right Client and Lines into a Draft, let the person see\nwhat Essentio computed, and then issue and send only what they approved.\n\nWork in this order. Each step says why, so you can adapt when the person asks for less (only a Draft,\nor issue without sending).\n\n## 1. Find the Client\n\nCall `essentio_search_clients` with `search` set to the name, email, VAT number or account code the\nperson gave. Use the `id` of the Client that matches.\n\n- Several match: show their names and emails and ask which one. Guessing would bill the wrong Client.\n- None matches: ask whether to create one. `essentio_create_client` needs an `email`, a `country` and a\n  `name` or `legal_name`; a VAT number is optional and is checked with the EU's VIES service. Create it\n  only after the person confirms the details.\n\nIf you need the Client's currency or payment terms, `essentio_get_client` reads them.\n\n## 2. Read the Business's setup\n\nCall `essentio_get_business_setup` once. It gives the reporting currency, the active VAT rates (each\nwith the VAT category a Line takes at it) and the bank accounts. Take each Line's `vat_rate` and\n`vat_category` from those rates rather than from memory: a rate the Business does not use is a\ndifferent document. A 0 rate in a category other than `S` and `Z` needs a `vat_exemption_code`\n(a VATEX code) — ask the person for it rather than choosing one.\n\nWhen the person names a Product or service they sell, `essentio_search_products` gives its name, unit,\nprice and VAT rate.\n\n## 3. Create the Draft\n\nCall `essentio_create_draft` with:\n\n- `document_type`: `invoice` unless the person asked for a `proforma`, `quote` or `credit_note`;\n- `client_id` from step 1;\n- `currency`: the Client's currency if it has one, otherwise the Business's; ask if the person said\n  another;\n- `due_date` (YYYY-MM-DD): today plus the Client's payment terms, unless the person gave a date;\n- `lines`: each with `description`, `quantity`, `unit_price` (VAT excluded) and `vat_rate`, all as\n  decimal strings such as `\"500.00\"` and `\"19\"` — never as numbers.\n\nA Draft has no number and no issue date, is not sent and counts in no report, so creating it commits\nthe person to nothing. A second identical `essentio_create_draft` within about ten minutes is answered\nwith the first Draft, marked as a replay, and creates nothing new; if the person really wants two\nidentical Drafts, send a fresh `idempotency_key` with the second.\n\n## 4. Check the figures with the person\n\nThe person is shown the Draft as a card with its Client, Lines, VAT and Total. Read the same answer\nyourself and compare it with what they asked for: the Client's name, each Line, `vat_groups`,\n`subtotal`, `total_vat`, `total` and `currency`.\n\n- Quote Essentio's figures as they are in the answer. Do not recompute VAT or totals and present your\n  own numbers: Essentio's rounding is the one the document will carry.\n- If something is not what the person meant (a price, a quantity, a rate, the wrong Client), change the\n  Draft with `essentio_update_draft`. Only the fields you send change, and `lines`, when sent, replace\n  every Line — so send them all.\n\nThen read the answer's `actions`. Each Action is `{open, code, remedy}`:\n\n- `actions.issue.open` false: the Draft cannot be issued as it stands. Say so, with its `code`, before\n  asking to issue.\n- `actions.send.open` false with `remedy` `connect_mail_provider`: Essentio cannot email the\n  document for the Business right now — it has no email address of its own, its recipients through\n  Essentio for today are all emailed (`sending_limit_reached`), or its connected mailbox was lost. Tell\n  the person now, in the refusal's words, and give them the `remedy_url`, Essentio's email settings.\n  Issuing still works.\n\n## 5. Issue, once the person says so\n\nAsk before issuing, and say what it means: the Draft takes its document number for good and today's\nissue date, a due date already passed becomes today plus the payment terms, and an issued document can\nno longer be deleted — only cancelled, or corrected with a Credit Note.\n\nThen call `essentio_issue_document` with the `document_id`. It does not email anything.\n\nThe card has its own Issue and Send buttons. If the person pressed one, the card already shows what\nhappened: call `essentio_get_document` to read the document as it is now instead of issuing again.\n\n## 6. Send, once the person says so\n\nAsk before sending: `essentio_send_document` emails the document, attached, to the Client's address on\nrecord, through the Business's connected mail account. It cannot send to any other address. `subject`\nand `message` are optional; left out, the Business's own template is used. If the document is still a\nDraft, sending issues it first.\n\nAn identical `essentio_send_document` call within about ten minutes emails nothing: it is answered with\nthe first call's answer, and a second text says \"Nothing was written again: an identical\nessentio_send_document call was made less than 10 minutes ago…\". When you see that, tell the person the\ndocument was not emailed again. If they do want it sent a second time, call it again with a fresh\n`idempotency_key` of your choosing (a UUID). The same holds for `essentio_create_draft` and\n`essentio_create_client`: an answer that says \"Nothing was written again\" is the first call's record,\nnot a new one.\n\nFinish by telling the person the document number, its status and Total, and its `public_url`.\n\n## When a tool fails\n\nA failed call answers a tool error whose text is JSON: `{\"error\": {\"type\", \"message\", ...}}`. Tell the\nperson what happened in `message`'s words, and act on `type`:\n\n- `refusal`: the Action is not open for the document as it stands. Quote `message`, which is written\n  for the person, and name the `code`. Stop there — do not retry with other values on your own.\n  Nothing was written, with one exception: a Send refused `mail_account_lost` (the connected mail\n  account refused to renew its access) may have issued its Draft on the way — when the error carries\n  a `document_number`, the Draft is now issued under that number and stays issued, unsent. With the\n  `remedy` `connect_mail_provider`, Essentio cannot email for the Business right now, as the refusal's\n  words say: the person puts it right in Essentio's settings (the document's `actions.send.remedy_url`\n  leads there) — or, past the day's limit, waits for tomorrow — then asks to send again.\n- `not_delivered`: the mail provider did not take the email. This is not \"nothing written\": a Send of a\n  Draft issued it on the way. When the error carries a `document_number`, the Draft is now issued under\n  that number and stays issued, unsent. Say so plainly, so the person does not think it is still a\n  Draft, and do not issue it again.\n- `permission`: the connection's Role may not do this (a Viewer's connection writes nothing). Someone\n  with a higher Role in the Business has to do it, or the person reconnects with that Role.\n- `invalid_request`: `errors` names each field at fault and what is wrong with it — a `client_id` that\n  is not one of the Business's Clients is answered this way by `essentio_create_draft`. Fix what the\n  person can confirm, and ask about the rest.\n- `not_found`: a tool that names a record by its id — for example `essentio_issue_document`,\n  `essentio_send_document` or `essentio_get_document` — did not find it in this Business. `message`\n  names the search tool that lists them; find it again there.\n- `idempotency_in_flight`: an identical call is still being performed, and nothing more was done. Make\n  the same call again, unchanged, a few seconds later: it answers what the first one did. If the first\n  call was refused or failed, it kept nothing, and the call again is a new attempt — before sending\n  again, read the document with `essentio_get_document` to see whether it was issued or sent.\n- `idempotency`: an `idempotency_key` you sent was used before with other arguments, and nothing was\n  done. A new call takes a new key.\n\nTwo failures carry no such tool error:\n\n- **The connector refused the request** (HTTP 429, a rate limit): the connection made more requests in\n  the last minute than it may — every request counts, listing the tools included — and the request\n  did not reach any tool. Wait about a minute. Before making a write again, read back with\n  `essentio_get_document` or a search whether it happened.\n- **An internal or server error**: a fault on Essentio's side, and it does not tell you what was\n  written. Read the document back with `essentio_get_document`, or search for it, before calling\n  anything again.\n\n## In a Test business\n\nWhen the connection is to a Test business, its documents are marked as samples and everything it sends\ngoes to its Owner, never to the Client. It is the place to try this workflow first.\n`essentio_get_business_setup` and every document say so with `is_test: true`, and every number it\nissues carries `TEST-`, such as `TEST-INV-2026-0007`. It issues no more Invoices a year than the\nFree plan: past that, Issue and Send are refused `issuing_limit_reached`, which its Owner clears by\nresetting it in Essentio. Tell the person it is a sample, not a real Invoice.\n"
}