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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are ordered oldest-first, invoices fully covered by credit notes are excluded from the list, and outstandingBalance is a net customer figure that can be lower than the listed invoices sum. It does not mention pagination, result limits, or match semantics.

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?

Purpose and ordering are front-loaded in the first clause, and each subsequent sentence explains a distinct figure (outstanding, grossOutstanding, outstandingBalance). It is nonetheless a dense block of prose for a one-parameter read tool, and the payment-allocation aside in the middle is longer than needed to support correct invocation.

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?

With no output schema, the description carries the burden of explaining the returned figures and does so thoroughly, including the relationship between outstanding, grossOutstanding, and outstandingBalance, and the balanceNote caveat. Remaining gaps are match semantics and pagination/result limits.

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 single required parameter is undocumented in the schema (0% coverage). The description clarifies that it is a customer name to search by rather than an ID, which is genuinely useful, but it does not say whether matching is exact, partial, or fuzzy, nor what happens on ambiguity (resolve_customer exists as a sibling, suggesting ambiguity is possible).

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 a specific verb+resource+scope: 'The unpaid (or part-paid) invoices for one customer, oldest first', which an agent can distinguish from balance-level siblings like ar_aging or ap_aging. It stops short of naming an alternative tool or stating what this is NOT, so sibling differentiation is implied rather than explicit.

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?

'search by customer name' implies the intended invocation, and 'for one customer' implies the scope versus a portfolio-level aging report. However, there is no explicit when-to-use versus when-not guidance and no alternative named (e.g. ar_aging for all customers), so usage is only implied.

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