| name | budget-guard |
| model | sonnet |
| description | Produces a structured APPROVE / WARN / BLOCK decision by checking remaining token budget across query, session, and monthly tiers before an expensive operation runs. Use when: "is this operation within budget", "pre-flight check before web search", "budget alert fired", "before a multi-step pipeline", "session above 70% utilization". |
| license | proprietary |
| category | system-health |
| triggers | ["is this operation within budget","pre-flight check before web search","budget alert fired","before a multi-step pipeline","session above 70% utilization"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"operation_description","type":"string","description":"Description of the operation to check against remaining budget","required":true},{"name":"estimated_tokens","type":"number","description":"Estimated token count for the operation","required":false}] |
| outputs | [{"name":"budget_decision","type":"string","description":"Structured APPROVE/WARN/BLOCK decision with remaining budget across query, session, and monthly tiers"}] |
I. Philosophy
Token budgets are not bureaucratic limits — they are the financial physics of
agent operation. Ignoring them does not make the cost disappear; it makes the
cost invisible until it becomes a crisis. Budget Guard makes cost visible before
it is incurred, giving operators and users the information they need to make
deliberate decisions rather than discovering overruns after the fact.
The three-tier structure (query, session, monthly) mirrors how costs actually
accumulate: individual calls compound into sessions, sessions compound into
monthly spend. A healthy system enforces all three, not just the monthly cap.
II. When to Use
Use this skill:
- Before any orchestration plan that includes web search, compute-heavy
inference, file processing, or multi-step memory operations.
- When a user explicitly asks about remaining budget or cost of a planned
action.
- When BudgetMiddleware response headers (
X-Budget-Remaining,
X-Budget-Tier) indicate the session is above 70% utilization.
- As a pre-flight check in any automated pipeline where token cost is variable
and potentially unbounded.
- After an unexpected spike in usage to determine whether the monthly tier is
at risk.
Do not use this skill as a post-hoc audit tool. It is a forward-looking gate,
not a ledger review. For historical cost analysis, use agent-performance-report.
III. Workflow
Step 1 — Receive proposed action and estimated cost.
Accept two inputs from the caller:
action_description: a plain-language description of the operation to be
checked (e.g., "web search for competitive analysis across 10 URLs")estimated_tokens: the caller's raw token estimate before category
adjustment (use EstimatePlanCost(plan) output if available from the
orchestration engine)
If estimated_tokens is not provided, apply a conservative default based on
action type: web operations default to 2000 tokens, compute operations to 3000,
file operations to 1500, memory operations to 800.
Step 2 — Query remaining budget across all three tiers.
Call BudgetTracker.GetRemaining(userID) to retrieve:
query_remaining: <tokens remaining in current query limit>
session_remaining: <tokens remaining in current session>
monthly_remaining: <tokens remaining this calendar month>
monthly_reset: <ISO date of next monthly reset>
The binding limit is the minimum across all three tiers. A session approaching
its limit is just as blocking as a monthly cap.
