set_agent_key_budget

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It excellently does so by explaining the fail-closed behavior, that spend past the budget is refused until the window rolls, that a 0 budget is invalid, and that a developer key is required. This goes far beyond schema information and provides critical operational context for an agent.

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 three dense sentences, each contributing valuable information: purpose, fail-closed behavior, and constraints/auth. There is no fluff or redundancy. Every word earns its place.

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?

Given the tool has no annotations and no output schema, the description does well covering purpose, behavior, auth requirement, and invalid input handling. The only gap is that it does not describe the success response or what the tool returns after setting a budget. Since the output schema is absent, some indication of the return value would improve completeness, but the operational context is otherwise strong.

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% coverage with descriptions for all parameters, so the baseline is 3. The description reinforces the budget constraint and rolling window concept but does not add significant new parameter-specific meaning beyond what the schema already states. It adds a little context by framing the budget as 'rolling spend' but this is already implied by the window_seconds parameter.

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+resource combination: 'Set or update the rolling spend budget on one agent API key.' This clearly states the tool's function and distinguishes it from sibling key-management tools like revoke_agent_key or create_agent_key. The scope ('one agent API key') further narrows its purpose.

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?

The description implies when to use the tool: when setting or updating a budget on a specific agent API key. It also provides an explicit exclusion for a 0 budget and directs users to revoke the key to block entirely, which serves as an alternative approach. However, it does not name specific sibling tools for comparison, though the alternative guidance is clear.

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