espnfantasy_league_history

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

The description discloses important behavior beyond annotations: it returns a single-element ARRAY (not an object), 404s when the league lacks history, and provides a verified example of that failure. It also mentions auth requirements and that a cookie unlocks more data. None of this contradicts annotations (readOnlyHint, openWorldHint, idempotentHint) — it complements them.

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 clear sections (purpose, prerequisites, return format, example, auth) and front-loads the core purpose. It's slightly verbose with the 'verified: public league 1234...' detail, but every part earns its place given the complexity of the tool's behavior.

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 output schema, the description thoroughly explains the return structure ('Returns: [{id, seasonId, settings, teams, status, …}] — ARRAY wrapper'), error behavior (404 and fallback), how to verify availability, and authentication. It leaves no ambiguity about how to use the tool 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?

Schema coverage is 100%, so parameters are already documented. The description adds meaningful semantics: explains that omitting seasonId returns every season with history, describes the view as 'same vocabulary as the seasons path,' and provides a concrete example request. This goes beyond the schema's basic descriptions.

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 that the tool retrieves pre-2018 seasons and cross-season history via the leagueHistory path. It uses a specific verb (returns history) and resource (leagueHistory path), and distinguishes itself from sibling tools like espnfantasy_league and espnfantasy_status by focusing on historical data and returning an array.

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?

Explicit when-to-use guidance is provided: 'Only works for leagues that HAVE history — check espnfantasy_status.status.previousSeasons first; an empty list there means this returns 404.' It also names an alternative ('fall back to the seasons path') and explains the condition for using that alternative. This is excellent usage differentiation.

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