Collections sequence

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

Beyond the annotations (readOnlyHint false, openWorldHint true), the description discloses a significant behavioral trait: it costs credits from the account wallet. It also describes the escalation behavior ('escalating at the right pace and tone for how late it is'). This adds value beyond what annotations provide, though it doesn't mention idempotency or side effects on the invoice itself.

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 sentences with no redundant words. The main function is front-loaded ('An overdue invoice → a ready-to-send collection sequence'), and the credit cost is a crucial detail placed in the second sentence. Every phrase 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 complexity (nested objects, 5 parameters, no output schema), the description is insufficient. It does not explain what the returned collection sequence looks like, what 'steps' means, how 'tone' interacts with escalation, or what 'channel' options imply. The openWorldHint suggests possible side effects, but only the credit cost is mentioned. An agent would struggle to call this tool correctly without inspecting the schema, and the schema lacks descriptions for most fields.

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?

With only 20% schema description coverage, the description must compensate for undocumented parameters, but it does not. It mentions 'overdue' and 'how late it is', which loosely relates to daysOverdue and dueDate, but gives no detail on steps, channel, or tone values. The enums and integer steps are unexplained, leaving the agent to guess their semantics. The description provides high-level context but fails to clarify individual parameter meaning.

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 conversion: 'An overdue invoice → a ready-to-send collection sequence' with escalation based on lateness. It clearly identifies the resource (invoice) and the output (collection sequence), and is distinct from the many parserail siblings which focus on parsing or extraction. The credit cost is also mentioned, adding to purpose specificity.

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 implies when to use it (for overdue invoices) but does not explicitly mention alternatives or when not to use it. There is no comparison to sibling tools, though the name 'dunning' makes its niche clear. It lacks explicit conditions like 'use this only if invoice is overdue' or 'for other actions use X'.

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