affiliate_affilae_list_transactions

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that returns are Transaction records and that a derived 'ageDays' field is included, and implies read-only behavior through the verb 'List.' It does not mention pagination, authentication, or rates, but covers key behavioral aspects for a list operation.

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 three sentences, front-loaded with the primary action and resource. Each sentence adds distinct value: purpose, use-case triggers, and return/complement information. No redundant or filler content.

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 tool's moderate complexity (9 parameters, no output schema, no annotations), the description gives a clear functional overview and derived ageDays, but lacks details on return structure, pagination, and parameter semantics for all fields. It is sufficient for a first-order understanding but not fully complete.

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%, so the description must compensate. It explains the domain meaning of core filters (time window, programme, status) but omits others like limit, cursor, offset, minAgeDays, maxAgeDays. It provides partial value beyond the schema, but not enough for a 9-parameter tool.

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 the specific action ('List affiliate transactions') and the resource (Affilae), and distinguishes from sibling tools by scope: 'within a window or for a specific programme.' It also enumerates relevant statuses (earned, pending, reversed, paid), making the purpose unmistakable.

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?

Explicit usage guidance is provided via direct example queries ('what did I earn last month?', 'what's still pending?', 'show me reversed sales') and a clear alternative/complement: 'pair with get_earnings_summary for aggregate totals.' This tells the agent when to use this tool and when to use another.

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