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. 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.1/5.0

Behavior5/5

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

Annotations only flag destructive=true and idempotent=true; the description goes well beyond by disclosing the 80% warning, the hard block enforced through ledger_track, that an existing budget is overwritten, and the first-call workspace_key → agent_secret mint-once handshake. This is exactly the behavioral context structured fields cannot 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?

Front-loaded with the core action and the enforcement rule, then layered auth and cap-dimension details. Every sentence carries information, though the line-broken paragraphs are slightly denser than needed for a 5.

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 mutating tool with an output schema, the description covers the destructive overwrite, the auth handshake, and the two-dimensional cap model, so nothing critical 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.

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 meaning the schema lacks: the dollar-vs-token cap independence, the rail="tokens" coverage semantics, the monthly-required / 0-means-no-limit convention, and the workspace_key/agent_secret lifecycle. That is real added value over the terse property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Set spending caps for an agent" is a specific verb+resource, and the description clarifies scope (dollar vs token caps, monthly required) so an agent can distinguish this from ledger_track or ledger_report. It never names an alternative sibling to route against, which keeps it just short of a 5.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: it explains that dollar and token caps are independent and "Set both if the agent uses both," and that ledger_track calls crossing the cap are rejected. There is no explicit "use this when / use X instead" routing against the six sibling tools.

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.