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

With no annotations, the description carries the full burden and does well: it discloses the return value (count deleted), a per-call cost of 1 CRD charged even on rejection, the 429 exception that costs nothing, and that errors carry a request_id to quote to support. It stops short of stating whether deletion is permanent/reversible or what permissions are required beyond the api_key in schema.

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?

Four sentences, all load-bearing, with the primary action and its scope front-loaded before cost and error-handling details. No filler or repetition.

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, yet the description still names the return value, and it covers billing, error metadata, and the pause alternative. For a destructive single-purpose tool at full schema coverage, 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% and every parameter is already documented, including credit_type_id's 'omit to delete every rule' semantics. The description's restatement of that behavior adds reinforcement but no new meaning beyond the schema, so the baseline 3 applies.

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 (delete) and resource (auto top-up rule) plus the exact scoping variable (credit_type_id) and the omit-means-all behavior. An agent can distinguish it from save_auto_topup and get_auto_topup without opening any 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 both usage modes (single rule by credit_type_id vs. all rules when omitted) and names the explicit alternative for the adjacent intent: 'To pause instead, save_auto_topup with enabled: false.' The condition that selects the alternative is stated, not implied.

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