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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses extensive behavioral details: the transactions_basis field with three possible values and their implications, the authoritative totalAmount (don't sum transactions), the cost of the opt-in, and the subtle fact that payments[] typically refers to the previous bill's payment. It also notes Pluggy does not return a paid/status field. This goes far beyond what annotations provide.

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 very long, but it is structured with bolded section headers (e.g., 'ITEMIZED PURCHASES (OPT-IN)') and uses inline code formatting for clarity. It front-loads the core purpose in the first sentence. However, it is far from concise; each sentence carries critical caveats, but the sheer volume may overwhelm an agent. The structure helps but is not enough to overcome the length.

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 0% schema coverage and no output schema, the description is remarkably complete. It explains the response batch shape, the transactions basis logic, the need for account_id, the alternative to opt-in, and the paid-status caveat. It even provides query hints (using billClosingDate as range end). There is no obvious missing information that an agent needs to call it correctly.

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 no descriptions (0% coverage), so the description must compensate. It explains bill_ids (array, discover via list), account_id (needed for include_transactions), and include_transactions (opt-in for transactions). However, it completely omits the 'transactions_detail' parameter with its enum values (compact, rich, raw), leaving that parameter's semantics unexplained. This is a gap given the zero schema coverage.

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 states the tool returns bill-level detail for credit card bills via a specific endpoint (GET /bills/:id), listing exact fields. It distinguishes itself from sibling tools by explicitly mentioning openfinance_list_credit_card_bills for discovery and openfinance_list_transactions for self-fetching transactions, so an agent knows exactly what this tool does and what it doesn't.

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 gives explicit when-to-use guidance: use the opt-in for transactions only when needed, and notes it costs an extra scan; it says to use openfinance_list_credit_card_bills first to get ids; it also advises against assuming paid status from payments[] and recommends the listing tool for payment_status. This clearly differentiates from alternatives and provides exclusions.

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