spendctl

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

Goes well beyond the annotations by disclosing downstream effects (approved payments complete only on a later sandbox_pay call; denied ones stay refused), the return payload (approval id and new status), and the conflict-resolution rule that the first decision wins on repeats. The first-wins rule sharpens what idempotentHint=true alone cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its precondition, then the consequences and the idempotency rule, with no wasted sentences. The real-product-versus-sandbox role framing is mildly tangential but does justify why the model is permitted to decide.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter mutation tool with no output schema, the description covers what it does, when it may be used, what it returns, and what happens afterward. Nothing an agent needs in order to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 lifecycle meaning for approvalId that the schema does not: it must come from this sandbox and must be reused in sandbox_pay to complete an approved payment. The 'note' parameter and the decision enum are left to the schema, which fully documents them.

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

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

States specific verbs (approves or denies) plus the exact resource (a payment that sandbox_pay reported as waiting for approval), which cleanly separates it from the sibling sandbox_pay that creates those holds. An agent can identify the tool's role without reading the schema.

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

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

Gives an explicit precondition (only with an approval id from this sandbox), names the sibling that produces that id (sandbox_pay), and frames the role distinction between real product and sandbox. It also tells the agent the downstream step: call sandbox_pay again with the same approvalId for an approved payment.

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

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

The annotations already establish read-only and closed-world behavior, and the description adds useful detail about what the tool returns: agent name and mode, limits, approval threshold, exceeded-budget behavior, allowed hosts, and per-window spent/limit/remaining values. The phrase 'Read-only; changes nothing' repeats the annotation but also reinforces the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then usage, then return details. It is efficient overall, though the final read-only sentence is largely redundant with the annotations and the return-value list is somewhat dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: agent mode, per-request limit, approval threshold, exceeded-budget behavior, allowed hosts, and hourly/daily window status. That is sufficient for an agent to call and interpret this read-only budget check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% description coverage for the single sandbox_id parameter, so the baseline is 3. The description does not add syntax, format, or selection guidance beyond what the schema already provides for sandbox_id.

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

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

The description uses a specific verb and resource: it shows the sandbox agent's spending limits, spent amounts, and remaining budget by window. This clearly separates it from siblings such as sandbox_pay, get_policy, and list_receipts, which cover payment, policy, and receipts rather than live budget status.

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

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

It gives clear usage contexts: before a paid call when remaining budget matters, or after a refusal to identify the limit hit. It does not explicitly name alternative tools or state when not to use this one, so it falls short of the strongest possible guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added context is what counts: it discloses that the policy is immutable and that changing presets requires a new sandbox. It also tells the agent the return is raw YAML text rather than a parsed object, which affects how it should be presented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what is returned, then when to use it, then the immutability constraint. No filler or restated name/title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description compensates by describing the returned document's contents. Combined with the immutability note and clear usage triggers, an agent has everything needed to call this correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and its schema coverage is 100% with a description pointing to sandbox_create for the ID. The tool description adds nothing about the sandbox_id itself, but the schema already carries that burden, so a baseline 3 is appropriate.

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

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

States a specific verb and resource (returns the sandbox's spendctl.yaml as text) and enumerates the contents the caller will see: preset name, budgets, allowed hosts, approval rules. This clearly separates it from siblings like check_budget or list_receipts, which report runtime state rather than the policy document.

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

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

Gives explicit use cases: explain why a payment was refused or held, or inspect what a spendctl policy file looks like. It also steers the caller away from trying to mutate the policy ('create a sandbox with another preset instead'), though it does not name the sibling tool sandbox_create explicitly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing 'Read-only' adds little, but the description contributes real behavioral context: newest-first ordering, one line per attempt, the empty-state string 'No payments yet.', and the failure mode of refused attempts carrying reason codes. It does not mention pagination beyond limit or rate limits, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: what it lists, then when to use it, then return shape. It is a dense single paragraph with little waste, though the trailing 'Read-only.' partly repeats the annotation and the return-field enumeration could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating return fields (time, receipt id, method, URL, amount, status) and the empty-result message. For a 2-parameter read-only list tool, an agent has everything needed to call and interpret it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, including range, default and pattern for both parameters, so the schema does the heavy lifting. The description only clarifies that `limit` counts lines/attempts and that ordering is newest first, which is a marginal addition over the schema text.

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

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

States a specific verb (lists) and resource (sandbox agent's most recent payment attempts) with scope and ordering (newest first), plus the three outcome categories covered. An agent can distinguish it from sandbox_pay (which makes payments) and approve (which handles holds) without opening a schema.

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

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

Gives concrete use cases — 'report what happened so far' or 'find a receipt id' — and cross-references sandbox_pay for the approval id after a hold. It stops short of an explicit exclusion (e.g. 'do not use to make or approve payments, use X instead'), but the routing intent is clear.

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

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

Annotations only cover the basic safety hints; the description goes further by explaining that the sandbox has a throwaway wallet, mock facilitator and mock APIs, that no real money moves, and that nothing outside the sandbox is reachable. It also discloses rate limits (5/min) and expiry rules (2 hours idle, 24 hours max), which the agent could not otherwise know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and the call-first constraint are front-loaded in the first two sentences. Every subsequent sentence (environment nature, return contents, limits, preset examples) earns its place with distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly explains what is returned (sandbox_id, policy with budgets/allowed hosts/approval rule, paid endpoints and prices). It also covers lifecycle and rate limits, leaving nothing an agent needs in order to call and reuse the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the preset enum is already fully documented in the schema, so the baseline is 3. The description nevertheless adds intent-level guidance—using 'strict' to see refusals and 'approvals' to see a payment held—which helps an agent choose a preset rather than merely pass a valid enum value.

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

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

States a specific verb and resource ('Creates an isolated spendctl sandbox') and immediately names the return value (sandbox_id). It also distinguishes itself from all siblings by declaring that every other tool needs the sandbox_id, making its role as the entry point unambiguous.

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

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

Gives explicit when-to-use guidance ('Call it first: every other tool needs the sandbox_id') and a precise when-to-create-another condition ('create another only to try a different preset'). No alternative is left to inference.

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

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

Adds substantial context beyond the annotations: payments use a throwaway wallet with no real funds, policy (budget/allowlist/approval) is enforced by the sidecar, requests are always GET, responses are clipped at 20,000 characters, and a result may come back as a refusal or a pending approval id. Annotations only cover safety flags, so this is doing the real work; the only gap is that it doesn't say what the pending-approval path means for the caller's retry/cost beyond the schema's idempotencyKey note, which the description never mentions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and usage directive before detail, and every sentence carries operational information (endpoints, prices, refusal behavior, return shape). It runs long with an inline docs URL and repeated host enumeration, which costs a bit of tightness but not clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates fully by describing the return shape: a one-line summary with HTTP status, amount paid, decision and receipt id, followed by the body, or a refusal with reason, or an approval id. Combined with the endpoint list and GET/clipping constraints, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds flow-level meaning: dryRun yields a decision without paying, approvalId completes a payment previously held and approved, and the url must match one of two priced sandbox endpoints with example syntax. It omits any mention of idempotencyKey, leaving that entirely to the schema.

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

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

States a specific verb and resource ('fetches one of the sandbox's paid endpoints') and explains the full path: routed through the spendctl sidecar which applies budget, allowlist and approval policy before paying. This is clearly distinguishable from siblings like check_budget, get_policy and approve, which only inspect or authorize rather than fetch.

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

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

Gives an explicit directive ('Use it for every paid call in the sandbox') plus the two operating modes: dryRun to see the decision without paying, and approvalId to complete a held-then-approved payment. It also bounds applicability by naming the only two permitted hosts and stating that any other host is refused.

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