Skip to main content
Glama

get_usage

Check what your own API key has spent, so you can decide mid-task whether to keep going. Reading it is free: it costs no quota. Optional from and to (YYYY-MM-DD UTC, inclusive, at most 92 days apart) bound the report; omitted, it covers the current month to date. Returns days (per-day, per-endpoint), totals per endpoint over the range, total_units, plus month_used_units against monthly_quota_units and the prepaid balance_millipence (thousandths of a penny). Everything is counted in UNITS, weighted quota units, where a heavier endpoint costs more than one unit per request, so never report these figures as a number of calls. When identity_pooled is true the quota is shared with the other keys belonging to the same owner, so these figures are not yours alone. The key that authenticates the call is the key reported on: there is no way to read another caller's usage. On the hosted endpoint, connect with your own key (a bearer snk_ key or OAuth sign-in): an anonymous connection is refused rather than shown the server operator's usage. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoLast day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to today.
fromNoFirst day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to the first day of the current month. At most 92 days may separate `from` and `to`.

Output Schema

NameRequiredDescriptionDefault
toYesLast day covered, `YYYY-MM-DD` inclusive.
daysYesPer-day breakdown over the range, oldest first. A day with no usage is absent rather than reported as zero.
fromYesFirst day covered, `YYYY-MM-DD` inclusive.
key_idYesIdentifier of the key this usage belongs to.
totalsYesUnits per endpoint over the whole range.
total_unitsYesTotal units over the whole range.
identity_pooledYesWhether quota is pooled across every key belonging to the same identity. When true, these figures are the identity's shared consumption, so another key of the same owner also spends them.
month_used_unitsYesUnits counted against the monthly quota right now: the very number the quota check enforces on, independent of `from`/`to`. Quota is monthly, so this (not `total_units`) is what to compare with `monthly_quota_units`. It includes units recorded but not yet written to the daily counters, so over a whole-month range it can exceed `total_units`; that is not a discrepancy.
balance_millipenceYesPrepaid balance in millipence (thousandths of a penny), for usage beyond the monthly allowance.
monthly_quota_unitsYesThe key's monthly allowance in units.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / month_used_units / description
      Previous value: -"Units counted against the monthly quota right now: the very number\nthe quota check enforces on, independent of `from`/`to`. Quota is\nmonthly, so this — not `total_units` — is what to compare with\n`monthly_quota_units`. It includes units recorded but not yet\nwritten to the daily counters, so over a whole-month range it can\nexceed `total_units`; that is not a discrepancy."New value: +"Units counted against the monthly quota right now: the very number\nthe quota check enforces on, independent of `from`/`to`. Quota is\nmonthly, so this (not `total_units`) is what to compare with\n`monthly_quota_units`. It includes units recorded but not yet\nwritten to the daily counters, so over a whole-month range it can\nexceed `total_units`; that is not a discrepancy."
  2. Added

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: no quota consumed, no mutation of state, auth required, anonymous access refused, and a pooling caveat that changes how results must be interpreted. The units warning ('never report these figures as a number of calls') is exactly the kind of behavioral nuance annotations could never convey.

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

Conciseness3/5

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

Front-loaded correctly, but it is a single dense block and enumerates return fields (`days`, `totals`, `total_units`, `month_used_units`, `monthly_quota_units`, `balance_millipence`) despite an output schema existing, which is redundant length. The units and pooling cautions earn their space; the field list largely does not.

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 two-parameter read tool with a full output schema and no annotations, this covers everything an agent needs: cost, scope, auth mode, default range, output unit semantics, and the shared-quota caveat that affects interpretation of every returned figure.

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

Parameters3/5

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

Schema coverage is 100%, so `from`/`to` formats, inclusivity, defaults and the 92-day cap are already documented in the schema. The description restates the same facts (UTC, inclusive, 92-day span, current-month default) without adding new semantics, so the baseline 3 applies.

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?

States a specific verb and resource with scope: 'Check what your own API key has spent'. It also names the boundary (the authenticating key is the key reported on; no way to read another caller's usage), which makes it unmistakable against every geo/routing sibling in the list.

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?

Gives an explicit when-to-use ('decide mid-task whether to keep going'), an explicit cost condition ('Reading it is free: it costs no quota'), and an explicit exclusion ('there is no way to read another caller's usage'). It also states the preconditions for the hosted endpoint (bearer `snk_` key or OAuth; anonymous connections are refused) and the gateway requirement.

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.

Resources