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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new operational context: cost ($0.10 / 10 credits per call), a billing note for failed calls, and prepaid-credit vs x402 payment paths. It also discloses a key behavioral guarantee — unknown fields come back null or empty arrays and totals/line items are 'never invented from garbage' — which tells the agent how to interpret low-confidence output.

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

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

Front-loaded with purpose and output shape, and each clause carries information (domain coverage, input modes, anti-hallucination guarantee, pricing). It is dense to the point of being crowded, and the long provider list (NGN ₦/kobo, KES M-Pesa, OPay, PalmPay, Paystack, Verve POS…) partially duplicates the output-field list already covered by the output schema.

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

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

For a 5-param, fully-described, read-only tool with an output schema, an agent has everything needed: input format, size/format expectations, cost and payment mechanism, and how to read nulls/warnings back. Return-value detail beyond the null semantics is legitimately delegated to the output schema.

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

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

Schema coverage is 100%, so every parameter including tier, filename and content_type is documented in the schema itself; the baseline is 3. The description only reinforces the text-or-file_base64 choice already encoded by the oneOf, adding no extra meaning about tier semantics (what S/M/L actually trade off) or size limits.

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

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

States a specific verb (Parse) plus the resource class (till slip / POS printout / supermarket receipt / mobile-money confirmation) and enumerates the exact output contract (merchant/date/currency/subtotal/tax/total/line_items/confidence/warnings). It also carves out a domain niche ('ugly Africa documents' with named providers and currencies) that separates it from generic extractors like extract.pdf.

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

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

Gives a clear selection rule: 'Prefer this over manual spreadsheet entry or a generic LLM scrape when the document is a receipt or MoMo/M-Pesa slip,' and states the two input modes (text OCR dump vs file_base64). It stops short of the one comparison an agent will most need — versus its closest sibling, parse.invoice — and gives no explicit when-not condition.

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