find_broken_invoice_references

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld behavior, so the safety profile is covered. The description contributes beyond that by disclosing the detection methodology (structured Key references only, never free-text descriptions), which materially affects result interpretation and is not derivable from structured fields.

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?

Front-loaded with the detection target, then a clarifying example and a scope caveat. Dense but every sentence carries information; the em-dash construction is slightly harder to parse than it needs to be.

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?

An output schema exists so return values needn't be explained, and annotations cover safety. However, for a query tool with a required, undocumented 'resource' parameter and no date-filter guidance, the definition leaves the agent guessing on invocation, which is a real gap.

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% and the description says nothing about any of the three parameters. In particular the required 'resource' parameter is entirely opaque - no hint whether it is an entity type, a resource name, or a scope selector - and from_date/to_date semantics are unexplained.

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 names a precise detection target: payments/receipts whose structured AR/AP invoice-Key line reference fails to resolve to a current invoice. It adds the framing 'the general form of a missing invoice' with a concrete supplier-payment example, which distinguishes it from sibling finders like find_unallocated_transactions and verify_invoice_balance.

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?

Usage is implied rather than stated: the tool is for hunting dangling invoice references, and the closing sentence ('Never uses the transaction's free-text description') implies a scope boundary, but no sibling is named and no explicit when-to-use/when-not guidance is given.

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