Cito API

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

Beyond the readOnly/openWorld/destructive annotations, the description adds valuable behavioral context: parallel-safety, upstream cost range, best-effort probing behavior, and which error situations warrant calling it. This gives the agent a clear model of the tool's side effects and operational profile.

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 tightly organized with front-loaded output information, a compact when-to-use list, and a short example. Every section earns its place, and there is no filler or redundant repetition of schema fields.

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

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

Despite having an output schema, the description still supplies operational context such as upstream cost, parallel-safety, and error recovery triggers. For a simple single-parameter health-check tool, this is complete enough for an agent to select and 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?

The schema already documents includeGameProbes at 100% coverage, so the baseline is 3. The description adds a concrete usage example and links the parameter to the 'best-effort included games' behavior, making the optional flag's purpose clearer without repeating the schema.

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

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

The description states exactly what the tool reports: API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games. It clearly differentiates from siblings by naming live_matches as the alternative for live scores.

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 when-to-use scenarios, including once per session, after specific errors, and for entitlement checks. It also gives a 'Prefer over' instruction and a 'Do not use when' rule, which is exactly the kind of routing guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds critical behavioral context beyond that: path allowlist constraints, rejection of absolute URLs and path traversal (PATH_NOT_ALLOWED), parallel-safety caveats ('discouraged in bulk'), and upstream cost (1). It also clarifies the raw/unshaped return format. No contradiction with annotations; the read-only nature is reinforced by 'GET only'.

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 information-dense and well-structured: a one-line core purpose, then bullet points for when to use, when not to use, path constraints, parallel guidance, cost, and an example. Every section carries unique value; no filler. It is longer than typical but the tool is an escape hatch with non-obvious constraints, so the length is justified and front-loaded with the core purpose.

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 description covers all decision-relevant aspects: what the tool does, when to use it, when not to, path validation rules, error behavior, parallel usage guidance, and cost. Since an output schema exists (has output schema true), the raw return format is implied. For a raw-access tool with these constraints, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a single combined example that demonstrates method, path, and queryJson together, which clarifies how the parameters interact. It also reinforces that method is read-only, though that's already in the schema enum. The description doesn't introduce new parameter meanings but the example adds practical usage clarity beyond the per-parameter descriptions.

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

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

The description opens with 'Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.' This states the verb (call), resource (Cito REST), and the key differentiator (raw/unshaped output). It explicitly contrasts with curated tools: 'Prefer curated tools for all standard jobs,' naming the sibling set. An agent can immediately tell this tool is for uncached, raw access and not for standard curated endpoints.

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 an explicit 'When to use' list (long-tail paths, debugging, user knows an OpenAPI path) and a 'Do not use when' clause (a curated tool covers the outcome). It also names alternatives implicitly via 'Prefer curated tools' and warns about parallel storms. This is exactly the kind of decision guidance needed for an escape-hatch tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the structure of the data (1v1, 1v2, ..., attempted vs won) and the global leaderboard option, which goes beyond the annotations and clarifies response semantics without contradiction.

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

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

The description is a single, front-loaded sentence that states the purpose first, then explains the two modes. It contains zero fluff and every clause carries essential information, making it optimally concise and well-structured.

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 is a simple read-only stats query with full schema coverage on both parameters and an output schema provided, the description fully covers the invocation variants (player vs global). No additional context is needed for correct usage; the output schema handles return format details.

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% for both parameters, so the baseline is 3. The description adds value by explaining that playerId triggers a specific breakdown (listing clutch scenarios) and that omission yields the global leaderboard, which is more semantic detail than the schema's 'if omitted, returns global leaderboard' explanation.

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 provides '1vX clutch situation success records' and distinguishes between two modes: per-player breakdown or global leaderboard. This uniquely identifies the tool's resource and differentiates it from sibling tools like cs2_opening_duels or leaderboard_aces.

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

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

The description gives clear usage context: pass playerId for a player's breakdown, omit for global leaderboard. While it doesn't explicitly name alternatives or exclusion criteria, the conditional usage is unambiguous and effectively guides the agent on how to invoke the tool for the desired result.

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, so the safety profile is covered. The description adds meaningful behavioral context by specifying 'live real-time' and 'active match,' indicating that data is ephemeral and tied to ongoing matches. No contradiction 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-load the core purpose and immediately follow with valuable specifics. Every clause earns its place with no repetition or filler.

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

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

Given the simple single-parameter schema, the presence of an output schema, and annotations covering safety, the description is nearly complete for an agent to invoke the tool. Minor gaps include not explaining behavior for expired or finished matches, but this is not critical for a live scoreboard 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 covers the single matchId parameter 100%, including examples and description. The description does not add parameter-level details beyond implying the match must be active, so the baseline of 3 is appropriate since the schema carries the burden.

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

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

The description clearly identifies a specific resource: a live in-game scoreboard for an active CS2 match. It enumerates distinctive data elements (round, bomb status, team scores, player stats) that differentiate it from sibling tools like cs2_clutches or cs2_round_economy.

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

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

The phrase 'for an active CS2 match' implies when the tool should be used, and the tool's unique focus on live scoreboard data is clear. However, it does not explicitly state when not to use it or name alternatives, leaving some routing 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about the specific stats (FK, FD, conversion %) but does not disclose additional behavioral traits such as sorting, recency, or response shape; that burden is moderated by the existing annotations and output schema.

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

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

A single, well-structured sentence that front-loads the resource and then lays out both usage modes with no filler. Every clause earns its place, and the description avoids restating the tool name or redundant schema details.

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 simple two-optional-parameter interface, read-only annotations, and existing output schema, the description covers everything an agent needs to decide and call correctly. There is no missing operational context that would lead to misinvocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by naming the returned metrics (First Kills, First Deaths, opening duel conversion %) and explicitly tying playerId to pro-player stats versus the global leaderboard. This helps the agent understand what each call mode will yield.

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

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

The description clearly identifies the tool as providing first blood and opening duel statistics, with an explicit verb ('view') and resource (CS2 opening duels). It further distinguishes two distinct modes—player-specific stats versus global leaderboard—making its purpose unambiguous and separable from sibling CS2 tools.

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 clearly explains when to pass playerId versus omit it, giving the agent concrete conditional guidance. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for a read-only stats tool with a simple two-mode interface.

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, so the safety profile is covered. The description adds the temporal scope 'recent' but does not specify the exact time window, pagination, or sorting behavior. It provides minimal additional behavioral context beyond the annotations, which is acceptable for a simple read operation but not rich.

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

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

The description is a single, concise sentence that front-loads the core functionality. There is no fluff, redundant phrasing, or extraneous detail. Every word contributes to the meaning, making it efficient and easy to scan.

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

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

Given the tool's simplicity (one parameter, read-only, output schema present), the description is largely sufficient. The only notable gap is the vague term 'recent', which could benefit from a defined time range. However, for a basic informational tool, the description covers what an agent needs to know to call it correctly.

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

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

The input schema fully documents the single 'limit' parameter with default, min, max, and an example, achieving 100% schema coverage. The description adds no extra meaning about the parameter, so it relies entirely on the schema. This meets 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 resource and topic: professional CS2 roster changes, benchings, stand-ins, and transfers. It distinguishes from siblings like cs2_live_scoreboard or cs2_team_map_stats by focusing on roster events rather than match stats. However, it lacks an explicit verb like 'list' or 'retrieve', making the action implied rather than stated.

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

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

Usage is implied: use this tool when roster transfer information is needed. There is no explicit statement of when to use it versus alternatives, and no mention of scenarios where it should not be used. Since no direct sibling offers the same functionality, the lack of alternatives is acceptable, but the description provides no contextual guidance beyond its topic.

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?

Read-only nature is covered by annotations; description adds specific behavioral detail about classifying rounds and exposing economy stats. No side-effect caveats needed beyond readOnlyHint.

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

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

Two short, dense sentences front-load the purpose and list concrete outputs. 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?

With the schema covering the input and an output schema present, the description tells the agent what the tool produces at the map level. No usage exclusions or alternative routing are mentioned, but the context is inferable for a read-only map-economy query.

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 single mapId parameter is already fully described in the schema with an example. The description does not add parameter-specific meaning, but schema coverage is complete.

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 action ('Classifies') and resource (round-by-round economy for a CS2 map) with concrete output categories (buy types, spend, freeze-time values, loss bonus). It is distinct from sibling CS2 stat tools.

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 intended use is implied by the content (analyze CS2 round economy), but there is no explicit statement of when to use it vs. sibling tools, nor any 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds context about the data scope (history over 30/90 days) and that it covers the competitive map pool, but does not disclose any additional behavioral traits such as filtering restrictions, pagination, or response structure. That is acceptable given the read-only nature.

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

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

The description is a single sentence that front-loads the key metrics and then scopes them to the map pool and timeframe. It is concise and avoids redundant detail. It loses a point for the slight inconsistency with the schema's timeframe list and the embedded map list could be considered an unnecessary elaboration, but overall it is 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?

With an output schema present and annotations covering the read-only safety profile, the description does not need to explain return values or side effects. However, the mismatch in valid days values is a genuine gap that could cause incorrect parameter usage. The description otherwise gives a good overview of the data content, so it is adequate but not fully complete.

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 would be 3, but the description actually introduces a contradiction: it says 'over the last 30 or 90 days' while the schema's days parameter explicitly allows 30, 90, 180, or 365. This misrepresents valid input and could mislead an agent. No extra meaning is added beyond what the schema already provides.

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 data returned: team win rates, round win rates, CT/T splits across a defined map pool. This separates it from siblings like cs2_clutches or cs2_round_economy, though it does not explicitly name any alternative. The noun-phrase style is a minor drawback but the meaning 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?

There is no guidance on when to use this tool versus alternatives. It does not mention when to prefer it over cs2_veto_sequence, cs2_round_economy, or player_stats, nor does it give exclusion criteria. The only implied use case is needing team-level map stats, which is thin.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context by noting the 'Sub-second cached' nature, which informs the agent about performance characteristics. It also specifies the exact metrics returned, going beyond the annotations.

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

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

The description is a single, information-dense sentence that front-loads the key behavioral trait ('Sub-second cached') and then lists the specific metrics. Every word 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 tool's simplicity (1 optional parameter, no nested objects, output schema present), the description is nearly complete. It covers the data source (CS2 utility/flashbang), the performance characteristic (cached), and the return metrics. The only minor gap is not explicitly stating the ranking order or whether the output is sorted, but the output schema likely covers that.

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

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

Schema description coverage is 100%, so the single 'limit' parameter is fully documented in the schema. The description does not add additional parameter-level detail beyond what the schema provides, but the baseline of 3 is appropriate given the complete 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's function: it returns a cached leaderboard of CS2 utility and flashbang efficiency, with specific metrics (effective blind duration per flash, enemy blind time, flashes thrown, grenade ADR). This is a specific verb-resource pairing that distinguishes it from sibling tools like cs2_clutches or leaderboard_aces.

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 implies usage for querying CS2 utility leaderboard data, but does not explicitly state when to use this tool versus alternatives like cs2_team_map_stats or other leaderboard tools. The 'Sub-second cached' hint suggests a performance context, but no explicit when/when-not guidance is provided.

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

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

Annotations already establish this as a safe read-only, non-destructive, open-world call. The description adds useful behavioral detail by specifying chronological ordering and the categories of information returned, without contradicting 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?

Two short sentences with no filler; the first sentence names the resource and the second details the output. Every clause earns its place.

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

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

For a one-parameter read-only tool with a supplied output schema, the description is nearly complete. The only missing nuance is an edge-case caveat (for example, whether veto data is available before/during a match), which would have pushed it to a 5.

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 has 100% description coverage for the only parameter, including an example and explicit required flag. The description doesn't need to add parameter details, so the baseline 3 applies; it contributes no extra semantics beyond 'for a CS2 match.'

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 ('Shows') and names a concrete resource: a CS2 match's pick/ban veto sequence. It enumerates exactly what is displayed (team bans, map picks, decider map, chronological order), which makes it immediately distinguishable from sibling tools like cs2_team_map_stats or match_details.

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 context is clearly a single CS2 match via matchId, but the description never states when to prefer this tool over siblings or when not to use it. Selection guidance is implied by the unique 'veto sequence' scope rather than explicitly provided.

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

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

While annotations already mark readOnlyHint=true and destructiveHint=false, the description goes far beyond by disclosing card ordering (main event first), bout and corner fields, the CORS limitation and recommendation to use proxiedImageUrl, no need for per-fighter call_api, tennis bracket truncation behavior, parallel-safety, and upstream cost. There is no contradiction with 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 long but tightly organized with bolded section labels and front-loaded purpose. Every sentence either explains when to use it, what behavior to expect, or what to prefer instead. There is no filler or repetition; the density is justified by the tool's breadth across multiple games and tennis special cases.

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 7 parameters, multiple game-specific behaviors, and a tennis special path, the description is complete: it covers route selection, data shapes, alternatives, exclusions, parallel-safety, cost, and an example call. Since an output schema exists, the description appropriately focuses on decision-relevant behavior rather than restating return types.

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 baseline is 3, but the description adds meaningful depth to every parameter: q resolves internally, eventIdOrSlug is preferred over q, limit bounds bouts and tennis draws, drawMaxMatches fills rounds from the final backwards and reports truncation, includeMatches includes the draw, and includeStandings triggers an extra call plus rank enrichment. This goes well beyond the schema's raw descriptions.

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

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

The description opens with a specific composite pattern ('COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet') and immediately lists concrete event types (UFC, CS2, tournament/event overview). It explicitly distinguishes itself from match_preview, match_summary, live_matches, and standings, so an agent can select it with confidence.

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 'When to use', 'Prefer over', 'Prefer X for Y', and 'Do not use when' sections, naming exact sibling tools and conditions. This leaves no ambiguity about when event_card is the right tool versus alternatives like match_preview or live_matches.

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, and the description adds meaningful details: parallel-safety, upstream cost formula, name resolution via player search, cell orientation as W-L from the row player's perspective, and '-' on the diagonal. 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?

Well-structured into purpose, usage, exclusions, and behavior sections with no filler. Every sentence carries routing, semantics, or cost information, and the most important scope constraint appears early.

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 2-parameter tool with an output schema, this is complete: it covers player limits, input forms, cell semantics, routing to alternatives, and upstream cost. Return-value details are covered by the output schema, so the description does not need to repeat them.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly restricting the tool to tennis despite the multi-game enum and by clarifying that names resolve via player search. The only wrinkle is the schema's game enum/examples implying other games, but the explicit 'Tennis-only' statement compensates.

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 object: a multi-player tennis head-to-head grid showing each pair's series record. It names the adjacent sibling head_to_head and positions itself as the matrix form for N-player fields, so an agent can immediately distinguish it.

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 explicitly states when to use the tool (draw/field analysis, group-stage/semifinal comparisons), what to prefer it over (N head_to_head calls or raw call_api), and when not to use it (two-player deep-dive → head_to_head, stat leaders → leaderboard_*, rankings → standings). This is complete routing guidance.

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

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

Annotations already indicate read-only and non-destructive behavior; the description adds meaningful context: server-side filtering instead of a native endpoint, weaker Dota filters with meta.warnings, parallel-safety, and upstream cost. These go beyond the structured annotations and inform 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 well-structured with front-loaded purpose, clear usage sections, a caveat, and an example. Every sentence adds value, and the length is justified given the number of parameters, siblings, and the need to disambiguate from related tools.

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 rich input schema, annotations, output schema, and explicit routing to sibling tools, the description covers all essential context an agent needs. It includes limitations, parallel-safety, cost, and a concrete invocation example, so no critical operational gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's example clarifies expected slug-style values but adds no new semantic meaning beyond what the schema provides, 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 resource: a composed head-to-head record between two teams, UFC fighters, or tennis players. It also differentiates itself by noting that no first-class REST H2H exists and by explicitly routing single-side questions to team_profile or player_profile.

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 explicit when-to-use scenarios, a 'prefer over' instruction, and a direct 'do not use when' rule with named sibling alternatives. This leaves little ambiguity about when an agent should select this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, and non-destructive behavior. The description adds useful behavioral context beyond that: data is from 'real match-stats aggregates,' rows contain aces and matches played, results are ordered most aces first, and the tool is 'Parallel-safe: yes. Upstream cost: 1.' This goes beyond what the annotations alone convey, though it does not address potential staleness or result shape details, which the output schema covers.

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

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

The description is well-structured with labeled sections ('When to use', 'Prefer over', 'Do not use when') and compact sentences. Every line carries information: scope, defaults, exclusions, parallel-safety, and cost. There is no filler or repetition of schema content.

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 output schema exists, the description does not need to repeat return structure. It covers the tool's purpose, use cases, exclusions, defaults, ordering behavior, and execution safety. Nothing relevant to selecting or calling 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter guidance by clarifying that season defaults to 2026 and tour (ATP|WTA) is optional, explicitly instructing to omit it for the combined board. It also reinforces that division is a synonym for tour, matching the standings tool spelling, which helps disambiguate the two interchangeable parameters.

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 precise statement: 'Tennis season aces leaderboard: most aces served in a season, from real match-stats aggregates.' This names the resource (season aces leaderboard), the metric (aces served), and the domain (tennis), making the tool's purpose unambiguous and distinct from sibling leaderboard tools.

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 when-to-use guidance ('Who leads the tour in aces this season'), a preferred alternative ('Prefer over: raw leaderboard via call_api'), and clear exclusions with named alternatives: standings for ranking position, rankings_movers for week-over-week movement, and player_form for recent form. It also states 'Tennis-only' and explains optional tour behavior.

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 readOnlyHint, openWorldHint, and destructiveHint. The description adds useful context: 'Parallel-safe: yes', 'Upstream cost: 1', an eligibility threshold (50 break opportunities), and default season/tour behavior. The phrase 'read return-side' is ambiguous, and there is no mention of pagination or output size limits beyond schema defaults, so a 5 is not warranted.

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

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

The purpose is front-loaded and sections are clearly labeled, but the main sentence is duplicated verbatim in the When-to-use section. Some phrasing like 'read return-side' is awkward and the bullet 'season tables; clutch/serve-efficiency leader queries' adds little. It could be tightened without losing information.

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

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

Covers the eligibility threshold, tennis-only scope, optional tour, season default, and parallelism. The presence of an output schema relieves the need to document return values. Minor gaps remain: game selection guidance is left to the schema enum, and 'read return-side' is unclear. Overall, the definition provides enough for correct invocation.

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

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

The schema covers all 5 parameters at 100% with descriptions, examples, defaults, and an enum for game. The description adds the 'omit tour for the combined board' nuance and repeats the season default, but it does not materially expand on parameter meanings. 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?

States a specific metric (share of break opportunities converted) with a clear resource (tennis season leaderboard) and ordering (highest pct first). It is distinct from the sibling leaderboard_break_points_saved because it focuses on conversion rather than saves. The tennis-only scope and season default further pin down intent.

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 'When to use' section lists use cases and a 'Do not use when' section names specific sibling tools (standings, rankings_movers, player_form) with conditions. It even suggests preferring this over call_api for agent-normalized rows. An agent needs no inference to decide when to invoke 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 non-destructive behavior; the description adds valuable context: only players facing at least 50 break points qualify, season defaults to 2026, omitting tour yields the combined board, and it is parallel-safe with upstream cost 1. No contradiction 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?

Well organized with labeled sections, front-loaded key result, and minimal fluff. Slight deduction because the 'When to use' bullet repeats the opening definition almost verbatim.

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

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

An output schema exists, so the description need not explain return shape. It covers selection criteria, defaults, filtering threshold, parallel-safety, and routing to alternatives. Nothing essential is missing for a correct call.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine parameter meaning by restricting usage to tennis despite the schema's broader game enum and clarifying that omitting tour produces the combined board. Limit and season are already well documented 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?

States exactly what the tool returns: share of break points saved per player, from real match-stats aggregates, ordered highest percentage first. This clearly distinguishes it from siblings like leaderboard_break_conversion and leaderboard_aces.

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 'When to use', 'Prefer over', and 'Do not use when' sections with concrete alternative tools (standings, rankings_movers, player_form, call_api). An agent can confidently select or reject this tool without opening sibling schemas.

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 readOnlyHint=true annotation, the description discloses tennis-only scope, the 2026 default season, optional ATP/WTA tour behavior, the 20-match qualification threshold, parallel-safety, and upstream cost. This adds substantial behavioral context beyond what annotations alone would convey.

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 definition is front-loaded and well-sectored, but the first sentence is repeated almost verbatim in the 'When to use' bullet, adding minor redundancy. Overall it remains appropriately sized and scannable.

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 leaderboard tool with an output schema and 5 parameters, the description covers scope, defaults, routing, qualification criteria, and operational traits. Nothing critical is missing for an agent to select and 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%, so the baseline is 3. The description adds value by explaining cross-parameter behavior: tour is optional and omitting it yields the combined board, division is a synonym for tour, and the 20-match qualification threshold affects results. It does not deeply explain the game parameter, but the enum already bounds 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 opens with a specific, unambiguous definition: 'Share of matches won after losing the first set per player, from real first-set rows joined to completed matches, ordered highest pct first.' This names the exact metric, source rows, and ordering, clearly distinguishing it from sibling leaderboard_* tools.

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 'When to use', 'Prefer over', and 'Do not use when' sections, naming concrete alternatives such as standings, rankings_movers, and player_form for different intents. This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, covering safety. The description adds genuine behavioral context beyond that: 'Tennis-only', season default, tour optionality for a combined board, a minimum 10-decider qualification, parallel-safe status, and upstream cost. This helps an agent reason about cost and data filtering beyond the basic read-only profile.

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 essential definition, then organized into clear usage blocks (When to use, Do not use, defaults). It is slightly bloated by repeating the same 'Share of deciding sets...' phrasing in both the opener and the 'When to use' bullet, but overall every section earns its place and guidance is easy to scan.

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

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

For a read-only leaderboard tool with an output schema and strong annotations, the description covers all necessary context: game restriction, season default, tour behavior, minimum match qualification, throughput safety, and alternative tool routing. An agent has 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 description coverage is 100%, so the baseline is fair. The description doesn't add much beyond the schema: it repeats the season default and tour optional/combined-board behavior that already appear in parameter descriptions. The only extra is the minimum 10-decider threshold, which is not parameter-specific but a data filter. It doesn't materially de-risk parameter choice beyond the schema.

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

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

The description opens with a highly specific purpose: a tennis season leaderboard for share of deciding sets won, from real match rows, ordered by percentage. It distinguishes itself from sibling leaderboards like leaderboard_tiebreak_win_pct and leaderboard_break_points_saved by name and metric, so an agent can tell which leaderboard to pick without opening schemas.

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

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

The description provides a dedicated 'When to use' block, names an alternative ('raw leaderboard via call_api') and explicitly states 'Do not use when' with concrete alternative mappings (standings, rankings_movers, player_form). This is exactly the kind of when/when-not/exclusion guidance the dimension asks for.

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/open-world/non-destructive behavior; the description adds meaningful extras beyond them: that only players contesting at least 3 finals qualify, that data comes from real completed finals rows, that it is parallel-safe, and that upstream cost is 1. No contradiction 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?

The key metric is front-loaded, and the bulleted When/Prefer/Do-not-use structure is easy to parse. However, the first bullet under 'When to use' repeats almost verbatim the opening sentence, adding minor redundancy in an otherwise efficient description.

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

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

Given schema coverage, output schema, and annotations, the description is complete enough for effective selection and invocation: it covers qualifying threshold, optional tour behavior, season default, ordering, parallel-safety, and routing. There is no missing information that would cause an agent to call this tool incorrectly.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter detail in the description. The description restates a few defaults (season 2026, optional tour, omitted for combined board) that are already present in the schema, but it does not add meaningfully beyond the schema for parameter usage.

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 opening sentence names a specific resource ('finals-record leaderboard'), a specific metric ('share of finals won per player'), a data scope ('real completed finals rows'), and an ordering ('highest pct first'). This clearly distinguishes it from sibling leaderboard_* tools that focus on aces, tiebreak win percentage, or break conversion.

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 ('share of finals won... clutch/serve-efficiency leader queries'), when to prefer a different tool ('prefer over call_api'), and provides a 'Do not use when' section mapping concrete alternatives such as standings, rankings_movers, and player_form. This is unambiguous routing guidance.

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

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

The description adds materially beyond the readOnly/openWorld/destructive annotations: it states data is from real match-stats aggregates, enforces a 300-first-serve qualification threshold, clarifies season default and tour-omission behavior, and declares parallel-safety and upstream cost. 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 definition is well-structured with clear labeled sections and front-loaded content. It loses a point because the opening line and the first 'When to use' bullet repeat the exact same sentence verbatim, adding unnecessary 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 rich input schema, output schema, and annotations, the description still supplies the essential call-time context: defaults, optional parameter behavior, qualification threshold, and routing to sibling tools. Nothing an agent needs to decide whether and how to call 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 coverage is 100%, so the schema already documents all parameters. The description still adds value by clarifying the combined-board behavior when tour/division is omitted, the Tennis-only scope, and the 300-first-serve qualification floor tied to the underlying data, going beyond the bare parameter names.

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 (tennis season first-serve-won leaderboard), the metric (share of first-serve points won per player), the data source (real match-stats aggregates), and the ordering (highest pct first). This clearly distinguishes it from the many other leaderboard_* siblings.

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

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

It has an explicit 'When to use' section, a 'Prefer over' statement routing away from raw call_api, and a 'Do not use when' list with named alternatives (standings, rankings_movers, player_form). The agent receives concrete selection criteria with zero inference required.

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 read-only/non-destructive, and the description adds meaningful behavior: data comes from real match-stats aggregates, results are ordered, season defaults to 2026, players must have at least 100 return games played, and parallel-safety/upstream cost are disclosed. This goes well beyond the annotations without contradicting them.

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

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

The description is well-sectioned and mostly efficient, but it repeats the near-identical opener inside the 'When to use' bullet, which wastes space. The phrase 'season tables; clutch/serve-efficiency leader queries' is also awkwardly terse and could confuse rather than guide.

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 leaderboard tool with a rich output schema, the description covers the metric, sort order, defaults, tour behavior, eligibility threshold, alternatives, and safety/cost characteristics. Nothing critical is missing for an agent to call it correctly; even the required game parameter is inferable from 'Tennis-only' and the tool name.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by restricting the tool to tennis despite the broad game enum, explaining that tour is optional and omitting it yields the combined board, and noting the minimum qualifying threshold. It does not need to restate defaults already present in the schema, but the game constraint is a useful clarification.

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 and metric: a tennis return-games-won leaderboard measuring share of return games won (breaks over opponent service games played), sorted by highest percentage first. This precisely distinguishes it from sibling leaderboards and makes the tool's purpose immediately actionable.

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 explicit when-to-use guidance ('season tables; clutch/serve-efficiency leader queries'), explicitly prefers this tool over raw call_api, and lists 'do not use when' cases with concrete sibling alternatives (standings, rankings_movers, player_form). An agent can select the correct tool with minimal 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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses that it is parallel-safe and the upstream cost is 1. It also adds specifics like the minimum 10 tiebreaks to qualify and the default season (2026). These are useful context not covered by 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 well-structured and front-loaded with the core purpose, followed by usage conditions, exclusions, and constraints. Every sentence adds value: the do-not-use section preempts misrouting, and the qualification rule is concise.

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 that the tool has an output schema (not shown) and annotations covering safety, the description is nearly complete. It covers usage, exclusions, defaults, and a qualification rule. Minor gap: it does not specify the return format or pagination beyond 'limit', but with an output schema, that is acceptable.

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

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

The schema has 100% coverage, so the baseline is 3. The description adds key semantics: the 'tour' parameter is optional and maps to the combined board when omitted, and the 'division' parameter is a synonym for tour, clarifying its usage. It also confirms 'game' is tennis-only, which is not fully explicit in the enum 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 clearly states the tool computes the share of classic 7-point tiebreaks won per player for tennis, ordered by highest percentage. It includes a specific verb ('share'), resource ('tiebreak-win-pct leaderboard'), and scope, with an example output context. It also mentions real match-set aggregatesaving for clarity.

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 lists when to use (clutch/serve-efficiency leader queries), what to prefer over (raw leaderboard via call_api), and do-not-use cases for related rankings (standings with game tennis, rankings_movers, player_form). It also specifies tennis-only and the season/tour defaults.

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 readOnlyHint, openWorldHint, and destructiveHint. The description adds useful behavioral context: the result is a curated catalog (not a raw API dump), it is parallel-safe, and it has zero upstream cost. This goes beyond the structured annotations without contradicting them.

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

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

The description is scannable and front-loads the purpose. Every section earns its place: use cases, exclusions, parallel-safety, upstream cost, and a concrete example. No fluff 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?

The description fully covers when to use, when not to use, safety behavior, upstream cost, and gives an example call. With an output schema present, the agent has everything it needs to decide whether and how to 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?

The input schema has 100% coverage with descriptions for each parameter, so the baseline is 3. The description adds an example payload and a shorthand list of job filters, which clarifies how to combine game/job/includeExamples in practice.

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 defines the resource: the curated catalog of cito-mcp tools, games, jobs, and builder recipes. It is clearly distinct from data-lookup siblings like live_matches or match_details, and it explicitly contrasts itself with call_api for discovery use.

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 'When to use', 'Prefer over', and 'Do not use when' sections. This gives an agent concrete routing rules, including the exclusion case where direct tool calls should win.

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 carry readOnlyHint=true and destructiveHint=false; the description adds a meaningful caveat about the /lol spec omission and that filtering by game=lol returns a caveat rather than an empty list. It also states 'Parallel-safe: yes. Upstream cost: 1.' No contradiction 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?

Front-loaded with a one-line purpose, then compact sections for when-to-use, caveats, and example. Every sentence carries useful signal and no padding.

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 safety, the description supplies usage boundaries, a known edge case, operational semantics (parallel-safe, upstream cost), and an example. Nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a concrete example combining game and q, and warns about game=lol's special behavior, giving the agent more than the raw schema provides.

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: 'Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.' It also differentiates from list_capabilities by calling it 'the escape hatch' and clarifying it is 'not a replacement for list_capabilities', so an agent can distinguish it from siblings.

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

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

Provides an explicit 'When to use' list covering concrete needs (long-tail path for call_api, checking endpoint existence, mapping raw data) and a 'Do not use when' clause directing to list_capabilities when a curated tool covers the outcome. The alternative is named directly.

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

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

Beyond the readOnly/openWorld/destructive annotations, the description discloses important behavioral details: parallel-safety, upstream cost range, CS2 live path, UFC empty-board handling including health fields and a warning never to fabricate match items from events[]. This is exactly the kind of operational nuance an agent needs.

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

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

The description is well-structured with clear sections: a one-line purpose, when-to-use, when-not-to-use, per-game edge cases, and performance notes. It is front-loaded with the core behavior and every section earns its place without unnecessary padding.

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 live-matches tool with 3 optional parameters and rich annotations, the description is complete: it covers alternatives, edge cases (UFC empty board), performance characteristics, and example usage. The presence of an output schema means return-value documentation is not required here, so nothing important 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 input schema already covers all parameters fully (100% schema description coverage), so the baseline is 3. The description adds value with a concrete usage example ({ "game": "all", "limitPerGame": 10 }), clarifies the single-game filter concept, and reinforces batching behavior via limitPerGame, slightly exceeding 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 states the tool provides a live matches board across primary games or a filtered single game, with normalized labels, scores, and matchIds. It explicitly distinguishes itself from upcoming_schedule, match_summary, and per-game call_api probes, so an agent can clearly understand what this tool is for.

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 explicit when-to-use scenarios ('What's live right now?', ops/dashboard live strip), names a preferred alternative path (avoid sequential call_api probes), and provides do-not-use guidance with direct sibling alternatives (upcoming_schedule, match_summary). This leaves minimal ambiguity about 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 cover the safety profile (readOnly, openWorld, non-destructive), and the description adds genuinely new behavioral context: parallel-safety, a section-gated upstream cost of 1–8, precedence rules for sections[] vs booleans, the LoL gameId precondition, and odds-specific caveats (closing lines returning currentlyOffered=false, NOT_IMPLEMENTED for non-UFC). This is well beyond what structured fields 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?

Front-loaded with the one-line purpose, then bulleted when/when-not, section mechanics, and a concrete example call. Dense with no filler; the only mild redundancy is the paired match_summary preference lines, which earn their place as a routing rule.

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

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

For a 7-parameter, multi-section tool with an existing output schema, the description supplies everything an agent needs: purpose, alternatives, section-selection mechanics, precedence, per-game constraints, cost, and an example invocation. Return-value explanation is correctly omitted given the output schema.

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

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

Schema coverage is already 100%, but the description adds precedence semantics absent from the schema — a non-empty sections[] overrides the booleans — plus the per-game conditional requirement that LoL liveState/advanced need gameId. It clarifies parameter interaction rather than restating field names.

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 line names a specific verb-and-resource (deep match package) and enumerates its contents (timelines, advanced stats, live state/snapshots, map/game tree, media inventory). It explicitly frames itself relative to the sibling match_summary, so an agent can distinguish the two without opening schemas.

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

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

Provides explicit when-to-use scenarios (analyst deep dive, live in-game window, full demo list), explicit when-not (first-pass live board → live_matches + match_summary), and names the preferred alternative for short answers. Routing decision is fully determined.

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 declare readOnlyHint=true and destructiveHint=false, and the description adds 'Parallel-safe: yes' and 'Upstream cost: 4–8', which are behavioral traits not in annotations. It also notes the optional surface filter is ignored for non-tennis games, matching the schema, without contradiction.

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 well-structured with clear sections: an opening definition, explicit 'When to use' and 'Do not use' lists, a 'Prefer over' statement, and behavioral notes. Every line adds distinct value, and the key information is front-loaded. Space is used efficiently.

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 (9 params, output schema present) and rich annotations/schema, the description covers all necessary aspects: when to use, what it returns, key parameter relationships, and alternatives. The output schema presumably handles return details, so nothing critical 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 already documents all 9 parameters, but the description adds valuable semantic context: the composite behavior, the matchId OR (teamA+teamB) relationship, the tennis-specific surface filter, and the parallel-safe/cost context. The example JSON also demonstrates the intended parameter usage, which exceeds 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 the composite pre-match briefing purpose, lists the content components (sides, roster/form snippets, H2H stub, event context), and explicitly names the intended use cases (pick'ems, articles, match-page). It distinguishes from siblings like match_summary and match_details by specifying when those are preferred.

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 'When to use' and 'Do not use when' conditions with concrete examples like deep links and 'Who should I watch'. It names alternatives (match_summary, match_details) and when to prefer each, plus warns against chaining multiple tools manually, making the routing decision clear.

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 as read-only and non-destructive, and the description adds non-obvious behavior: 'Parallel-safe: yes', 'Upstream cost: 2–5', and data availability caveats like 'when available'. This goes beyond the annotations, though it does not detail error cases or rate limiting.

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 well-structured with a one-line summary, bulleted usage guidance, routing notes, negative cases, and a compact example. Every section earns its place, and the most important information is front-loaded.

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

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

Given the rich input schema, existing output schema, read-only annotations, and clear sibling differentiation, the description covers what an agent needs to call the tool correctly. It also includes parallel-safety and upstream cost context, making it complete for this level of 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 coverage is 100%, so the schema fully documents all five parameters. The description adds a concrete usage example and links concepts like 'player performances' and 'VOD/demo links' to the relevant parameters, but it does not add substantial meaning beyond the schema's own parameter descriptions.

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

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

The description uses a specific opening phrase, 'COMPOSITE match card', and enumerates the delivered content: scoreline, key context, player performances, and VOD/demo links. It explicitly distinguishes this tool from match_details and match_preview, so an agent can easily tell what this tool is for.

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 a dedicated 'When to use' section, explicit routing guidance ('Prefer over match_details'), and clear negative cases such as 'no matchId yet' and 'pure pre-match → match_preview'. This leaves no ambiguity about when to call this tool versus its siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered. The description adds valuable context: row ordering (newest-first), default limit matches API (10, max 50), parallel-safety, and upstream cost. This goes beyond annotations, though it could specify what output format includes, but output schema exists.

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

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

Well-structured with clear sections: description, when-to-use, do-not-use, and technical notes. Front-loaded with the core purpose, then usage guidance. Every sentence earns its place; no 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 moderate complexity (4 params), the presence of an output schema, and annotations covering read-only safety, the description is complete. It covers usage context, exclusions, ordering, limits, and parallel-safety, leaving no critical gaps for correct invocation.

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

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

Schema description coverage is 100%, so all parameters are documented. The description adds context for the surface filter (e.g., clay last 5) and confirms limit semantics, but does not add significant new meaning beyond schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows'), distinguishing from siblings like player_profile by naming the unique output (streak, surface-specific). The purpose is clear and differentiated.

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 when-to-use examples ('How is X playing lately?'), prefers this tool over player_profile for streak queries, and explicitly states when NOT to use it (career totals, ranking deltas). Names alternatives (player_profile, rankings_movers) and conditions for switching.

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/destructiveHint=false, so safety is covered. The description adds genuinely non-structured traits: rows arrive newest-first, tennis-only scope, parallel-safe, and upstream cost of 1. It does not add much beyond the schema on limit/ordering, which is why it stops short of 5.

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

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

Front-loaded with the core statement, then cleanly grouped into when-to-use / prefer-over / do-not-use blocks. Minor waste: newest-first and the limit default/max are stated twice (opening sentence plus 'Limit defaults to 20 (max 50)', both echoed in the schema).

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

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

An output schema exists, so return shape needn't be explained. Given 5 params at full coverage plus annotations, the description covers routing, scope, ordering, limits and cost – nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates surface values (Hard/Clay/Grass) and 'tournamentId pins one event', which largely duplicates existing schema descriptions rather than adding format, id-resolution or edge-case guidance.

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 ('match log: every archived match for one player') and immediately scopes it (newest first, opponent/tournament/round/surface/score). Sibling names player_form and call_api are contrasted directly, so an agent can discriminate without opening either schema.

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

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

Explicitly provides when-to-use examples ('Show me Shelton's last 20 matches', tournament history, surface filtering), a 'Prefer over' routing rule against player_form and call_api, and a 'Do not use when' list routing aggregate/identity/box-score needs to player_stats, player_profile and match_details.

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, open-world, and non-destructive behavior. The description adds useful context beyond that: data may be unavailable ('when available'), parallel safety is guaranteed, and upstream cost is 2–5. This does not contradict 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 well-structured: core purpose first, then compact labeled sections for usage, exclusions, operational notes, and an example. No sentence is wasted, and the example is concise while illustrating key parameters.

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 output schema exists, return-value details are not needed. The description covers purpose, usage, alternatives, exclusions, parallel safety, cost, and a representative call, making it complete for this 8-parameter read-only tool.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds a concrete example JSON but doesn't materially enrich parameter meaning beyond what the schema provides, 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 identifies the resource as a player or UFC fighter profile and enumerates the content: identity, current team, recent matches, and form/trends/radar. It also distinguishes itself from related sibling tools like team_profile and resolve_entity, so an agent can tell them apart.

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 when-to-use examples, a 'Prefer over' note for call_api, and a 'Do not use when' section naming team_profile and resolve_entity. This gives an agent complete routing guidance with no ambiguity.

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

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

Beyond the readOnly/openWorld annotations, the description discloses real behavioral traits: tennis-only scope, chronological oldest-first ordering, the fact that the upstream route ignores ?limit= so the bound is applied locally, the window-metadata fields (hasMore, oldestReturned/newestReturned, omittedOlder), and parallel-safety/cost. None of this is derivable from annotations or schema.

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 one-line purpose followed by clearly labeled When/Prefer/Do-not-use blocks and a trailing operational note. Long but every sentence carries information an agent needs; nothing is redundant padding.

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

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

Despite an output schema existing, the description still explains the returned window semantics (hasMore, oldestReturned/newestReturned, omittedOlder) and ordering, plus cost and safety. For a 4-param read tool with a required enum and player id, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds genuinely non-obvious semantics for limit: it keeps the most RECENT N rows even though rows are returned oldest-first, and the upstream route ignores ?limit=. That is meaning beyond the schema's 'Max history rows'. The game/since parameters get no extra description, keeping it from a 5.

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: 'Tennis player ranking trajectory: every published ranking date for one player, plus career-high and weeks at No.1.' It also explicitly names the sibling tools it is not (standings, rankings_movers, player_profile), so an agent can disambiguate 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?

Provides explicit 'When to use' with concrete example phrasings, a 'Prefer over' clause naming three alternatives with the reason each is inferior, and a 'Do not use when' routing the current top-N case to standings. This is about as complete as usage guidance gets.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds value beyond that: it declares the tool is tennis-only (despite the game enum offering six titles), states the upstream cost of 1, and enumerates the valid filter values. It stops short of describing result shape or any rate/limit behavior, but the output schema covers returns.

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 resource and its outputs, then structured into clearly labeled use/prefer/avoid sections, with a compact trailing line for the tennis-only constraint and cost. Slightly verbose with repeated filter enumerations, but every block carries routing or constraint information.

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

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

For a read-only aggregate tool with a full output schema and 100% parameter coverage, the description supplies everything an agent needs: what it returns, when to choose it, which siblings to prefer, the tennis-only scope, and the cost. No material gap remains.

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 every parameter is already documented, including the surface enum and yearFrom/yearTo bounds. The description restates the same filter set (surface Hard/Clay/Grass/Carpet, yearFrom/yearTo) without adding format or semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (tennis player career statistics) and enumerates exactly what aggregates are returned: W/L, win%, titles, Grand Slam/Masters titles, per-surface and per-level breakdowns. It also explicitly names the sibling tools it is not (player_profile, player_matches), so an agent can distinguish it without opening another 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?

Contains explicit 'When to use' examples, a 'Prefer over' section naming player_profile and player_matches with the reason each differs, and a 'Do not use when' section routing the match log to player_matches and ranking-over-time to player_rankings_history. 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 cover the safety profile (readOnly, non-destructive, openWorld), but the description adds unique operational context: parallel-safe, upstream cost of 1, the API's handling of zero-diff cloned lists, and the caveat that the two lists are not always one week apart with a warning above a ten-day gap. That is exactly the kind of behavioral detail annotations cannot carry.

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 one-line summary followed by labeled sections (When to use / Prefer over / Do not use when) and a short caveat block. Bullets and headers keep it scannable and every sentence carries routing or behavioral information.

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

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

An output schema exists so return values need no explanation, annotations carry the safety profile, and the description covers routing, direction semantics, date resolution, and the week-gap pitfall. An agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: 'both' means largest absolute change, 'up' is the default, date pins an older list and the default latest resolves past zero-diff clones, and it cross-references division as the standings-tool spelling of tour. Only 'within' and gapDays/comparisonWindow output fields go unelaborated.

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+scope: 'biggest climbers/fallers between the latest ATP/WTA list and its predecessor, plus new entries and drop-outs.' It explicitly names the siblings it is not (standings, call_api, player_profile), so an agent can distinguish it 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?

Gives explicit 'When to use', 'Prefer over' with the reason each alternative is worse (standings = snapshot with no delta; call_api = raw unnormalized rows), and 'Do not use when' routing to standings and player_profile. 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 convey readOnlyHint, openWorldHint, and destructiveHint, and the description adds substantial behavioral context: empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true, no hard AMBIGUOUS_ENTITY error, parallel-safety, and upstream cost. This goes well beyond what annotations alone 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 well-structured with a front-loaded summary, clear use-case sections, an example, and no filler. Every sentence contributes either scoping, alternative selection, edge-case behavior, or operational cost information.

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

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

For a fuzzy-resolution tool with output schema available, the description covers the full decision context: when to use, when not to use, how it differs from the closest sibling, behavior on ambiguous results, cost, parallelism, and an example. Nothing an agent needs to invoke it correctly is missing.

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

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

Input schema coverage is 100%, so the schema already fully documents q, game, type, and limit with enums, defaults, and examples. The description adds practical selection guidance ('small ranked set to chain', 'pick from candidates or refine q/game/type') and a concrete example call, which elevates it above the baseline without needing to compensate for schema gaps.

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 immediately defines the tool's specific purpose: 'Natural-language / fuzzy query → best typed entity ID(s) + game', listing entity types. It explicitly distinguishes itself from the sibling search_entities by describing when each should be used, so an agent can reliably tell them apart.

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 explicit when-to-use scenarios ('User named an entity without an ID', 'Need a canonical id/slug before profile or match tools'), a direct contrast with search_entities ('Prefer over search_entities when you want one best match... Prefer search_entities when browsing many results'), and a clear exclusion ('Do not use when you already have a stable id/slug').

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=true, openWorldHint=true, destructiveHint=false), the description discloses UFC-specific ranking behavior, client-side re-ranking, the guarantee that 'Jon Jones' returns jon-jones first, parallel-safety, and upstream cost. This gives the agent behavioral expectations well beyond what annotations provide.

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

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

The description is organized into clear sections — purpose, when to use, when not to use, special behavior, and an example. Despite its length, every section earns its place and no information is redundant 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 six parameters, multiple sibling tools, and an output schema that already documents return shape, the description covers all necessary context: use cases, exclusions, alternative selection, ranking behavior, parallel-safety, cost, and a representative call example. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the q parameter's ranking semantics for UFC, providing a concrete example object, and clarifying that type filters and pagination are core behaviors rather than just 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 opens with a specific verb-resource pair: 'Browse/search teams, players, tournaments, events, fighters with type filter and pagination.' It then differentiates itself from resolve_entity, team_profile, and player_profile, so an agent can immediately tell what this tool is for and what it is not.

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?

Usage guidance is explicit and concrete: typeahead/pickers, list requests, entity exploration, and UFC fighter lookup. It also names the preferred alternative for the opposite case ('Prefer resolve_entity when chaining one name into a profile tool') and states a negative rule with the correct sibling tool to use instead.

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 (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds real behavioral context: parallel-safe flag, upstream cost of 1-2, the per-game scope-key requirement table, and the notable caveat that Dota may return NOT_IMPLEMENTED or a weak worldRanking. It does not discuss rate limits or error shapes, keeping it short of a 5.

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

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

Front-loaded one-line definition followed by labeled bullet groups and a concrete example call; no sentence is filler, and the routing constraints (prefer/do-not-use) appear before the parameter detail so an agent can bail out early.

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

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

For an 11-parameter, multi-game tool with an output schema already documenting return shape, the description supplies everything else needed: game-specific scope rules, pagination strategy, cost/parallelism, and the known Dota limitation. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description meaningfully augments it by mapping each game to the scope keys it requires (lol needs leagueId or tournamentId, cs2 omits for world vs eventId for events, tennis defaults to ATP) and by prescribing cursor paging over raising limit for UFC world scope. That is genuine semantic value beyond the schema.

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

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

States a specific resource ('league/event standings or world/division rankings normalized to ranked rows') with a clear verb-like outcome, and enumerates the concrete domains it covers (UFC rankings, CS2 world/event, CDL, LoL tables). An agent can distinguish it from sibling leaderboards and rankings_movers without opening any schema.

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

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

Explicitly enumerates when to use, names the preferred alternative ('raw standings via call_api'), and gives two named do-not-use routes with their alternatives (team_profile for single team form, live_matches for live scores). This is a full routing decision tree.

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

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

Beyond the read-only and open-world annotations, the description discloses parallel-safety, upstream cost of 2–4, the Dota partial-roster API gap, and the fact that form/trends/radar are only returned 'when available.' No contradiction with annotations exists.

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

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

Every line earns its place: concise summary, direct usage conditions, clear exclusions, known caveat, cost hint, and a concrete example. The structure front-loads the core purpose and then layers decision-relevant guidance.

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 six-parameter tool, the description covers when to use, when not to use, parameter preferences, API limitations, cost, concurrency safety, and includes an example. Combined with the output schema and rich parameter descriptions, 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?

Although schema coverage is already 100%, the description adds valuable selection guidance: prefer slug for lol/cod, teamId for cs2, and note that at least one of teamId/slug is required. The example payload further clarifies how parameters combine.

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

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

The description opens with a specific resource and content list: 'Team/org card: identity, roster, recent matches, and form/trends/radar when available.' It also explicitly distinguishes itself from player_profile and call_api, so an agent can tell exactly what this tool covers relative to siblings.

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

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

Provides explicit 'When to use' and 'Do not use when' sections, including routing to player_profile for UFC fighters and resolve_entity for unknown names. It also names call_api as an alternative to prefer this tool over, giving clear decision criteria.

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?

Goes well beyond the readOnly/openWorld annotations: discloses that the two halves are fetched in parallel and can fail independently, that 'limit' is enforced locally because the upstream completed route ignores ?limit=, and that the two halves overlap so the same matchId can appear twice. It also states parallel-safety and upstream cost (1 or 2 calls).

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

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

Front-loaded one-line summary followed by clearly labelled when-to-use / prefer-over / do-not-use sections and then behavioral notes. Dense but every clause carries operational information; slightly long, and the overlap warning could sit closer to the limit discussion.

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

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

With an output schema present the description need not explain returns, yet it still documents scheduledCount/completedCount semantics and the duplicate-matchId hazard, plus failure independence and cost. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'date' MUST be YYYY-MM-DD and defaults to today (UTC), 'limit' bounds EACH half while counts still report the full day, and 'include' selects the halves. The only gap is that the required 'game' parameter is never named — 'Tennis-only' implies the value but does not say 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?

States a specific verb+resource+scope: 'One day of tennis: the day's schedule and/or the matches completed that day, across ATP and WTA.' An agent can immediately distinguish this from upcoming_schedule, live_matches, and player_matches 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?

Explicit 'When to use', 'Prefer over' naming call_api routes and the specific query-param reason (?date=), plus 'Do not use when' routing to live_matches and player_matches. Both the positive and negative conditions are enumerated.

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

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

Beyond the read-only/non-destructive/open-world annotations, the description discloses non-obvious behaviors: a level name starting with ATP/WTA fixes the tour and contradicting tour= arguments are rejected, and the source cannot separate ATP 500 from ATP 250. It also reports parallel-safety and upstream cost, which no annotation conveys.

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 one-line purpose followed by clearly labeled When-to-use, Prefer-over, and Do-not-use sections, so it is scannable. Slightly longer than necessary, with the level examples repeated ("WTA 1000" appears in both the usage and semantics blocks).

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?

Output schema already documents the return shape and annotations cover the safety profile, so the description is free to focus on selection guidance, which it does thoroughly, including domain caveats an agent could not infer from the schema 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?

Schema coverage is 100%, so the structured fields are already documented and baseline is 3. The description earns above baseline by explaining semantics the schema does not: that level accepts names or raw tier codes (G/M/A/C/D), and the level/tour interaction rule that would otherwise be invisible.

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 ("Tennis tournament catalog: find tournaments") plus the exact filterable dimensions, and explicitly distinguishes itself from siblings event_card and call_api. An agent can tell instantly what this returns versus the bracket/edition tool.

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 concrete when-to-use example queries, names the alternatives (event_card, call_api) with the condition that selects them ("when you do NOT already have a tournament id"), and adds an explicit do-not-use section redirecting bracket and calendar needs to event_card. This is the full when/when-not/alternative triad.

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 and non-destructive, and the description adds substantial behavioral context beyond that: unsupported params are silently ignored with meta.warnings, per-game filter application varies, 'hours not applied upstream' for cs2, client-side filtering for dota2/ufc, parallel safety, and upstream cost. These are critical operational details not derivable from the schema or 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 longer than average but every section earns its place: purpose, usage context, exclusions, per-game filter caveats, parallel safety, cost, and an example. The bulleted structure keeps it scannable and the critical filter caveat is front-loaded before the per-game breakdown.

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 multi-game tool with 9 parameters, varying filter support, and an output schema available, this description is complete. It covers what the tool returns conceptually, when to use it, when not to, per-game filter limitations, ignored-parameter behavior, and performance characteristics. Return-value details are appropriately left to the output schema.

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

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

Although schema coverage is 100%, the description adds meaning the schema cannot convey: which parameters are actually honored per game, which are ignored, and which are applied client-side rather than upstream. The worked example '{"game": "lol", "hours": 72, "team": "t1", "limit": 20}' further clarifies intended usage.

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: 'Upcoming matches/events for one game, with game-specific filters.' It immediately differentiates from the sibling 'live_matches' by stating 'Prefer over: live_matches for not-yet-started fixtures,' so an agent can tell which tool matches the requested state.

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?

Usage guidance is explicit: 'When to use' bullets cover calendar UI and team next-match queries, and 'Do not use when: only in-progress matches needed → live_matches' provides a direct exclusion and alternative. This is exactly the kind of when-versus-sibling guidance an agent needs.

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