EndzoneAPI

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-annotation context: a 5-credit cost and per-source year availability (NGS 2016+, PFR 2018+), which affect whether the call is worth making. It stops short of return format or rate-limit behavior, so this is a modest add on top of 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?

Front-loaded with the use case, then the source/metric breakdown, then the filter workflow and cost. The two long metric enumerations are dense but each item is load-bearing for source selection; nothing is redundant.

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 7-value enum tool with an output schema, the description covers source choice, metric coverage per source, valid time ranges, filterable dimensions, and credit cost. Nothing an agent needs before calling is missing, and return values are correctly left to the output schema.

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 3, but the description adds real semantic value by mapping each source family to what it returns (ngs_* vs pfr_* metric lists) and restating the year floors that gate valid season values. That helps an agent pick the right enum value, not just the right syntax.

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?

States a specific verb+resource — advanced metrics the box score does not carry — and enumerates the exact metric families available (time to throw, air yards, CPOE, pressures, missed tackles, etc.). The phrase 'the box score does not carry' implicitly separates it from get_player_stats/get_team_stats, so an agent can route correctly without opening a schema.

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 clear usage context ('Use for tracking and advanced metrics the box score does not carry') and a concrete workflow ('Pick a source, then filter by season, week, player or team'). It does not name the sibling it substitutes for or state exclusions, so it falls short of an explicit when-not.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds material context they cannot: a 10-credit cost, the closing-by-default vs opening behavior, the 2023-2025/6-book data boundary, and a compliance rule against computing stakes, payouts or recommending bets. That last constraint is genuinely decision-relevant and unobtainable from structured fields.

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?

Front-loaded with the 'Use for...' clause, then layers coverage, defaults, parameter semantics and the compliance caveat in a dense but readable block. The inline price examples ('KC -10.5 at +260') are illustrative but add length; nothing is outright wasted.

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 an output schema exists, the description need not explain return shapes. It still covers market scope, snapshot default, book coverage, credit cost and the market-information caveat, which is everything an agent needs to invoke this 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 description coverage is 100%, including defaults for snapshot_type and market, so the baseline is 3. The description mostly restates those defaults ('closing... last before kickoff') and then discusses 'side' (home/away, over/under) and 'point', which are not parameters in the schema at all — useful for interpreting results but not a parameter contribution.

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?

States a precise verb+resource+scope: alternate spreads and totals per sportsbook, down to 'every point on each book's ladder with its price'. The word 'alternate' implicitly separates it from main-line odds tools like get_odds or get_line_movement, so an agent can route without opening a schema.

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?

'Use for alternate spreads and totals by sportsbook' plus the game/season/book coverage gives clear context for when this tool applies. It does not, however, name the sibling to use for main lines (get_odds) or state exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already establish the read-only, non-destructive safety profile, so the description's main contribution is the 'Costs 2 credits' disclosure, which is real behavioral information an agent cannot get from structured fields. It omits any note on response shape, but the output schema covers that.

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?

A single compact sentence front-loads the purpose, then the field list, then the default, then the cost. Every clause carries information and nothing is padded.

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?

With an output schema present, return values need no explanation, and the description covers scope, defaults, and credit cost. The only gap is a lack of guidance on when to prefer this over adjacent tools like get_snap_counts or get_player_stats, which is minor for a low-complexity read tool.

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 description coverage is 100%, so all four parameters (team, week, season, formation) are already documented in the schema, including the week default. The description restates the week default and 'by week' scope but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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?

States a specific verb ('get/use for') and resource ('a team's depth chart by week') and enumerates the returned fields (formation, position, depth rank, player), which is unusually concrete. It doesn't explicitly contrast with siblings, but the resource is distinctive enough within the sports-stats family that disambiguation is not needed.

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?

'Use for a team's depth chart by week' plus 'Defaults to the latest week available' gives an implied usage context and default behavior, but names no alternatives or when-not-to-use conditions (e.g. versus get_snap_counts or get_team_stats).

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond annotations: a 10-credit cost per call and a hard usage constraint that prices are market information and must not be used for stake/payout/profit calculations or sportsbook referrals.

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?

Four dense sentences: use case and payload first, then prerequisite, then cost, then the market-information constraint. No filler, no restating the title, and the most decision-relevant information is front-loaded.

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?

An output schema exists, so return-format explanation is unnecessary. The description still covers the payload inventory, the required prerequisite and its source, the credit cost, and the policy constraint — everything an agent needs to invoke this correctly and responsibly.

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?

With one parameter and 100% schema description coverage (schema shows the exact game_id format, e.g. 2025_01_KC_BUF), the baseline is 3. The description goes beyond this by citing the source tools for the id, adding provenance the schema does not carry.

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?

States a specific verb+resource ('everything about one game') and enumerates the payload precisely: team box-score stats, consensus closing line, per-bookmaker odds, weather, surface, officials. An agent can distinguish this from get_odds, get_team_stats, or get_games without opening a schema.

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?

'Use when you need everything about one game' gives clear usage context and 'Requires a game id from get_games or get_schedule' names the upstream tools that supply the prerequisite. It stops short of explicit when-not guidance (e.g. use get_odds if you only need prices), so a 4 rather than 5.

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

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

Annotations already cover the read-only/safe profile, and the description goes beyond them by disclosing the credit cost (5 cr vs 2 cr) and a hard usage policy limiting market-price interpretation. It also enumerates the returned fields, so the agent knows what behavior to expect from a call.

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?

Front-loads the use-when clause, then the return set, the alternative, the cost, and the policy constraint in a tight sequence. Every sentence carries distinct information with no filler.

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?

With an output schema present and 100% parameter coverage, the description only needs to add routing, cost, and policy context – all of which it provides. Nothing an agent needs to call this correctly is missing.

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 all eight parameters including the two enums are already documented. The description recaps the same filter names but adds no syntax, format, or defaulting detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb+resource (query games) and enumerates the dimensions it filters on (season, week, team, date range, game type, status) plus what it returns. It explicitly names the sibling get_schedule as the alternative for upcoming-only games, so an agent can separate the two without opening either schema.

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?

Opens with an explicit use-when clause, then names the alternative (get_schedule) and the condition that selects it (upcoming-only), and even cites the relative credit cost. This is textbook when/when-not guidance with a named route to the sibling.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds a genuinely useful non-obvious trait: the operation 'Costs 10 credits', which an agent cannot infer from structured fields.

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?

A single front-loaded sentence that names the purpose first and packs in the return contents and the credit cost with no filler. Slightly dense but every clause earns its place.

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?

With an output schema present, the description need not explain return values, and annotations carry the safety profile; the credit cost closes the main behavioral gap. An agent has enough to call it correctly, though no sibling-routing guidance is given.

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 description coverage is 100%, so the schema already documents team1, team2, limit, and season. The description's 'filter by season or get all-time' restates the season parameter semantics but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (compare) and resource (two teams' history) and enumerates the concrete outputs: recent meetings with scores, win/loss record, average margin. It is clearly distinct from get_games or get_team_stats in intent, but it never names or explicitly rules out a sibling.

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?

'Filter by season or get all-time' gives a usage hint for one parameter but does not say when to prefer this tool over get_games, get_team_stats, or get_game_detail. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds two things annotations cannot: the 2-credit cost and the default-resolution behavior for week/season, which matters for an agent budgeting calls.

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?

Three tight sentences with the payload description front-loaded, then defaults, then cost. No filler or tautology. Slightly dense in enumerating return fields, but every clause carries information.

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?

With an output schema present, return values need no explanation, and the description supplies the domain scope, defaults, and credit cost. The only omission is guidance on when the default week may be empty or how filtering interacts with team, which is minor for a zero-required-parameter read.

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 description coverage is 100%, so all four parameters (team, week, season, status) are already documented in the schema, including the week default and the Out/Doubtful/Questionable values. The description repeats the status vocabulary and defaults without adding syntax or format detail, so baseline 3 applies.

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?

States a specific resource (official injury report), the exact payload (game status values plus practice participation with the injury named), and the grouping dimensions (by team and week). No sibling tool covers injuries, so an agent can immediately tell this apart from get_depth_chart or get_player_stats.

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?

"Use for the official injury report" sets a clear condition and the default (latest reported week of the current season) tells the agent it can call with no arguments. It does not name an alternative or a when-not condition, but no sibling overlaps this domain.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds material context beyond them: relative cost (25 cr), the alternative's cost, and a compliance boundary (no stake/payout math, no bet recommendations, no sportsbook referrals). It does not describe auth or rate-limit behavior, so it stops short of a 5.

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?

Front-loaded with the core capability, then cost comparison, then the compliance caveat — a sensible ordering. The third sentence is a long policy clause, but every clause carries real constraint value rather than filler, so it stays efficient.

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?

An output schema exists, so return values need no explanation. Between the cost framing, the explicit alternative, the snapshot semantics, and the usage restrictions, an agent has everything needed to decide whether to call this tool and how to interpret the result.

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 description coverage is 100%, so all three parameters are already documented, including the non-obvious all_snapshots dedup behavior. The description reinforces that filtering is per bookmaker and that snapshots are hourly, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb+resource ('see how a game's lines moved') and immediately scopes the payload (per-bookmaker hourly snapshots plus the latest capture). It explicitly names the sibling get_odds as the alternative, so an agent can distinguish it from the other 20 odds/stats tools without opening either schema.

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 an explicit when-to-use rule ('use get_odds (10 cr) if you only need opening, closing, or current lines') and a cost-based selector (25 cr vs 10 cr), which is exactly the kind of routing guidance an agent needs. It also states the standing constraint on how the data may be used.

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

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

Annotations only cover the safety profile (readOnly, non-destructive), so the description adds substantial unseen context: credit costs (10/game, 10 per game returned), pagination (100 per page, up to 500), data-source attribution (espn 2014-2019 vs the_odds_api from 2020), and an explicit policy constraint against computing stakes or recommending bets.

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?

Front-loaded with 'Use for betting lines' and packed with actionable detail, but the single dense paragraph mixes pricing, coverage eras, sourcing and policy into long run-on sentences that are harder to scan than the content warrants.

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 high-complexity, 8-parameter tool with an output schema, the description supplies everything the agent needs to call it correctly: mode selection, credits, pagination, source labeling, era-dependent coverage, and the estimate_only escape hatch.

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 3, but the description goes further by tying parameters to cost and output shape (credits per game returned, array ordering 'given by columns', snapshot defaults differing between single-game and season modes). These are meaningful additions beyond the schema text.

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?

States a specific resource (betting lines/odds) and resolves the two operating modes — single game via game_id vs. whole season via season — so an agent can distinguish this from siblings like get_games and get_line_movement. It also names get_games explicitly for the consensus-closing-only case.

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 routing: 'Pass game_id for one game' or 'pass season (optionally team) for a season', plus 'For consensus closing lines only, get_games returns a whole season for 5 credits'. It also tells the agent when to use estimate_only and when moneyline/book coverage is unavailable by era.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond the annotations: counting stats are summed while rate stats are averaged, and each call costs 5 credits — both material to how an agent plans usage.

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?

Front-loaded with the use case, then the stat vocabulary, then aggregation rule and filters, closing with cost. The long stat enumeration is long but earns its place by preventing schema-opening reconnaissance; only minor trimming is possible.

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?

With an output schema present, return values need not be described. The description covers the critical caller-facing facts — stat vocabulary, aggregation behavior, filterable dimensions, and credit cost — leaving only minor gaps like pagination/limit semantics, which the schema already documents.

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 3. The description exceeds it by expanding the 'stat' parameter from three examples into a large enumerated vocabulary (~130 more) and by explaining the aggregation semantics of the stat value itself; it does not, however, explain limit or season_type defaults beyond what the schema states.

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 opens with a specific verb+resource ('rank players on any weekly stat over a season') and enumerates representative stat columns, so the agent knows exactly what the tool produces. It does not explicitly contrast itself with the closest sibling, get_player_stats, which returns raw stat lines rather than rankings, leaving that distinction to inference.

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 phrase 'Use to rank players' gives implied context, and the filter list (position, team, minimum games) hints at narrowing scenarios. However, there is no when-not guidance and no named alternative for retrieving individual player stats instead of rankings, so the agent must infer the boundary with get_player_stats.

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

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

Annotations only cover the read-only safety profile, yet the description adds real behavioral context: a concrete 10-credit cost model, a free estimate_only path, closing-line-as-default versus opening, and explicit policy constraints on stake/payout advice. This is meaningful disclosure beyond the structured fields.

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?

It leads with what the tool returns and its scope, then usage modes, cost, default snapshot, and policy limits, with no filler. The single long first sentence is dense but every clause adds a filter or market the agent needs.

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?

An output schema exists, so return values need not be described. Given that, the description covers markets, books, usage patterns, cost, snapshot default, and usage policy comprehensively enough for correct 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 3. The description goes further by explaining the interplay between game_id and player_id+season and the per-game credit charge, which the schema does not state. It stops short of enumerating every optional filter, so a 4 is appropriate.

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 states a specific verb and resource: player prop lines by sportsbook, enumerating six exact markets and naming the seven covered books and the 2023 season. This is far more specific than the name alone. It does not explicitly differentiate itself from close siblings such as get_prop_history or get_odds, so it stops short of a 5.

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 clearly describes the two usage modes: game_id for every player's props in one game, or player_id with season for one player across a season. It also flags estimate_only as the way to preview price without being charged. No alternatives (e.g. get_prop_history) are named, so it lacks the explicit routing a 5 requires.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: a 5-credit cost, the latest-season default when season is omitted, that totals are summed across all stat categories, and that per-week lines are included. It stops short of noting pagination or response size, which matters given the volume implied.

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?

Front-loaded with the scope qualifier and the cost statement is cleanly separated as its own sentence. The middle clause is a long enumeration, but each item is a distinct data category the caller needs, so it earns its length.

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?

With an output schema present the description need not spell out return types, and it still usefully previews the payload's breadth plus cost and defaults. The one gap is that it never flags how large a full weekly-lines response will be or any pagination/truncation behavior.

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 description coverage is 100%, so the schema already documents player_id's GSIS format, the season default, and the REG/POST enum. The description's season-default statement merely repeats the schema text, adding no syntax or edge-case meaning beyond it; baseline 3 applies.

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?

States a specific verb and resource and enumerates exactly what comes back: bio, draft, physicals, id crosswalk, summed season totals across stat categories, weekly lines, and games played. The 'Use for one player' opener immediately separates it from team-level siblings like get_team_stats and from the narrower get_advanced_stats.

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 'Use for one player' framing implies the scope and the season default is stated, but no alternative tool is named and no when-not-to-use condition is given (e.g. use get_advanced_stats for deeper metrics, search_players for id lookup). Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: pagination via offset and a cost of 10 credits per call, plus a per-query EPA/success-rate summary on the return. It does not mention auth requirements or the default limit (schema covers the latter).

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?

Front-loaded with the use case, then filters, then return shape, pagination, and cost in a tight sequence with no filler sentences. The metric enumeration is long but every item earns its place given 17 parameters to advertise.

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?

An output schema exists, so return values need no elaboration, yet the description still calls out the EPA/success-rate summary. Combined with cost, pagination, and filter-combination rules for a 17-param, zero-required tool, an agent has everything needed to call it 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 description coverage is 100%, so the schema already documents all 17 parameters, making 3 the baseline. The description mostly restates schema field names, though it adds mild semantics by framing min_wp/max_wp as a 'win-probability band' and describing how game vs. season+week/team/player filters combine.

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?

States a specific verb-resource (play-by-play) and enumerates the nflfastR play-level metrics it exposes (EPA, WPA, CPOE, air yards, formation flags), which cleanly separates it from aggregate siblings like get_advanced_stats, get_player_stats, and game-level get_game_detail.

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 explicit filter recipes: by game, or by season plus week/team/player, plus play type, down, quarter, win-probability band, red zone, third down. It provides clear context for when the tool is the right one but names no alternative or when-not conditions (e.g., when to prefer get_player_stats for aggregates).

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), but the description adds real value beyond them: a concrete cost model (10 credits for up to 200 games) and a firm compliance constraint forbidding stake/payout calculations, bet recommendations, or sportsbook referrals. It also discloses what a returned row contains, which is unusually concrete for a read tool.

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?

Front-loaded with the purpose, then the cost and policy caveats, with no filler sentences. The inline enumeration of all ten markets duplicates the enum already in the schema, making the first sentence longer than needed.

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 an output schema exists, the description need not detail return values, yet it voluntarily describes row structure and the over rate. Filters (player, market, dates, bookmaker) are covered by the schema, and cost limits are stated. Pagination is handled only in the schema's limit description, which is adequate but not reinforced here.

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 description coverage is 100%, so the schema already documents every parameter, including the plain-language market enum mapping and the bookmaker median-vs-single-book semantics. The description restates the market list and the median/single-book distinction without adding new format or constraint detail beyond the schema, so the baseline 3 applies.

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 states a specific verb and resource — see how a player performed against his prop line over time — and enumerates the markets and the row contents, which makes the historical nature of the tool clear. It stops short of naming a sibling (e.g. get_player_props for current lines), so the agent must infer the distinction from context rather than being told.

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?

"Use to see how a player did against his prop line over time" gives a clear usage context, and the credit cost plus 200-game cap hint at when it is worth calling. No explicit when-not-to-use or named alternative is provided, so routing against get_player_props or get_line_movement is left to inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new operational context: a 2-credit cost and explicit policy constraints about not computing stakes/payouts or recommending bets. It doesn't cover pagination or result limits, but the added cost and policy disclosure is meaningful 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 core purpose is front-loaded in the first clause, and the remaining sentences carry the cost and policy information. The policy sentence is somewhat long but earns its place by constraining agent behavior around betting-related responses.

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?

An output schema exists, so return values need not be explained. The description covers purpose, both invocation modes, cost, and policy constraints; the only minor gap is result limits or ordering, which is arguably the output schema's job.

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 description coverage is 100%, so the schema already documents days, team, and week. The description restates the default of 7 days and notes that week returns all games played or not, but adds no syntax or format detail the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb+resource ('see what is coming up: unplayed games') and specifies scope precisely — upcoming N days, or a specific week of the current season. It does not explicitly name or contrast with siblings like get_games or get_game_detail, so it falls short of a 5 despite being clear and specific.

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 clear context for when to reach for this tool ('what is coming up') and the two modes of use (days vs. week). It doesn't state when NOT to use it or point to the alternative tools (e.g. get_games for past results), so it stops short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the credit cost ('Costs 5 credits'), which is real behavioral information the annotations do not carry. It does not disclose pagination behavior, though the output schema and limit param partly cover that.

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?

Two tight sentences: the capability and supported query shapes come first, the cost note follows. No filler, nothing repeated from the name or title.

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?

With an output schema present, return values need no explanation, and the description covers all three access patterns for a 6-parameter, zero-required tool. It does not clarify how parameters combine (e.g., whether season is mandatory alongside team/player) or what happens with no filters, which is a modest remaining gap.

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 description coverage is 100%, so the schema already documents all six parameters, including that player_id is a PFR id sourced from search_players. The description's mention of game/player/team-season modes maps to game_id, player_id, and team but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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?

States a specific verb-and-resource purpose ('playing time: offensive, defensive, and special-teams snaps and snap shares') and enumerates the three query shapes (game, player by PFR id, team season). No sibling tool covers snap counts, and the description makes that scope explicit.

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?

'Use for playing time' plus the three supported query modes gives clear context for when to reach for this tool rather than get_player_stats or get_team_stats. It stops short of naming an explicit alternative or stating exclusions, so it is clear but not fully routing.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is added context — and it delivers: tiebreak ranks follow the real NFL procedure and report the deciding step, data is computed from final scores, and the call costs 2 credits. It does not cover error or empty-result behavior, keeping it below a 5.

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?

Purpose leads, followed by output fields, then behavioral notes (tiebreaking, provenance, default, cost) in short declarative sentences. No filler or repetition of the title.

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?

An output schema exists, so return-value documentation is unnecessary. The description covers scope, all three filter defaults, the tiebreak methodology, data provenance, and cost — everything an agent needs to decide and call 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 description coverage is 100%, so the schema already documents season, division, and conference including the current-season default. The description's restatement of the default adds no syntax or format detail beyond it; baseline 3 applies.

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?

States a specific resource with enumerated outputs: record, win%, points for/against, home/away/division/conference records, streak, division rank, conference seed. This is clearly distinguishable from siblings like get_team_stats or get_advanced_stats, which cover different stat families.

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?

"Use for regular-season standings and playoff seeding" gives clear conditions for selection, and "Defaults to the current season" sets the default scope. However, it names no alternative (e.g. use get_team_stats for per-team aggregate stats) and states no exclusions, so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new operational context — "Costs 5 credits" — which an agent cannot get from the structured fields. It does not, however, note rate limits or output characteristics.

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?

A single front-loaded sentence opening with "Use for" and a compact enumeration of the payload. Every clause contributes; the credit cost is tucked at the end where it is easy to scan.

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?

An output schema exists, so return-value documentation is not needed, and the description still summarizes payload breadth plus the credit cost. Required vs optional parameters are handled by the schema. Minor gap: no note on default season behavior in prose, though the schema covers it.

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%, and the schema documents team code format, season default, and the REG/POST enum, so the baseline is 3. The description only loosely gestures at season scope ("season", "weekly stat line") and adds no syntax or constraint detail beyond the schema.

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?

States a specific resource (one team's season stats) and enumerates exactly what is returned — totals, EPA per play, yards per attempt/carry, standings row, weekly stat lines. This implicitly separates it from get_player_stats and get_standings, though it never names a sibling to sharpen the distinction.

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?

"Use for one team's season" gives an implied scope, but there is no explicit when-not guidance or routing to alternatives such as get_advanced_stats or get_standings, which overlap in content. The agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds non-annotation value: the credit cost (1 credit, cheapest) and the scope of the dataset (32 current teams, i.e. no historical franchises).

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?

Three short sentences, front-loaded with the use case, then output detail, then cost. Nothing is padded or repeated from the schema or annotations.

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?

With an output schema present, return values need no explanation, and the description covers scope, spelling conventions and cost. It leaves minor gaps such as whether results are paginated or how current the roster data is, but nothing an agent needs to call it 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 description coverage is 100% and both filters (division, conference) are already documented with examples and an enum in the schema, so the baseline of 3 applies. The description's nflverse spelling note clarifies output values rather than the parameters themselves.

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?

Names the resource (teams) and precisely enumerates what is returned: team codes plus all 32 current teams with conference, division, colours and logo URLs. The nflverse spelling note (LA, WAS) further pins down the exact output, making it unmistakable against siblings like get_standings or get_team_stats.

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?

"Use when you need team codes" gives a clear triggering condition, and the 1-credit cost note helps an agent pick this over costlier siblings. However, it never names an alternative or states when NOT to use it, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, and the description adds genuinely new behavior: the dataset size and time span, the active-only default with automatic fallback and self-reporting, and a cost signal ('Costs 2 credits'). These are traits an agent could not derive from the structured fields.

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?

Three sentences, front-loaded with the use case, then scope, then fallback behavior, then cost and the downstream handoff. No filler and nothing repeated from the title.

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?

An output schema exists, so return shape needn't be explained, and the description supplies the remaining decision-critical facts: search scope, fallback logic, credit cost, and the id handoff to get_player_stats. Nothing an agent needs to call this correctly is missing.

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 description coverage is 100%, so all five parameters (query, team, limit, active, position) are already documented, including the fallback semantics of 'active'. The description restates the default/fallback behavior but adds no syntax or format detail beyond the schema, matching the baseline for a fully-covered schema.

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?

States a specific verb+resource ('find a player by name, partial match') and immediately scopes the corpus ('~25,000 players back to 1999'). It also differentiates itself from the sibling get_player_stats by declaring that its output (the GSIS player id) is what that tool requires.

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 clear entry context ('Use to find a player by name') and a downstream routing hint ('Returns the GSIS player id needed by get_player_stats'), which tells the agent where this fits in a chain. It does not state when *not* to use it (e.g. versus get_player_leaders or get_player_stats directly), so it falls short of full alternative coverage.

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