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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds minor context about OVERDUE semantics but does not disclose additional behavioral traits such as pagination behavior or default sorting, which are partially present in the schema via the limit parameter.

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 two short sentences totaling 17 words, front-loaded with the primary action. The second sentence provides a concrete, actionable example without redundancy or filler. Every word earns its place.

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 presence of a comprehensive input schema, output schema, and annotations, the description is sufficient. It covers the tool's core purpose and adds a useful filter guideline. No critical information is missing; the schema handles parameter details and the annotations handle safety and idempotency.

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 has 100% description coverage for all five parameters, so the baseline is 3. The description adds meaningful value by explaining that OVERDUE means 'unpaid invoices past due date,' which clarifies an enum value beyond the schema's simple 'Filter by invoice status.' This extra semantic helps with correct parameter selection.

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 'List invoices with optional filters,' which is a specific verb-resource pair. It distinguishes this from invoice-related siblings like get_invoice (single invoice) and create_invoice/write tools, and the OVERDUE example reinforces the listing 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?

The description provides clear context for using the tool—listing invoices with filters—and gives a concrete use case: using status OVERDUE to find unpaid past-due invoices. It does not explicitly mention alternatives like get_invoice for a single invoice, but the usage context is unambiguous enough to guide an agent.

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