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

Although no annotations are provided, the description fully discloses the behavioral aspects: it explains that returned caps are live and enforced, and importantly, it warns that price-shaped fields are retired and must never be quoted, directing to `currentPlans.tiers` for actual charges. This is critical behavioral disclosure that prevents misuse of the tool's output.

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 compact, front-loading the core purpose and the key actionable insight ('caps are live and enforced'), then delivering the critical pricing caveat. Every sentence serves a purpose, with no filler. It is succinct while covering essential 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?

Given the tool has zero parameters and no output schema, the description fully compensates by detailing the scope of the response (resources and billing info) and the crucial caveat about retired prices. It also implicitly guides the agent on how to use the data (for caps and actual pricing). There is no missing information that would impede correct invocation or interpretation.

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 tool has zero parameters, so the schema offers no hints. The description compensates by thoroughly describing what the response contains (active counts, caps, card-on-file, next invoice date) and the critical distinction between usage and pricing. Since there are no parameters, the description's role is to clarify the output semantics, which it does well.

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 clearly states that the tool retrieves the caller's org resource caps and usage, listing specific resources (agents, members, workspaces, etc.) and includes billing details like card-on-file and next invoice date. This is a specific verb ('get') and resource ('billing'), and it stands out among siblings because no other tool retrieves billing/caps information.

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 explicitly mentions that the caps are 'live and enforced' and instructs the agent to 'use them,' implying this tool is for checking current usage against limits. It also explicitly states what the tool does NOT do ('This tool does NOT price anything') and warns against quoting retired prices, instead directing to `currentPlans.tiers` for actual charges. This provides clear when/when-not guidance.

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