doc-cheap

Overview Schema Source Related Servers Discussions Admin

Check remaining credits

check_balance

Read-only

Check remaining account credits before a document batch or when a scan is refused for lack of credit. Shows free and paid balances, credits spent, and scan counters by status.

Instructions

Return how many credits are left on the account and what the current period has used: the balance, split into this month's free credits (100 every month, drawn first) and the paid credits, the credits spent, and the scan counters broken down by status (recognized, unreadable, no document found, unsupported document, rejected). Takes no arguments and calls GET /v1/usage; under the public sandbox key it answers without calling anything. One recognised document draws one credit, at $0.01; scans that recognised nothing are counted and never charged. Needs a real API key – under the public sandbox key there is no account behind the call, and the answer says so instead of reporting zeros that read like a balance. Use it before working through a batch of documents, or when a scan is refused for lack of credit.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Output Schema

TableJSON Schema

Name	Required	Description
`scans`	Yes
`period`	Yes	Bounds of the current usage period (UTC calendar month).
`credits_spent`	Yes	Credits charged within the period.
`free_allowance`	Yes	This month's free credits, drawn before paid credits; null when the account may not draw free credits (its email address is not confirmed, or its free credits were withdrawn) and for a key with no account.
`balance_credits`	Yes	Credits currently available to the account: this month's free credits plus the paid credits; null for a key with no account (the public sandbox key).
`paid_balance_credits`	Yes	Paid credits: bought or granted to the account, drawn once this month's free credits are used up, and never reset; null only for a key with no account (the public sandbox key).
`credits_spent_by_kind`	Yes	Credits charged within the period, by the kind that paid.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.7Sep 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint and openWorldHint annotations. It discloses the sandbox behavior (no account, answer says so), the need for a real API key, and the credit/charge logic (one recognized doc costs $0.01, unrecognized scans free), providing rich behavioral context.

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 description is dense but efficient; every sentence adds value, from the core result to pricing, sandbox notes, and usage guidance. It is front-loaded with the main purpose, though slightly long for a no-parameter tool.

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 an output schema exists, the description doesn't need to detail the return structure. It covers the essential semantics: credit split, spending, scan counters, costs, sandbox behavior, and when to call it. Nothing an agent needs to use it correctly 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?

With zero parameters, the baseline is 4. The description adds meaning by explaining what the output represents, but since there are no parameters, there is nothing to elaborate on beyond the schema's empty object.

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?

The description clearly states the tool's purpose: returning credit balance and usage details. It names the specific resource (GET /v1/usage) and enumerates the data returned, making it unmistakable from siblings like scan_document and search_docs.

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 states when to use it ('before working through a batch of documents, or when a scan is refused for lack of credit') and even covers the sandbox key exception, guiding the agent on appropriate invocation contexts.

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

Deploy Server