EndzoneAPI

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds the non-obvious cost signal ('Costs 5 credits') and the per-source historical coverage limits, both of which affect whether an agent should call it. It does not mention pagination behavior beyond the schema's limit, but the credit cost and coverage constraints are the material extras.

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 purpose, then the two metric families, then the how-to and the cost — a sensible order with no filler sentences. The metric enumerations are long but each names real, otherwise-unknowable content, so they earn their space; slightly denser than needed for selection alone.

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 shape needn't be described, and the description covers purpose, coverage years, filter dimensions, and credit cost. The only gap is that it never states the consequence of an out-of-range season for a given source (e.g. PFR before 2018), which an agent may need to avoid wasted calls.

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%, including enum values, the week-0 season-aggregate note, and the per-source player ID convention, so the schema already does the heavy lifting. The description only restates that a source must be picked and that season/week/player/team are the filters, adding nothing beyond the structured fields.

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 (advanced/NGS and PFR metrics) and enumerates the actual metric families it returns (time to throw, air yards, pressures, missed tackles), which is far more specific than the name alone. The phrase 'the box score does not carry' implicitly positions it against the box-score siblings get_player_stats/get_team_stats, so an agent can tell what it adds.

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 coverage windows (NGS 2016+, PFR 2018+) and a clear procedure: 'Pick a source, then filter by season, week, player or team.' It doesn't explicitly name the alternative tool (e.g. use get_player_stats for standard box-score stats) or state exclusions, so it is clear context without hard 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?

Beyond the read-only and idempotent annotations, the description discloses the 10-credit cost, the covered bookmakers, the season range including the current season, the default closing snapshot behavior, and compliance constraints around market information. These details significantly exceed what the annotations provide.

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 front-loaded with the core use case and remains information-dense, with every major sentence contributing context. It is a long paragraph and includes some details, such as the full bookmaker list and side/point explanation, that could be tightened, but overall it earns its space.

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, full annotation coverage, and complete schema descriptions, the description supplies the remaining operational context an agent needs: data scope, default snapshot behavior, cost, and usage constraints. Nothing essential for correct invocation appears 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 the schema already documents all four parameters well. The description restates the bookmaker list and snapshot default, and mentions side/point semantics that are not input parameters, but it adds limited new parameter-level meaning 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?

The description states a specific resource and scope: alternate spreads and totals by sportsbook, every point on each book's ladder with prices, for one game, from 2023 onward. It clearly distinguishes this from general odds or line-movement tools by emphasizing alternate ladders and per-book pricing.

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 usage context: use this for alternate spreads and totals by sportsbook, with closing ladders returned by default and opening ladders available. It does not explicitly name when to use a sibling tool instead, so it falls short of full alternative-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/idempotent/non-destructive, yet the description adds substantial context: the data capture window (once, in the final 75 minutes pre-kickoff), the cohort of 3-6 books, the per-line over/under shape, a 10-credit cost, and an explicit safety policy against computing stakes or recommending bets. Nothing essential is left for the agent to discover by trial.

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?

Well front-loaded: purpose, then inputs, then return shape, then availability caveats, then routing and cost/usage policy. Dense but every sentence carries information. It runs long, and the market list partially duplicates the enum, which keeps it just short of a 5.

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?

Despite an output schema being present, the description still tells the agent what a row looks like (per line, the over price, and the under where posted) and when the dataset will be empty. Combined with the cost and the no-advice policy, an agent has everything needed to call it correctly and interpret an empty 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 the enum meanings, game_id format, bookmaker key, and estimate_only are already documented. The description echoes the player_id sourcing ('a GSIS id from search_players') and the required game_id/market but adds no syntax or format detail beyond that. Baseline 3 applies when the schema carries the parameter burden.

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 verb ('Use for') plus the resource ('alternate player prop lines by sportsbook') and immediately scopes it: 'every line a book posted for a player in one game, not only the main one', with a concrete example ladder. An agent can distinguish it from get_player_props and get_prop_history without opening any 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?

Explicitly names the alternatives and the condition that selects each: get_player_props for the main line and opening/closing prices, get_prop_history for how a player did against his main line. It also states the availability boundary (NFL 2023+, last 75 minutes before kickoff, 3-6 books, none for games further out) so the agent can decide when the tool will return data at all.

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, idempotent, non-destructive, closed-world), so the description's main added value is the 'Costs 2 credits' disclosure and the default-week behavior — both genuinely useful beyond structured fields. It stops short of describing result shape or ordering, but the output schema carries 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 front-loaded sentence that states purpose, return fields, default behavior, and cost with zero filler. 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 four fully described params, an output schema, and annotations covering the safety profile, the description supplies what is still needed: cost and the week default. A brief note on how formation filtering interacts with depth rank would make it fully complete, but nothing essential 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 the schema already documents team, week, season, and formation. The description reinforces the week default but adds no format or syntax detail beyond what the schema states, making the baseline 3 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 names a specific verb+resource (a team's depth chart by week) and enumerates what it returns: formation, position, depth rank, player. It is clear what the tool produces, though it does not explicitly contrast itself with adjacent siblings like get_snap_counts or get_injuries.

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' gives a clear context for invocation, and the default-to-latest-week note tells the agent it can omit the week. It lacks explicit when-not-to-use guidance or named alternatives among siblings, so it falls short of a 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 readOnly/idempotent/non-destructive/no open world, so the description wisely spends its words elsewhere: the 10-credit cost is a real usage constraint an agent must weigh, and the market-information policy (never compute stake/payout/profit or recommend a bet) is a behavioral guardrail found nowhere in structured fields. Return format is not described, 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?

Front-loaded with the usage trigger, followed by the contents list, cost, and the betting-policy caveat — no filler sentences. The middle content enumeration is dense but each item tells the agent what it is paying 10 credits for, so little could be cut without losing 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, the description needn't explain return values, yet it still summarizes them well enough to judge fit. Combined with the id prerequisite, credit cost, and policy constraint, an agent has everything needed to decide and invoke 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 coverage is 100% and the schema itself supplies the id format example (2025_01_KC_BUF). The description adds provenance beyond the schema by naming get_games and get_schedule as the sources of a valid id, which is the one piece of semantic guidance the parameter needs.

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 and resource ('everything about one game') and enumerates the exact contents: both teams, box-score stats, consensus line, per-book odds, weather, surface, officials. That is far more concrete than the title. It stops short of explicitly contrasting with narrower siblings like get_odds or get_team_stats, so it is clear but not sibling-differentiating.

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 a clear triggering condition, and 'Requires a game id from get_games or get_schedule' tells the agent how to obtain the required input. It does not state when to prefer a cheaper sibling (e.g. get_odds) instead, so no explicit alternatives or exclusions are offered.

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?

Beyond the readOnly/idempotent annotations, it discloses credit cost (5), the aggregation rule ('only identical lines are combined'), how many books back each number, and the timing semantics of the default snapshot (latest until kickoff, closing after). These are meaningful operational traits the annotations do not cover.

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 purpose and scope contrast, followed by aggregation rule, defaults, alternative tool, cost and usage constraint. Every sentence carries information; nothing is 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?

The tool is simple (2 params, output schema present) and the description covers scope, defaults, cost, aggregation semantics and the sibling to use for raw prices. Nothing needed to invoke it 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 both parameters are already documented and the baseline applies. The description's note on snapshot timing adds only a small nuance beyond the schema's 'last pre-game price so far' and says nothing further about game_id format.

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 (average implied vs. fair probability for moneyline, spreads and totals for one game) and immediately contrasts scope with per-book pricing. It is clearly separable from get_odds, get_market_odds and get_prop_probabilities.

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?

Explicitly names the condition for use ('what the market thinks of one game, not any one book's price') and routes the alternative case to get_odds. It also gives the default-vs-request rule for opening lines, so the agent knows when to pass snapshot_type=opening.

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 read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: the credit cost, returned fields, a clear market-information safety policy, and the upcoming-only alternative. This is rich behavioral guidance for an agent.

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 front-loaded with the usage condition and filters, then returns, alternative, cost, and safety policy. Each sentence adds practical value, with no filler or repetition.

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 an 8-parameter filtered-list tool with full schema coverage, annotations, and an output schema, the description supplies all the call-selection and behavioral context an agent needs. Nothing important about invocation 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?

The schema has 100% description coverage, so parameter meaning is already established. The description lists filter categories in prose but adds no syntax, defaults, or edge-case semantics beyond what the schema provides; baseline 3 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?

States a specific verb-resource ('querying past or future games') and enumerates the filter dimensions. It clearly distinguishes this tool from get_schedule by noting that get_schedule is for upcoming-only games.

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?

Explicitly says when to use it (past or future games with filters) and names the alternative for upcoming-only queries. It also gives the credit cost and points to the cheaper sibling, leaving little ambiguity for tool selection.

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, idempotent, non-destructive and closed-world, so safety is covered. The description adds two traits not in structured data: a concrete cost of 10 credits and the data-coverage boundary (meetings back to 1999 only). It stops short of noting result limits or pagination, which keeps it from 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?

A single dense sentence, front-loaded with the use case and followed by output details and cost. The clause 'where our games start' is slightly cryptic phrasing for the data-coverage cutoff but carries real 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?

An output schema exists, so return values need no explanation, yet the description still summarizes them usefully. Combined with the credit cost and historical cutoff, an agent has enough to call it correctly; only edge behavior such as what happens with an unknown team code is unaddressed.

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 100% schema description coverage, the schema already documents team codes, the limit cap, and the season/omit-for-all-time behavior. The description largely restates the season semantics ('over one season or every meeting since 1999') and adds little about the team1/team2 code format or how limit interacts with the two modes.

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 ('compare two teams' history') and enumerates exactly what comes back: recent meetings with scores, the win/loss record, and average margin. No sibling tool covers head-to-head comparison, so the agent can route here without 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?

'Use to compare two teams' history' gives an implied trigger but no explicit when-not or named alternative (e.g., get_game_detail for a single meeting, get_team_stats for aggregate form). The season-vs-all-time scope hint partially guides parameter choice but is framed as capability, not usage 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds two genuinely useful facts not in structured fields: the credit cost (2 credits) and the defaulting behavior to the latest reported week of the current season. It stops short of describing pagination or result size, but an output schema exists to carry return shape.

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 purpose, then the defaulting rule, then the cost. Nothing is padded and 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?

For a four-parameter, all-optional read tool with full schema coverage, annotations, and an output schema, the description supplies everything still missing: what the report contains, the default week/season behavior, and the credit cost. An agent can call this correctly without further inference.

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 four parameters including their defaults. The description only restates the team/week dimensions and the week default, adding no format or syntax detail (e.g. valid team code forms) beyond the schema. Baseline 3 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 names the specific resource (the official injury report) and enumerates its contents: game status values (Out, Doubtful, Questionable) and practice participation with the injury named. It also states the query dimensions (team and week), so an agent knows exactly what it retrieves. No sibling tool covers injuries, so no disambiguation is 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 the official injury report" plus the stated default (latest reported week of the current season) gives clear context on when this tool applies. It does not state exclusions or point to an alternative, but none of the siblings (get_player_stats, get_depth_chart, get_odds) overlaps in scope.

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 read-only, idempotent, non-destructive; the description adds what annotations cannot: the 25-credit cost, the default dedup behavior (identical captures dropped, latest always kept), and a hard compliance constraint forbidding stake/payout math or betting recommendations. That is materially useful behavioral context.

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 cost/alternative, then the compliance rule; every sentence carries information. The opening sentence is dense with nested parentheticals but not 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?

An output schema exists, so return-shape explanation is unnecessary. Given the tool's cost, alternatives, default filtering, and legal constraints are all covered, an agent has everything needed 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 coverage is 100%, so game_id, bookmaker filter, and all_snapshots are all documented in the schema, including the dedup semantics of all_snapshots. The description restates all_snapshots but adds no syntax or format 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 and resource: how a game's lines moved, returning each bookmaker's hourly snapshots where a line changed plus the latest. The scope (per-bookmaker, change-only by default) makes it distinguishable from odds-related siblings.

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?

Explicitly routes the agent: 'use get_odds (10 cr) if you only need opening, closing, or current lines', with a cost comparison that makes the trade-off concrete. It also explains when to pass all_snapshots rather than relying on the default.

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 safe-read profile, and the description adds substantial operational context: 10-credit cost, refund when a game has no lines, 2023-season data retention limited to larger books, incomplete market coverage per game, and the meaning of a negative minutes_before_start. It also flags the domain restriction (never compute stakes/payouts or recommend bets), which is behavior an agent cannot infer from 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 purpose and the sibling routing, then costs and caveats, which is the right order. It repeats the market enumeration already present in the enum, which is the one clearly redundant passage.

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 paid, historical, filtered-odds tool the description covers cost, refunds, data availability limits, line semantics and the parameter source. An output schema exists, yet the explanation of opening/closing lines and outcomes adds needed interpretation rather than duplicating structure.

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 baseline is 3, and the description does add value by sourcing game_id and explaining estimate_only's billing behavior. However, it never mentions the optional bookmaker filter, leaving one parameter's intent to the schema alone.

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 ('extra betting markets of a game as history') and enumerates the exact markets covered. It also explicitly separates itself from get_odds, which handles full-game moneyline/spread/total, so an agent can pick the right tool without opening the 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 explicit routing: use this for derivative markets, use get_odds for full-game lines, and get game_id from get_schedule or get_games. It also names a real alternative entry point (estimate_only) for price checking before committing.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses credit pricing (10 credits per game, 5 via get_games), pagination defaults (100 per page, max 500), historical coverage boundaries (1999 for spread/total, 2010 for moneyline, 2014/2020 book eras), the source field semantics, and estimate_only pricing behavior. This is rich behavioral context an agent cannot get from the structured fields alone.

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 purpose is front-loaded in the first sentence, and nearly every clause carries substantive information about modes, costs, or coverage. The main weakness is structure: the second sentence is a very long run-on with nested parentheticals that is harder to parse than it needs to be.

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 complexity (8 parameters, two distinct modes, credit pricing, historical book coverage), the description covers everything an agent needs to call it correctly, including pricing, pagination, mode defaults, and usage constraints. An output schema exists, so return-value explanation is appropriately delegated to 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%, so the baseline is 3, but the description adds cross-parameter meaning: game_id vs. season mode selection, team/limit/offset only applying with season, snapshot_type defaults differing by mode, and credit costs tied to the chosen mode. It also clarifies array ordering for per-book lines, though it does not add much beyond the already-detailed schema descriptions for individual fields.

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 purpose (betting lines) and then precisely enumerates the two retrieval modes (single game via game_id vs. whole season via season), including data coverage by era. It explicitly distinguishes itself from the sibling get_games by noting that get_games only returns consensus closing lines for 5 credits, so an agent can route correctly without opening schemas.

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 mode-selection guidance (pass game_id for one game, or season optionally with team for a season) and names get_games as the cheaper alternative for consensus-only needs. It also states a firm usage constraint about not computing stakes or recommending bets. However, it does not explicitly exclude adjacent siblings like get_line_movement, get_player_props, or get_alt_lines, leaving some routing ambiguity.

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 this is a read-only, idempotent, non-destructive, closed-world tool. The description adds meaningful behavior beyond annotations by explaining that counting stats are summed and rate stats averaged, plus the 5-credit cost.

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 front-loaded with the core use case, followed by compact aggregation behavior, filters, and cost. The stat examples are long but directly useful for selecting the required stat parameter, and no sentence is 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?

With an output schema present, rich annotations, and full schema description coverage, the description supplies the remaining decision-critical context: ranking purpose, aggregation semantics, filter scope, and credit cost. Nothing essential for correct invocation appears 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 the schema already documents each parameter. The description adds useful semantics for the stat parameter by explaining the aggregation rule: counting stats are summed and rate stats are averaged.

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: rank players on weekly stats over a season, with example stat columns. It clearly distinguishes leaderboard-style ranking from raw stat retrieval, though it does not explicitly name a sibling tool such as 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?

The opening phrase 'Use to rank players...' gives clear when-to-use guidance, and the description mentions supported filters and the 5-credit cost. It does not specify when not to use this tool or name alternatives, so it stops short of full alternative 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?

Beyond the read-only annotations, the description discloses credit costs, pre/post-kickoff pricing, legacy account pricing, default closing-line behavior, estimate_only billing behavior, and market-information usage restrictions. This is substantial behavioral context for an agent.

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 front-loaded with purpose and then packs cost, query patterns, defaults, and compliance constraints into a compact paragraph. Every sentence carries operational value for invoking the tool correctly.

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 annotations, a full input schema, and an output schema, the description supplies the remaining operational context: cost model, default line type, estimate mode, query combinations, and usage restrictions. Nothing critical for correct invocation 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 the baseline is 3, but the description adds useful combination semantics for game_id versus player_id with season, clarifies the default snapshot_type, and explains estimate_only's billing effect. It does not add much for bookmaker or market 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?

The description states a specific resource and scope: player prop lines by sportsbook, with named markets and books. It is clearly about player props, but it does not explicitly distinguish itself from siblings like get_prop_history or get_market_odds.

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 query patterns: use game_id for all props in one game, or player_id with season for one player across a season. It also explains the default closing line and estimate_only, but does not state when to prefer alternatives or when not to use this tool.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations by disclosing the 5-credit cost and the latest-season default, though it does not discuss pagination or output volume.

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 front-loaded with 'Use for one player' and uses only three sentences, with the long list of stat categories earning its space by defining the tool's output scope. The credit cost and default are placed at the end without unnecessary prose.

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 full schema coverage, existing annotations, and an output schema, the description provides sufficient context: it identifies the single-player scope, default season, returned stat categories, and credit cost. Remaining parameter details are adequately handled by the schema and 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 description coverage is 100%, so parameters are already well documented, including player_id format, season default, and season_type enum. The description repeats the latest-season default but adds no parameter meaning 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?

The description clearly states this is for one player and enumerates the returned data: bio, draft, physicals, ID crosswalk, summed season totals, weekly lines, and games played. It implicitly distinguishes from team/leader tools by saying 'for one player,' but it does not explicitly differentiate from siblings like 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 phrase 'Use for one player' gives a clear usage context, and the description notes the latest-season default and credit cost. It does not state when not to use the tool or name alternatives such as get_advanced_stats or get_player_leaders.

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 read-only, idempotent, non-destructive behavior, so the description's real contribution is the cost disclosure ('Costs 10 credits'), the pagination mechanism, and the fact that a per-query EPA/success-rate summary comes back. That is meaningful operational context an agent cannot get from 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?

Five tight sentences, each carrying distinct information in priority order: purpose, filter paths, return summary, pagination, cost. No restatement of the title and 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?

For a 17-parameter tool with an output schema, the description covers the decision-critical pieces: which identifier combinations are valid, what summary comes back, how to page, and the cost. Nothing essential is missing, though a note on default result size or the limit cap would close the last 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 coverage is 100%, so the baseline is 3, but the description adds value by grouping the 17 filters into coherent paths (game_id vs season+week/team/player) and calling out the win-probability band, red zone, and third-down toggles as a set. It does not explain the GSIS id parameters, which the schema handles on its own.

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 ('play-by-play with advanced metrics') and enumerates the metrics returned (EPA, WPA, CPOE, air yards), which clearly separates it from aggregate siblings like get_team_stats or get_player_stats. It never names a sibling explicitly, so the differentiation is implied by granularity rather than stated.

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 play-by-play with advanced metrics' plus the two supported filter paths (by game, or by season plus week/team/player) tells the agent how to scope a query. It stops short of saying when to prefer get_advanced_stats or get_player_stats instead, so a boundary case 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?

Adds substantial context beyond the read-only/idempotent annotations: one row per player per game at the median closing line, results split by season, a 95% interval, and the explicit disclaimer that it describes the past and recommends nothing. It also discloses the 25-credit cost, which the annotations do not cover. A 4 rather than 5 because it doesn't say what happens on thin samples or whether low-count buckets are dropped.

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 output shape, then grain, then the sibling pointer and cost, so an agent can stop reading early. The example sentence and the 'recommends nothing' disclaimer each earn their place, though the description runs long for a tool whose schema is fully documented.

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 17-parameter aggregation tool with an output schema, the description covers purpose, aggregation grain, output contents (hit rate, interval, implied and fair probabilities, per-season split), historical scope, and cost. Nothing an agent needs to call it correctly or interpret the result 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?

With 100% schema coverage the schema already documents all 17 parameters, so the baseline is 3. The description still adds meaning by tying filters to the worked example ('receiving yards overs for tight ends on home underdogs' maps to market, side, position, team_role) and by clarifying that the line filter is the median closing line and that fair-probability filters refer to the chosen side. It does not explain season/week interaction or the side default.

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: aggregate a backtest of a prop hypothesis, comparing how often the side hit versus the market-implied probability. It immediately distinguishes itself from the sibling get_prop_history by grain (aggregate rate vs one player game by game), so an agent can route 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?

Explicitly frames the use case ('test an idea ... without pulling every row'), names the alternative for the drift case ('For one player game by game use get_prop_history'), and bounds history to finished games since 2023. Only a hard when-not list is absent, which is minor.

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, idempotent and non-destructive, so the safety profile is covered; the description earns credit by adding what annotations cannot: the credit cost model (10 credits per 25 games, minimum 10, legacy accounts), the free estimate_only preview, and the policy that prices are market information with no stake/payout/recommendation advice. It does not discuss rate limits beyond cost or error behavior, but the added context is substantial.

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 and cost are reasonably front-loaded, but the bulk is a single run-on sentence that re-lists fifteen markets already enumerated in the schema enum (passing, rushing, receiving yards, touchdowns, longest completion/rush/reception), which is wasted length. The cost and responsible-use sentences are the parts that actually earn their 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 needn't explain return values, and it goes further anyway by describing row contents and the over rate. Cost, limits, pagination continuation (next_from_date) and the estimate_only escape hatch are all covered, leaving little an agent needs beyond the default of 50 games that lives in the 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 description coverage is 100%, so the schema already documents every parameter including bookmaker, estimate_only, limit and the market enum. The description explains the bookmaker choice (median across books vs one book's close) and the one-capture opening-line behavior, but those are largely return-shape semantics rather than parameter meaning, so it lands at the baseline.

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 gives a specific verb and resource — see how a player performed against a prop line over time — and precisely enumerates the markets, the per-game row contents (closing line, opening line, prices, box-score result, over rate) and the 200-game cap. It is unmistakably a historical prop tool, but it never names a sibling such as get_player_props or get_line_movement to draw the boundary explicitly.

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 opens with an explicit 'Use to ...' framing and explains the estimate_only workflow for pricing a call before spending credits, which is real operational guidance. It still lacks any 'not for X, use Y' exclusion against the many nearby prop/odds tools.

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?

Beyond the read-only annotations, the description discloses ordering ('oldest first'), grouping ('book by book'), the line_change computation, that capture counts vary by game and book, and a 10-credit cost — a real consumption constraint an agent cannot get elsewhere. It also flags the legal boundary on using price data, which is genuine behavioral context rather than restated safety hints.

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 purpose is front-loaded in the first clause, and every following sentence carries distinct payload: ordering, the line_change formula, capture variability, credit cost, and the usage restriction. Nothing is padded or repeated from the schema.

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 does not need to enumerate return fields, yet it still characterizes the payload (line, both prices, minutes before start) and explains the one derived field an agent would otherwise misread. Credit cost and the pricing-usage restriction close the remaining gaps for a read-only, single-player lookup.

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 schema already documents all four parameters including the market enum, so the baseline is 3. The description adds only indirect meaning — 'book by book' hints at what the optional bookmaker filter does — and adds nothing for game_id or player_id that the schema does not already 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?

The description states a specific verb and resource: showing how one player's prop line moved before a game. That separates it from get_line_movement (game-level lines) and get_prop_history in spirit, but it never names a sibling or states the boundary explicitly, so an agent must infer the split from the word 'prop'.

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 opening 'Use to see how one player's prop line moved before a game' gives a clear condition for selection, and the pricing disclaimer defines a hard scope limit on how results may be used. There is no explicit when-not or named alternative such as get_prop_history, which keeps it short of a 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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: identical lines only are combined, one-sided markets yield no fair probability, prices are latest pre-game, and the call costs 10 credits. It also states a hard usage constraint (never compute stakes/payouts, recommend bets, or refer to a sportsbook), which is behavioral guidance unavailable in 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 purpose and the sibling distinction, then caveats and cost, then the policy constraint. Dense but readable; the pricing/credit and responsible-use sentences are slightly detachable from the core explanation but still earn their place for an agent operating this 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?

An output schema exists, so return values need not be enumerated, yet the description still summarizes what each row contains (average implied probability, fair probability, book count). For a read-only aggregation tool with fully documented parameters, nothing an agent needs to call it 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 three parameters are already documented and the baseline would be 3. The description adds interpretation that affects parameter choice, notably that only identical lines are combined and that one-sided markets such as player_anytime_td lack a fair probability, which helps the agent anticipate results for particular market enum values.

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: aggregated average implied probability (margin in) and fair probability (margin out) per player per line in one game, plus the number of contributing books. It explicitly contrasts itself with per-book pricing, so an agent can distinguish it from get_player_props and get_alt_player_props without opening schemas.

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 the selection condition ('what the market thinks of the player props in one game, not any one book's price') and names the alternative for the other case ('For each book's prices use get_player_props'). It also flags the one-sided-market caveat (anytime touchdown has no fair probability) that tells the agent when the fair value will be absent.

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 read-only, idempotent, closed-world behavior, so the description's job is to add what those hints cannot. It does: a concrete cost of 2 credits, disclosure that consensus lines appear only 'where posted', and a hard restriction on how the returned market information may be used. Missing only return-shape or volume expectations, which the output schema covers.

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 use case and the two modes are front-loaded in the first clause, and the cost and compliance sentences are short and non-redundant. Slight density in the final compliance sentence, but nothing that wastes space.

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 it covers scope, cost, and usage restrictions. An optional parameter set with no required inputs needs little more. It leaves the days-versus-week precedence only loosely implied rather than stated outright.

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 three parameters are already documented, including the default of 7 and the range on days. The description restates the default and implies days and week are alternatives, but adds no syntax, format, or interaction detail beyond the schema. Baseline 3 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?

States a specific ability: upcoming unplayed games within N days, or a specific week of the current season, plus the presence of consensus lines. The resource and the two retrieval modes are unambiguous. It stops short of naming get_games or get_game_detail as the contrasting sibling, so an agent must infer the boundary from the sibling list.

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 what is coming up' gives a direct use condition and the two qualifying modes (next N days vs specific week) are spelled out, so the agent knows which parameter shape selects which behavior. It also constrains downstream use of the returned prices. No explicit when-not guidance or named alternative tool is provided.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds the important cost signal ('Costs 5 credits'), which is valuable behavioral context not present in the annotations. It does not describe output format, but an output schema exists.

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 a single, front-loaded sentence that packs the tool's purpose, supported scopes, and cost without any filler. Every element 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 annotations covering safety traits, a 100% schema description coverage, and an output schema handling return values, the description provides all the additional context an agent needs: what the tool returns, the three invocation modes, and the credit cost.

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 adds meaningful semantics by mapping the three usage modes to parameter combinations: one game (game_id), one player using PFR id (player_id), or a team's season (team + season). This clarifies how to combine the optional parameters beyond their individual schema descriptions.

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 resource (snap counts) and elaborates on the metrics (offensive, defensive, special-teams snaps and snap shares) and scope (game, player, team season). It clearly distinguishes itself from generic stats tools like get_player_stats, though it does not explicitly name a sibling alternative.

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 for playing time' gives a clear context for when to use the tool, and the three supported modes (game, player, team season) further guide invocation. It lacks explicit when-not-to-use conditions or named alternatives, which keeps it from a 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?

Beyond the annotations, which already declare this a safe read-only/idempotent operation, the description discloses that ranks apply the real NFL tiebreaking procedure, reports which step decided each rank, is computed from final scores, defaults to the current season, and costs 2 credits. These are valuable behavioral details an agent needs.

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 front-loaded with 'Use for' and packs the scope, output fields, tiebreaking behavior, data source, default, and cost into a few dense sentences. Every sentence contributes useful information without waste.

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?

The tool has an output schema, so return values need not be explained, and the annotations cover safety. The description sufficiently completes the picture with scope, computation method, tiebreaking transparency, default behavior, and credit cost.

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 100% schema description coverage for all three parameters, the schema already documents season, division, and conference. The description only repeats that it defaults to the current season, so it adds little beyond the structured parameter definitions; baseline 3 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 explicitly states the tool is for regular-season standings and playoff seeding, and enumerates the specific outputs: record, win%, points for/against, various splits, streak, division rank, and conference seed. This clearly distinguishes it from sibling stat tools such as get_team_stats or 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 description gives clear usage context with 'Use for regular-season standings and playoff seeding' and notes it defaults to the current season. It does not explicitly name when not to use it or point to alternatives, but the intended use case is unambiguous.

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 readOnly, idempotent, closed-world, non-destructive semantics, and the description adds a genuinely useful behavioral fact the annotations don't carry: a 5-credit cost. It stops short of noting caching/freshness of the weekly lines, but against rich annotations the incremental context is solid.

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 short elements: a content-scope sentence front-loaded with 'Use for', then a separate cost clause. Nothing is padded, though the parenthetical stat-family list is dense and slightly listy.

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 convey scope and any operational constraint; it does both, including cost. Nothing an agent needs to invoke it correctly appears 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% with team code examples, season defaulting, and a season_type enum, so the schema carries the parameter burden. The description only reinforces the single-team single-season scope and adds no format or default detail beyond that.

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 enumerates exactly what the tool returns for a single team-season (totals by unit, EPA per play, efficiency rates, standings row, weekly lines), which distinguishes it in practice from aggregate siblings like get_standings or get_player_stats. It lacks an explicit verb and never names a sibling, so the differentiation is inferred rather than stated.

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' is an implied usage cue, but there is no guidance on when to prefer get_standings, get_advanced_stats, or get_player_stats instead, nor any exclusion. An agent must reason from the content list to pick this tool.

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, idempotentHint, non-destructive, and closed-world behavior. The description adds useful context about returned fields and a cost signal ('cheapest tool at 1 credit'), which goes beyond the annotations without contradicting them.

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 tightly written sentences, front-loaded with the primary use case and the key return contents. Every clause carries useful information with no repetition or 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?

The tool is simple: two optional filters, rich annotations, and an output schema. The description covers the main use case and return contents, and the schema covers parameter semantics. Additional detail about filter behavior or pagination is not strictly necessary 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 both optional filters are already well documented in the input schema. The description mentions conference and division as returned fields, but adds no filter syntax or behavioral nuance beyond what the schema provides, meeting the baseline for high-coverage schemas.

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 ('list... all 32 current teams') and enumerates the returned fields: conference, division, colours, logo URLs. It also clarifies team-code format with examples, making it easy to distinguish from sibling tools like get_team_stats or get_standings.

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 a clear use case ('when you need team codes') and notes this is the cheapest tool at 1 credit, which helps with routing decisions. It does not explicitly name alternatives or exclusions, but the context is sufficient for most agent decisions.

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?

Beyond the readOnly/idempotent annotations, it discloses the dataset size, the current-season-first search strategy, the automatic fallback to all players when nothing matches, and a concrete cost of 2 credits — all genuinely useful pre-call context. It doesn't say how matching works (case sensitivity, ranking of results) or how the limit ceiling interacts with the fallback.

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, front-loaded with the capability, then the fallback behavior, then the downstream use and cost. Every clause carries information an agent needs; 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?

An output schema exists, so return-shape explanation isn't required, and the description still names the one field that matters downstream (GSIS id). Cost, scope, and fallback are all covered; only the ambiguity-resolution path for multiple partial matches is left unstated.

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 team, position, limit, active, and query are all already documented, including the active/fallback nuance. The description restates the fallback rather than adding new parameter meaning, so this sits at the baseline for a fully documented 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 and resource ("find a player by name (partial match)") plus the corpus scope (~25,000 players back to 1999) and the default result set. An agent can distinguish this from get_player_stats or get_player_leaders purely from the text.

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?

Explicitly frames this as the entry point for resolving a name to a GSIS id that get_player_stats then consumes, which gives clear context for when to reach for it. It stops short of naming exclusions (e.g., use get_player_leaders for ranked leaderboards, get_team_stats for team-level queries) and doesn't say what to do with ambiguous multi-match results.

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