getCreditCardInvoices

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals an important default behavior (date omission filters to open/future invoices) but does not mention other traits such as id semantics, response format, or error conditions. This adds some value but remains limited.

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 a single, focused sentence that conveys a specific behavioral rule without wasted words. It is front-loaded and easily parsed, making it appropriately concise for a simple list tool.

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?

Despite having an output schema and low complexity, the description omits the core statement of what the tool does—it only provides a conditional edge-case note. It does not explain that 'id' refers to a credit card, nor does it explicitly say it lists invoices. An agent would have to rely on the tool name and sibling context to understand basic usage, which is insufficient for a standalone description.

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 coverage is 67%, with start_date and end_date documented. The description adds meaning by explaining the consequence of omitting both dates (returns only open/future invoices). However, the required 'id' parameter has no description in schema or description, leaving its role ambiguous beyond what the tool name implies.

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 name 'getCreditCardInvoices' and the Portuguese description 'retorna apenas faturas em aberto e/ou futuras' indicate the tool returns invoices. It clearly distinguishes from the singular sibling 'getCreditCardInvoice' by implying a list operation. However, the description focuses on a conditional case rather than stating the core purpose outright.

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 provides clear conditional usage: if start_date and end_date are omitted, only open/future invoices are returned. This guides when to omit dates. It does not explicitly reference alternatives like the singular invoice tool, but the conditional behavior serves as practical usage context.

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