AgentLedger

Set Agent Budget

ledger_set_budget

DestructiveIdempotent

Set spending caps for an agent. Warns at 80%, blocks spend when exceeded — enforced: a ledger_track call that would cross the cap is rejected.

Dollar caps (monthly_cents/daily_cents) and token caps (monthly_tokens/ daily_tokens) are independent dimensions: dollar caps only cover non-"tokens" rails, token caps only cover rail="tokens" bookkeeping rows (tokens_in/tokens_out). Set both if the agent uses both.

Monthly cap is required; the rest are optional (0 = no limit). Overwrites any existing budget for the agent — with one rule: raising or removing an existing cap requires the workspace_key. An agent_secret can tighten its own caps but never loosen them; to grow an allowance the agent asks its owner (see ledger_request_approval). Claiming a brand-new agent_id requires your workspace_key; that first call mints an agent_secret (returned once — save it); later calls for that agent_id must pass the agent_secret back (no workspace_key needed again).

Input Schema

TableJSON Schema

Name	Required	Description
`agent_id`	Yes	unique agent identifier
`daily_cents`	No	daily spending cap in cents (0 = no daily cap)
`agent_secret`	No	required for every call after the first for this agent_id
`daily_tokens`	No	daily token-burn cap (0 = no cap)
`monthly_cents`	Yes	monthly spending cap in cents
`workspace_key`	No	required when claiming a brand-new agent_id; not needed once the agent_id has been claimed
`monthly_tokens`	No	monthly token-burn cap (0 = no cap)

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 11, 2026

addedInput schema / properties / workspace_key

Added value: +{
+  "default": "",
+  "description": "required when claiming a brand-new agent_id; not\n           needed once the agent_id has been claimed",
+  "type": "string"
+}

Changed2 schema fields changedSep 10, 2026

addedInput schema / properties / daily_tokens

Added value: +{
+  "default": 0,
+  "description": "daily token-burn cap (0 = no cap)",
+  "type": "integer"
+}

addedInput schema / properties / monthly_tokens

Added value: +{
+  "default": 0,
+  "description": "monthly token-burn cap (0 = no cap)",
+  "type": "integer"
+}

Changed1 schema field changedSep 8, 2026

addedInput schema / properties / agent_secret

Added value: +{
+  "default": "",
+  "description": "required for every call after the first for this agent_id",
+  "type": "string"
+}

First observedSep 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses the warn-at-80%/block-on-exceed behavior, that enforcement manifests as a rejected ledger_track call, that existing budgets are overwritten, and precise auth semantics (workspace_key required to raise/remove a cap or claim a new agent_id; agent_secret can only tighten, never loosen). This is rich context that the structured fields do not carry.

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?

The purpose is front-loaded in the first sentence and the denser paragraphs are grouped by topic (cap dimensions, overwrite rule, credential lifecycle). It is longer than most definitions, but nearly every sentence carries operational information; only mild tightening would be possible.

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 7-parameter mutation tool with an output schema present, the description covers everything an agent needs: enforcement behavior, required vs optional params, overwrite semantics, and the full credential lifecycle including the one-time agent_secret return. Return values are appropriately left to the output schema.

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 the baseline is 3, but the description adds genuine meaning: it explains that monthly_cents/daily_cents and monthly_tokens/daily_tokens are independent dimensions covering disjoint rails, that monthly cap is required while the rest default to 0, and which credential each parameter requires. This goes beyond the schema's per-parameter blurbs.

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 first sentence states a specific verb and resource ('Set spending caps for an agent') and immediately elaborates scope with the enforcement mechanism. It is clearly distinguishable from siblings like ledger_track (which it names as the enforcement point) and ledger_request_approval. An agent can identify what this does without opening the schema.

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?

The description gives strong conditional guidance: dollar vs token caps are independent dimensions and 'Set both if the agent uses both,' monthly cap is required, and agents that need a larger allowance are routed to ledger_request_approval (its owner). It names an alternative with the condition that selects it, though it never states an explicit when-not-to-use case.

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

All AgentLedger tools Inspect

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.