Skip to main content
Glama
Sign In
Storno CLI

Storno CLI

Official
by stornoro
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

reports_vat

Read-onlyIdempotent

Summarize collected and deductible VAT by rate, net VAT and invoice counts for a month, quarter, year or custom range, with filters for direction, client, supplier, currency and document type.

Instructions

VAT (TVA) summary of a period: issued (collected) and received (deductible) invoices totalled and broken down by VAT rate, net VAT and invoice counts, in the invoice currencies. Period: year+month (default: current month), year+quarter, year+period=year (whole year) or from+to (YYYY-MM-DD). Filters: direction (outgoing|incoming), clientId, supplierId, currency (ISO code), vatRate (only the lines at that rate count), documentType (invoice|credit_note), finalOnly (leave drafts, rejected and converted documents out). Requires X-Company header (companyId param or STORNO_COMPANY_ID env var).

Input Schema

NameRequiredDescriptionDefault
toNoRange end, YYYY-MM-DD (with from)
fromNoRange start, YYYY-MM-DD (with to)
yearNoReport year (default: current year)
monthNoReport month (1–12); the default period when no quarter / period / range is given
periodNo'year' for the whole year
quarterNoQuarter (1–4) instead of a month
vatRateNoOnly the lines at this VAT rate (e.g. 21); totals are then summed from those lines
clientIdNoOnly invoices of this client (UUID)
currencyNoOnly invoices in this currency (ISO code, e.g. RON)
companyIdNoCompany UUID (overrides STORNO_COMPANY_ID env var)
directionNoOnly issued or only received invoices
finalOnlyNoLeave drafts, rejected and converted documents out (cancelled ones never count)
supplierIdNoOnly invoices of this supplier (UUID)
documentTypeNoOnly invoices or only credit notes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changedv1.0.57
    • addedInput schema / properties / clientId
      Added value: +{
+  "description": "Only invoices of this client (UUID)",
+  "type": "string"
+}
    • addedInput schema / properties / currency
      Added value: +{
+  "description": "Only invoices in this currency (ISO code, e.g. RON)",
+  "type": "string"
+}
    • addedInput schema / properties / direction
      Added value: +{
+  "description": "Only issued or only received invoices",
+  "enum": [
+    "outgoing",
+    "incoming"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / documentType
      Added value: +{
+  "description": "Only invoices or only credit notes",
+  "enum": [
+    "invoice",
+    "credit_note"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / finalOnly
      Added value: +{
+  "description": "Leave drafts, rejected and converted documents out (cancelled ones never count)",
+  "type": "boolean"
+}
    • addedInput schema / properties / from
      Added value: +{
+  "description": "Range start, YYYY-MM-DD (with to)",
+  "type": "string"
+}
    • changedInput schema / properties / month / description
      Previous value: -"Report month (1–12)"New value: +"Report month (1–12); the default period when no quarter / period / range is given"
    • addedInput schema / properties / period
      Added value: +{
+  "description": "'year' for the whole year",
+  "enum": [
+    "year"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / quarter
      Added value: +{
+  "description": "Quarter (1–4) instead of a month",
+  "maximum": 4,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / supplierId
      Added value: +{
+  "description": "Only invoices of this supplier (UUID)",
+  "type": "string"
+}
    • addedInput schema / properties / to
      Added value: +{
+  "description": "Range end, YYYY-MM-DD (with from)",
+  "type": "string"
+}
    • addedInput schema / properties / vatRate
      Added value: +{
+  "description": "Only the lines at this VAT rate (e.g. 21); totals are then summed from those lines",
+  "type": "number"
+}
    • changedInput schema / properties / year / description
      Previous value: -"Report year (e.g. 2026)"New value: +"Report year (default: current year)"
    • removedInput schema / required
      Removed value: -[
-  "year",
-  "month"
-]
  2. First observedv1.0.17

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real value on top: the mandatory X-Company header resolved via companyId or STORNO_COMPANY_ID, that cancelled documents never count, and that finalOnly excludes drafts/rejected/converted. It does not mention volume limits or pagination for large result sets.

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

Conciseness4/5

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

Front-loads what the report returns before moving to period formats and filters, so an agent gets the payload first. It is dense but well ordered; the main inefficiency is re-listing parameters the schema already documents at 100% coverage.

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

Completeness4/5

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

With no output schema and 14 optional parameters, the description does the necessary work of describing the returned totals and breakdown, plus the auth header requirement. Missing is any statement distinguishing it from reports_vat_oss and any note on result size for wide ranges.

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

Parameters3/5

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented. The description largely restates the schema (direction, clientId, supplierId, currency, vatRate, documentType, finalOnly) without adding syntax or interaction rules beyond noting that vatRate restricts the summed lines. Baseline 3 applies since the schema does the heavy lifting.

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

Purpose4/5

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

States a specific resource and scope: VAT (TVA) summary for a period, with issued vs received invoices totalled and broken down by VAT rate. The output shape is spelled out concretely. It does not, however, differentiate itself from the sibling reports_vat_oss, whose domain overlaps enough that an agent could hesitate between them.

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

Usage Guidelines3/5

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

The description explains how to configure the period (year+month, year+quarter, period=year, from+to) and enumerates filters, which implies usage but never states when to pick this report over reports_vat_oss, balance_analysis or reports_sales_analysis. No exclusions or prerequisites are given beyond the X-Company header requirement.

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

Deploy Server

Other Tools