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

Annotations already declare this a safe, idempotent, closed read, so the description is not the only safety signal. It still adds real behavioral context the annotations cannot: plan-tier limits (free plan capped at one team and its last 10 games), that an unloaded league returns an empty page with a warning, and that SOCCER/TENNIS aggregate every competition while each row names its competition. Return shape and pagination behavior remain unstated.

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?

Core purpose and the by= mode split are front-loaded in the first sentence, with prerequisites and plan limits after. It is terse to the point of clipped fragments ('Send team, or a season to read every team'), which is efficient but slightly telegraphic for a 13-parameter tool.

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 13-parameter tool with 100% schema coverage, rich league-coverage notes, and annotations covering the safety profile, the description needs mainly to orient rather than document each field, and it does. The remaining gap is return content: with no output schema, an agent learns rows are per-game per-team or per-position stats but not which stat columns appear.

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 the baseline would be 3, but the description adds interpretive meaning the schema only hints at: the team-vs-season dichotomy for scoping rows, the by=position mode as a different unit of analysis, and end_date framed as 'the day before' a game for pre-game features. That framing is genuinely useful for an agent reasoning about point-in-time reads.

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 resource and verb-equivalent: 'What a team gives up per game to opposing teams,' and immediately branches the semantics with 'or by=position for what each position records against it.' An agent knows exactly what data is returned per row. It stops short of naming its closest sibling (get_team_stats), so an agent must infer the team-offense vs opponent-allowed distinction from names 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 concrete selection rules: pass a team for one defense, or a season to read every team, and use end_date to read a past-day snapshot. It also states hard preconditions — league must be in meta.stats_leagues — and the free-plan restriction of one team over its last 10 games. No explicit exclusion against alternatives like get_team_stats or get_hit_rates, which keeps it out of the top band.

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