Skip to main content
Glama

tokmeter_budget

Read-only

Check AI coding spend against daily, weekly, or monthly budgets, optionally scoped to a project or providers. Get spent, remaining, percent used, status, progress bar, and end-of-period projections.

Instructions

Check spend against one or more budgets you pass in (daily, weekly = rolling last 7 days, monthly = calendar month), optionally for one project or a set of providers. For each budget: spent, remaining, percent used with a status, and a progress bar; weekly and monthly also project to the end of the period at the average daily rate so far. Use it for a scoped budget question ("is project X on track this month?"); for a whole-account red/yellow/green status with hours left at the current hourly burn, use tokmeter_budget_alert. Nothing is stored: budgets live only in the call.

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": "tokmeter_budget"
  }
}

Input Schema

NameRequiredDescriptionDefault
projectNoFilter by project name/path substring
providersNoFilter to specific providers (e.g. ['claude-code','cursor'])
daily_budgetNoDaily budget in USD
weekly_budgetNoWeekly budget in USD
monthly_budgetNoMonthly budget in USD

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.19.3

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and closed-world, so the safety burden is light. The description still adds non-obvious behavior beyond annotations: the exact window semantics (weekly = rolling last 7 days, monthly = calendar month), end-of-period projection at average daily rate, and the critical statelessness note that budgets live only in the call and are not stored.

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?

Dense but front-loaded: purpose and window definitions come first, the sibling hand-off last. Every sentence carries information, though the return-value enumeration and the alternative-routing sentence in one paragraph makes it slightly heavy for a single reading.

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?

No output schema exists, but the description compensates by naming the returned fields (spent, remaining, percent used with status, progress bar, end-of-period projection). Combined with the statelessness note and window semantics, an agent has everything needed to call and interpret it correctly.

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 baseline is 3; the description earns extra by defining the temporal semantics of weekly_budget and monthly_budget ('rolling last 7 days' vs 'calendar month'), which the schema does not state. It does not add detail on the project/providers filter syntax beyond the schema, so not a 5.

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 ('Check spend against one or more budgets you pass in') plus the scoping dimensions (project, providers). It explicitly distinguishes itself from the sibling tokmeter_budget_alert, so an agent can route without opening either 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?

Gives an explicit when-to-use case ('scoped budget question — is project X on track this month?') and names the alternative with the exact condition that selects it (whole-account red/yellow/green status with hours left at current hourly burn → tokmeter_budget_alert). Both sides of the routing decision are covered.

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