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

The annotations already declare read-only, idempotent, non-destructive and open-world, yet the description still adds substantial behavior: case/accent-insensitive name matching rules, the guarantee that unknown or ambiguous names never error, the exact semantics of needs_clarification and partial, candidate ordering (most-owned first), and the free-account teaser limitation. The projectionNotes caveat about divergence from saved analyses is precisely the kind of context annotations cannot carry.

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 comparison scope is front-loaded in the first sentence, followed by resolution rules and then status handling, so the structure follows the agent's decision order. It is a dense single block with some parenthetical asides, but nearly every clause carries actionable information rather than filler.

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?

With no output schema, the description usefully sketches the return shape: xpTotal, xpByGw, a status field, per-entry message plus candidates or suggestions, and projectionNotes. Combined with full schema coverage this is nearly sufficient, though it never explains horizon or how it interacts with xpByGw, and does not state the response envelope for the successful multi-player case.

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 coverage is 100%, so the baseline is 3; the description goes further by spelling out name-resolution semantics (web name, surname, full name, initial+surname, accent folding like Gross = Groß) and clarifying that playerIds are FPL element ids. The horizon parameter is left entirely to the schema, which is the one gap preventing a 5.

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 names a specific verb and resource: compare FPLai's current-season projections (xpTotal, xpByGw) for 2–5 players, resolved by playerIds or playerNames. It also implicitly separates itself from the saved-analysis siblings by noting results can differ from a saved analysis (see projectionNotes). An agent can distinguish this from get_fplai_player (single player) and get_fplai_analysis without opening any schema.

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?

Concrete operational guidance is present: pass playerIds or playerNames, and when a name is ambiguous retry with playerIds or ask the user. It states what needs_clarification and partial statuses mean, which tells the agent how to react. It does not explicitly contrast when to use this versus get_fplai_player or run_fplai_analysis, which keeps it below a 5.

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