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

The annotations already declare read-only, idempotent, non-destructive, so the bar is lower, but the description adds precisely the non-obvious behavioral detail: 'worth it to charge for an extra full transaction scan', 'date_window = estimation (confidence:'low')', 'the bill's own totalAmount is authoritative — do NOT rebuild it by summing transactions', and the the-importanted payments gotcha. It also discloses that Pluggy returns no paid/status field. This far exceeds what the annotations convey.

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 long and heavily nested, but the primary purpose is front-loaded in the first sentence and the rest is high-density operational context with no wasted sentences. The payment-status paragraph and reconciliation rule are structurally important. Some edge (the identity rules interspersed in parentheticals) costs a little conciseness, but the length is justified by the number of pitfalls it protects the agent from.

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 its complexity, the description is remarkably complete — response shape, the definition of the pay-around from date, the estimated transaction window, the errors/results batch shape, and the paid-status caveat are all covered. The only remaining gap is the transactions_detail enum values, which would matter for an agent that needs to know how much detail it is requesting.

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 schema has 0% description coverage, so the description has to make up for it. It helps for three of four params: bill_ids, array usage, and how to find the ids; include_transactions, including the extra scan; and account_id (because the bill has no account reference). The gap is transactions_detail — the enum compact/rich/raw is never defined, so an agent choosing 'rich' does not know what it will return.

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 opening sentence names a concrete verb, resource, and scope: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)', then lists the actual fields. It also signals what the tool is not by showing that itemized purchases live on the account, not in the bill payload, and that transaction fetching has its own sibling tools.

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 orchestrates the workflow: it instructs the agent to call openfinance_list_credit_card_bills first to discover ids, it gives an alternative way to get the transactions (fetch them yourself via openfinance_list_transactions with a range ending at billClosingDate), and it says to reuse openfinance_list_credit_card_bills when paid status is what matters. That is explicit when/when-not/alternative guidance with no ambiguity.

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