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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely useful behavioral context beyond that: result ordering (newest first), the fact that email/stripe lookups return zero or one, what expand changes, and the underlying GET endpoint. It stops short of describing pagination/return envelope details, which keeps it from a 5.

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 dense sentences with the list/default behavior front-loaded, followed by filtering, lookup, and expansion, capped by the endpoint mapping. No filler sentences; each clause carries information.

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?

No output schema exists, so the description takes responsibility for signaling returned content (affiliates with visitors/leads/conversions) and the expandable nested objects, which is adequate for a list tool. Pagination behavior is only delegated to schema fields, leaving a minor gap.

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 100%, so all six parameters are already documented; the baseline is 3. The description adds only marginal meaning for a few params (email/stripe_customer_id cardinality, expand rationale) and does not extend the schema's syntax or format guidance.

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?

States a specific verb+resource ('List affiliates') plus scope details: sort order (newest first), returned metrics (visitors/leads/conversions), and the zero-or-one lookup modes. It differentiates itself from read siblings implicitly via 'List', but never names get_affiliate as the id-based alternative, so sibling routing is left to inference.

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?

Explains the in-tool usage patterns: filter by campaign, look up by email or Stripe customer id, expand for detail. However, it gives no when-to-use guidance relative to alternatives like get_affiliate (e.g. 'for a single affiliate by id, use get_affiliate'), so cross-tool selection is only implied.

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