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

Annotations already declare this as read-only, idempotent, and non-destructive, so the description need not repeat that. It adds value by disclosing the output structure (top-line summary, daily histogram, paginated rows), the distinction between lifetime_* and filtered_* metrics, and the effect of include_comparison. It also warns about the date format (Elasticsearch date math), which is a behavioral detail not in the schema. This exceeds the baseline.

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?

Four sentences, all information-dense. The purpose is front-loaded, the output structure is summarized efficiently, the conditional comparison mode is explained with a usage hook, and the date format is noted in a single final sentence. No filler or redundancy.

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?

For a tool with 9 parameters, no output schema, and no enums, the description covers the core behaviors (output shape, comparison flag, date format) but omits any description of the filtering parameters (tags, uuids, domains, q) and pagination mechanics. The read-only annotations reduce the need to discuss side effects, but the parameter semantics are incomplete, leaving agents to guess at how to use the filtering fields.

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 44% (only sort, since, until, include_comparison have descriptions). The description partially compensates by explaining the date math for since/until and the effect of include_comparison, but it does not add anything for q, page, tags, uuids, or domains. The phrase 'paginated per-link rows' hints at page, but no concrete semantics are provided. Given the low coverage, the description does not do enough to fill the gaps.

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 clear purpose: 'Per-link performance: clicks, revenue, commissions, GMV, conversion rate.' It names the resource (per-link) and the specific metrics, distinguishing it from sibling tools like split_performance_by_brand or split_get_earnings. The verb 'returns' and the concrete output structure further solidify the purpose.

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 explicitly instructs when to use include_comparison: 'use that for any "how does this compare" question.' This is direct usage guidance for a key flag. However, it does not name alternative tools or state when NOT to use this tool, relying on the tool name and purpose to differentiate it from siblings. The guidance is adequate but not exhaustive.

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