Proof Holdings

get_balance

Read-only

Get the prepaid balance (in euro cents and mills), the low-balance threshold, the top-up amounts on offer and the auto top-up setting. Proofs past the plan's included amount are drawn from this balance; once billing is live, an account whose balance is at or below zero is refused new proof requests (402 balance_empty) until it tops up. billing_enabled says whether billing is live. Topping up and changing auto top-up are done by the owner in the dashboard.

ACCESS: needs a Proof account. Authenticate this client (Claude Code: /mcp → Authenticate), then call this tool again. start_login does NOT open this tool.

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": "get_balance"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description
`balance`	Yes
`auto_top_up`	Yes
`top_up_amounts`	Yes	The top-up amounts on offer, in euros.
`top_up_charges`	No	What each amount in `top_up_amounts` charges this account, VAT included, as Stripe Tax works it out from the account's company details: an automatic top-up charges the saved card this total. Null when it cannot be worked out (billing off, no payment made yet, or Stripe not answering); absent from an API that predates it.
`billing_enabled`	Yes	Whether billing is live. While it is off, nothing is drawn from the balance and nothing is paused.
`low_balance_threshold`	Yes	The balance in euro cents below which the owner is sent a low-balance notice.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 9, 2026

addedOutput schema / properties / top_up_charges

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "amount_eur": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "total": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "vat": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "amount_eur",
+          "vat",
+          "total"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "What each amount in `top_up_amounts` charges this account, VAT included, as Stripe Tax works it out from the account's company details: an automatic top-up charges the saved card this total. Null when it cannot be worked out (billing off, no payment made yet, or Stripe not answering); absent from an API that predates it."
+}

AddedNov 2, 2026

TDQS

A4.1/5.0

Behavior5/5

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

readOnlyHint=true already covers the safety profile, and the description goes well beyond it: it discloses the drawdown model, the concrete failure mode (402 balance_empty), the meaning of the billing_enabled flag, and the fact that billing must be live for the refusal to apply. It also flags an authentication prerequisite and notes that start_login does not unlock this tool, which is behaviorally important and not derivable from annotations or schema.

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?

The core purpose is front-loaded in the first sentence, and the failure/eligibility semantics follow logically. Some wording is redundant ('billing_enabled says whether billing is live' restates the flag name), and the auth paragraph is long, but it is actionable rather than filler.

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 a no-parameter read tool with an output schema, the description supplies everything else an agent needs: what the values mean, when the account is blocked, how billing state interacts, and the authentication requirement. No call-critical information is missing.

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?

The tool takes zero parameters, so the baseline is 4, but the description's field-level explanation (cents and mills, threshold, offered top-ups, billing_enabled) overlaps with what the existing output schema should already convey. That overlap is mildly useful for orienting the agent but does not add semantics beyond structured data.

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?

The opening sentence names a specific verb+resource and enumerates exactly what is returned: prepaid balance in euro cents and mills, low-balance threshold, top-up amounts on offer, and auto top-up setting. It does not, however, distinguish itself from the sibling list_balance_ledger, so an agent must infer that this is a current-state snapshot rather than a transactional history.

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

Usage Guidelines4/5

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

It supplies clear operational context: proofs past the included plan amount are drawn from this balance, and a balance at or below zero causes 402 balance_empty refusals. It also pre-empts a wrong path by stating that topping up and changing auto top-up are owner actions in the dashboard, so the agent knows not to look for those here. It stops short of naming a sibling or an explicit 'use this instead of X' rule.

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

All Proof Holdings 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.