Lumify Sports Intelligence

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

The description adds meaningful behavior beyond the readOnlyHint, openWorldHint, and idempotentHint annotations: found events return full detail, missing events return a not_found list, and missing events are never billed. It also sets the 25-id cap. The description does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, with only three sentences: one for purpose and usage, one for limits and return behavior, and one for sibling guidance. The main scoping constraint is front-loaded 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 and full parameter documentation in the input schema, the description provides exactly what the structured fields cannot: selection criteria, the 25-id boundary, and not-found billing behavior. An agent can decide whether to use this tool versus its siblings without needing further documentation.

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 description coverage is 100%, so all four parameters, including bookmaker and both include flags, are fully documented there. The description adds useful context about event_ids and billing behavior, but it does not need to explain each parameter again, so a 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 opens with a specific action and resource, stating it gets multiple events by id in one call. It also clarifies how this differs from get_event (single event) and list_events/query_events (discovery), so an agent can identify the tool without reading sibling 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?

Explicit usage context is provided: this is for agents that already have a list of ids and want full detail without one call per event. The last sentence directly names alternatives, telling the agent to use get_event for a single id and list_events/query_events to discover ids first.

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral detail: no credits are spent, results are a [min_credits, max_credits] range, costs are data-dependent, and specific free-call cases are given. This goes well beyond the structured safety hints and enriches the agent's mental model.

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 accomplish all goals: purpose, behavior, and usage example. Nothing is redundant; every sentence carries essential information. The structure is front-loaded with the core function and then elaborates with context and a concrete example.

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 tool's moderate complexity (array input, max 50 items) and the presence of an output schema, the description fully covers what an agent needs to invoke it correctly: the input format, the output format (range), and special cost edge cases. No critical information 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 0% schema description coverage, the description fully compensates by explaining the required 'calls' array structure, the 'tool' and 'arguments' fields, and providing a concrete JSON example. The agent knows exactly what to pass without needing to infer from a bare 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 opens with a specific verb ('Estimate') and resource ('credit cost of planned tool calls'), making it unmistakable. It explicitly states 'before making them' and 'no credits are spent,' distinguishing it from all sibling tools that actually fetch data. This is a model of clear purpose differentiation.

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 conveys when to use the tool (before executing calls, to estimate cost) and provides a usage example. However, it does not explicitly state when not to use it or name alternatives. The context makes the use case obvious, but explicit exclusion guidance is missing.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it raises a not-found error for invalid event_id and clarifies the credit behavior for inline data. This helps an agent predict runtime outcomes.

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 purpose in the first sentence, usage guidance in the second, and error/cost behavior in the third. Every sentence earns its place 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?

With an output schema present, the description covers the return contents, the not-found behavior, the credit profile, and the discovery/batch routes. The combination of annotations, schema, and description gives an agent everything needed to correctly select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter already meaningfully documented including defaults, valid values, and credit impact. The description only repeats the credit information and does not add substantially new parameter meaning, so a baseline score of 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 states 'Get a single event with participants and venue', which names the exact resource, scope, and expected return content. It explicitly distinguishes itself from discovery and batch siblings by referencing list_events/query_events and batch_get_events.

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 explicitly says to 'Use list_events / query_events to discover ids first, or batch_get_events to fetch several ids in one call', which tells the agent when to use this tool versus alternatives. It also clarifies that odds and intelligence can be inlined with no additional credit, so cost-aware selection is possible.

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, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context: the probability surface is fair-price + line-shopping (not picks), 'Price gap ≠ EV', 'Match-level tokens ... have null player/team attribution', and 'available:false is free'. These are non-obvious behaviors that go well beyond the annotations and prepare the agent for realistic outcomes.

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 dense and information-rich, with a clear initial sentence followed by relevant caveats and a link to documentation. Every sentence contributes useful behavior or context, though the multiple clauses make it a bit long. It is front-loaded with the core purpose and then detailed branches, which is a good structure.

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 (context indicates 'Has output schema: true'), so return values are documented elsewhere. The description covers edge cases (available:false, no-op bookmaker, null attributions), explains the semantic meaning of the output (not picks, price gap ≠ EV), and links to a field catalog. For an agent, the description provides all necessary context to invoke the tool correctly and interpret results.

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% for both parameters, so the baseline is 3. The description adds meaningful context for bookmaker by specifying it has no effect on probability-model sports, which clarifies its real-world behavior. The event_id semantics are already well covered in the schema, so the description correctly does not repeat them.

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 ('Get AI bet intelligence for an event') and immediately differentiates from siblings by describing the branching logic (probability vs. points models) and the scope (bet intelligence, not raw odds). The name and description together make it unambiguous which tool to use among the sibling tools like get_odds or get_event.

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 contextual cues such as 'Other soccer leagues may return available:false' and 'bookmaker is a no-op for probability-model sports', which tells the agent when certain parameters or results are irrelevant. It does not explicitly name alternatives or say 'use this instead of X', but the description makes the tool's niche clear enough that an agent can infer when to call it.

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 and idempotentHint, but the description adds valuable context: 'Cheaper and faster' performance expectations and the 'not-found error' behavior. It also clarifies the lightweight nature and what fields are included, exceeding the structured metadata's coverage.

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 main purpose, followed by usage and error info. Every sentence adds distinct value with no redundancy, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with output schema and strong annotations, the description covers purpose, usage, alternatives, and error behavior. It is complete and self-contained for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the single parameter event_id with a clear origin ('from list_events, query_events, or search results'). The description adds no new parameter-level semantics beyond what the schema already states, 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 uses a specific verb ('Get a lightweight live score snapshot') with a clear resource ('an event') and enumerates exact contents (status, period, clock, scores, last-updated). It also distinguishes from sibling get_event by highlighting the scope difference, making its purpose unambiguous.

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 explicitly states when to use this tool instead of get_event ('when you only need the score, not participants or venue') and notes the error condition for a non-existent event_id. This provides clear decision guidance relative to alternatives.

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

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

Annotations cover read-only, idempotent, open-world, and non-destructive behavior, but the description reveals non-obvious behavior annotations cannot: returning available:false with no charge if odds are not posted, falling back to another bookmaker while appending requested_bookmaker/fallback_bookmaker, and explicitly refusing to fall back when bookmaker='pinnacle'. This is valuable behavioral disclosure beyond the structured metadata.

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 purpose and includes details that materially affect tool invocation. It is slightly dense with fair_price/consensus and final-event behavior, and some phrasing repeats what the schema already captures, but each sentence adds at least some interpretive value.

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 annotations covering the safety profile, the description supplies the remaining invocation-critical context: default bookmaker, alternate lines, fallback behavior, no-odds behavior, and the relationship to get_odds_history. An agent has enough information to call this tool correctly and interpret edge cases.

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 raises the score by explaining the fallback semantics of the omitted bookmaker parameter and the credit behavior for 'all'/comma-separated lists. The event_id and include_alts parameters are already well-covered by the schema, so the description does not need to add more.

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 first sentence states the exact resource and action: 'Get current betting odds for an event: per-bookmaker lines and last-updated time.' It also differentiates the tool from get_odds_history by defining the temporal scope: current odds vs. line movement over time.

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 explicitly routes the agent to get_odds_history for line movement, and it clarifies when this tool should be used for current lines, including multi-bookmaker requests. It also documents the default Pinnacle behavior and the fallback when Pinnacle has not posted odds, so the agent understands call outcomes without guessing.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that it returns a list of past snapshots with timestamps and limit entries, but this doesn't go beyond the schema or output schema. It adds some context but not rich behavioral details.

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 core purpose, and every word earns its place. No fluff or redundant explanation.

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 history tool with an output schema and well-documented params, the description is complete. It clearly distinguishes from get_odds and gives the key default behavior, making it fully sufficient for an agent to select and call 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 description coverage is 100%, with each parameter already documented (limit, event_id, bookmaker). The description echoes 'bookmaker defaults to pinnacle' and 'up to limit entries', but adds little meaning 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?

The description clearly states the tool's purpose: 'Get line-movement history for an event' and differentiates it from the sibling tool get_odds by noting the latter is for the current line. The verb 'Get' and resource 'line-movement history' are specific and unambiguous.

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?

Provides explicit guidance on when to use this tool vs. the alternative: 'Use get_odds instead if you only need the current line.' Also notes the default bookmaker, giving practical context for invocation.

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 the tool read-only/idempotent, but the description adds valuable behavior beyond those hints: the period-vs-full-game grading, the fallback available:false with no charge, and the HTTP 400 for unsupported sports. This is genuinely useful, non-obvious behavioral detail.

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 dense sentences with no filler. The first sentence states the operation and scope, the second clarifies period-score joining and grading semantics, and the third covers boundary cases. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema already present, the description only needs to convey scope and behavior; it does. It covers supported sports, period composition rules, no-data behavior, unsupported-sport error handling, and the distinction from get_odds. The tool is fully usable from the description alone.

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 only parameter, event_id, already has a 100%-covered schema description explaining its origin from list_events, query_events, or search results. The tool description itself does not add new parameter semantics, so the schema-coverage baseline of 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 opens with a specific verb and resource: 'Get first-half / first-five lines and live progress' and explicitly lists the supported sports (NFL, NCAAF, NBA, NCAAB, MLB). It further distinguishes itself from get_odds by stating that GET /odds / get_odds stay on moneyline/spread/total.

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 explicitly tells the agent when not to use this tool by noting that get_odds covers moneyline/spread/total instead. It also states the boundary conditions: supported sports are named, unsupported sports return HTTP 400, and no period mains yield available:false.

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 semantics. The description adds valuable behavioral details: it raises a not-found error for invalid player_id and notes that tennis ranking is returned conditionally (if applicable). This goes beyond the annotations and helps set expectations.

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 sentences, front-loaded with the core purpose and field list, followed by error and id-resolution guidance. Every sentence earns its place with no redundancy or fluff.

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 simple single-parameter getter with an output schema present, the description adequately covers purpose, error behavior, and id resolution. It is complete for the tool's complexity and aligns well with the provided annotations and 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?

The schema fully documents player_id with a description referencing search_players. The tool description repeats this guidance but does not add new semantic details beyond what the schema already provides. Baseline 3 is appropriate given the high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a single player profile and enumerates the specific fields returned (name, sport, country, position/handedness, physical stats, current team, tennis ranking). It distinguishes itself from sibling tools like get_player_events and search_players by focusing on a single profile retrieval.

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 explicitly instructs to resolve ids via search_players, providing a clear alternative for id lookup. However, it does not explicitly contrast with other player-related getters (e.g., get_player_events, get_stats), so the guidance is helpful but not fully comprehensive.

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 indicate read-only and idempotent. The description adds useful behavioral details: pagination by after_id and the default ±30-day date window when no filter is provided. No contradictions with 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?

Two concise sentences, front-loaded with the core action. Every clause adds value: scope, pagination, default window, and prerequisite. Zero 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?

With a full output schema and rich annotations, the description doesn't need to detail return format or safety. It covers core behavior, pagination, defaults, and the player_id prerequisite, making it complete for the tool's complexity.

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 descriptions cover 100% of parameters, including player_id origin and after_id cursor semantics. The description reiterates these but doesn't add substantially new parameter-level information beyond connecting the pagination flow.

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 it lists a player's events, with 'player's' distinguishing it from broader event tools. The parenthetical (schedule/results) and pagination mention add specificity. This is a specific verb+resource+scope, meeting the top criteria.

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?

Provides clear context: it's for retrieving a specific player's events, and instructs to resolve player_id via search_players first. However, it does not explicitly contrast with alternative event-listing tools like list_events or query_events, so it lacks explicit exclusions or alternatives.

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

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

Annotations already signal read-only and idempotent behavior, but the description adds substantial non-obvious context: joining persisted prop mains to box counts, grading various prop types, returning available:false without charge when no prop mains exist, and rejecting unsupported sports. Nothing contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every clause earns its place: sports scope, output contents, prop types covered, sibling distinction, no-charge behavior, and error handling are all stated 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?

An agent has enough information to call the tool correctly: which sports/events are valid, what categories of props are graded, when not to expect results, and which sibling tools to use instead. The presence of an output schema covers return structure, so 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?

The schema already fully documents event_id, including its source from list_events, query_events, or search results. The description adds useful sport-level context but does not materially extend the meaning of the single parameter beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: retrieving player-prop lines and live progress, and enumerates the supported sports. It also differentiates itself from get_odds by explicitly saying that odds tools stay on moneyline/spread/total.

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?

Names the alternative tool category (GET /odds / get_odds) and clarifies that those tools cover moneyline/spread/total, making the selection boundary clear. It also explains the no-charge available:false case and the HTTP 400 behavior for unsupported sports.

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?

The description adds behavioral details beyond the annotations: it explains the return of available:false with no charge when data isn't captured or sport is unsupported, and clarifies that bookmaker slugs match get_odds rather than upstream keys. This informs cost and data availability behavior.

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 concise yet information-dense: three sentences cover purpose, bookmaker naming convention, sport availability, and fallback behavior. 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?

With an output schema present and one parameter, the description covers key context: supported sports, unsupported sports, return behavior when unavailable, and naming convention. It is sufficient for an agent to 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?

The schema already provides full coverage of the single parameter (event_id) with a description of valid sources. The tool description does not add parameter-specific semantics beyond the schema, so 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 clearly identifies the tool's function: retrieving public betting splits (bets% and handle%) for an event. It specifies the resource (betting splits) and the action (get), and distinguishes from sibling tools like get_odds by focusing on splits and per-bookmaker breakdown.

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 provides explicit context on when to use the tool: for MLB, NBA, NHL, and NFL events, and explicitly lists unsupported sports (tennis, soccer, NCAAF). It does not directly compare with get_odds but references the same odds slugs, implying a relationship. However, it lacks a direct 'use this instead of X' statement, so not 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, the description discloses deterministic behavior, sport-specific payload structures (teams vs. players), tennis doubles/qualifying returning available:false, the exclusion of walkovers and major-league preseason data from form/record/H2H, and the HTTP 400 error condition. This is substantial behavioral context that annotations alone do not 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 dense but every clause adds valuable information: the core behavior, exclusions, sibling differentiators, sport-specific payload, edge cases, and a documentation link. It is front-loaded with the main action and instantly usable.

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 breadth of the potential outputs and the many sport-specific edge cases, the description is remarkably complete: it lists which sports are covered, how the payload changes, what happens in edge cases (tennis doubles/qualifying, walkovers, preseason), and what happens with unsupported sports. The output schema is also shown as present, so the thesis of response details is covered.

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 only parameter, event_id, is already fully documented in the schema (100% schema_description_coverage), so the description need not repeat it. The description adds no additional semantics for this parameter itself, 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 starts with a specific verb and resource ('Get raw, deterministic team/match statistics') and lists all supported sports. It explicitly contrasts itself with get_odds and get_intelligence, so an agent can clearly distinguish it from those sibling tools without opening their 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 provides explicit when-not-to-use guidance: 'no odds (use get_odds)' and 'no scoring (use get_intelligence)'. It also sets hard boundaries for accepted sports ('Other sports return HTTP 400'), so an agent knows precisely when this tool applies and when to route elsewhere.

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?

With annotations already covering read-only, open-world, and idempotent hints, the description adds valuable behavioral context by disclosing the not-found error behavior. It also notes the inclusion of 'home venue' in the response, going beyond the annotation coverage.

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 concise sentences, front-loaded with the core purpose. No wasted words; every sentence contributes useful 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?

This is a simple single-parameter tool with an output schema, and the description covers purpose, error behavior, and id resolution. It is complete for the tool's complexity and schema richness.

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 input schema already provides full coverage (100%) for team_id, including 'Team id, from list_teams.' The description adds no new parameter semantics beyond what the schema states, so the baseline of 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 clearly states the tool's function: 'Get a single team profile with its home venue.' It uses a specific verb and resource, and the singular 'team profile' distinguishes it from sibling tools like list_teams.

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 practical guidance: 'Resolve ids via list_teams,' indicating that team_id should be obtained from list_teams first. It also warns about not-found errors. However, it does not explicitly state when not to use this tool versus other alternatives, 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?

The description adds meaningful behavioral detail beyond the readOnly/idempotent/annotations: it reveals the underlying join with Pinnacle metrics, how live progress is graded, the no-charge behavior when no team-total mains exist, and the HTTP 400 error for unsupported sports.

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 concise and front-loaded. The second sentence explains the internal mechanism, and subsequent sentences capture marketplace boundaries and error/edge-case behavior without redundancy.

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 tool has a full output schema, the description focuses on what a caller needs to know before invoking: expected event type, why the response might be unavailable, and error conditions. This is complete and leaves no obvious operational gaps.

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 input schema for event_id is fully described, with guidance that the id comes from list_events, query_events, or search results. The tool-level description adds the NFL requirement and clarifies the specific data context, making parameter meaning sufficiently clear.

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 starts with a specific verb and resource: 'Get team-total lines and live progress for an NFL event.' It clearly identifies the unique scope of the tool (NFL team totals) and distinguishes it from get_odds by explicitly noting get_odds covers moneyline/spread/total.

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 provides clear usage context by indicating that only NFL events are supported (other sports return HTTP 400) and that get_odds is for a different market set. It does not exhaustively compare to all sibling tools, but the core alternative is called out explicitly.

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 a read-only, idempotent, non-destructive operation. The description supplements this with pagination details (after_id), the behavior of include_scores ('intended for small result sets'), and the exact fields returned. This goes beyond the annotations in a meaningful way.

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 carry a wealth of information without filler. It starts with the core action, then systematically covers filters, return fields, and alternatives, all while remaining scannable and direct.

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 tool with 13 optional parameters and a well-documented schema, the description covers all essential behavioral aspects: purpose, filtering, pagination, return shape, performance notes, and pointer to sibling tools. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds value by explaining the pagination flow (after_id from next_after_id) and the performance caveat for include_scores, which isn't evident from 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?

The description opens with 'List events (schedules and live scores)', a clear verb+resource statement, and immediately differentiates itself from siblings by mentioning pagination via after_id and structured filters. It also names get_event and query_events as alternatives, making its own scope evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'use get_event for one event's full detail, or query_events for free-text/natural-language filters instead of structured params'. It also tells agents to resolve team IDs via list_teams/get_team, covering 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 cover safety (read-only, idempotent, non-destructive), and the description adds meaningful behavior: default active-only filtering, optional historical inclusion, and return field details. It does not contradict annotations and provides useful context beyond 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?

Four short sentences, front-loaded with the core purpose, then defaults, return fields, and an alternative. Every sentence earns its place with no filler or redundancy.

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 simple read-only list tool with an output schema and full annotations, the description fully covers defaults, filtering, and alternatives. There are no meaningful gaps for selection or invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description mirrors the schema's current_only and sport semantics without adding new parameter-level details, but it does reinforce them in natural language.

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 specific verb 'List' with a clear resource 'seasons' and scope 'per sport/league'. It explicitly distinguishes itself from the sibling list_sports by directing users there for just current-season info.

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 default behavior (only active seasons), how to opt into historical seasons (current_only=false), optional sport filtering, and explicitly names list_sports as an alternative when simpler data suffices. This provides clear when-to-use 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 read-only and non-destructive behavior. The description adds useful context about the returned data structure (sport id, slug, name, team-sport flag, leagues with current_season) that is not redundant with the output schema, and it clarifies the tool's scope beyond the 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?

Two sentences: the first leads with the action and key outcome, the second details return fields and the alternative for historical data. Every sentence earns its place with no redundancy 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?

Given the single optional parameter, rich annotations, and presence of an output schema, the description fully covers the tool's purpose, return shape, and related tool guidance. No important gaps remain for a simple list operation.

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 input schema already provides a full description for active_only (100% coverage), so the schema does the heavy lifting. The description does not add additional parameter meaning beyond what is in the schema, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists supported sports with their leagues and current season, naming the exact fields returned. It distinguishes from sibling tools by explicitly pointing to list_seasons for historical seasons, and the scope (sports vs teams/events) is unambiguous.

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?

Provides explicit guidance to use list_seasons with current_only=false for historical seasons, which is a clear alternative. Does not enumerate all when-not-to-use scenarios, but the primary use case is evident and the alternative is well-targeted.

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 and destructiveHint=false, which covers the safety profile. The description adds behavioral context about pagination ('paginated by id (after_id)') and the return fields, which is beyond what annotations provide. No contradictions detected.

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 only two sentences, front-loaded with the core action and immediate pagination note, followed by a concise list of filters and return fields. Every sentence earns its place, no redundancy.

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 tool has 9 optional parameters and an output schema, the description covers the essential contextual aspects: what it lists, how pagination works, what fields are returned, and when to use a sibling. The presence of an output schema means return value details are already structured; the description still states the main fields for quick reference.

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 input schema already documents all 9 parameters with descriptions (100% coverage). The description adds minimal extra meaning by clarifying that 'after_id' is a pagination cursor and that 'q' is a partial name match, but these are already in the schema. Thus 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 clearly states the tool 'List teams' with a specific verb and resource, and immediately distinguishes it from siblings by saying 'Use get_team for full detail on one id once resolved here.' It also enumerates the filtering capabilities, making the purpose unambiguous.

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 explicitly provides an alternative tool for a different use case ('Use get_team for full detail on one id once resolved here'), and the filter list implies when to use this tool (to find or list teams by criteria). This satisfies the 'when vs alternatives' guidance requirement.

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 (read-only, idempotent, non-destructive), the description adds critical behavioral details: it is rule-based not an LLM, specific language features are recognized, bare 'football' is ambiguous and left unrecognized, and the response includes interpreted filters, equivalent REST call, and unrecognized_terms.

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 dense but every sentence contributes useful information. It opens with the primary purpose, provides illustrative examples, explains internal behavior, and closes with usage guidance—all without fluff.

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 tool's natural-language processing complexity, the description thoroughly covers usage scope, behavioral limitations, and response contents. The output schema handles return values, so no additional detail is needed there. The description is comprehensive for an AI agent to decide when and how to invoke 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?

Although the schema documents both parameters, the description enriches the 'query' parameter by detailing supported sports, statuses, date formats, and the ambiguity behavior. It also clarifies the 'limit' parameter's override semantics, adding value beyond the schema 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 clearly states the tool's purpose: search events using natural-language queries instead of structured filters. It provides concrete examples and explicitly distinguishes it from sibling tools like list_events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit guidance on when to use this tool versus the alternative, stating 'Prefer list_events when you already know the structured filters you want.' This directly addresses 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, and non-destructive behaviors. The description adds valuable behavioral context about pagination ('paginated by id (after_id)') and response shape (returns specific fields, tennis ranking only if applicable). While it doesn't discuss response ordering or edge cases, the combination with annotations is sufficient for safe invocation.

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 sentences, front-loaded with the core functionality, then response details, then alternatives. Every phrase serves a purpose with no waste or redundancy.

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 search tool with 7 optional parameters, an output schema, and rich annotations, the description covers purpose, criteria, pagination, response fields, and explicitly names alternatives. It is complete enough for an agent to understand when and how to use it, leaving no critical gaps.

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 parameters are already documented. The description adds meaning by grouping searchable parameters ('by name, sport, country, ranking, or active status') and explaining the pagination mechanism with after_id. This gives a higher-level understanding of how the parameters relate, exceeding 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 clearly states 'Search players by name, sport, country, ranking, or active status' with a specific verb and resource, listing search criteria. It distinguishes itself from sibling tools by explicitly directing to get_player and get_player_events for different needs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is provided: 'Use get_player for full detail on one id, or get_player_events for a player's schedule/results.' This clearly indicates when to use this tool versus alternatives, making the intended use case unambiguous.

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