Invoices_getInvoices

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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose the execution environment ('Runs in your Kuudo deployment, not here') and implies a read-only retrieval operation via 'Returns invoice details.' However, it does not mention side effects, permissions, rate limits, pagination, or output format, leaving the agent with only partial behavioral transparency.

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 short and easily scannable, but it is not optimally structured. The opening phrase 'Catalog entry' is filler that adds no actionable information, and the core purpose appears only in the second sentence. Removing the filler and front-loading the actual behavior would improve the structure.

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 the empty input schema, lack of output schema, and absence of annotations, the description leaves too much unspecified. It does not identify which filters are available, what the returned invoice details look like, whether results are paginated, or how this tool differs from Invoices_getInvoice and the related invoice document/export tools. In a sibling set this large, the description is insufficient for confident selection and invocation.

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 input schema defines zero properties but allows additionalProperties, so the schema itself provides no parameter information. The description adds meaning by stating that the tool accepts 'filters that you specify,' which tells the agent the call will include free-form filter parameters. It does not enumerate those filters, but the zero-parameter baseline makes this acceptable.

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 states a specific verb and resource: 'Returns invoice details for the invoices that match the filters that you specify.' It clearly conveys the plural, filter-based lookup behavior and implies a contrast with the singular sibling Invoices_getInvoice, though it does not explicitly name that sibling. The phrases 'Catalog entry' and 'Runs in your Kuudo deployment, not here' add noise but do not obscure the core purpose.

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 no explicit guidance on when to use this tool versus its many siblings. The only conditional note, 'Runs in your Kuudo deployment, not here,' addresses execution environment rather than tool selection. With siblings like Invoices_getInvoice, Invoices_getInvoicesDocument, and Invoices_createInvoicesExport, an agent needs explicit direction such as 'use getInvoice for a single invoice' or 'use getInvoicesDocument to download the document.'

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