Keel Stats

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. Beyond that, the description adds two non-obvious behaviors: rank semantics (1 = allows the most) and an entitlement gate (window 'recent' requires Pro), which prevents a paid-endpoint failure loop. It stops short of noting ordering, pagination, or whether teams with no games are included.

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 trigger is front-loaded, then output shape, then the exclusion — a sensible order for an agent skimming. Every clause carries information, though the parenthetical-heavy single paragraph is dense enough that the Pro-window caveat is easy to miss on a fast read; a short clause break would improve scannability without adding 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?

For a read-only, single-required-parameter aggregation tool with no output schema, the description covers everything necessary: what is returned (per-game allowed by position group plus pace), how values are ranked, which league/position vocabularies apply, entitlement constraints, and the tool it should not be used for. No gap remains for correct selection and 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, but the description goes past the schema by spelling out the valid position-group vocabulary per league and the Pro restriction attached to the 'recent' window value. Season defaults are also covered. It doesn't explain how 'position' interacts with the NBA pace column or whether omitting it returns all groups.

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 uses a concrete verb and resource: it returns what every NBA or NFL team allows per game to each position group, with league ranks. It names the exact output columns (NBA G/F/C with pace; NFL QB/RB/WR/TE) and explicitly separates itself from player-level matchup tools, so an agent can distinguish it from siblings 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?

The description opens with a triggering user-question pattern ('best matchups for centers', 'defenses vs TE') and closes with an explicit exclusion naming the alternative tool and its condition ('Not for one player's matchup (player_profile's next game)'). Both the when and the when-not are stated, not implied.

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 mark this as read-only, idempotent, non-destructive, and not open-world. Beyond those annotations, the description discloses the fallback behavior: returning the game on a specified date, or the last three finished and next three games when no date is given, along with returned fields such as game_id, start time, state, week, score, and page URLs.

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 two tightly packed sentences with zero wasted phrasing. The primary usage condition is front-loaded, followed by return behavior and exclusions.

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 read-only lookup tool with full schema descriptions and annotation coverage, the description supplies the missing context: exact use cases, fallback return behavior, and sibling exclusions. There is no output schema, but the description lists the key returned fields so an agent knows what to expect.

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 parameter documentation is already strong. The description still adds meaning by clarifying the date behavior: a date retrieves that day's game, while omitting the date returns recent and upcoming games, and by framing opponent matching as a specific meeting between the pair.

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: finding a team's game and retrieving its game_id. It gives concrete examples such as 'Lakers next game' and 'Cowboys vs Eagles on November 23', and explicitly distinguishes the tool from related siblings like tonight_slate and head_to_head.

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 states when to use the tool: when the user asks about one team's game on a date, its next or last game, or a specific meeting. It also names alternatives for excluded cases: the whole slate (tonight_slate) and pair history (head_to_head).

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 job is to add behavior — and it does, disclosing the Pro entitlement gate and exactly which extra fields a paid account unlocks. It stops short of stating pagination, latency, or error behavior for bad game_id, which keeps 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?

Front-loaded with the usage trigger, then the return payload, then the prerequisite and the exclusion — a sensible ordering. The long semicolon-chained inventory of return fields is dense but each item is informative; only mild trimming would be 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?

There is no output schema, so the description must describe returns itself, and it does comprehensively (probabilities, market lines, ATS form, leaders, injuries, and the Pro-only extras). Given the tool's complexity and three-parameter surface, an agent has everything needed to call it and 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 coverage is 100%, so all three parameters are already documented, including the Pro requirement on include_breakdown. The description's only added param meaning is restating that game_id comes from tonight_slate or find_game, which the schema already says. Baseline 3 is appropriate when the schema carries the load.

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 ('who is favoured in one game, by how much, or how the two sides compare') and enumerates the concrete outputs (win probability, projected margin, spread/total, ATS form). An agent can distinguish this from head_to_head or props_research 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?

Opens with an explicit when-to-use trigger ('when the user asks who is favoured in one game'), states the prerequisite ('Needs a game_id from tonight_slate or find_game'), and names an exclusion ('Not for picks or betting advice'). That is when/when-not/prerequisite in one compact block.

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, destructiveHint=false and openWorldHint=false, so the safety profile needs no restatement. The description still contributes beyond that by disclosing the full return payload (records, per-season splits, last ten meetings with top players, leaders, next-game projection with chance and margin), which is genuinely useful for deciding whether to call it. It does not mention result size or pagination, so it is not exhaustive.

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 is front-loaded: the usage trigger comes first, then the return contents, then the exclusion. The single long enumeration sentence is dense but each item (series leaders, last ten with top player, next game projection) maps to a distinct decision-relevant output, so little is wasted; it would read better split into two shorter sentences.

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?

There is no output schema, and the description compensates by enumerating essentially every returned component, including the next game with projected chance and margin. Combined with the explicit sibling handoff to game_projection, an agent has everything needed to select and call this tool 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%, with team_a_id and team_b_id already documented as 'from search (e.g. the Celtics)' and league as an enum of nba/nfl. The description adds no parameter-level detail such as ordering behavior between team_a_id and team_b_id or whether the pair must be in the same league, so the schema does all the heavy lifting and 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 names a specific verb-and-resource ('how two teams have fared against each other') and enumerates the exact outputs: all-time and by-season records, this season's series, last ten meetings with top players, series leaders, and next game projection. It distinguishes itself from game_projection by name, 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?

It states the triggering user phrasing explicitly with examples ('Celtics vs Knicks history', 'Cowboys Eagles record') and adds a clear exclusion: 'Not for a single game's preview: use game_projection with the game_id it returns.' Both when-to-use and when-not-to-use are given, including the alternative tool and how to obtain its argument.

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 as a safe, idempotent, non-destructive read, so the bar is lower. The description still adds real behavioral content by disclosing what each mode returns: win-probability and spread shifts plus the teammates whose minutes or target/carry share rises.

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 trigger condition, followed by return behavior, then a single exclusion clause. Three compact sentences with no filler and clear priority ordering.

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 no output schema, the description correctly explains return values for both modes, which is the essential missing structured information. It is slightly thin on the shape of the league injury report itself, but nothing needed to select or invoke the tool is absent.

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 description's account of player_id largely restates the schema's own text (omit for the league report, use for absence consequences). With the schema doing the heavy lifting, baseline 3 applies; the description adds emphasis but little new syntax or constraint.

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 (league injury report / absence consequences) with two clearly delineated modes: league-level report and player_id-level impact analysis. It distinguishes itself from siblings by explicitly naming player_profile as the tool for a player's own injury status.

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 when-to-use clause plus two concrete user-phrasing examples ('Lakers injury report', 'what if Haliburton is out'). It also provides an explicit exclusion and names the alternative (player_profile) for the case this tool should not handle.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the set of values returned, which is useful since there is no output schema, but it says nothing about response size, pagination of the ten-game log, or behavior for an unknown player_id. With annotations carrying safety, a 3 fits.

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 trigger condition and examples, then the payload, then the exclusions. Every clause carries information an agent needs for selection and there is 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 read-only, three-parameter lookup with a full schema and no output schema, the description covers purpose, return contents, and routing exclusions. It stops short of describing caveats such as a missing/limited player or malformed player_id, which leaves a small 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%, and all three parameters already have descriptions including the season default and the enum for league. The description adds no parameter-level meaning beyond the schema, so the baseline of 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 opens with a specific verb+resource ('one player's season or recent form') and enumerates the returned content: season averages, efficiency metrics per league (TS%, eFG%, USG%, BPM; yards, touchdowns, EPA), Keel Impact with rank, injury status, and last ten games. It also names the sibling tools it is not, so an agent can route without opening the 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 states explicitly when to invoke ('when the user asks about one player's season or recent form') with two realistic example queries, and gives exclusions naming the exact alternatives: player_splits_and_on_off for on/off or teammate splits and props_research for prop lines. Nothing 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: a Pro entitlement requirement and the behavior that the answer explicitly reports when the account lacks Pro. It does not describe output shape or any latency/limits, but with no output schema that is a minor gap.

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: trigger conditions first, then the return scope, then the entitlement constraint. Every clause earns its place and nothing is buried.

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 4-parameter read tool with no output schema, the description covers purpose, triggering questions, season scope, and the Pro gate. The remaining gap is what the returned splits actually look like (e.g., on/off ratings vs. share percentages), which the description only gestures at.

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 each parameter (including teammate_id's 'two-man / with-without splits' and season default) is already documented. The description adds only indirect meaning by specifying what split types exist per league; it gives no extra guidance on when to supply teammate_id versus omit it.

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 and scope: on/off splits, clutch/garbage-time splits, and with/without teammate splits, plus an NFL-specific variant (target/carry/red-zone shares). It is clearly distinguishable from siblings like player_profile or head_to_head, though the framing is usage-first rather than a crisp verb+resource statement.

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 this when the user asks...' trigger list covering the three main question shapes, which is strong when-to-use guidance. It does not name a when-not condition or a specific alternative sibling (e.g., use player_profile for overall stats), so it stops 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 declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds things annotations cannot: a Pro-tier access requirement and an explicit non-recommendation guarantee ("never gives a pick"). It stops short of covering pagination or result-size limits for the board view.

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 sentences, front-loaded with the usage trigger, then the return payload. It is dense but every clause maps to a distinct output or constraint. The long second sentence packs many return artifacts together, which slightly reduces scannability but wastes no words.

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?

There is no output schema, so the description carries the full burden of describing return values, and it does so thoroughly: upcoming lines, book-by-book odds and moves, averages, L5/L10/L20/season hit rates, model probability, over/under/push record against closing lines and alternate ladders, plus board/cheat-sheet contents. Both branches (player_id present or absent) are covered, along with the access prerequisite and the non-advisory nature.

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 parameter documentation is already complete and detailed (date format, stat code examples, game_id filter, player_id behavior). The description adds the useful cross-parameter semantic that omitting player_id switches the entire output shape to the board plus cheat sheet, but it does not add per-parameter detail beyond what the schema states. 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 names the resource precisely (prop lines, hit rates, book-by-book odds, closing-line record, ladders) and distinguishes two operating modes: with player_id it returns that player's research; without it, the daily board and cheat sheet. No sibling tool (defense_vs_position, game_projection, tonight_slate, etc.) covers prop research, so the agent can route here unambiguously.

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 trigger: "Use this when the user asks about a player's prop lines, how often he clears a line, book-by-book prices, or today's prop board." It also states a prerequisite (Keel Stats Pro) and a hard boundary ("Research only: it never gives a pick"). It does not name a sibling alternative for overlapping queries such as slate-level context, 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (ranked list plus the URL of its table) and a tier gate (Pro adds offense/defense, box prior, RAPM and on/off components). It doesn't mention result size limits or how partial seasons are handled, 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?

Three sentences, front-loaded with the usage trigger, followed by the covered list and the exclusion. No redundant restatement of the title or annotations, 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?

With no output schema, the description takes on the burden of describing returns and does so (ranked list with table URL, Pro-only components). For a read-only, closed-world leaderboard tool with fully documented parameters, that is nearly everything an agent needs; only pagination/result-size behavior is 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 coverage is 100% with two enums, so the schema already documents all three parameters thoroughly; baseline 3 applies. The description loosely maps natural-language requests to kinds, but the example "top 10 NFL defenses by EPA" sits ambiguously between power_rankings and efficiency, so it adds marginal rather than clarifying value.

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 trigger ("user asks for a league-wide list") and enumerates the exact resources covered: standings, NBA Keel Impact ratings, NFL EPA per play, weekly power rankings. It explicitly carves out what it is not ("Not for one team or player"), so an agent can distinguish it from team_profile and player_profile 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?

It states both the when (league-wide ranked lists) and the when-not (single team or player), and names the correct alternative ("use their profile"). The example phrasing "top 10 NFL defenses by EPA" gives the agent a concrete pattern to match user requests against.

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, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: accent- and typo-tolerant matching, and the shape of the result (matching players and teams with ids and urls). It does not say how many matches are returned or how ambiguity/ranking is handled, which is the main remaining gap.

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 sentences, no filler, and the primary trigger is front-loaded before the exclusion. Every clause carries information the agent can act on.

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?

There is no output schema, and the description compensates by describing the return contents (players and teams with numeric ids and page urls). For a two-parameter lookup tool with full annotation coverage, 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 coverage is 100%, so the schema documents both parameters and the enum. The description still adds meaning beyond it by disclosing that the query is accent- and typo-tolerant, which tells the agent it can pass loosely spelled names rather than needing exact strings.

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 resource (NBA and NFL players and teams) and the concrete output (numeric ids and page urls), so the agent knows exactly what a call produces. It also distinguishes itself from the profile siblings by stating it is not for 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?

It gives an explicit trigger ('when you need a player_id or team_id') and a concrete unresolved-name scenario with real examples. It also names the alternatives and the condition that selects them: 'Not for stats: call player_profile or team_profile with the id.'

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 the safety profile needs no restating. The description adds genuinely new behavioral context by disclosing the return payload (record, ratings with league ranks, roster, last/next games) and notably that games carry a game_id, which signals follow-up chaining to find_game. It does not mention the season default or any pagination/size limits on the roster, leaving a small gap.

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 sentences, both load-bearing: the first establishes purpose and scope, the second covers return contents and sibling routing. Trigger condition is front-loaded and there is no filler or redundant restatement 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?

There is no output schema, so the description carries the burden of describing return values, and it does so concretely down to the game_id field. Combined with annotations covering the safety profile and a fully documented schema, nothing an agent needs to select or invoke this tool 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 league, season and team_id are already fully documented, including the current-season default and the pointer to the search tool for team_id. The description adds only the framing that the profile is scoped to a single team's season, which is marginal 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 concrete verb-and-resource pairing ('one team's season: its record, ratings, roster, recent and coming games') and enumerates exactly what the tool covers. The closing sentence names the two siblings it is not (rankings_and_ratings, head_to_head), so an agent can route correctly 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?

Opens with an explicit trigger condition ('Use this when the user asks about one team's season') and follows with explicit exclusions naming the alternative tool for each excluded case. Both the when and the when-not are stated, which is the full bar for this dimension.

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 needs no restating. The description adds context the annotations cannot: the exact return payload (games, times, scores, probabilities, starters, injury deltas). It does not mention volume, pagination or how live scores refresh, which is the only remaining gap.

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 trigger condition, followed by return contents and then the routing exclusion. The dense field list is informative rather than padding, and 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?

With no output schema, the description carries the burden of describing results and does so explicitly, plus league scoping and date optionality via the schema. For a two-optional-parameter read tool, an agent has everything needed to call it and interpret the response.

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 both parameters are already documented, including the enum and the YYYY-MM-DD format, so the baseline is 3. The description reinforces the date semantics with a worked example and implies omitting the date yields the current slate, but adds no syntax or behavior not already in 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 names a specific resource (a day's slate of games) and enumerates what comes back: game_id, US Eastern times, live/final scores, win probabilities, starters and injury changes. It also differentiates itself from the sibling find_game, so an agent can pick between them without inspecting 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?

It states the triggering user intents ('what is on tonight', 'today's scores', 'a given day's games') with a concrete date example, and gives an explicit exclusion plus the alternative: not a game weeks away or a single team's schedule — use find_game. Both the when and the when-not are present.

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