Skip to main content
Glama

Price usage

defrr_usage_billing

Use when customers are billed on what they use and you need the usage turned into what it costs, month by month. Send each customer-and-product's pricing (flat or volume tiers, a prepaid credit balance, or a hybrid: a fixed monthly fee with included units and a price per unit above them) and the quantity used in each month; get back each month's revenue, the total across all of them, and any prepaid overage (units beyond the balance, flagged and not priced). A hybrid line returns revenue (the fixed fee, which excludes overage), overage (units over the allowance, priced) and revenueInclOverage for each month. Without a startDate the allowance starts again each month you list. With a startDate (and dated usage entries) the cycles follow the contract's anniversary: the fee is booked in full in the month each cycle starts, whether or not anything was used, and the overage in the month the cycle ends; the response also lists each cycle. Quantities are what was used in that month, not a running total. Tiers price band by band, and the bands start again each month. Costs 1 credit per line (refunded if it fails). Nothing you send is stored.

Input Schema

NameRequiredDescriptionDefault
linesYesThe customer-and-product lines to price, up to 50. Each is charged 1 credit.
breakdownNoTrue to list, for each flat or volume month, the units and amount in each band. Defaults to false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changed
    • changedInput schema / properties / lines / items / properties / pricing / description
      Previous value: -"How the usage is priced. flat and volume use tiers; prepaid_credit uses unitPrice and openingBalance."New value: +"How the usage is priced. flat and volume use tiers; prepaid_credit uses unitPrice and openingBalance; hybrid uses baseFee, includedUnits and overageUnitPrice."
    • addedInput schema / properties / lines / items / properties / pricing / properties / baseFee
      Added value: +{
      +  "description": "For hybrid: the fixed fee for each month listed. It is the month's revenue and excludes overage.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / lines / items / properties / pricing / properties / cycle
      Added value: +{
      +  "description": "For hybrid: the cycle length. Only monthly is supported, and it is the default.",
      +  "enum": [
      +    "monthly"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / lines / items / properties / pricing / properties / includedUnits
      Added value: +{
      +  "description": "For hybrid: the units each month's fee includes.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • changedInput schema / properties / lines / items / properties / pricing / properties / model / enum
      Previous value: -[
      -  "flat",
      -  "volume",
      -  "prepaid_credit"
      -]New value: +[
      +  "flat",
      +  "volume",
      +  "prepaid_credit",
      +  "hybrid"
      +]
    • addedInput schema / properties / lines / items / properties / pricing / properties / overageUnitPrice
      Added value: +{
      +  "description": "For hybrid: the price of each unit above includedUnits in a month.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / lines / items / properties / startDate
      Added value: +{
      +  "description": "Hybrid only: the date the contract starts, YYYY-MM-DD. The cycles then follow the contract: each starts on the anniversary of this date (the same day each month, or the month's last day when it has no such day). The fee is the revenue of the month a cycle starts in, in full and whether or not anything was used; the overage of a cycle falls in the month it ends in. With a startDate, usage entries carry a date instead of a period.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / lines / items / properties / through
      Added value: +{
      +  "description": "Hybrid with a startDate only: price every cycle that starts on or before this date, YYYY-MM-DD, including cycles with no usage. Defaults to the date of the last usage entry. To stop a subscription that has ended or isn't being paid, set it to the date it stopped or to the start of the last paid cycle.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / lines / items / properties / usage / description
      Previous value: -"The units used in each month, up to 24 months. A month listed twice is refused."New value: +"Without a startDate: the units used in each month, up to 24 months, one entry per month (a month listed twice is refused). With a startDate (hybrid): dated entries, up to 1000, each assigned to the contract cycle its date falls in; the same date may appear more than once and is added up."
    • addedInput schema / properties / lines / items / properties / usage / items / properties / date
      Added value: +{
      +  "description": "The day the units were used, YYYY-MM-DD. Only with a startDate, on or after it.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / lines / items / properties / usage / items / properties / period / description
      Previous value: -"The month, YYYY-MM."New value: +"The month, YYYY-MM. Not used with a startDate."
    • changedInput schema / properties / lines / items / properties / usage / items / properties / quantity / description
      Previous value: -"Units used in that month: not a running total."New value: +"Units used in that month (or on that day): not a running total."
    • changedInput schema / properties / lines / items / properties / usage / items / required
      Previous value: -[
      -  "period",
      -  "quantity"
      -]New value: +[
      +  "quantity"
      +]
    • changedInput schema / properties / lines / items / properties / usage / maxItems
      Previous value: -24New value: +1000
    • changedInput schema / properties / lines / items / properties / usage / minItems
      Previous value: -1New value: +0
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

The description details critical behavioral traits not found in the schema or standard annotations, such as the credit cost per line ('Costs 1 credit per line'), the data retention policy ('Nothing you send is stored'), and the specific calculation methodology for hybrid lines.

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 very long due to the inherent complexity of the tool's logic, but it is well-structured. Every sentence provides necessary functional context rather than padding.

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?

The definition is exhaustively complete for such a complex financial tool. It covers input expectations, calculation cycles, credit usage, and output behavior, leaving almost no ambiguity for the AI agent.

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

Parameters5/5

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

Given the complexity, the description goes beyond the schema by explaining the logic of the inputs. It clarifies concepts like how tiers function ('Tiers price band by band') and the difference between usage quantities (not running totals).

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 defines the tool's purpose: to convert customer usage into monetary costs month by month. It also identifies the four specific pricing models it supports (flat, volume, prepaid, hybrid).

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?

It provides detailed instructions on when and how to use the tool based on the billing cycle. It contrasts standard monthly usage (without startDate) against contract-based, anniversary cycles (with startDate), which is crucial for correct invocation.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.