affiliate_adcell_get_earnings_summary

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds context by stating that the return includes 'oldestUnpaidAgeDays' and clarifies this is a summarization tool (implying aggregation, not raw listing). It does not disclose pagination or filtering behavior for the optional parameters, but the read-only nature is strongly implied by 'summarise', and the output detail adds value.

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, front-loaded with the verb and resource, then a usage example and sibling pairing. Every sentence contributes distinct information (purpose, when-to-use, return detail, related tool), with no fluff.

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 core functionality is well described for a summary tool: it explains the aggregation, the date window, the breakdowns, and a specific return field. However, it lacks details on the optional parameters (age filters, pagination) and the full return structure. Since there is no output schema, the description needs to provide more on the return shape beyond a single field, and it only partially does so.

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 partially explains key parameters: 'date window' maps to from/to, 'by programme' maps to programmeId, and 'by transaction status' maps to status. However, it does not explain limit, cursor, maxAgeDays, or minAgeDays, leaving half of the parameters semantically unexplained. The description adds some value but not enough to cover the 8-parameter 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 ('Summarise') and resource ('earnings on Adcell') with clear scope ('across a date window, with breakdowns by programme and by transaction status'). It clearly distinguishes this from sibling tools like list_transactions (which would provide raw records) and get_programme (which provides programme details).

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 an explicit when-to-use directive: 'Use this when the user wants a single-figure answer plus context' with a concrete example. It also suggests pairing with list_transactions to drill into underlying records, indicating an alternative/complementary tool.

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