Skip to main content
Glama

Kema Invoice

by com.kema-studio
OverviewDiscussionsAdmin

List invoices

list_invoices
Read-only

List the authenticated tenant's invoices, most recent first. Supports filtering by status, document type, and a free-text search on invoice number or client name, plus pagination.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNo1-based page number (default 1).
typeNoFilter by document type.
searchNoFree-text match on invoice number or client name.
statusNoFilter by invoice status.
per_pageNoResults per page (default 20, max 100).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageYes1-based page number returned.
itemsYesInvoices of the requested page, most recent first.
totalYesTotal number of matching documents.
per_pageYesPage size used.
total_pagesYesTotal number of pages.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "items": {
+      "description": "Invoices of the requested page, most recent first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "company": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Client company name, null when unknown."
+          },
+          "currency": {
+            "description": "ISO 4217 currency code (EUR, USD, GBP or CHF).",
+            "type": "string"
+          },
+          "due_date": {
+            "description": "Due date, YYYY-MM-DD.",
+            "type": "string"
+          },
+          "gross_total": {
+            "description": "Total incl. VAT, in the document currency.",
+            "type": "number"
+          },
+          "id": {
+            "description": "Invoice UUID.",
+            "type": "string"
+          },
+          "invoice_number": {
+            "description": "Human-readable invoice number.",
+            "type": "string"
+          },
+          "issue_date": {
+            "description": "Issue date, YYYY-MM-DD.",
+            "type": "string"
+          },
+          "paid_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Payment timestamp (ISO 8601), null while unpaid."
+          },
+          "status": {
+            "description": "Document status: Draft, Sent, Paid, Overdue, Cancelled, Rectified, Accepted, Rejected or Expired.",
+            "type": "string"
+          },
+          "type": {
+            "description": "Document type: invoice, credit_note, provision or quote.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "invoice_number",
+          "type",
+          "status",
+          "issue_date",
+          "due_date",
+          "paid_at",
+          "currency",
+          "gross_total",
+          "company"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "page": {
+      "description": "1-based page number returned.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "per_page": {
+      "description": "Page size used.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "total": {
+      "description": "Total number of matching documents.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "total_pages": {
+      "description": "Total number of pages.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "items",
+    "total",
+    "page",
+    "per_page",
+    "total_pages"
+  ],
+  "type": "object"
+}
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

The readOnlyHint annotation already communicates no side effects, and the description adds useful behavioral details such as default ordering, filtering options, and pagination. It does not describe the response format, but the output schema covers that.

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

Conciseness5/5

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

The description is a single, compact sentence that conveys the core purpose, ordering, filtering capabilities, and pagination. No redundant wording or unnecessary detail is present.

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

Completeness5/5

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

Given the output schema and full parameter descriptions, the description covers all necessary context: what is listed, the ordering, available filters, and pagination. No critical information is missing for an agent to invoke this tool correctly.

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?

All five parameters have descriptions in the schema, so the baseline is met. The description summarizes filtering and pagination but does not add meaning beyond what each parameter's own description already provides.

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

Purpose5/5

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

Clearly states the tool lists invoices for the authenticated tenant, with a specific ordering (most recent first). The scope and resource type are unambiguous, and it is easily distinguished from sibling tools like get_invoice or list_companies.

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

Usage Guidelines2/5

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

The description implies when to use the tool (when a list of invoices is needed) but does not explicitly contrast it with alternatives like get_invoice for single records or other list tools. It gives no direct guidance on when not to use this tool.

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

All Kema Invoice toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources