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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: the data is live from the FPL API, i.e. freshness is guaranteed rather than cached, which matters for deadline calculations. It does not describe the response shape, which keeps it at a 4.

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 sentences, front-loaded with what is returned, followed by the actionable use case. No filler or repetition.

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 zero-parameter, read-only utility with annotations covering safety, the description supplies purpose, freshness, and use cases. It could name the returned fields (current GW id, next GW id, deadline timestamp), but with no output schema this is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's framing of the three returned values is a small bonus.

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 exactly what is returned: the current gameweek, the next gameweek, and the transfer deadline, sourced live from the FPL API. No sibling (fixtures, players, squads) covers this temporal anchor, so there is no ambiguity to resolve.

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?

Gives concrete usage contexts: anchoring 'this week'/'next week' questions and computing time left before the transfer deadline. It does not mention when not to use it, but no sibling overlaps, so the omission is minor.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real context beyond them: the data is live from the FPL API, the FDR scale is defined (1 easiest, 5 hardest), and the omit-parameter behavior produces a ranked list. It stops short of describing response shape or refresh/rate behavior, but for a read-only analytics tool that is a minor gap.

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?

Three sentences, each earning its place: what is computed, how to call it in both modes, and when to prefer it. Purpose and the key routing decision are front-loaded rather than buried.

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 carries the burden of describing results — and it does, listing average FDR, home/away split, blank/double gameweeks, and the ordering of the ranked list. For a two-parameter read-only tool, nothing an agent needs to call or interpret it is missing.

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 baseline would be 3; the description earns above that by explaining the semantic consequence of omitting team (rank all 20 teams, easiest first) rather than just 'optional team filter'. It also anchors the default window length to the next gameweek, adding slight meaning beyond the schema's 'default 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?

States a specific verb+resource (fixture run difficulty) and enumerates exactly what it computes: average FDR on a 1-5 scale, home/away split, and blank/double gameweeks. Explicitly distinguishes itself from the sibling get_fixtures, so an agent can route correctly without opening a 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?

Gives both modes of use — 'Pass team for its fixture-by-fixture run; omit it to rank all 20 teams, easiest run first' — and names the alternative with its selection condition: 'Prefer this over get_fixtures when judging transfers, captaincy or chip timing.' When-to-use, when-to-use-the-other, and the branching behavior of an optional parameter are all explicit.

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

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

The annotations already establish that this is a safe, read-only, idempotent query. The description adds useful behavioral context such as the default window of five gameweeks and that data is live from the FPL API, but it does not describe return shape, pagination, or other operational details.

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 tight sentences with the core resource and default behavior front-loaded. Every clause adds useful information about defaults, parameters, or the FDR scale.

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 the rich annotations, full schema coverage, and the absence of an output schema, the description provides enough context to invoke the tool correctly. It covers the default behavior and each parameter's effect, though it could more explicitly distinguish this tool from get_fixture_run.

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 the schema already documents all three parameters. The description adds meaning beyond the schema by explaining that team shows a run from that team's own perspective, gameweek narrows to a single round, and gameweeks_ahead extends the window.

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 resource as FPL fixtures and highlights the key attribute: difficulty ratings on a 1–5 FDR scale, live from the FPL API. It stops short of explicitly naming or contrasting with the sibling get_fixture_run, so it does not earn a 5.

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 explains what happens with no arguments and how each optional parameter changes the view, which gives implied usage context. However, it does not explicitly say when to choose this tool over alternatives such as get_fixture_run, nor does it provide exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds value by disclosing the data source ('Live from the FPL API') and the fallback behavior when no gameweek is specified. It does not mention rate limits, empty-result behavior for future/blank gameweeks, or pagination.

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?

Three tight sentences, front-loaded with the core operation and its default behavior, followed by a freshness note and intent examples. The illustrative queries earn their place by anchoring retrieval to natural-language phrasings.

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 establishes the grain (one row per player), ordering, and default window, which is enough to call it correctly. It stops short of describing what stat columns each row actually contains, which would help an agent interpret the response.

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 80%, so most parameters are already documented (team examples, limit bounds, sort_by enum, gameweek default). The description reinforces ranking direction and filter intent but adds no new syntax or defaults beyond what the schema states; 'position' is the only parameter the description meaningfully supplements.

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 and resource with scope: 'Every player's stats for one gameweek, ranked.' The cross-player, per-gameweek ranking scope makes it clearly distinct from siblings like get_player_history (single-player) and get_xpts (projections) without needing to name them.

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?

Gives concrete usage contexts ('top scorers last week', 'which defenders kept clean sheets in GW9', 'who got the most bonus') that map directly onto agent intents, and notes position/team filtering. It lacks explicit when-not-to-use guidance or a named alternative, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: results come live from the API, the no-argument default returns only currently flagged players ordered newest-news-first, and named players are returned even when fully available. The status-code legend and chance_of_playing note further explain semantics the schema can't express.

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?

Front-loaded with the actionable instruction ('Call this before recommending...') before the mechanics, and every sentence carries a distinct fact. The status-code legend is dense but useful; overall length is justified by the tool's role as a pre-pick gate.

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 must convey return behavior, and it does: who is returned, ordering, and the inclusion of available players plus the chance_of_playing field. It stops short of describing the full record shape (e.g. the news text field), so a 4 rather than a 5.

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% (baseline 3), and the description still adds meaning beyond it: the empty-arguments default listing behavior and the non-obvious rule that explicitly passed players are returned even when fully available. It doesn't clarify array-combination semantics (e.g. AND vs OR between players and statuses), which is the one remaining ambiguity.

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 resource (FPL injury, suspension and availability flags) and source ('fetched live from the FPL API'), which clearly separates it from static siblings like search_players and get_xpts. An agent can tell immediately that this is the freshness/availability check, not a general player lookup.

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?

Gives an explicit prescriptive trigger: 'Call this before recommending, picking or captaining any player,' which is exactly the when-to-use guidance an agent needs. It also documents the two invocation modes (no args = all flagged players; args = filtered lookup), though it doesn't name a sibling it should be preferred over or excluded for.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: data is live from FPL's public API and requires no authentication, plus it inventories the returned fields. It does not discuss rate limits or freshness/caching, which keeps it below 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?

Three sentences, front-loaded with what the tool returns, followed by the identifier lookup and the usage hook. Dense and largely waste-free, though the parenthetical about the public API could be trimmed or placed last.

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 takes on the burden of describing the return payload and does so by listing the key fields. For a two-parameter, read-only tool the remaining gaps (error behavior for invalid team IDs, which gameweek is returned when omitted) are modest.

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 baseline is 3; the description exceeds it by explaining where to find team_id ('the number in the URL of the manager's FPL Points page'), which the schema does not say. The gameweek parameter's default behavior is left entirely to the schema, so it is not 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?

Specific verb+resource: retrieves a manager's FPL squad for a gameweek, and enumerates the returned contents (captain, bench, bank, squad value, transfers, chips). It is clearly distinct from the sibling tools, which deal with players, fixtures, and gameweek aggregates rather than a manager's own team.

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 states the primary use case explicitly: 'Use it as the starting point for transfer, captain and chip advice on their actual team.' It also explains how to obtain the required identifier. It stops short of naming exclusions or alternatives for adjacent needs (e.g. player-level stats via get_xpts), so it is a 4 rather than a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds the meaningful behavioral facts — data is live from the FPL API and match-level granularity is current-season-only. It stops short of describing pagination or response shape, but with a read-only tool that is a minor gap.

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 core payload (what it returns) is front-loaded, followed by the optional filters, the usage examples, and the data-availability caveat. Every sentence earns its place with no repetition.

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?

There is no output schema, so the description carries the burden of explaining return content — and it does, listing minutes, goals, assists, clean sheets, bonus, xG/xA and points, plus season totals for past seasons. Nothing needed to call it correctly is missing.

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 both optional filters are already documented in the schema. The description confirms the filters exist and scope the result ('only against one opponent or the last N matches') but adds no format, precedence, or combination rules beyond that.

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 and resource ('match-by-match record this season') and enumerates the returned stats, which clearly separates it from sibling tools like get_gameweek_stats or search_players. An agent can tell exactly what this returns without opening the 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?

Provides concrete trigger phrasings ('how has Saka done against Spurs this season', 'is his form real') and an explicit when-not: match-level data exists only for the current season, so opponent splits for earlier seasons are unavailable. That is enough to route an agent correctly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further by disclosing methodology (season xG/xA/clean-sheet/save/bonus rates, expected minutes, fixture difficulty) and two real behavioral caveats (season-start noise, rotation blindness). It stops short of describing row shape or ordering guarantees, 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 tight sentences: the core ranking behavior and methodology come first, filters second, caveats and the handoff last. No sentence is filler and the most decision-relevant caveat is not buried.

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 carries the burden of explaining what comes back, and it does so at a high level (xPts estimate shown beside ep_next). It covers caveats and methodology well; only output ordering and the default row count remain unstated.

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 80%, so team, position and max_price are already documented in the schema; the description only restates 'Filter by position, team and max price' without adding format or interaction guidance. Neither gameweek defaulting behavior nor the limit cap is touched on in the description, so it adds little beyond the 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?

Opens with a specific verb and resource ('Rank players by estimated expected points (xPts) for a gameweek') and names the data source (FPL API). The ranking framing plus the 'shown beside FPL's own ep_next' clause makes it clearly distinct from search_players or get_player_history.

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?

States both positive uses ('captain shortlists and finding transfer targets') and explicit limitations ('noisy early in the season and ignores rotation'). It also routes the agent to a specific sibling for the gap it cannot cover: 'cross-check availability with get_live_availability.'

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing that data is live from the FPL API and enumerating the returned stat fields. It omits freshness/caching behavior and any rate-limit notes, 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?

Three tight sentences: purpose and source front-loaded, then return fields, then usage exemplars. No repetition and every 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?

With six optional parameters and no output schema, the description compensates by listing the return fields (price, total points, form, ownership, ep_next, availability) so the agent knows what it gets back. Nothing essential to calling it correctly is missing.

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 83%, so the schema already documents nearly every parameter including examples and defaults. The description only paraphrases 'sorted by a chosen stat' and the filter set, adding no format or edge-case semantics beyond structured fields — the 3 baseline applies.

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 and resource ('Find and rank current-season FPL players'), names the data source (live FPL API), and enumerates the filter and sort dimensions plus the returned fields. An agent can distinguish it from get_player_history or get_live_availability on description alone.

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?

Gives three concrete usage exemplars ('best midfielders under £8m', 'how is Palmer doing', 'find a replacement') that map cleanly to the parameter set. It does not explicitly name sibling tools or state when-not to use this one, so it stops short of full routing guidance.

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