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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing that `status` is applied to the fetched page rather than server-side and how to compensate via page_size/next_page – a genuine behavioral gotcha. It also notes the underlying endpoint (GET /vendor/bill) and that bill ids are numeric.

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?

Front-loaded with the resource and returned fields, then the pagination caveat, then the endpoint. The inline enum repetition (pending, processing, succeeded, failed, canceled) and the 'Bill ids are numbers' detail are minor redundancy since the schema covers both, but nothing is padded.

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?

With no output schema, the description carries the burden of describing returns and does so by enumerating the bill fields plus pagination mechanics. It does not explain the response envelope (whether total/next_page are always present) or default sort behavior, which leaves a small gap for a no-required-parameter list tool.

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 100%, so all six parameters are already documented in the schema; baseline 3 applies. The description adds only marginal value – it restates the status enum and implies billing-date filtering, but never mentions `sort` or the after/before boundary semantics.

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 and resource ('List billing attempts across all subscriptions') and enumerates the returned fields (amount, status, billing date, retry count, error, subscription, customer). The phrase 'across all subscriptions' implicitly distinguishes it from smartrr_get_subscription_bills, so an agent can route without opening schemas.

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 concrete operational guidance: 'Filter by billing date; `status` filters the returned page only (use page_size 100 and next_page to cover more)' – this tells the agent exactly how to work around the client-side filter. It stops short of explicitly naming smartrr_get_subscription_bills as the alternative for a single subscription, so the when-not is inferred rather than stated.

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