The smartbill-mcp server enables complete management of Romanian financial documents and account data via the SmartBill Cloud API. Key capabilities include:
Invoice Management: Create new invoices, issue from proformas, create reversal (storno) invoices, download PDFs, check payment status, email, and manage lifecycle (cancel, restore, delete).
Proforma (Estimate) Management: Create proformas, download PDFs, list invoices issued from a proforma, email, and manage status (cancel, restore, delete).
Payment & Receipt Management: Record various payments (including receipts), cancel/delete receipts, delete other payments, fetch fiscal receipt text, and optionally settle specific invoices when recording payments.
Account & Catalogue Data: List document series with next numbers, VAT rates, and stock levels.
Document Delivery: Email issued invoices or proformas directly to clients.
Hosted Mode Reports (requires database): Access client lists, client details, receivables aging, client balances, client statements/ledgers, payments received, and product sales analytics over periods.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@smartbill-mcp Create an invoice for client ABC for 500 RON."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for the SmartBill Cloud API. It lets an MCP client issue and manage Romanian invoices, proformas and payments, download document PDFs, and read VAT rates, series and stock levels.
Run in hosted mode with a database, it also adds session-backed reporting tools the public API cannot provide — customer roster, receivables/aging, client statements and ledgers, collections and product sales (see Portal report tools).
Hosted instance: a public deployment runs at https://smartbill-mcp-coolify.bogdanripa.com/. Open it in a browser to connect your own SmartBill account and generate a connector URL.
It runs two ways:
stdio, single account, on your machine — credentials come from the environment.
HTTP, multi-tenant, hosted — credentials arrive with each request, so one deployment serves any number of SmartBill accounts.
You need a SmartBill Cloud account. How credentials reach the server depends on the mode:
stdio uses an API token, generated in Contul meu → Integrari → API, set in the environment (below). A SmartBill token has full account access and no scoping — anything holding it can issue and delete real fiscal documents.
HTTP asks the user for their SmartBill email and password during the OAuth sign-in and reads the token itself; nothing needs to be generated by hand. See Authentication.
Related MCP server: Invoicetronic MCP Server
npm install
npm run build
cp .env.example .env # then fill it inVariable | Required | Description |
| yes | Account email. |
| yes | API token from SmartBill Cloud. |
| yes | Your company CIF, used as the default |
| no | Default invoice series, e.g. |
| no | Default proforma series. |
| no | Default receipt (chitanta) series. |
| no | Where PDFs are written. Default |
| no | Override the API base URL. |
The series defaults are optional but convenient: with them set, tools can be
called with just a document number. Without them, pass seriesName explicitly.
claude mcp add smartbill \
--env SMARTBILL_USERNAME=you@example.com \
--env SMARTBILL_TOKEN=your-api-token \
--env SMARTBILL_VAT_CODE=RO12345678 \
--env SMARTBILL_INVOICE_SERIES=FF \
-- node /absolute/path/to/smartbill-mcp/dist/index.jsThe token is read once at startup, turned into an Authorization: Basic header
inside the HTTP client, and never enters the model's context — no tool takes a
credential argument, so it cannot surface in a tool result.
npm run build
npm run start:http # or: node dist/index.js --httpVariable | Default | Description |
| — | Set to |
|
| Port to listen on. |
|
| Interface to bind (dual-stack; falls back to IPv4 if IPv6 is unavailable). |
|
| Base path the endpoint is mounted at. |
| — | Comma-separated |
| required | Postgres connection string. Stores tenants and OAuth clients/tokens. |
| required | 32-byte key as 64 hex chars; encrypts stored credentials at rest. |
HTTP mode is OAuth-authenticated and needs a database, so DATABASE_URL and
SMARTBILL_SESSION_KEY are required. Without them the server still starts,
but refuses MCP requests with 503 — it has no way to authenticate a caller. No
per-account SMARTBILL_* secrets are read in this mode; each account signs in
through the OAuth flow.
GET /health answers without credentials, for platform health checks:
{ "status": "ok", "version": "0.1.0", "commit": "9f2c1ab..." }commit is the git SHA the image was built from, baked in via the BUILD_SHA
build argument ("dev" outside a built image). It exists because a redeploy
leaves the outgoing container serving: a check that only asks for a 200 is
answered by the container being replaced. The deploy workflow waits for
commit to equal the SHA it just built, so it tests the new container rather
than racing it.
The connector URL carries nothing secret — it is just the MCP endpoint:
https://smartbill.example.com/mcpA client adds that URL, discovers the server requires authorization, and runs the standard OAuth 2.1 authorization-code + PKCE flow. The server is both the authorization server and the resource server, and exposes:
Endpoint | Purpose |
| RFC 9728 resource metadata (points at the auth server). |
| RFC 8414 authorization-server metadata. |
| Dynamic Client Registration (RFC 7591) — clients self-register. |
| The SmartBill sign-in page and its submission. |
| Authorization-code and refresh-token grants. |
| Token revocation (RFC 7009). |
On the /authorize page the user signs in with their SmartBill email and
password. The server logs into SmartBill, scrapes the account's API token and
CIF, stores the tenant (password + session cookies encrypted at rest with
SMARTBILL_SESSION_KEY), and issues an authorization code bound to it. The
client exchanges that for an access token and calls the MCP endpoint with:
Authorization: Bearer <access token>The SmartBill token never leaves the server. The client only ever holds an
opaque, revocable access token that maps to the stored tenant — so a leaked
token is revoked here (POST /revoke, or by deleting the row) without touching
the SmartBill credential. Access tokens and authorization codes are stored
hashed (SHA-256); codes are single-use; PKCE (S256) is required.
An unauthenticated MCP request gets 401 with a WWW-Authenticate header
pointing at the resource metadata — that is what kicks off the flow.
The marketing / overview page (what the connector does and how to add it) is a
static site under web/, served by the platform's CDN — the backend renders
no HTML. It is not a setup form; sign-in happens on the server-rendered
/authorize page during the OAuth flow. Direct hits to the backend container at
/ (before the frontend is published, or from a health check) get a small JSON
status blob instead. The connector URL on the page is derived client-side from
location.origin, so the same file works on any host.
The Dockerfile builds for the runtime Prionman expects — linux/arm64,
listening on port 80, no secrets baked into the image:
docker build --platform linux/arm64 -t smartbill-mcp .
docker run -p 8080:80 smartbill-mcpThe static homepage in web/ is deployed separately from the container: the CI
workflow zips it and uploads it to the platform's static host, which serves it
at / in front of the backend. Paths the bundle doesn't contain — /mcp,
/authorize, /token, /.well-known/*, /health — fall through to the
container.
Tool | What it does |
| Issue an invoice, optionally recording a payment and emailing it. |
| Issue an invoice that copies its details from a proforma. |
| Issue a storno invoice reversing an existing one. |
| Download the invoice PDF. |
| Total, paid and unpaid amounts for an invoice. |
| Cancel an invoice, or undo the cancellation. |
| Permanently delete an invoice. |
Tool | What it does |
| Issue a proforma. |
| Download the proforma PDF. |
| List invoices already issued from a proforma. |
| Cancel a proforma, or undo the cancellation. |
| Permanently delete a proforma. |
Tool | What it does |
| Record a collection, optionally settling specific invoices. |
| Delete a receipt (chitanta) by series and number. |
| Delete a non-receipt payment (card, transfer, ...). |
| Printable text of a fiscal receipt, base64-decoded for you. |
Tool | What it does |
| Document series configured on the account, with their next number. |
| VAT rates, for the |
| Stock levels on a date, optionally per warehouse or product. |
| Email an already-issued invoice or proforma. |
Registered only in hosted mode with DATABASE_URL + SMARTBILL_SESSION_KEY set.
They read the SmartBill web account through an authenticated session to answer the
questions the public API cannot — the customer roster and the reports behind
SmartBill Cloud's dashboards. All read-only.
Tool | What it does |
| Search / list customers (the nomenclator), by name substring. |
| A customer's full record — address, CIF, IBAN, VAT-payer status. |
| Unpaid invoices with status and days overdue, grouped by client. Paged internally, so every client is returned. |
| Outstanding balance per client as of a date. |
| Every document issued to one client over a period. |
| A client's ledger with a running balance. |
| Collections received over a period, linked to the invoices they settled. |
| Sales grouped by product over a period. |
Signing in (via the OAuth flow) stores the account
login encrypted with SMARTBILL_SESSION_KEY, so an expired session is renewed
automatically. After three consecutive sign-in failures the account is frozen and
the tools ask the user to authorize again, which clears the block.
The descriptions are written for a model choosing between them, not just for a
human reading the list. Every tool states what it does, when to reach for it,
what it returns, and which sibling tool to use instead when it is the wrong
choice — delete_invoice points at cancel_invoice, create_invoice points at
create_invoice_from_estimate, and so on. Irreversible tools say so and ask for
confirmation; read-only ones are marked readOnlyHint and destructive ones
destructiveHint, so clients can gate them.
The server also ships instructions, which explain the domain a model has to get
right up front: how series and numbers work, the difference between an invoice, a
proforma and a payment, and the asymmetry between deleting, cancelling and
reversing.
test/documentation.test.ts enforces this — it fails the build if a tool loses
its title, gets a thin description, stops saying when to use it, drops one of the
cross-references, or grows an undocumented parameter.
Errors. SmartBill reports business failures with HTTP 200 and a non-empty
errorText (and the email endpoint uses a status.code instead). Both are
turned into tool errors, so a failed call never looks like a success.
Rate limiting. SmartBill allows 3 calls per second. The client serialises requests and spaces them out, so a burst of tool calls queues instead of failing.
PDFs. Delivery is chosen with as. The default is text over HTTP (the
extracted text layer — the only readable form of a document's fields) and file
over stdio (writes to SMARTBILL_DOWNLOAD_DIR). To hand the actual file to the
user, pass as: "document": the PDF comes back as an MCP embedded resource the
client can display or save. as: "base64" returns the raw bytes for a
programmatic caller.
Email fields. SmartBill expects the email subject and body base64-encoded. Pass plain text; the encoding is handled for you.
Irreversibility. Only the last document in a series can be deleted. Older
documents can be cancelled (cancel_invoice) or reversed with a storno invoice
(create_reverse_invoice). The server tells the model this in its instructions
and marks the destructive tools accordingly, but the client still decides whether
to prompt — treat write tools as needing confirmation.
npm test # vitest, no network access needed
npm run typecheck
npm run dev # stdio, from sourceTests drive the real MCP server — over an in-memory transport for the tool layer
and over a real socket for the HTTP layer — with a stubbed fetch, so they cover
the tool schemas, the request bodies sent to SmartBill, the error mapping and
per-tenant credential isolation.
SmartBill's reference lives at https://api.smartbill.ro/, which serves a Swagger spec at https://api.smartbill.ro/data/swagger.json. Every endpoint, field name and query parameter used here has been checked against it. Three details are worth flagging:
delete_payment calls DELETE /payment/v2. The plain /payment path accepts
only POST; the delete operation for non-receipt collections lives on /v2,
and takes the same query parameters this tool already sent.
Receipts have no cancel operation. Invoices and proformas can be voided while
keeping their number (/invoice/cancel, /estimate/cancel), but there is no
/payment/cancel — a receipt can only be deleted, and only if it is the last
one in its series.
create_payment sends the internal note as observation, singular. Invoices
and proformas spell the same field observations.
No endpoint returns an invoice's issue date, client or line items.
/invoice/paymentstatus gives three amounts and a paid flag; that is the whole
of the structured data available about an issued document. Everything else exists
only as rendered text inside the PDF.
get_invoice_pdf and get_estimate_pdf therefore default to as: "text" over
HTTP, which extracts the text layer (via unpdf, no system dependency) and
returns it — the only mode whose output a language model can inspect. The other
modes:
document returns the PDF as an MCP embedded resource (a binary blob the
client receives, with mimeType: application/pdf). This is the way to deliver
the actual file to a user over HTTP.
file writes the PDF to SMARTBILL_DOWNLOAD_DIR on the machine running the
server. Over HTTP that is a different machine, and nothing is served from that
directory, so it is useful only for stdio, where client and server share a
filesystem.
base64 returns the raw bytes as a JSON string, for a programmatic caller.
send_document_email is an alternative for delivery: it has SmartBill mail the
document to the client.
GET /invoice/paymentstatus returns invoiceTotalAmount, paidAmount and
unpaidAmount as bare doubles. The documented response schema has no currency
field, and the figures are in whatever currency the invoice was issued in — an
EUR invoice returns the EUR amount, indistinguishable from a RON one.
Read unqualified next to a Romanian invoicing service, that reads as RON. It
happened: a 1250 EUR invoice was reported as "1250 RON", understating it more
than fivefold. get_invoice_payment_status therefore annotates its result with
currency: "unknown" and a note, so the caveat sits beside the number rather
than only in the tool description. get_invoice_pdf is the way to establish the
actual currency.
There is no way to enumerate anything. The published API is 20 paths, and every
document read — /invoice/paymentstatus, /invoice/pdf, /estimate/pdf,
/estimate/invoices — is keyed by cif + seriesName + number. There is no
search, no date range, no pagination, and no customer resource of any kind:
clients are only ever written, as a nested block on a document, with saveToDb
persisting them into the nomenclator with no read path back out.
So "all invoices for client ABC", "everything issued last month" and "list my
customers" are not answerable through this API. /tax, /series and /stocks
are the only endpoints that return a list. The server instructions tell the model
this, so it reports the limitation instead of probing series numbers one at a
time — which would also hit SmartBill's request rate limit.
In hosted mode with a database, the portal report tools answer exactly these questions by reading the web account through an authenticated session; without that configuration the limitation stands, and the instructions adapt to whichever set of tools is registered.
create_invoice_from_estimate sends useEstimateDetails: true with an
estimate reference and no client block, letting SmartBill copy the client and
line items from the proforma — this matches the documented
exempluFacturaDinProforma shape.
MIT
Void a proforma. It stays in SmartBill, keeps its number and is marked cancelled, so the series has no gap. Reversible with restore_estimate.
Use this when a quote is withdrawn or the customer declines. Use delete_estimate only if it is the last one in its series and should disappear entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Estimate number, without the series prefix. | |
| seriesName | No | Estimate series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive and idempotent. Description adds that it's reversible, keeps the number, and prevents series gaps, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct paragraphs with clear structure: first explains what it does, second gives usage guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 params and no output schema, the description covers behavior, reversibility, and differentiation from key siblings. Complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description does not add parameter-level details, but baseline 3 is appropriate as schema already covers all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Void a proforma' with clear verb and resource, and distinguishes from siblings like delete_estimate by explaining that it marks as cancelled and keeps the number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when a quote is withdrawn or the customer declines') and when to use delete_estimate instead, providing clear differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Void an invoice (anulare). The document stays in SmartBill, keeps its number and is marked cancelled, so the series has no gap. Reversible with restore_invoice.
Use this when an invoice was issued in error. Use delete_invoice only if it is the last one in its series and should vanish entirely; use create_reverse_invoice when the undo has to appear in the accounts as a storno document.
Confirm with the user before calling — this changes the status of a real fiscal document.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Invoice number, without the series prefix. | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotation hints (idempotent, destructive), the description adds that the document stays in the system, keeps its number, and is marked cancelled to avoid series gaps. It also mentions reversibility via restore_invoice and warns that it changes the status of a real fiscal document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using three short paragraphs. The first clearly defines the action, the second provides usage context, and the third gives a critical user confirmation warning. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema) and high schema coverage, the description covers all necessary behavioral aspects: what happens on cancellation, reversibility, alternatives, and user safety. It is complete for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description does not add extra meaning to parameters, so a baseline score of 3 is appropriate per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it voids an invoice, specifies the effect (keeps number, marked cancelled, no gap), and distinguishes from sibling tools delete_invoice and create_reverse_invoice. The verb 'void' and the term 'anulare' add specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (invoice issued in error) and when not to, naming specific alternatives (delete_invoice for last in series, create_reverse_invoice for storno). Also instructs to confirm with the user before calling, which is crucial for a destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Void a receipt (chitanta) without removing it: it keeps its number and is marked cancelled, so the receipt series has no gap.
Use this when a receipt was issued in error. This only applies to receipts — to remove a card or bank transfer collection, use delete_payment; to remove the receipt entirely, use delete_receipt.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Receipt number. | |
| seriesName | No | Receipt series. Falls back to SMARTBILL_RECEIPT_SERIES. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true and idempotentHint=true. The description adds behavioral nuance: the receipt keeps its number, is marked cancelled, and series has no gap. This goes beyond annotations but could be more detailed about reversibility or post-void state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs: first explains action and effect, second gives usage with clear alternatives. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully covers the tool's purpose, behavior, and context. Sibling tools are named for disambiguation, and annotations cover safety semantics. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no new parameter details beyond the schema, which is acceptable. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool voids a receipt without removing it, distinguishing it from deletion tools. It specifies the verb 'void' and the resource 'receipt', and differentiates from siblings like delete_payment and delete_receipt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use this when a receipt was issued in error.' And it specifies when not to use: for card/bank transfer collections use delete_payment, to remove entirely use delete_receipt. This provides excellent decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a proforma (estimate) — a quote or payment request that is not yet a fiscal invoice. Returns { series, number, url }.
Use this when the customer needs something to approve or to pay against before being invoiced, or when the user asks for a quote, an offer or a proforma. Use create_invoice instead when the sale is final and a fiscal document is what's wanted.
Once the customer accepts, turn it into an invoice with create_invoice_from_estimate rather than building the invoice by hand. As with invoices, call list_taxes for valid VAT rates.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email overrides used when sendEmail is true. | ||
| client | Yes | The client the document is issued to. | |
| dueDate | No | Due date (YYYY-MM-DD). | |
| isDraft | No | Issue as a draft instead of a final document. | |
| currency | No | Document currency. Default RON. | |
| language | No | Document language: RO, EN, DE, IT, ES, FR, HU. Default RO. | |
| mentions | No | Free text printed on the document. | |
| products | Yes | Line items on the document. | |
| issueDate | No | Issue date (YYYY-MM-DD). Defaults to today at SmartBill. | |
| issuerCnp | No | Personal numeric code of the issuing person. | |
| precision | No | Number of decimals used for amounts. Default 2. | |
| sendEmail | No | Email the document to the client on issue. | |
| issuerName | No | Name of the issuing person. | |
| seriesName | No | Document series. Falls back to the configured default. | |
| delegateAuto | No | Delegate vehicle; only printed when delegateName and delegateIdentityCard are also sent. | |
| delegateName | No | Person collecting the goods (delegat), printed on the document. | |
| deliveryDate | No | Delivery date (YYYY-MM-DD). | |
| exchangeRate | No | Exchange rate to RON when currency is not RON. | |
| observations | No | Internal note; not printed on the document. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. | |
| delegateIdentityCard | No | Delegate ID card series and number; only printed when delegateName is also sent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive. Description adds that it creates a non-fiscal document, returns series/number/url, and is part of a lifecycle (estimate → invoice). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and return value, then usage guidance. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 21 parameters and no output schema, the description explains return value, lifecycle (create → convert), and links to related tools. It is sufficiently complete given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds useful contextual guidance (e.g., 'As with invoices, call list_taxes for valid VAT rates'), but does not repeat schema descriptions. This raises it slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it issues a proforma (estimate), not a fiscal invoice, and specifies return structure. Distinguishes from create_invoice by contrasting use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (customer needs approval/payment before invoicing, user asks for quote/offer/proforma) and when to use create_invoice instead (final sale). Also advises using create_invoice_from_estimate after acceptance and calling list_taxes for VAT rates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a new invoice (factura) in SmartBill for a normal sale. Returns { series, number, url }, where url links to the document in SmartBill Cloud.
Before calling: use list_taxes to get valid taxName/taxPercentage values rather than guessing a VAT rate, and list_series if you do not know which series to issue into.
Do not use this to invoice an existing proforma — use create_invoice_from_estimate, which links the two documents. Do not use it to reverse an invoice — use create_reverse_invoice.
An issued invoice is a fiscal document that generally cannot be deleted afterwards. Confirm the client, the amounts and the VAT rate with the user before calling, and pass isDraft: true while details are still unsettled — a draft can be edited or discarded in SmartBill.
| Name | Required | Description | Default |
|---|---|---|---|
| aviz | No | Delivery note number when invoicing an aviz. | |
| No | Email overrides used when sendEmail is true. | ||
| client | Yes | The client the document is issued to. | |
| dueDate | No | Due date (YYYY-MM-DD). | |
| isDraft | No | Issue as a draft instead of a final document. | |
| payment | No | Record a payment at the same time as the invoice is issued. | |
| currency | No | Document currency. Default RON. | |
| language | No | Document language: RO, EN, DE, IT, ES, FR, HU. Default RO. | |
| mentions | No | Free text printed on the document. | |
| products | Yes | Line items on the document. | |
| useStock | No | Deduct the invoiced quantities from stock. | |
| issueDate | No | Issue date (YYYY-MM-DD). Defaults to today at SmartBill. | |
| issuerCnp | No | Personal numeric code of the issuing person. | |
| precision | No | Number of decimals used for amounts. Default 2. | |
| sendEmail | No | Email the document to the client on issue. | |
| issuerName | No | Name of the issuing person. | |
| paymentUrl | No | Payment link printed on the PDF. | |
| seriesName | No | Document series. Falls back to the configured default. | |
| colectedTax | No | Collected VAT amount, when usePaymentTax is true. | |
| paymentBase | No | Collected base amount, when usePaymentTax is true. | |
| paymentDate | No | Date of the payment recorded with the invoice. | |
| delegateAuto | No | Delegate vehicle; only printed when delegateName and delegateIdentityCard are also sent. | |
| delegateName | No | Person collecting the goods (delegat), printed on the document. | |
| deliveryDate | No | Delivery date (YYYY-MM-DD). | |
| exchangeRate | No | Exchange rate to RON when currency is not RON. | |
| observations | No | Internal note; not printed on the document. | |
| paymentTotal | No | Total collected, when usePaymentTax is true. | |
| usePaymentTax | No | Apply VAT on collection (TVA la incasare). | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. | |
| delegateIdentityCard | No | Delegate ID card series and number; only printed when delegateName is also sent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that an issued invoice generally cannot be deleted afterwards, which is critical behavioral context beyond the annotations. It also mentions the return format. However, it does not elaborate on authentication or rate limits, but given the annotations' limited scope, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences with no fluff, front-loading the purpose and return value, followed by prerequisites, exclusions, and consequences. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (30 parameters, nested objects, no output schema), the description covers purpose, return type, prerequisites, exclusions, and a critical post-condition (inability to delete). The schema handles parameter details, leaving the description to fill contextual gaps, which it does effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters. The description adds some high-level guidance (e.g., using list_taxes for valid tax values), but does not add significant per-parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool issues a new invoice for a normal sale, specifying the resource (invoice in SmartBill) and action (create). It also distinguishes itself from sibling tools like create_invoice_from_estimate and create_reverse_invoice by explicitly stating what not to use it for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (normal sale) and when not to (invoice from proforma, reverse invoice). It also advises using list_taxes and list_series beforehand, and instructs to confirm details with the user and use isDraft for unsettled cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue an invoice from a proforma the customer has accepted. Returns { series, number, url }.
Prefer this over create_invoice whenever a proforma exists: it links the two documents, so the proforma is reported as invoiced by get_estimate_invoices. Rebuilding the same invoice by hand leaves the proforma looking unbilled.
The client and the line items are copied from the proforma — do not re-send them. seriesName is the invoice series to issue into; estimateSeriesName and estimateNumber identify the source proforma.
| Name | Required | Description | Default |
|---|---|---|---|
| dueDate | No | Payment due date (YYYY-MM-DD). | |
| isDraft | No | Issue as a draft instead of a final invoice. | |
| mentions | No | Free text printed on the invoice. | |
| issueDate | No | Invoice issue date (YYYY-MM-DD). Defaults to today at SmartBill. | |
| sendEmail | No | Email the invoice to the client on issue. | |
| seriesName | No | Invoice series to issue into. | |
| observations | No | Internal note; not printed on the invoice. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. | |
| estimateNumber | Yes | Number of the source estimate. | |
| estimateSeriesName | No | Series of the source estimate. Falls back to SMARTBILL_ESTIMATE_SERIES. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool links documents and reports the proforma as invoiced, and warns against re-sending client/line items. It also specifies the return format. This adds useful behavioral context beyond annotations, though it could mention if the action is reversible or any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus a short paragraph. It is front-loaded with the main purpose, followed by usage guidelines, and then parameter clarifications. No redundant information; every sentence serves a purpose. Could be slightly more compact but is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters (1 required) and no output schema, the description covers purpose, behavioral effects, parameter hints, and return format. It provides sufficient context for an AI to decide when to use and how to invoke it. Missing explicit return value details beyond { series, number, url }, but that is enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by explaining that client and line items are copied from the proforma (so not to be sent) and that seriesName is for the invoice while estimateSeriesName/estimateNumber identify the source. This clarifies the role of parameters beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (issue an invoice), the source (from a proforma/estimate), and distinguishes it from the sibling create_invoice by emphasizing that it links documents. The verb 'issue' and resource 'invoice from proforma' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises preferring this tool over create_invoice when a proforma exists, and warns against manually rebuilding the invoice. It also notes that client and line items are copied, so they should not be re-sent. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record money received from a client (incasare). Use this when the user says a customer has paid.
Pass invoices to settle specific invoices — their payment status then reflects the collection, which you can confirm with get_invoice_payment_status. Leave invoices empty only for a standalone payment such as an advance not yet tied to any invoice.
Pick type to match how the money arrived: 'Ordin plata' for a bank transfer, 'Card' for a card payment, 'Chitanta' to issue a numbered paper receipt (this one needs seriesName, the receipt series), 'Bon' for a fiscal receipt. Ask the user rather than guessing — the type appears on the accounting record.
This does not issue an invoice; use create_invoice for that.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text printed on the receipt, e.g. 'Contravaloare factura FF 120'. | |
| type | Yes | Payment method. | |
| value | Yes | Amount collected. | |
| client | Yes | The client the payment comes from. | |
| isCash | No | True for cash collection. Default false. | |
| isDraft | No | Record as a draft instead of a final collection. | |
| currency | No | Payment currency. Default RON. | |
| invoices | No | Invoices this payment settles. | |
| language | No | Document language: RO, EN, DE, IT, ES, FR, HU. Default RO. | |
| issueDate | No | Payment date (YYYY-MM-DD). Defaults to today at SmartBill. | |
| precision | No | Number of decimals used for amounts. Default 2. | |
| seriesName | No | Receipt series, used when type is 'Chitanta'. | |
| exchangeRate | No | Exchange rate to RON when currency is not RON. | |
| observations | No | Internal note. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. | |
| translatedText | No | The `text` value in the document language, when not RO. | |
| useInvoiceDetails | No | Take the client details from the referenced invoice instead of the `client` argument. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains behavioral consequences: settling invoices updates their payment status, confirmable with get_invoice_payment_status. It also notes that this does not issue an invoice. Annotations already indicate it's not read-only and not destructive, which aligns. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three paragraphs) and front-loaded with the main purpose. Each paragraph adds essential information: usage trigger, invoice handling, type guidance, and distinction from create_invoice. No unnecessary words or repetitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, nested objects) and lack of output schema, the description covers key aspects: when to use, how to handle invoices, type selection, and relationship to invoices. It doesn't detail every parameter, but the schema compensates. The description is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter. The description adds value by explaining the purpose of invoices, the meaning of type values, and conditions for seriesName. However, it doesn't cover every parameter beyond what the schema provides, so it provides moderate additional guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Record money received from a client') and the resource (payment). It distinguishes itself from create_invoice by explicitly stating 'This does not issue an invoice; use create_invoice for that.' The title 'Record a payment' aligns with the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use this when the user says a customer has paid.' It explains when to pass invoices vs. leave empty, and advises to ask the user rather than guessing for the type. It also mentions an alternative tool (create_invoice) for issuing invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a storno invoice that reverses an existing invoice in full, into the same series. This is the accounting-visible way to undo an invoice: both documents remain, and they cancel out.
Use this when an invoice is too old to delete and the reversal has to appear in the books. Use cancel_invoice instead when the invoice was issued in error and simply needs to be voided. For a partial correction, issue a new invoice with negative quantities rather than reversing the whole document.
This creates a new fiscal document — confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Invoice number, without the series prefix. | |
| issueDate | No | Issue date of the storno invoice (YYYY-MM-DD). | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=false and destructiveHint=false. The description adds that this creates a new fiscal document and that both documents remain and cancel out, which is useful context. It does not contradict annotations, and the confirmation warning adds transparency. However, it could mention side effects like potentially affecting accounting periods.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, front-loaded with purpose and usage guidance. Every sentence adds value, and there is no unnecessary repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when to use, alternatives, and a confirmation warning. Given the lack of output schema, it could be more complete by briefly stating what the response contains or if any side effects occur (e.g., immediate posting to accounting). However, it is fairly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds minor context (e.g., 'into the same series', fallback defaults) but does not significantly enhance understanding of parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool issues a storno invoice that reverses an existing invoice in full into the same series. It uses a specific verb ('Issue') and resource ('storno invoice'), and distinguishes it from siblings like cancel_invoice and delete_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (invoice too old to delete, needs to appear in books) and when not to (use cancel_invoice for voiding, or issue a new invoice with negative quantities for partial corrections). It also advises confirming with the user before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove a proforma, freeing its number for reuse. Irreversible — there is no restore.
SmartBill only allows this for the LAST proforma in a series and rejects it for any earlier one; use cancel_estimate for those. Ask the user to confirm, and prefer cancel_estimate when unsure.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Estimate number, without the series prefix. | |
| seriesName | No | Estimate series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true; description adds irreversibility and number reuse details. No contradiction. Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load key information with zero waste. Efficient and clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete description for an irreversible mutation tool with series constraints. No output schema needed; all behavioral and usage details are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description does not add additional parameter information beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool permanently removes a proforma and frees its number. Distinguishes from cancel_estimate by specifying it only works for the last in a series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (last proforma only) and when not to (earlier ones), recommends cancel_estimate as alternative, and advises user confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove an invoice, freeing its number for reuse. Irreversible — there is no restore.
SmartBill only allows this for the LAST invoice in a series and rejects it for any earlier one. For those, use cancel_invoice to void it or create_reverse_invoice to storno it.
Destroys a fiscal document: ask the user to confirm explicitly, and prefer cancel_invoice when unsure.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Invoice number, without the series prefix. | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by noting irreversibility ('no restore') and warning about fiscal document destruction. Annotations already declare destructiveHint=true and idempotentHint=true; the description supplements but does not contradict. Idempotency is not explained, but overall transparency is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise paragraphs: main action, usage constraints with alternatives, and a final warning. Every sentence provides essential information without redundancy, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive financial tool with constraints, the description covers the core action, conditions, alternatives, and user confirmation requirement. No output schema exists, but the explanation suffices for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are described in the schema (100% coverage), so the description's role is limited. It mentions 'invoice number' without series prefix, which matches the schema. No additional semantic value beyond what the schema provides, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently remove an invoice, freeing its number for reuse.' This provides a specific verb-resource pair and distinguishes itself from siblings like cancel_invoice and create_reverse_invoice by highlighting the effect of number reuse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the condition for use ('only for the LAST invoice in a series') and provides alternatives ('cancel_invoice' and 'create_reverse_invoice') with clear instructions for uncertain cases, fulfilling explicit when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a collection that has no receipt number of its own — a card payment, bank transfer, promissory note and so on. Irreversible.
Use this to undo a create_payment that recorded the wrong amount, the wrong client or a payment that never arrived. Because these payments have no series and number, identify one either by the invoice it settles (invoiceNumber, plus invoiceSeries) — which is the reliable way — or, if it is not tied to an invoice, by paymentDate and paymentValue together with the client.
For receipts (chitanta), use cancel_payment or delete_receipt instead. Confirm with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| clientCif | No | Client CIF. Not needed when the invoice is known. | |
| clientName | No | Client name. Not needed when the invoice is known. | |
| paymentDate | No | Payment date (YYYY-MM-DD). Not needed when the invoice is known. | |
| paymentType | Yes | Type of the payment to delete. | |
| paymentValue | No | Payment amount. Not needed when the invoice is known. | |
| invoiceNumber | No | Number of the settled invoice. | |
| invoiceSeries | No | Series of the settled invoice. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explicitly states 'Irreversible', aligning with destructiveHint=true. Adds behavioral context about undoing create_payment and identification strategies beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: definition, consequence, usage scenarios, alternatives. All sentences are informative; no fluff. Slightly long but fully justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a delete tool with 8 params and no output schema. Covers identification, prerequisites, irreversibility, and sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds value by clarifying which parameters are needed when (e.g., clientCif not needed if invoice known) and how to identify a payment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool removes non-receipt payments (card, bank transfer, etc.) and explicitly distinguishes from receipt-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (undo wrong payments), when-not-to-use (receipts use cancel_payment/delete_receipt), and identification methods. Also advises confirming with user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove a receipt (chitanta), identified by its series and number. Irreversible.
Use cancel_payment instead when the receipt should stay on record as voided — that is usually what accounting expects. This tool is only for receipts; other payment types are removed with delete_payment. Confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Receipt number. | |
| seriesName | No | Receipt series. Falls back to SMARTBILL_RECEIPT_SERIES. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description says 'Permanently remove' and 'Irreversible', matching the destructiveHint and idempotentHint annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each important: purpose, alternatives, and user confirmation. Front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, alternatives, and user guidance. With annotations and full schema, no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already provides full descriptions for all 3 parameters (100% coverage). Description adds minimal extra meaning beyond identifying receipt by series and number.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it permanently removes a receipt, and distinguishes from cancel_payment and delete_payment for other cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use alternatives (cancel_payment for voided records, delete_payment for other payment types) and advises user confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a proforma has already been invoiced, and which invoices came out of it. Read-only.
Call this before create_invoice_from_estimate to avoid double-invoicing the same proforma, and to answer questions like 'did we ever bill that quote?'. An empty result means the proforma is still open.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Estimate number, without the series prefix. | |
| seriesName | No | Estimate series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces that it is read-only. It adds context about checking invoices, but no additional behavioral traits beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Only three sentences, front-loaded with purpose and usage. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what an empty result means and implies the result is a list of invoices. Adequate for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully described in the schema. The description does not add further details about parameters, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Check whether a proforma has already been invoiced, and which invoices came out of it.' It uses specific verbs and resources, and distinguishes from sibling tools like create_invoice_from_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Call this before create_invoice_from_estimate to avoid double-invoicing' and answers specific questions. Tells what an empty result means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the PDF of an already-issued proforma, for when the user wants the document itself. Read-only.
Returns either a path on the server's filesystem or base64 bytes, depending on how the server is running; force one with as. To send the proforma to the client by email, use send_document_email instead.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | How to return the PDF: 'file' writes it to the server's download directory and returns the path; 'base64' returns the bytes inline. Defaults to whichever suits the transport in use. | |
| number | Yes | Estimate number, without the series prefix. | |
| seriesName | No | Estimate series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds key details: return format varies by server (path or base64) and how to force a specific format via 'as' parameter. Discloses behavior beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose and read-only status. Every sentence adds value: purpose, return format behavior, alternative tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with 100% parameter coverage and readOnlyHint, the description fully addresses usage, return types, and alternatives. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds context for 'as' parameter: explains default behavior and how to force file or base64. Provides additional meaning beyond enum labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Fetch the PDF' with specific resource 'already-issued proforma'. Explicitly states read-only nature and distinguishes from sending via email. Differentiates from siblings like send_document_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use: 'when the user wants the document itself'. Provides explicit alternative: 'To send...by email, use send_document_email instead'. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the printable text of a fiscal receipt (bon fiscal) by its SmartBill id, decoded to plain text. Read-only.
Use it to inspect or reprint what was on a fiscal receipt. This needs the receipt's internal SmartBill id, not a series and number — if you only have those, this is not the right tool.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | SmartBill id of the fiscal receipt. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint annotation by specifying that the tool is read-only ('Read-only'), fetches decoded plain text, and requires the SmartBill id (not series/number). This provides useful operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no waste. The first sentence states the core purpose, the second adds usage guidance, and the third clarifies the identifier. It is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters (one required), no output schema, and annotations providing readOnlyHint, the description adequately describes the output, input semantics, and usage. It is complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has good descriptions (100% coverage) for both parameters. The description further clarifies the 'id' parameter by emphasizing it is the internal SmartBill id, not series/number, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'fiscal receipt (bon fiscal)', and the identifier type 'SmartBill id'. It distinguishes from siblings by specifying that series and number are not the right input, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('inspect or reprint') and when not to ('if you only have those [series and number], this is not the right tool'). It provides clear context for appropriate usage, though it does not name a specific alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer whether an invoice has been paid, and how much of it. Returns invoiceTotalAmount, paidAmount, unpaidAmount and a paid flag. Read-only — this reports on collections, it does not record one.
Use it for questions like 'has invoice FF 120 been paid?' or 'how much does this client still owe on it?', and to confirm the effect after calling create_payment. To record money received, use create_payment.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Invoice number, without the series prefix. | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a read operation. The description reinforces this by stating 'Read-only — this reports on collections, it does not record one.' However, it adds little beyond the annotation, merely elaborating the read-only nature. With annotations covering safety, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose and return values, then usage guidelines. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists all returned fields (invoiceTotalAmount, paidAmount, unpaidAmount, paid flag) and gives example queries. It covers parameter count and usage context adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptions for all three parameters (number, seriesName, companyVatCode). The description does not add additional meaning beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers whether an invoice is paid and returns specific amounts (invoiceTotalAmount, paidAmount, unpaidAmount) and a paid flag. It uses specific verbs ('answer', 'returns') and clearly distinguishes itself from sibling tools like create_payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides example questions ('has invoice FF 120 been paid?', 'how much does this client still owe?') and advises to use it after create_payment to confirm effects. It also directs users to create_payment for recording payments, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the PDF of an already-issued invoice, for when the user wants the document itself — to read it, attach it somewhere, or save a copy. Read-only.
Returns either a path on the server's filesystem or base64 bytes, depending on how the server is running; force one with as. To send the invoice to the client by email, use send_document_email instead — that does not require downloading it first.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | How to return the PDF: 'file' writes it to the server's download directory and returns the path; 'base64' returns the bytes inline. Defaults to whichever suits the transport in use. | |
| number | Yes | Invoice number, without the series prefix. | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds further detail about return format (path or base64) and the ability to force one via 'as' parameter, which goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with about four sentences covering purpose, usage, return format, and alternative tool. It is front-loaded with the primary action. Could be slightly more structured, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has well-documented parameters (100% schema coverage) and no output schema, the description sufficiently describes the return types (path or base64) and the ability to force format. No missing critical information for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions, so baseline is 3. The description adds value by explaining the 'as' parameter's purpose and default behavior, and implies usage of other parameters (e.g., invoice number), elevating it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Fetch' and clearly identifies the resource as 'PDF of an already-issued invoice'. It distinguishes the tool from its sibling 'send_document_email' by stating its purpose for when the user wants the document itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'for when the user wants the document itself'. It also provides an exclusion criterion: 'to send the invoice to the client by email, use send_document_email instead'. This clearly guides the agent on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the document series configured on the account, each with the next number it will issue. Read-only and cheap.
Call this whenever you need a seriesName and do not already have one, and after any call that fails with an unknown-series error — rather than guessing a series name. Also answers 'what number will the next invoice get?'.
| Name | Required | Description | Default |
|---|---|---|---|
| documentType | No | Restrict to one document type. Omit to list every series. | |
| companyVatCode | No | Company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses 'read-only and cheap' beyond the readOnlyHint annotation, adding cost context that helps the agent prioritize.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, each sentence contributing specific guidance. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 optional params, no output schema, and read-only nature, the description fully covers what the tool does and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds value by noting companyVatCode falls back to SMARTBILL_VAT_CODE, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists document series on the account with their next numbers, distinguishing it from sibling tools that are write-oriented or more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to call: when needing a seriesName, after unknown-series errors, and to answer next invoice number. Also advises against guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read stock levels as of a date, optionally narrowed to one warehouse or one product. Read-only.
Use it to answer 'how many do we have left?', to check availability before invoicing with useStock, or to report stock as it stood on a past date. Omitting warehouseName covers every warehouse; omitting date reports today.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date to report stock for (YYYY-MM-DD). Defaults to today. | |
| productCode | No | Narrow to a single product by code. | |
| productName | No | Narrow to a single product by name. | |
| warehouseName | No | Warehouse name. Omit for all warehouses. | |
| companyVatCode | No | Company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, and description adds value by explaining read-only nature, date behavior, and defaults. No contradictions, but the description doesn't disclose pagination or return format, which would have made it a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. The purpose is front-loaded, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return value (stock levels) and covers all usage contexts. The tool has few parameters and no nested objects, so completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by explaining parameter defaults and behavior (e.g., 'Omitting warehouseName covers every warehouse; omitting date reports today'). This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read stock levels as of a date' with optional narrowing by warehouse or product. This is a specific verb+resource combination that distinguishes the tool from sibling tools focused on invoices, payments, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'to answer how many do we have left?', 'check availability before invoicing with useStock', or 'report stock as it stood on a past date'. Also explains defaults for omitted parameters, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the VAT rates configured for the company, as name/percentage pairs. Read-only and cheap.
Call this before create_invoice or create_estimate whenever you are not certain which rate applies, and copy the returned taxName and taxPercentage onto the line items verbatim. Romanian VAT rates and their names change over time and differ per account, so do not rely on remembered values.
| Name | Required | Description | Default |
|---|---|---|---|
| companyVatCode | No | Company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares 'Read-only and cheap' which aligns with annotation readOnlyHint=true. Adds contextual insight: rates change over time and differ per account, justifying read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences in first paragraph for purpose, then usage instructions. No fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description specifies output format (name/percentage pairs). Also provides usage context and caveats, making it complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for companyVatCode. Description doesn't add new meaning beyond schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states verb 'list', resource 'VAT rates', and output format 'name/percentage pairs'. Distinguishes from sibling tools by specifying its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call before create_invoice or create_estimate when uncertain about rates, and to copy returned values verbatim. Also warns against using remembered values due to variation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo cancel_estimate and put a cancelled proforma back into its normal state.
Use this when a quote was voided by mistake and is live again. It cannot bring back a proforma that was deleted — deletion has no undo.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Estimate number, without the series prefix. | |
| seriesName | No | Estimate series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false. Description adds key behavioral context: undoes cancel_estimate, cannot restore deleted ones, and puts back into normal state. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Clear and front-loaded with the core action and limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema, description covers purpose, usage guidelines, and a key limitation. Omits mention of precondition (estimate must be cancelled) but it's implied. Slightly incomplete but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description does not add any parameter-level details beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'undo cancel_estimate and put a cancelled proforma back into its normal state', specifying verb (restore), resource (cancelled estimate), and differentiating from deletion. It distinguishes from sibling tools like cancel_estimate and delete_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when a quote was voided by mistake and is live again' and clarifies when not to use: 'It cannot bring back a proforma that was deleted'. Provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo cancel_invoice and put a cancelled invoice back into its normal, valid state.
Use this when an invoice was voided by mistake and should count again. It has no effect on an invoice that was never cancelled, and it cannot bring back one that was deleted — deletion has no undo.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Invoice number, without the series prefix. | |
| seriesName | No | Invoice series. Falls back to the configured default. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive; the description adds that it is an undo operation with specific limitations (no effect on non-cancelled, no restore for deleted), which complements annotations well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words: first sentence states core action, second gives usage context, third clarifies edge cases. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full parameter coverage and annotations, the description covers purpose, usage, and limitations completely. No output schema is needed for a state-changing tool; the behavior is fully described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 applies. The description does not add any parameter detail beyond the schema, but the schema itself is sufficiently descriptive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'undo cancel_invoice' and the resource 'cancelled invoice', and distinguishes from siblings like cancel_invoice and delete_invoice by specifying it only works on cancelled invoices, not deleted ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('when an invoice was voided by mistake and should count again') and when not to use ('no effect on never-cancelled', 'cannot bring back deleted'). This provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an invoice or proforma that already exists to the client by email, with the PDF attached by SmartBill. Use this when the user asks to send or resend a document.
Omit to, subject or bodyText to use the client's stored address and the templates configured in the SmartBill account — usually the right choice. Pass plain text for the subject and body; encoding is handled for you.
To email a document at the moment it is issued instead, set sendEmail: true on create_invoice or create_estimate rather than calling this afterwards. This sends real mail to a customer: confirm the recipient with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Carbon copy address. | |
| to | No | Recipient address. | |
| bcc | No | Blind carbon copy address. | |
| number | Yes | Document number. | |
| subject | No | Plain text; encoded for the API automatically. | |
| bodyText | No | Plain text; encoded for the API automatically. | |
| seriesName | No | Document series. Falls back to the configured default. | |
| documentType | Yes | Which document to send. | |
| companyVatCode | No | Issuing company CIF. Falls back to SMARTBILL_VAT_CODE. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool sends real email and instructs to 'confirm the recipient with the user first.' Annotations only indicate non-readonly and non-destructive, but the description adds crucial behavioral warning about irreversible action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: starts with core purpose, then usage guidelines, parameter tips, and an alternative. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers most aspects thoroughly, but lacks any mention of return values or success/failure responses. Given no output schema, a brief note on what the tool returns (e.g., confirmation) would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond the schema by explaining that omitting 'to', 'subject', or 'bodyText' uses defaults, and that plain text is acceptable with encoding handled automatically. Schema coverage is 100%, but the description enriches understanding with practical usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Send an invoice or proforma that already exists to the client by email, with the PDF attached by SmartBill.' It specifies the resource (existing document) and verb (send via email), and distinguishes from sibling tools like create_invoice which issue documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('when the user asks to send or resend a document') and when not to: 'To email a document at the moment it is issued instead, set sendEmail: true on create_invoice or create_estimate rather than calling this afterwards.' This provides clear alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0cancel_estimatecancel_invoicecancel_paymentcreate_estimatecreate_invoicecreate_invoice_from_estimatecreate_paymentcreate_reverse_invoicedelete_estimatedelete_invoicedelete_paymentdelete_receiptget_estimate_invoicesget_estimate_pdfget_fiscal_receipt_textget_invoice_payment_statusget_invoice_pdflist_serieslist_stockslist_taxesrestore_estimaterestore_invoicesend_document_emailEach tool targets a distinct operation (invoice/estimate/payment lifecycle, stock, series, taxes, email). Overlapping actions like cancel vs delete vs reverse are clearly differentiated in descriptions, leaving no ambiguity.
All tools follow verb_noun snake_case pattern (e.g., create_invoice, cancel_payment, list_taxes). There are no mixed conventions or unpredictable names, making the set easy to navigate for an agent.
23 tools is slightly high but well-justified by the complexity of accounting operations (invoices, estimates, payments, stocks, email). Each tool serves a necessary purpose without redundancy.
The tool surface covers the full lifecycle of invoices and estimates (create, get PDF, cancel, restore, delete, reverse), payments (create, cancel, delete), plus supporting tools (list series, taxes, stocks, email). No obvious gaps for the SmartBill domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
Brazilian fiscal MCP server - issue NF-e, NFC-e, NFS-e, CT-e, MDF-e and DC-e via SEFAZ.
Fakturownia.pl (Polish invoicing) via MCP: invoices, clients, products, warehouse. Full read-write.
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bogdanripa/smartbill-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
