Skip to main content
Glama
Sign In
octonull

billingo-mcp

by octonull
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

List documents

billingo_list_documents
Read-onlyIdempotent

Lists invoices, receipts, proformas, and drafts newest first, with filters for type, dates, partner, payment status or method, and document block to find and review billing documents.

Instructions

Lists documents (invoices, receipts, proformas, drafts and more), newest first. Filter by type, invoice date range, fulfillment date range, payment date range, last modification time, partner, payment status/method or document block.

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting at 1.
typeNoRestrict to one document type. Only "invoice" or "receipt" are accepted here.
queryNoFree-text search.
block_idNoRestrict to one document block.
end_dateNoInclude documents invoiced on or before this date.
per_pageNoResults per page (1-100, default 25).
partner_idNoRestrict to one partner.
start_dateNoInclude documents invoiced on or after this date.
paid_end_dateNoInclude documents paid on or before this date.
payment_methodNo
payment_statusNo
paid_start_dateNoInclude documents paid on or after this date.
last_modified_dateNoInclude documents created or modified after this moment, "YYYY-MM-DD HH:MM:SS" in Europe/Budapest local time. Use it to fetch only what changed since a previous call.
fulfillment_end_dateNoInclude documents fulfilled (teljesítés) on or before this date.
fulfillment_start_dateNoInclude documents fulfilled (teljesítés) on or after this date.

Output Schema

NameRequiredDescriptionDefault
dataYes
totalNo
per_pageNo
last_pageNo
current_pageNo
next_page_urlNo
prev_page_urlNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.1.3
    • addedInput schema / properties / fulfillment_end_date
      Added value: +{
+  "description": "Include documents fulfilled (teljesítés) on or before this date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / fulfillment_start_date
      Added value: +{
+  "description": "Include documents fulfilled (teljesítés) on or after this date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / last_modified_date
      Added value: +{
+  "description": "Include documents created or modified after this moment, \"YYYY-MM-DD HH:MM:SS\" in Europe/Budapest local time. Use it to fetch only what changed since a previous call.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / paid_end_date
      Added value: +{
+  "description": "Include documents paid on or before this date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / paid_start_date
      Added value: +{
+  "description": "Include documents paid on or after this date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "current_page": {
+      "type": [
+        "number",
+        "string",
+        "null"
+      ]
+    },
+    "data": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "block_id": {
+            "type": [
+              "number",
+              "string",
+              "null"
+            ]
+          },
+          "cancelled": {
+            "type": [
+              "boolean",
+              "number",
+              "null"
+            ]
+          },
+          "conversion_rate": {
+            "type": [
+              "number",
+              "string",
+              "null"
+            ]
+          },
+          "correction_type": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "currency": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "due_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "fulfillment_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "gross_total": {
+            "type": [
+              "number",
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "number"
+          },
+          "invoice_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "invoice_number": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "items": {
+            "anyOf": [
+              {
+                "items": {
+                  "additionalProperties": {},
+                  "properties": {
+                    "gross_amount": {
+                      "type": [
+                        "number",
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "name": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "net_amount": {
+                      "type": [
+                        "number",
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "net_unit_amount": {
+                      "type": [
+                        "number",
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "quantity": {
+                      "type": [
+                        "number",
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "unit": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "vat": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "online_szamla_status": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "paid_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "partner": {
+            "anyOf": [
+              {
+                "anyOf": [
+                  {
+                    "additionalProperties": {},
+                    "properties": {
+                      "id": {
+                        "type": [
+                          "number",
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "name": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "taxcode": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      }
+                    },
+                    "type": "object"
+                  },
+                  {
+                    "items": {},
+                    "maxItems": 0,
+                    "type": "array"
+                  }
+                ]
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "payment_method": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "payment_status": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "related_documents": {
+            "anyOf": [
+              {
+                "items": {
+                  "additionalProperties": {},
+                  "properties": {
+                    "id": {
+                      "type": [
+                        "number",
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "invoice_number": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "summary": {
+            "anyOf": [
+              {
+                "anyOf": [
+                  {
+                    "additionalProperties": {},
+                    "properties": {
+                      "gross_amount_local": {
+                        "type": [
+                          "number",
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "net_amount": {
+                        "type": [
+                          "number",
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "vat_amount": {
+                        "type": [
+                          "number",
+                          "string",
+                          "null"
+                        ]
+                      }
+                    },
+                    "type": "object"
+                  },
+                  {
+                    "items": {},
+                    "maxItems": 0,
+                    "type": "array"
+                  }
+                ]
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "type": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "last_page": {
+      "type": [
+        "number",
+        "string",
+        "null"
+      ]
+    },
+    "next_page_url": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "per_page": {
+      "type": [
+        "number",
+        "string",
+        "null"
+      ]
+    },
+    "prev_page_url": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "total": {
+      "type": [
+        "number",
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered structurally. The description adds one genuine behavioral fact — results are returned newest first — but says nothing about pagination limits, total counts, or rate behavior beyond what the schema states.

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?

One sentence, front-loaded with the operation and ordering, then the filter set. No filler or repetition; the small cost is a dense comma-list that is slightly harder to scan than a structured breakdown.

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?

For a 15-parameter read-only list tool with an output schema and 87% schema coverage, the description establishes scope, default ordering and the filter surface adequately. The missing piece is paging guidance, which is left entirely to the schema.

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 87%, so per-parameter meaning is largely already documented. The description's filter list (type, invoice date range, fulfillment date range, payment date range, last modification time, partner, payment status/method, block) maps onto parameters but adds no format, interaction, or precedence guidance.

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?

Specific verb + resource ("Lists documents") with an enumeration of what counts as a document (invoices, receipts, proformas, drafts) and an explicit default ordering ("newest first"). An agent can distinguish this list operation from the singular get_document sibling, though no sibling is named directly.

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 enumerates the filter axes, which implies usage for filtered retrieval, but never states when to prefer this over siblings such as billingo_export_documents (bulk export) or billingo_get_document (single record). No exclusions or prerequisites are given.

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