Invoice reading

Read an invoice

parse_invoice

Read-onlyIdempotent

Read one text invoice into seller, tax ids, date, currency, and net, VAT, and gross amounts. Returns credits_remaining and fields. Amounts are digit strings, not numbers. Costs 0.15 credit only when text is extracted. A missing key, a missing file, or a PDF with no text layer (error no_text_extracted) is not charged. Send file_text when you already have the invoice text, or file_base64 for a text PDF, and set filename so .pdf is read as PDF and .txt as text. Do not send a photo or a scanned image-only PDF. vendor_name is the first line and can be wrong. Key: https://firm.bestsmartgoods.com/signup

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "parse_invoice"
  }
}

Input Schema

Name	Required	Description
`filename`	No	Original file name with its extension. A name ending in .pdf is parsed as PDF. Any other name, or omitted, is treated as plain text.
`file_text`	No	Plain invoice text. Send this or file_base64, not a photo. Preferred when the text is already extracted.
`file_base64`	No	Text PDF, or a .txt file, encoded as base64. Use this instead of file_text when you have the file bytes. Image-only PDFs fail with no_text_extracted and are not charged.

Output Schema

Name	Required	Description	Default
`fields`	Yes
`credits_remaining`	Yes	Balance after this successful call.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 3, 2026

changedInput schema / properties / file_base64 / description

Previous value: -"Invoice file encoded as base64."New value: +"Text PDF, or a .txt file, encoded as base64. Use this instead of file_text when you have the file bytes. Image-only PDFs fail with no_text_extracted and are not charged."

changedInput schema / properties / file_text / description

Previous value: -"Invoice text. Use this or file_base64."New value: +"Plain invoice text. Send this or file_base64, not a photo. Preferred when the text is already extracted."

changedInput schema / properties / filename / description

Previous value: -"Original file name, including its extension."New value: +"Original file name with its extension. A name ending in .pdf is parsed as PDF. Any other name, or omitted, is treated as plain text."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "credits_remaining": {
+      "description": "Balance after this successful call.",
+      "type": "number"
+    },
+    "fields": {
+      "properties": {
+        "confidence": {
+          "description": "0.45 when a tax id or net amount was found, otherwise 0.2.",
+          "type": "number"
+        },
+        "currency": {
+          "description": "HUF when Ft or HUF appears, otherwise EUR when EUR appears.",
+          "enum": [
+            "HUF",
+            "EUR",
+            null
+          ],
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "customer_tax_id": {
+          "description": "Second tax id of that shape, when present.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "emails": {
+          "description": "Up to three email addresses found in the text.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "gross_amount": {
+          "description": "Gross or total amount as a digit string.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "invoice_date": {
+          "description": "First date, as written on the invoice.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "method": {
+          "const": "heuristic",
+          "type": "string"
+        },
+        "net_amount": {
+          "description": "Net amount as a digit string.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "raw_excerpt": {
+          "description": "First 1500 characters of the extracted text.",
+          "type": "string"
+        },
+        "vat_amount": {
+          "description": "VAT amount as a digit string.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "vendor_name": {
+          "description": "First non-empty line. Heuristic, often the seller.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "vendor_tax_id": {
+          "description": "First Hungarian tax id shaped 12345678-1-23.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "credits_remaining",
+    "fields"
+  ],
+  "type": "object"
+}

First observedNov 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safe-read profile; the description goes well beyond by disclosing billing semantics (0.15 credit only on successful text extraction, free on missing key/file or no_text_extracted), the error code, and the output quirk that amounts are digit strings rather than numbers. It even flags a known reliability caveat (vendor_name taken from the first line and can be wrong).

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-loaded with the outcome, then cost, then input selection, then caveats — a sensible priority order with little waste. The trailing signup URL is slightly out of place in an otherwise purely operational paragraph, but it is a single clause.

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?

Although an output schema exists, the description still adds the non-schema-relevant part an agent needs — data typing of amounts and credit accounting. Combined with the cost/error/no-charge rules, nothing required to call this correctly or interpret failures is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: which parameter to prefer when, how filename extension switches parser modes, and the 'this or that, not a photo' exclusivity. It does not document the vendor_name caveat as a parameter (it is not one), so it stays just below the top mark.

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?

States a specific verb and resource ('Read one text invoice') and enumerates exactly what is extracted (seller, tax ids, date, currency, net/VAT/gross), plus what is returned. There are no siblings, but a caller knows precisely the scope: single invoice, text-based only.

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

Usage Guidelines5/5

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

Explicitly routes between input modes: send file_text when the text is already available, file_base64 for a text PDF, and set filename so extension decides parser. It also names the exclusion ('Do not send a photo or a scanned image-only PDF'), which is the main failure mode an agent could hit.

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

All Invoice reading tools Inspect

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.