affiliate_financeads_list_transactions

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

No annotations exist, so the description must carry behavioral disclosure. It adds value by explaining that results are Transaction records with a derived ageDays field and by enumerating commission statuses (earned, pending, reversed, paid), which gives the agent insight into return semantics. However, it omits pagination behavior, auth prerequisites, and other operational traits, leaving some transparency gaps.

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?

Two sentences: first establishes scope, second provides usage triggers and return/pairing info. Front-loaded and efficient with no filler.

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?

The description covers common user questions and return context, but the absence of an output schema and 0% parameter-level schema documentation means the agent must guess at pagination and date-filter details. It's adequate for simple queries but not fully complete for edge cases like paging through large result sets or combining age filters.

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 0% schema coverage, the description compensates partially by tying 'within a window' to from/to, 'specific programme' to programmeId, and statuses to the status parameter. But cursor, offset, limit, minAgeDays, maxAgeDays, and exact status value formatting are not explained, leaving a significant semantic gap for 9 parameters.

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 ('List') and resource ('affiliate transactions') scoped to 'financeAds' with modifiers for window/programme and explicit statuses. This differentiates it from sibling tools like get_earnings_summary and list_clicks, and from similarly named list_transactions tools on other networks.

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?

It provides direct query examples ('what did I earn last month?', 'what's still pending?') that signal exactly when to invoke, and explicitly recommends pairing with get_earnings_summary for aggregate totals. This is explicit guidance on usage and a complementary alternative, though it doesn't list exclusions (e.g., when to prefer list_clicks).

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