get_live_availability

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

With no annotations, the description carries the full burden and does substantial work: it discloses the live-API, no-database fetch model, the default no-arg behavior and sort order, and the non-obvious rule that explicitly named players are returned even when fully available. It omits operational details such as rate limits, failure behavior, and the full returned field set, so it is strong but not exhaustive.

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-loads purpose, then the call trigger, then default behavior, then the status legend, with no filler sentences. The status-code block is dense but earns its place by decoding enum values the schema never explains.

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 annotations and no output schema, the description must cover both selection and behavior, and it does: defaults, sorting, the availability caveat, and the status/chance_of_playing vocabulary. The main residual gap is that the returned record shape is only partially conveyed (chance_of_playing is mentioned but the other fields are not), which is a modest shortfall for a zero-annotation tool.

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 a baseline of 3 applies, but the description adds real meaning beyond the schema: it clarifies that passing players returns them regardless of availability, that players and statuses can be combined ('and/or'), and it decodes every status code (a/d/i/s/u/n) that the bare enum leaves undefined. Only the players-name matching rule is left to 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?

'Current FPL injury, suspension and availability flags, fetched live from the FPL API' states a specific verb (fetch), resource (injury/suspension/availability flags) and scope (live/current), which implicitly but clearly separates it from the only sibling, query_historical_stats. An agent can tell at a glance this is the real-time counterpart to historical stats.

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 call trigger — 'Call this before recommending, picking or captaining any player' — with the rationale (avoid missing a newly flagged or suspended player), and explains the no-argument default (list all flagged players, newest news first). It never names the sibling tool or states when not to use this, so it stops short of a full when/when-not/alternatives treatment.

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