espn_cdn_call

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses caching behavior, the default xhr=1 query parameter, league coverage limitations, and the error behavior for guessing operations. This adds substantial operational context without contradicting 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?

Every sentence in the description earns its place: source, data types, slug rules, coverage limits, operation discovery, and auth. The information is front-loaded and the Returns/Auth lines are terse yet useful, making this a well-structured and efficient description.

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?

Given the generic gateway nature with no output schema and three parameters, the description covers essential knowledge: endpoint source, slug semantics, default query parameter, how to discover operations, and auth. It also notes a key error-recovery behavior (guessing an operation returns alternatives), making it complete for first-time invocation.

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 is met. The description adds practical meaning beyond the schema by giving concrete slug examples (nfl, eng.1), clarifying that path_params uses the league slug, and noting the automatic xhr=1 for query_params. These details are more actionable than the schema's generic catalogue references.

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 identifies the tool as a gateway to the ESPN CDN core live feed, listing the data types (scoreboard/game/boxscore/playbyplay JSON). It distinguishes itself from siblings by emphasizing the CDN source and providing league-slug examples, though the verb 'gateway' is slightly generic.

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?

It gives explicit usage context: path slug is the league not the sport, soccer uses competition slugs, no NHL coverage, and gameId comes from the scoreboard op. It also directs users to browse espn://cdn/operations. It doesn't name alternative sibling tools, but the guidance is sufficient for selection.

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