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

The description reveals significant behavioral detail well beyond the annotations: billClosingDate defines which purchases belong to the cycle; totalAmount is authoritative and should not be rebuilt from transactions; transactions_basis can be exact only when the bank tagged the transaction, otherwise it is an estimate with low confidence; payments[] refer to the previous bill in Brazilian Open Finance; Pluggy returns no paid/status field. This gives the agent both what the tool doesn't say and how to interpret ambiguous data.

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 opening sentence is a good front-loaded summary, and every sentence is technically informative. However, the description becomes long and dense, blending alert warnings, domain notes, batch shape, and parameter semantics into a single unstructured block. Some passages, especially the alternating transactions_basis clauses, feel redundant and could confuse an agent by obfuscating the core rules.

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 tool with no output schema, the description is unusually complete: it explains the default bill-level response, the optional transaction enrichment, the reconciliation basis, the batch shape `{ results, errors }`, and the payment-status caveat. The only material gap is the underdocumented `transactions_detail` parameter and the meaning of its three enum values. Overall, the agent has enough context to call the tool correctly in most situations.

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 entire semantic burden. It provides rich meaning for bill_ids (array), account_id (required only when include_transactions is true), and include_transactions (changes the response shape, adds transactions[], transactions_count, transactions_sum, reconciles_with_total). However, it does not explain the fourth parameter, transactions_detail, with its compact/rich/raw enum, which is a meaningful gap for correct invocation of the richer transaction modes.

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 opens with the verb-resource statement: 'Returns bill-level detail for one or more credit card bills by id' and names the GET endpoint. It goes beyond a basic ID fetch by enumerating the key response fields, and clarifies that this is the detailed bill data tool rather than a list tool. It could more explicitly distinguish itself from openfinance_list_credit_card_bills, though using 'by id' and 'discover ids' already points in that direction.

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 tells the agent to discover bill IDs via openfinance_list_credit_card_bills first, and explains when to pass include_transactions and account_id. It also gives the agent an explicit alternative for pulling transactions yourself through openfinance_list_transactions and recommends openfinance_list_credit_card_bills for paid-status checks. It does not, however, state a crisp and general when-to-use versus when-not-to condition, leaving that partially to inference.

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