fpl_set_piece_notes

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

Beyond the read-only and idempotent annotations, the description discloses the return structure, auth behavior (works without a key, FPL_SESSION_COOKIE unlocks more), and the nature of the data (official notes, subject to injuries). This adds substantial context not encoded in the annotations.

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 with purpose, return format, use case, example, and auth info clearly delineated. It's slightly promotional in the 'genuinely useful' section and the 'Example' line is a bit informal, but overall each part adds value and it remains reasonably concise.

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 no parameters and no output schema, the description is remarkably complete. It covers what the tool does, the shape of the returned data, an example note, the auth requirement, and practical use cases, giving an agent all necessary information to select and call it correctly.

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 has zero parameters, so schema coverage is complete and a baseline of 4 is appropriate. The description enriches the tool's semantics by showing an example of the data content (e.g., 'Penalties: Haaland, then Alvarez'), though it doesn't need to explain parameters.

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 states the tool provides official set-piece taker notes per club, specifying who takes penalties, corners, and free kicks. This is a specific, distinguishable purpose among the many FPL sibling tools, and the 'Example: Who takes the penalties' reinforces the use case.

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 notes the tool is 'genuinely useful for FPL and priced-market work alike' and adds context about penalty duty being valuable and subject to injuries. However, it doesn't explicitly mention when to avoid it or name alternative tools, so it lacks exclusionary guidance.

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