Skip to main content
Glama
BenjaminJ

enterprise-mcp-gateway

by BenjaminJ
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

getBillingHistory

Retrieve a customer's complete billing history, current balance, payment methods, and invoice details to resolve billing disputes and inquiries.

Instructions

Retrieve customer billing statements, balances, and payment methods - Retrieves complete billing statements, current account balance due, payment methods on file, and historical invoice IDs for a specific customer.

[Usage Guidelines]

  • When to use: Use this tool to answer customer inquiries regarding outstanding balances, billing disputes, invoice history, or active payment methods.

  • When NOT to use: Do NOT use this tool for customer account profile details; use 'getCustomerDetails' instead. Do NOT use to search for customer IDs; use 'listCustomers' first. Do NOT use to check customer support issues; use 'listSupportTickets' instead.

  • Prerequisites: Requires a valid customerId (e.g., 'cust-001') previously discovered using 'listCustomers'.

[Behavior]

  • Operation: Read-only and idempotent. No financial transactions, charges, or balance mutations are executed.

  • Authorization: Requires 'readonly_agent', 'support_agent', or 'admin' role.

  • DLP / Sanitization: All payment card numbers, bank account numbers, and CVVs in responses are automatically masked with [REDACTED] by the zero-allocation gateway sanitizer.

[Parameters]

  • 'customerId' (path, required): Unique customer identifier string (e.g. 'cust-001'). Must correspond to an active or archived customer account.

[Returns]

  • Returns HTTP 200 with JSON object containing: customerId, currency, balanceDue (decimal), paymentMethods (array of masked card tokens), and invoices (array of invoice objects with id, date, amount, status). Returns HTTP 404 if customerId is not found.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
customerIdYesUnique customer identifier in format 'cust-XXX' (e.g., 'cust-001'). Prerequisite is a valid customerId discovered from listCustomers.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.3
    • changedInput schema / properties / customerId / description
      Previous value: -"Unique customer identifier in format 'cust-XXX' (e.g., 'cust-001')."New value: +"Unique customer identifier in format 'cust-XXX' (e.g., 'cust-001'). Prerequisite is a valid customerId discovered from listCustomers."
  2. Changed2 schema fields changedv1.0.1
    • changedInput schema / properties / customerId / description
      Previous value: -"Unique customer identifier"New value: +"Unique customer identifier in format 'cust-XXX' (e.g., 'cust-001')."
    • addedInput schema / properties / customerId / example
      Added value: +"cust-001"
  3. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations provided, the description carries full responsibility for behavioral disclosure, and it delivers thoroughly. It explicitly states the operation is read-only and idempotent, lists the required authorization roles, and reveals that payment data is automatically redacted via DLP sanitization. This goes well beyond a typical tool description.

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

Conciseness5/5

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

The description is well-organized into Purpose, Usage Guidelines, Behavior, Parameters, and Returns sections. Each section is dense with actionable information and does not repeat details already present in the schema unnecessarily. The structure front-loads the tool's purpose and then logically covers when, how, and what to expect.

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?

There is no output schema, so the description correctly explains the return payload: HTTP 200 with a JSON object containing customerId, currency, balanceDue, paymentMethods, and invoices, plus HTTP 404 handling. It also covers prerequisites, authorization, and alternative tools, making the description complete for an agent to select and invoke the tool correctly.

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?

The input schema already documents customerId with an example and prerequisite, giving 100% schema coverage. The description adds extra meaning by specifying that the parameter is a path parameter, required, and must correspond to an active or archived customer account. This is meaningful enrichment beyond the schema, though only modestly so.

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 opens with a precise verb and resource: 'Retrieve customer billing statements, balances, and payment methods,' then enumerates the exact outputs: complete billing statements, balance due, payment methods, and invoice IDs. This clearly distinguishes it from sibling tools like getCustomerDetails and listSupportTickets, which are about profile or support data, not billing.

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?

The description provides explicit 'When to use' and 'When NOT to use' sections, naming specific sibling tools (getCustomerDetails, listCustomers, listSupportTickets) and the conditions that rule them in or out. It also states the prerequisite that a valid customerId must be discovered via listCustomers first, leaving no ambiguity about when to invoke this tool.

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

Deploy Server

Other Tools