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

Annotations only declare readOnlyHint=true; the description adds genuinely new behavioral context: the call is free, results are newest-first, refunds appear as negative costCents with a refund flag, and paging uses nextCursor. It still does not disclose rate limits or retention window, which keeps it below 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?

The Args/Returns layout is front-loaded and scan-friendly, with one line per parameter and no filler. The 'Returns' block is justified because there is no output schema, though the inline parenthetical noting costCents and the refund flag duplicates the later Returns line.

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 three-parameter read-only paginated query with no output schema, the description covers parameters, defaults, ordering, refund semantics, and the full return shape. Only secondary details such as time zone handling for 'since' or any row-count limits beyond limit=200 are absent.

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 description coverage is 0%, so the description carries the full burden and does so: limit takes 1-200 rows with a default of 50, cursor is the prior answer's nextCursor, and since is an ISO-8601 date filtering rows at or after it. Each of the three parameters gets meaning the bare schema does not provide.

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 states a specific resource and ordering: 'What you spent, per action, newest first', which is far more informative than the title 'Usage history'. It does not explicitly contrast with the sibling quick_balance, so it stops short of full sibling differentiation.

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?

Usage is implied by 'Free' and by the per-action spend framing, which suggests this is the detailed billing log rather than a balance check. However, there is no explicit statement of when to call this instead of quick_balance or equivalent tools, and no prerequisites are given.

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