get_affiliate_portal_stats

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

With no annotations provided, the description discloses several behavioral aspects: it is a GET operation, requires a dashboard JWT, returns scoped counts, and includes rate limit handling (HTTP 429 with Retry-After). However, it does not explicitly state idempotency, safety (read-only), or potential side effects, which are important for a GET tool.

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 concise, consisting of four sentences plus an example and a retry note. It is front-loaded with the core purpose and endpoint, then adds essential details (auth, UI mapping, rate limits). The inline example is helpful but slightly disrupts flow; overall, every sentence earns its place.

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 no output schema and 7 parameters, the description covers key points (endpoint, response fields, auth, rate limits, example) but omits explanations for most parameters and the full response structure. For a tool with moderate complexity, it is adequate 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 only 29%, and the description adds minimal parameter semantics. The example illustrates project_id and user_identifier format, but the other five parameters (from, to, this_month, conversion_external_id, conversion_name) are not explained in the description. The schema’s own descriptions for user_identifier and this_month are present but insufficient.

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 identifies the tool as retrieving affiliate stats for one user identifier, mentioning the endpoint path and the specific response fields (active_referred_users_r2–r4). While it distinguishes itself from sibling tools by focusing on individual stats, it does not explicitly contrast with similar tools like get_project_affiliates_breakdown, leaving some ambiguity.

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 does not provide explicit guidance on when to use this tool versus alternatives. It mentions that query params match the dashboard UI, implying a specific use case, but lacks when-not-to-use instructions or comparisons with sibling tools. The rate limiting advice is helpful but not sufficient for usage guidelines.

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