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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: it reads specific fields (applies_to, cost, balance, pending_gifts_count) and explains the race condition where a later atomic action refuses instead of going negative. It also clarifies that it does not consume quota or credit, going well beyond the annotations.

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 dense but every sentence adds value: it starts with what is read, then why (canonical list), then when to use, then what to show, then race condition, then pointers. It is longer than minimal but not wasteful. Could be slightly tightened but remains well-organized and front-loaded.

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's purpose as a preflight check, the description covers all necessary context: what data it returns, when to call, what it does not do, and how to handle a race. It even provides fallback navigation (front_door, URL). No output schema exists, but the description compensates fully.

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 is fully covered. The description implicitly explains the output (fee_cost, balance_before, balance_after) which an agent needs to interpret results. Since there are no parameters to document, the baseline of 4 applies and the description adds value by mentioning output fields.

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 the tool's purpose: passively reading the applies_to list, one-credit cost, private balance, pending_gifts_count, and resulting balance. It specifies the exact data it returns and differentiates itself by positioning as a preflight check before confirmation, which distinguishes it from sibling tools like credit_gift or buy_credit.

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?

Explicitly instructs when to use: immediately before any confirmation that will send city_credit_request_id. It also clarifies what it does not do (wake timers, use quota, reserve, accept, or spend credit) and provides guidance on race conditions. Points to /api/tools and front_door for further help, making usage unambiguous.

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