affiliate_kwanko-advertiser_list_transactions

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

With no annotations, the description must disclose behavior on its own. It mentions that it returns Transaction records with derived ageDays, giving some output transparency. However, it does not state that the operation is read-only, nor does it discuss pagination behavior, default date windows, or authentication requirements, leaving gaps for an agent relying solely on this text.

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 reasonably concise, with two sentences that avoid redundancy. The first sentence packs the core function and network/role context, while the second provides practical use cases and return details. It could be slightly tighter but is well-structured and front-loaded with the action.

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 10 parameters, no output schema, and no annotations, the description is insufficient for full invocation accuracy. It lacks explanation of the required `brand` field, drops several optional parameters, and does not clarify default behavior for date ranges or pagination. The mention of derived ageDays is helpful but not enough to make the tool self-explanatory.

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 purpose of from/to ("window"), programmeId ("specific programme"), and status (via statuses listed), but it leaves the required `brand` parameter unexplained and does not cover limit, offset, cursor, minAgeDays, or maxAgeDays. An agent would struggle to correctly populate all 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 clearly states it lists affiliate transactions with statuses (earned, pending, reversed, paid) on Kwanko specifically in the advertiser role. It distinguishes itself from sibling tools by explicitly mentioning 'Kwanko (advertiser)' and provides concrete example queries that indicate the tool's scope.

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 gives explicit usage examples ("what did I earn last month?", "what's still pending?") and recommends pairing with get_earnings_summary for aggregate totals, which is a helpful cross-reference. However, it does not explicitly state when not to use this tool or mention alternatives for other cases (e.g., clicks or programmes).

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