pinnacle_league_matchups

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

Annotations already mark this as read-only, idempotent, and open-world. The description adds the return payload structure with fields like hasMarkets and isLive, plus a note that authentication is not required, giving useful behavioral context beyond 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 compact: one purpose sentence, a return format block, and an auth note. Every line adds value and the key info is front-loaded in the first sentence.

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 one-parameter listing tool, the description covers the return structure, auth requirement, and league-based scoping. No output schema exists, so the inline return type is essential and provided.

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 single parameter leagueId has 100% schema coverage, including its source (pinnacle_sport_leagues) and URL path status. The description doesn't add parameter-specific details but doesn't need to since the schema already defines it clearly.

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 returns all matchups for a single league, with the NBA example providing concrete scope. This distinguishes it from sibling tools like pinnacle_sport_matchups and pinnacle_league_matchups_live by its specific league-level granularity.

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 (all matchups for one league) but does not explicitly mention alternatives or exclusions. While the sibling names hint at related tools, the description itself doesn't say when to prefer this over pinnacle_league_matchups_live or pinnacle_sport_matchups.

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