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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description builds beyond those without contradicting them. It discloses subtle behaviors: the bank payload contains no transactions (opt-in triggers an extra scan), the three possible values of transactions_basis and what each means, that totalAmount is authoritative and must not be re-derived by summing, that Pluggy does not return a paid/status field, and the counterintuitive semantics that Brazilian Open Finance payments[] typically refer to the previous bill. This is exactly the kind of context an agent cannot infer from annotations or schemas.

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 lengthy but every sentence earns its place: can't afford to waste space given the hidden semantics (false paid-status assumptions, estimated transactions, scan costs). Core data is front-loaded before the opt-in mechanics and gotchas. The main deduction is that it's a dense wall of text without bullet breaks or bolded terms; a light structural pass would make the key warnings (totalAmount authoritative, payments[] = previous bill) easier to surface for a quick-reading agent.

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 and zero schema_parameter descriptions, the description has to deliver everything, and it does. It covers the return shape, the optional enrichment path, the reconciliation field (reconciles_with_total), the estimation basis and its confidence, the batch shape { results, errors }, the paid-status limitation with a recommendation, and a fallback to list_transactions. For a tool this complex (Braziliian Open Finance bill semantics), an agent has enough to select, call, and correctly interpret the result.

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 must carry the full burden for all four parameters. It explains bill_ids ('Pass bill_ids as an array — use list first'), include_transactions ('plus account_id of the credit card, since the bill itself carries no account reference'), and account_id's role implicitly. However, transactions_detail ('compact', 'rich', 'raw') is never described — the agent cannot tell what 'rich' or 'raw' yields without guessing. That gap keeps this from a 5.

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 opens with a specific verb and resource — 'Returns bill-level detail for one or more credit card bills by id' — and enumerates the exact fields returned (dueDate, billClosingDate, totalAmount, financeCharges, payments[]). It clearly differentiates itself from siblings: it's the detail tool distinct from openfinance_list_credit_card_bills (discovery/payment_status) and openfinance_list_transactions (transaction fetching on the account).

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 context is explicitly spelled out: 'use openfinance_list_credit_card_bills first to discover ids', 'To check paid status, prefer openfinance_list_credit_card_bills', and for transactions 'fetch them yourself via openfinance_list_transactions'. It also states when NOT to use the opt-in (costs an extra full transaction scan) and when the estimate is unavoidable (open bills have no billId until the cycle closes). Alternatives are named outright and the selection criteria are clear.

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