Skip to main content
Glama

Plan/Credits: Search Billing History

get_plan_and_credit_billing
Read-onlyIdempotent

[Subscribe/Credits] [What it does] Returns exactly one billing result selected by billing_kind: subscription_billing (paid recurring and one-time subscription purchase records), credit_usage (AI Credits consumption history), or invoice_download (one invoice download URL). [When to use] Use when the user wants to see subscription payment history, AI Credits usage history, or download an invoice. [When not to use] For the current plan or Credits balance, use get_plan_and_credits. For order-level billing, use get_order_paymentlink_and_billing. This tool never creates a payment, changes a subscription, or recharges Credits. [How to use] billing_kind is required and selects exactly one mode per call. Each mode accepts only its own fields: subscription_billing uses start_time/end_time/billing_id/sort_by/pagination; credit_usage uses granularity/model/pagination; invoice_download uses only billing_id and invoice_id. subscription_billing is server-fixed to paid DSers subscription and one-time-purchase records only. [Side effects] None; read-only. [Confirmation] Not required.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "billing_kind": "<billing_kind>"
    },
    "name": "get_plan_and_credit_billing"
  }
}

Input Schema

NameRequiredDescriptionDefault
modelNocredit_usage only. Optional exact upstream model code filter.
sort_byNosubscription_billing only. Sort order; defaults to time_desc.
end_timeNosubscription_billing only. Optional Unix end timestamp. When both time fields are omitted, defaults to now.
page_sizeNoItems per page for the selected mode, up to 100.
billing_idNosubscription_billing only: optional exact subscription or one-time subscription Billing ID as a decimal string. invoice_download: required exact Billing ID returned by subscription_billing.
invoice_idNoinvoice_download only. Required exact invoice ID returned by subscription_billing as a decimal string.
start_timeNosubscription_billing only. Optional Unix start timestamp. Ignored as a default window when billing_id is set; when both time fields are omitted, defaults to 30 days before end_time.
granularityNocredit_usage only. per_round returns individual usage records; daily, weekly, and monthly return aggregated periods. Defaults to per_round.
page_numberNo1-based page number for the selected mode.
billing_kindYesRequired result kind. subscription_billing returns recurring subscription and one-time subscription purchase Billing records; credit_usage returns AI Credits consumption history; invoice_download returns a generated invoice URL.

Output Schema

NameRequiredDescriptionDefault
billing_kindYesSelected result kind: subscription_billing, credit_usage, or invoice_download
credit_usageNoAI Credits usage records; present only when billing_kind is credit_usage
invoice_downloadNoInvoice download URL; present only when billing_kind is invoice_download
toolcall_response_atYesUTC timestamp when the Tool response was returned, formatted as RFC3339.
subscription_billingsNoSubscription billing records; present only when billing_kind is subscription_billing

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'None; read-only' is largely redundant. The description does add real behavioral context the annotations cannot carry: one mode per call, per-mode field exclusivity, and the fact that subscription_billing is server-fixed to paid DSers subscription and one-time-purchase records.

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?

Bracketed headers make it scannable and the routing information is front-loaded before the parameter detail. It is slightly longer than necessary because the read-only and confirmation lines duplicate annotation content, but no sentence is genuinely wasted.

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?

For a 10-parameter, three-mode tool, the description covers mode selection, field scoping, side effects, and confirmation requirements. An output schema exists, so return-value detail is correctly omitted, and nothing an agent needs in order to call 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?

Schema coverage is 100%, so per-parameter meanings are already documented, including the 'X only' scoping notes. The description adds the cross-parameter rule that each mode accepts only its own fields — an exclusivity constraint the flat schema does not express — plus the default time-window behavior in summary form.

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 specific verb and resource ('Returns exactly one billing result') and immediately enumerates the three mutually exclusive result kinds with their payloads. An agent can distinguish this from get_plan_and_credits and get_order_paymentlink_and_billing without opening any schema.

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?

Explicit 'When to use' and 'When not to use' sections name the sibling alternatives and the conditions that select them (current plan/balance vs. order-level billing). It also rules out out-of-scope actions ('never creates a payment, changes a subscription, or recharges Credits').

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.