List sales invoices

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

Beyond the annotations, the definition reveals several non-obvious behaviors: the current-financial-year default, that any filter replaces Moneybird's default entirely, and that drafts without an invoice_date are only matched by a period containing today. These are exactly the kinds of edge cases that prevent incorrect calls.

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 main description is two sentences with the purpose front-loaded and the behavioral caveat immediately after. The long filter description is warranted because the filter has many keys and special matching rules; it is organized and readable.

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 read-only, idempotent list operation, the definition covers the default period, filter replacement behavior, draft edge case, pagination, and administration selection. No output schema is provided, but the return shape of a list endpoint is evident from the tool name and sibling patterns.

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?

All parameters are fully documented in the schema (100% coverage), including the complex `filter` syntax, keys, examples, and pagination bounds. The main description only adds the hint to pass an explicit `period`, which is already implied by the schema's filter documentation, so it contributes little semantic value beyond the schema.

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 the precise verb-resource pair 'List sales invoices' and adds a meaningful default-scope qualifier. It does not explicitly differentiate from sibling tools like get_sales_invoice or find_sales_invoice_by_invoice_id, though the list-vs-singular naming largely conveys that.

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 a clear within-tool rule: because it defaults to the current financial year, callers needing older data must pass an explicit `period`. However, it does not say when to prefer this tool over alternatives such as get_sales_invoice or find_sales_invoice_by_invoice_id, so cross-tool routing guidance is missing.

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