Skip to main content
Glama

MapMap

by ai.mapmap
OverviewDiscussionsAdmin

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. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).

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.4/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 behavioral burden and does so richly: reading is free and consumes no quota, the authenticating key is the only key reported, pooled quota (identity_pooled) may include other keys, and it requires the MapMap gateway env vars. It also clarifies that units are weighted, not call counts, which is a critical behavioral caveat.

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?

It is dense and front-loaded, leading with the purpose and cost profile before parameters and return semantics. The sentences are long but each carries distinct, non-redundant information, though the return-field enumeration partly duplicates the output schema.

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 read-only reporting tool, it covers purpose, cost model, range constraints, quota semantics, and auth requirements. Since an output schema exists, its description of return fields is supplementary rather than required, and nothing an agent needs 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.

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both optional params including the YYYY-MM-DD UTC format and 92-day cap. The description restates these rather than adding new syntax or format meaning, so the baseline of 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?

The description names a specific verb+resource ('Check what your own API key has spent') and immediately frames the scope (self-usage only, no other caller's usage). No sibling tool covers this domain, so there is nothing to confuse it with, and the purpose is unambiguous.

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

Usage Guidelines4/5

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

It states the motivating context clearly ('so you can decide mid-task whether to keep going') and highlights the free/non-quota nature that would drive selection. It stops short of naming an explicit alternative or when-not-to-use condition, but for a self-contained diagnostics tool that context is clear enough.

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

All MapMap toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources