central-mcp

Overview Schema Source Related Servers Discussions Admin

token_usage

Aggregate token usage across projects and agents, view breakdowns by project, agent, or source, and check per-agent subscription quota utilization in one query.

Instructions

Portfolio-wide token-usage aggregation (SQL over tokens.db) plus a normalized per-agent subscription quota snapshot.

Separated from orchestration_history so token monitoring can evolve independently of event/dispatch history (and eventually power a live token pane). Reads are windowed by the user's configured timezone.

period: today | week | month | all project: restrict to one project name (mutually exclusive with workspace; if both are given, project wins) workspace: restrict to projects in a workspace (via registry) group_by: project | agent | source — how breakdown is keyed include_quota: include per-agent subscription window utilization (default True). Cached 60s in-process; opt out for fast bulk polling. include_summary: include a pre-rendered markdown HUD (summary_markdown) the orchestrator can surface verbatim (default True). Uses Unicode block bars, emoji color markers (🟢 < 50%, 🟡 50–89%, 🔴 ≥ 90%), and fixed-width alignment inside a fenced code block. Disable to save tokens when you only need the raw structured data.

Returns: { "ok": True, "period": "today", "window": {"start": ISO, "end": ISO} | {"start": null, "end": null}, "group_by": "project", "breakdown": { key: {dispatch, orchestrator, total, input, output} }, # When group_by="project", # tokens that aren't tied to # any registered project # (orchestrator-session usage) # are bucketed under the # special key "ORCHESTRATOR", # always emitted first in the # breakdown. "total": {dispatch, orchestrator, total, input, output}, "quota": { # only when include_quota=True "claude": {"mode": "pro", "five_hour": {"used_pct", "resets_in"}, "seven_day": {"used_pct", "resets_in"}}, "codex": {"mode": "chatgpt", "primary": {...}, "secondary": {...}}, "gemini": {"mode": "auth_only", "auth_type": ..., "note": ...}, "fetched_at": ISO, "cached": bool, }, "summary_markdown": "Token Usage — ...\n```text\n..." # only when include_summary=True # — pre-rendered HUD; surface # verbatim, do not re-format. }

Input Schema

TableJSON Schema

Name	Required	Default
`period`	No	today
`project`	No
`group_by`	No	project
`workspace`	No
`include_quota`	No
`include_summary`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.20.0Sep 21, 2026

TDQS

A4.7/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden — and it delivers. It discloses the 60s in-process caching, the timezone-windowed reads, the ORCHESTRATOR special bucketing key for untied tokens, the mutual-exclusion precedence (project wins over workspace), and the quota cache behavior. For a read/aggregation tool this is exceptionally transparent.

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?

Front-loaded with purpose and sibling differentiation, then a clean param-by-param section, then the return shape. It is long, but the length is earned — 6 parameters and a rich nested return format warrant it. The only cost is the verbose inline-commented return dict, which could arguably be trimmed without losing meaning.

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 output schema in the description documents every return field including the conditional quota variants per provider (claude/codex/gemini), the ORCHESTRATOR key behavior, and the summary_markdown format. All parameters, defaults, cache semantics, and the windowing behavior are covered. Only error cases are unmentioned, which is minor for a read tool.

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?

Schema description coverage is 0%, and the description fully compensates. It supplies the valid values for period (today|week|month|all) that the schema omits, defines group_by keys (project|agent|source), states the project/workspace mutual-exclusion rule, and explains defaults and behavioral effects of include_quota and include_summary. Every one of the 6 params gains meaning beyond the bare schema.

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?

Opens with a specific verb+resource: 'Portfolio-wide token-usage aggregation (SQL over tokens.db) plus a normalized per-agent subscription quota snapshot.' It also explicitly separates itself from the sibling orchestration_history, explaining this tool covers token monitoring while that covers event/dispatch history. An agent can immediately distinguish it from all 18 siblings.

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?

Clearly justifies separation from orchestration_history ('so token monitoring can evolve independently of event/dispatch history') and gives usage direction per parameter: disable include_summary 'to save tokens when you only need the raw structured data' and opt out of include_quota 'for fast bulk polling'. It stops short of a formal when-to-use/when-not-to-use contrast with siblings, but the context is strong.

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