@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

get_usage

Read-only

Retrieves usage metrics for an authenticated Proof account, including verification counts, API calls, and quota usage, filtered by a specific month or up to 12 months of history.

Instructions

Get usage metrics for the authenticated account. Shows verification counts, API calls, and quota usage.

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again. start_login does NOT open this tool.

Input Schema

Name	Required	Description	Default
`months`	No	Number of months of history
`period`	No	Month to query in YYYY-MM format (e.g. 2026-01)

Output Schema

Name	Required	Description
`plan`	Yes
`limit`	Yes	The plan's included verifications per month
`balance`	Yes	The prepaid balance as `GET /me/billing/balance` reports it, without `billing_enabled` (the usage read carries that itself)
`periods`	Yes	The months asked for that have a record, newest first
`hard_limit`	Yes
`percentage`	Yes	`current_usage` as a percentage of `limit`, rounded
`is_on_track`	Yes	null when fewer than 5 days have passed or usage is 0
`card_on_file`	Yes
`top_channels`	Yes
`current_usage`	Yes	Verifications, confirmations, authorizations and delegations this month, counted from the requested months' records: 0 when `period` names another month, since the current month's record is then not among them
`current_period`	Yes	The current month, `YYYY-MM`
`days_remaining`	Yes
`billing_enabled`	Yes
`projected_eom_usage`	Yes
`projection_unreliable`	Yes	true when the projection exceeds the limit three times over
`channels_with_zero_completions`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.7.2Nov 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "Usage for the current billing period, with the months asked for",
+  "properties": {
+    "balance": {
+      "additionalProperties": {},
+      "description": "The prepaid balance as `GET /me/billing/balance` reports it, without `billing_enabled` (the usage read carries that itself)",
+      "properties": {
+        "auto_top_up": {
+          "additionalProperties": {},
+          "properties": {
+            "amount": {
+              "anyOf": [
+                {
+                  "maximum": 9007199254740991,
+                  "minimum": -9007199254740991,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "enabled": {
+              "type": "boolean"
+            },
+            "has_payment_method": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "enabled",
+            "amount",
+            "has_payment_method"
+          ],
+          "type": "object"
+        },
+        "balance": {
+          "additionalProperties": {},
+          "properties": {
+            "amount": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "currency": {
+              "type": "string"
+            },
+            "mills": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "amount",
+            "currency",
+            "mills"
+          ],
+          "type": "object"
+        },
+        "low_balance_threshold": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "top_up_amounts": {
+          "items": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "balance",
+        "low_balance_threshold",
+        "top_up_amounts",
+        "auto_top_up"
+      ],
+      "type": "object"
+    },
+    "billing_enabled": {
+      "type": "boolean"
+    },
+    "card_on_file": {
+      "type": "boolean"
+    },
+    "channels_with_zero_completions": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "current_period": {
+      "description": "The current month, `YYYY-MM`",
+      "type": "string"
+    },
+    "current_usage": {
+      "description": "Verifications, confirmations, authorizations and delegations this month, counted from the requested months' records: 0 when `period` names another month, since the current month's record is then not among them",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "days_remaining": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "hard_limit": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "is_on_track": {
+      "description": "null when fewer than 5 days have passed or usage is 0",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "limit": {
+      "description": "The plan's included verifications per month",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "percentage": {
+      "description": "`current_usage` as a percentage of `limit`, rounded",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "periods": {
+      "description": "The months asked for that have a record, newest first",
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "by_channel": {
+            "additionalProperties": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "properties": {},
+            "type": "object"
+          },
+          "by_hitl_channel": {
+            "additionalProperties": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "properties": {},
+            "type": "object"
+          },
+          "by_type": {
+            "additionalProperties": {},
+            "properties": {
+              "domain": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "email": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "phone": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "social": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "telegram_bot": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "wallet": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "phone",
+              "email",
+              "domain",
+              "social",
+              "wallet",
+              "telegram_bot"
+            ],
+            "type": "object"
+          },
+          "period": {
+            "type": "string"
+          },
+          "total_authorizations": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "total_confirmations": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "total_delegations": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "total_verifications": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "period",
+          "total_verifications",
+          "total_confirmations",
+          "total_authorizations",
+          "total_delegations",
+          "by_type",
+          "by_channel",
+          "by_hitl_channel"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "plan": {
+      "type": "string"
+    },
+    "projected_eom_usage": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "projection_unreliable": {
+      "description": "true when the projection exceeds the limit three times over",
+      "type": "boolean"
+    },
+    "top_channels": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "channel": {
+            "type": "string"
+          },
+          "completion_rate": {
+            "type": "number"
+          },
+          "count": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "channel",
+          "count",
+          "completion_rate"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "plan",
+    "limit",
+    "billing_enabled",
+    "card_on_file",
+    "hard_limit",
+    "balance",
+    "current_period",
+    "current_usage",
+    "percentage",
+    "days_remaining",
+    "projected_eom_usage",
+    "is_on_track",
+    "projection_unreliable",
+    "top_channels",
+    "channels_with_zero_completions",
+    "periods"
+  ],
+  "type": "object"
+}

First observedv1.1.0Sep 9, 2026

TDQS

A3.8/5.0

Behavior4/5

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely non-obvious operational context: the tool requires a Proof account, requires PROOF_API_KEY to be configured and the server restarted, and explicitly does not become available through start_login. That auth/setup disclosure is exactly the kind of behavior annotations cannot express.

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 function, followed by a short access block separated by a blank line. Two tight paragraphs with no filler; the only mild noise is the operational verbosity around setting an env var and restarting.

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?

An output schema exists, so return shape need not be described, and the input schema fully documents both optional parameters. The description covers purpose, reported metrics, and the blocking access requirement, leaving nothing an agent would need before calling it.

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% and both parameters (months with 1-12 bounds, period with a YYYY-MM pattern and example) are documented in the schema. The description adds nothing about months vs period, whether they are mutually exclusive, or which wins if both are supplied, so the baseline 3 applies.

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 description opens with a specific verb and resource ("Get usage metrics for the authenticated account") and enumerates contents: verification counts, API calls, quota usage. That distinguishes it reasonably well from account-level siblings like get_balance or get_subscription, though it never names a sibling explicitly.

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?

It gives an access precondition (needs a Proof account, set PROOF_API_KEY, start_login will not unlock it) but no guidance on when to prefer this over get_api_key_usage, get_platform_summary, or get_balance, which plausibly overlap on usage/quota data. Usage is implied by the reported content rather than stated.

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

Deploy Server