apply_credit_note

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'No cash moves' (a key non-obvious behavior), that both documents must be posted and from the same owner/currency/account, and describes the amount defaulting behavior. It could add what happens on partial netting or whether the operation is reversible, but the core behavioral profile is well disclosed.

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-organized with a lead behavioral sentence, a context paragraph, and a tidy Args block. Every sentence earns its place. Slightly longer than strictly necessary due to the worked example paragraph, but that example materially aids usage understanding, so the length is justified.

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 5-parameter, no-annotation, 0%-schema-coverage tool, the description is exceptionally complete. It explains the business purpose, constraints on every parameter (posted, same owner, same currency, same post account), defaults, when to use alternatives, and the optional owner_type disambiguator. The output schema exists so return-value documentation is not needed. This is a genuinely excellent tool description.

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 coverage is 0%, so the description bears full responsibility for the 5 parameters, and it delivers. Each parameter is explained with type guidance (Decimal-string), defaults ('Defaults to today', 'Defaults to min(...)'), posting/currency/owner constraints, and the purpose of the disambiguator (owner_type). The default formula for amount is particularly valuable semantic information not inferable from 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 states a specific verb+resource ('Net a posted credit note against a posted invoice or bill from the same owner') with a clear behavioral scope ('No cash moves — the credit balance transfers between lots on the same A/R or A/P account'). It clearly distinguishes from sibling pay_invoice by explicitly saying to use that tool instead for cash settlement.

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 explicit when-to-use context ('the most common credit-note settlement path'), a concrete workflow example (overcharge → net against next invoice/outstanding bill), and explicitly names the alternative (''Use pay_invoice instead when the credit note will be settled by sending or receiving cash''). This is a model of usage disambiguation.

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