apisports_handball_games

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

Annotations already cover read-only, open-world, and idempotent hints, but the description adds substantial context: a detailed return shape, score interpretation guidance (handball scores run 25-35 and under 10 usually indicates first half), an explicit warning that the shape is unverified from live responses, and an auth requirement. This goes well beyond what annotations provide and helps the agent set expectations.

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: the first sentence states the core purpose, followed by essential return shape, practical notes, a concrete example, and auth info. Every sentence provides value—no filler or tautology.

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?

Without an output schema, the description takes on the burden of explaining return values and does so thoroughly with the response shape and field-level hints. It also covers score interpretation, unverified shape caveat, a usage example, and authentication. For a 4-parameter read-only sports data tool, this is complete and highly informative.

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% with descriptions for all four parameters (date, team, league, season). The description only adds an example for 'date' and mentions 'by date or league', which doesn't meaningfully extend the schema's parameter documentation. Baseline 3 is appropriate when the schema handles parameter semantics.

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 handball games from specific leagues (EHF Champions League, Bundesliga, LNH and others) by date or league. It distinguishes itself from sibling sports game tools by naming the sport and leagues, and includes return shape details that remove ambiguity.

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 clear context on when to use it (for handball games, filtered by date or league) with a concrete example. However, it does not explicitly mention alternatives or exclusionary guidance (e.g., 'for football use apisports_football_fixtures'), so it doesn't fully meet the 'when-not/alternatives' bar.

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