list_invoices

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

No annotations are provided, so the description carries the full burden. It transparently discloses the non-obvious output format behavior (leads with a 'Showing X-Y of Z' line, compact one-line-per-invoice default), the verbose=true mode for full JSON, and the limit=0 count-only behavior. These are behaviors not inferable from schema or enums, and the description shares them well.

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?

Well front-loaded: the first sentence states the purpose. The output-format disclosure comes immediately after, followed by a clean numbered Args list. Slightly verbose with the example phrase 'useful for the what's part of this engagement? listing pattern' and the redundant default restatements (offset default 0, limit default 50 are already in schema), but overall efficient and scannable.

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 6-parameter read tool with no annotations, this is quite thorough. The output schema exists, so return-value documentation isn't strictly required. The description covers output format, filtering semantics, pagination, and the count-only mode. Minor gap: it doesn't explain default sort ordering or whether all six parameters compose together, but for this complexity level it is near-complete.

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 every parameter must be documented in the description. All six parameters (owner_type, status, verbose, limit, job_id, offset) are given semantic meaning beyond their schema types — including enum-like values for owner_type and status ('customer'/'vendor', 'posted'/'open'), the special limit=0 count behavior, and the practical use case for job_id. This fully compensates for 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?

Description clearly states verb 'List' plus resource 'invoices and/or vendor bills', with immediate disambiguation of owner_type (customer=invoices, vendor=bills). It also distinguishes from sibling get_invoice (singular fetch) and describes the output format lead line, firmly establishing purpose and scope.

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?

Explicit guidance on when to use this tool: the job_id parameter is framed for the 'what's part of this engagement?' listing pattern, and owner_type disambiguates between invoices and bills. While it doesn't name specific alternative tools, it gives clear usage context for filtering and pagination patterns that are not obvious from schema alone.

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