fpl_manager_picks

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

Beyond the readOnly, openWorld, and idempotent annotations, the description discloses critical behavioral details: the deadline dependency (hides picks before deadline), the 404 for unplayed gameweeks, the meaning of multiplier values (0=benched, 2=captain, 3=triple captain), and position semantics (1-11 XI, 12-15 bench). This significantly exceeds annotation coverage.

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 well-structured and front-loaded with the core purpose. It includes a compact return-type summary with semantic explanations, followed by an example and auth note. While somewhat detailed, every section earns its place and there is no 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?

Since there is no output schema, the description fully explains the return payload, including nested structures and value meanings (positions, multipliers). It covers authentication requirements and a call example. Nothing essential for calling this tool 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?

The schema already documents both parameters with descriptions, and the gameweek description includes the deadline/404 condition. The tool description does not add further meaning to the parameters themselves; it only provides an example call. With 100% schema coverage, a baseline of 3 is appropriate.

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 states a specific verb and resource: it retrieves the exact XI, bench order, captain, and chip used by a manager in a gameweek. This clearly distinguishes it from related FPL tools like fpl_manager or fpl_manager_history by focusing on the specific lineup and captaincy details.

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 gives important usage context: picks are hidden until the gameweek deadline passes, and an unplayed gameweek returns a 404. It also notes the authentication behavior (works without a key, FPL_SESSION_COOKIE unlocks more). However, it does not explicitly compare to sibling tools or state when NOT to use it, so it misses an explicit exclusion.

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