AcesAPI

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

The annotations already establish this is a safe, read-only, idempotent call. The description adds genuinely non-obvious behavior beyond those annotations: walkovers are listed but not counted as wins, incomplete records are excluded, and the call costs 3 credits. These are operational details an agent could not infer from structured fields.

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

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

The description is front-loaded with the use case and packs useful quirks into a compact block. However, the long enumeration of return fields duplicates the output schema, and the tour/league sentence is denser and more confusing than necessary.

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 and rich annotations already present, the description mainly needs to cover counting quirks and endpoint routing, which it does. It still leaves some ambiguity around how the 'tour' wording maps to the schema's league parameter and does not mention that player IDs can come from search_players.

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 does add a useful note to pass league: "wta" for WTA on the shared endpoint, but it frames the choice as 'Tour: atp (default) or wta' while the schema's league parameter defaults to 'tennis' and uses a different enum, creating terminology drift rather than clear added meaning.

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 two-player resource and enumerates the distinct contents of the report: wins each, sets won, surface and finals splits, and every meeting with score. This clearly separates it from siblings such as get_player_stats or get_match, so an agent can identify the head-to-head tool immediately.

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

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

The opening phrase 'Use for two players' head to head' gives a clear selection condition, and the note about passing league: "wta" on the shared endpoint helps with endpoint choice. However, it does not name alternatives or state when not to use this tool, so it falls short of explicit routing guidance.

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

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

Adds substantial context beyond the annotations: a concrete cost of 2 credits, an explicit data-availability caveat ("No serve statistics: they are not available"), the coverage scope for moneylines, and the meaning of captured_at. It also states a policy constraint about never computing stakes, payouts, or recommending bets, which an agent cannot infer from readOnly/idempotent hints alone.

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

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

Front-loaded correctly, but the middle is one sprawling sentence that itemizes return fields which an existing output schema already defines, so a chunk of the text does not earn its place. The genuinely load-bearing parts (cost, missing serve stats, market-information policy) are buried inside that enumeration.

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, effectively single-lookup tool this covers everything an agent needs: cost, the ID source, the WTA routing rule, what is deliberately absent (serve stats), when price data will be missing, and a guardrail on how the retrieved prices may be used. The output schema handles return-shape details, 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?

Schema coverage is 100%, so the schema already documents both parameters, and the description's match_id guidance merely echoes schema hints. The league/tour guidance does add routing value ("on the shared endpoint pass league: 'wta' for the WTA"), but it introduces a naming mismatch by calling it "Tour: atp (default) or wta" while the schema enum is tennis|wta with a default of tennis — so it clarifies and muddies in equal measure.

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

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

Opens with a specific verb-plus-resource framing ("Use for everything about one match") and immediately enumerates the exact payload: score by set with tiebreak points, seeds, per-player sets/games/tiebreaks, ratings before and after, and moneylines. An agent can distinguish this from get_matches/get_player_matches purely from the word "one match" versus those list-oriented 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?

"Use for everything about one match" gives a clear positive selection rule, and the note that moneylines exist "mostly Grand Slam, ATP Masters and WTA 1000 matches" tells the agent when the price data will be absent. There is no explicit exclusion naming a sibling (e.g. "use get_head_to_head instead for X"), which keeps it short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety needs no restating; the description instead adds the non-obvious cost signal ('Costs 2 credits') and the endpoint-dependent league quirk, which an agent cannot get from annotations. Returned content (players, seeds, score, sets with tiebreak points) is also disclosed, though pagination behavior is left to the 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-loads the purpose, then the required identifiers, then filters, then the cost note — a sensible ordering with little filler. The tour/league sentence is the one dense, slightly ambiguous spot, but the description is not bloated.

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 brief field listing is sufficient rather than redundant. With annotations covering the safety profile and the schema covering pagination bounds, the description supplies the only pieces an agent needs on top of them: which scoping keys count, the date format, and the credit cost.

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

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

Schema coverage is 75%; the description adds genuine value by resolving the semantics of the format-sensitive fields — date is UTC, round takes values like "Final", status is a filter, and league must be "wta" when hitting the shared endpoint. It does not cover limit/offset defaults or max limits, which the schema handles. Minor friction: it mentions a 'tour' concept (atp/wta) that does not map cleanly onto the enum-constrained 'league' parameter.

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

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

Opens with a specific verb+resource ('match results by day, tournament or season') and enumerates the returned fields, so the agent knows exactly what it retrieves. It never names a sibling such as get_match (single match) or get_player_matches, so differentiation must be inferred from the 'by day/tournament/season' scoping.

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 calling patterns: 'Pass a date (YYYY-MM-DD, UTC), a tournament_id or a season' plus optional round/status filters. It does not state when to prefer this over get_player_matches or get_match, and the 'Tour: atp (default) or wta; on the shared endpoint pass league: "wta"' sentence is somewhat cryptic about which endpoint you are on.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so much of the safety profile is free. The description's genuine addition is the cost disclosure ('5 credits'), which is real, actionable context beyond structured fields. It still omits anything about payload size or latency, which matters for a tool returning bio, rankings, ratings, career records, and 10 matches in one response.

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-loading is good — the purpose statement comes first and the cost last. But the middle is a semicolon-chained inventory of return fields that duplicates what the output schema already conveys, and the tour/league sentences are ambiguous enough to require a second read. It is dense rather than tight.

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 needn't explain return shape, and the credit cost plus the player_id/league guidance cover the practical call requirements. The remaining gap is sibling positioning against get_player_stats, get_ratings, and get_surface_splits, whose outputs this tool appears to bundle. That omission is the main thing an agent would still have to guess.

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%, both parameters are documented, and player_id's provenance ('from search_players') is already in the schema, so baseline is 3. The description's tour/league paragraph actually reduces clarity: it describes an 'atp (default) or wta' tour concept, then instructs passing league: "wta" on a shared endpoint, while the schema enum is tennis/wta defaulting to tennis — an agent has to reconcile 'atp' with 'tennis' on its own.

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

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

The description opens with a specific verb-plus-resource framing ('Use for a player profile') and then enumerates exactly what is returned: bio, latest ranking, ratings per surface with peak, career records, titles, and last 10 matches. That is far more concrete than the title 'Player'. It does not, however, distinguish this aggregate profile from overlapping siblings like get_player_stats, get_ratings, or get_surface_splits, so the agent can't tell from the text alone whether those are subsets or complements.

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

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

'Use for a player profile' gives an implied trigger, and 'Costs 5 credits' hints this is the heavier, broader call. But there is no explicit when-not, no mention of which sibling to prefer for just stats or just ratings, and the tour/league note reads as a usage instruction yet conflicts with the schema's enum. Usage is inferable, not stated.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds genuinely new behavioral facts: results are ordered newest-first, there is a 5-credit cost, and default tour is atp. That is meaningful context beyond the structured fields, though it says nothing about pagination or result-size limits.

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

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

Three dense sentences: purpose and returned fields first, then filters, then tour/league and cost. Every clause carries information and nothing is repeated from the schema 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?

Output schema exists and the description still summarizes payload shape, and it covers cost and tour defaults. The gap is the undocumented pagination behavior and the unresolved tour-vs-league naming, which leaves the agent with a slightly ambiguous call signature.

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 67% and the description does explain filters in natural terms (season, surface, opponent_id, tournament_id, draw) and clarifies the league='wta' case. However it introduces a 'tour: atp (default) or wta' option that does not exist in the schema (only 'league' does), which risks an agent passing an invalid parameter, and it never mentions limit/offset.

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

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

Opens with a specific verb/resource ('a player's matches') and enumerates the returned fields (tournament, surface, round, opponent, result, score by set, rating before/after), which makes it distinguishable from get_matches and get_head_to_head. It never explicitly names a sibling though, so the agent must infer the distinction from the player-scoping.

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

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

Gives clear context for use (per-player match history, newest first) and lists the available filtering dimensions plus the tour/league default behavior. It does not say when to prefer get_matches, get_head_to_head, or get_player_stats instead, so the alternative-routing element is missing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on value-adds: a concrete credit cost ('Costs 3 credits'), the derivation rule ('all counted from scores'), and a data-availability limit. It does not describe response timing, caching, or what an empty result looks like, which keeps it below a 5.

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

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

Front-loaded with the use case, followed by the metric list, the exclusion, the parameter caveat, and the cost — each element earns its place. The metric enumeration is dense but appropriate since it defines the tool's scope; the paragraph form is slightly harder to scan than a short structured list.

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

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

With an output schema present, the description need not explain return shapes, yet it still scopes the metric set and data provenance. It omits how season interacts with the round/ranking breakdowns (aggregate vs per-season) and leaves the league/tour naming mismatch for the agent to resolve, which are the main residual gaps.

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

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

The schema documents all three parameters at 100% coverage, so the baseline is 3. The description adds a genuinely useful operational hint ('on the shared endpoint pass league: "wta"'), but it also introduces confusion by describing the tour values as 'atp (default) or wta' while the schema enum is ['tennis','wta'] with a 'tennis' default — an agent must reconcile 'atp' with 'tennis' itself.

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 ('a player's match statistics by season') and then enumerates exactly which metrics are returned (wins, losses, sets, tiebreaks, deciding sets, 6-0 sets, retirements, plus breakdowns by round and opponent ranking). This is clearly distinguishable from siblings like get_player_matches (raw matches), get_surface_splits (surface dimension), and get_head_to_head (two-player comparison).

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

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

'Use for a player's match statistics by season' gives a clear activation context, and 'No serve statistics: they are not available' sets an explicit boundary on what this tool can answer. It stops short of naming alternatives for adjacent questions (e.g., surface splits or head-to-head), so routing is implied rather than spelled out.

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 readOnly/idempotent/non-destructive, so the description's added value is the credit cost (2 credits) and the data-coverage caveat (weekly lists hold roughly the top 100-150 for most weeks since 2007), which materially shapes expectations. 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?

Four tight sentences, front-loaded with the primary use case and each subsequent sentence handling a distinct concern (alternate mode, coverage, league, cost). No filler.

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

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

An output schema exists, so return values need no explanation; the description covers modes, coverage, league switching, and cost. The only gap is the phantom 'tour' parameter reference, which an agent must reconcile against the schema's league enum on its own.

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 earns an extra point by explaining how season and week combine, that date yields the list in force, and how tour maps onto the league enum. The reference to 'Tour: atp (default) or wta' names a parameter that does not exist in the schema, which slightly muddies the league semantics.

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 the resource (ranking list) and its three modes of resolution (latest default, season+week, date), plus the fields returned (rank, previous rank, points, player). It also separates the single-player history mode, so the agent can tell it apart from the list mode, though it never contrasts itself with the sibling get_ratings, which is the most likely confusion point.

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 routing rules: use the list form by default, pass player_id 'instead' for one player's history, and pass league: "wta" for WTA on the shared endpoint. Missing only an explicit statement of when to prefer a sibling such as get_ratings or get_player_stats.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing the 2-credit cost, the minimum-match filter, the active_since default, and the shared-endpoint league:'wta' quirk. It doesn't discuss result size or pagination beyond the limit.

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?

Dense and front-loaded: purpose first, then filters, then routing, then cost. It's telegraphic and slightly compressed, but every clause carries information, with no filler.

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

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

An output schema exists, so return values needn't be described; the description covers sorting, filters, defaults, and credit cost. Enough for an agent to call it correctly, with only minor gaps around surface enumeration and the atp/tennis naming mismatch.

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%, but the description goes beyond it by explaining the atp/wta tour concept and the mapping to league:'wta' for the shared endpoint, which the schema alone doesn't convey. Minor note: the description lists surfaces as hard/clay/grass while the schema also allows carpet.

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 the resource precisely ('our Elo ratings'), the sort order ('highest first'), and the two modes (overall or per-surface). This clearly separates it from get_rankings, which covers official rankings rather than Elo ratings.

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?

Explains eligibility (a rated match since active_since, at least 10 rated matches) and the tour/league routing rule. It gives clear usage context but never explicitly says 'use get_rankings instead for official rankings', so the alternative routing is left implicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is real: it discloses the 2-credit cost, the singles-only filter, the max 30-day cap, and the caveat that start time is present only 'where one is set'. It does not discuss pagination or result-size limits, which for a capped list tool would be the remaining useful detail.

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

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

Dense but front-loaded: the use case comes first, then scope, then parameters, then cost. Most clauses carry information, though the 'Tour: atp ... on the shared endpoint pass league' sentence is convoluted and is where the schema mismatch is introduced.

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 need not be explained; the description covers scope, defaults, caps and credit cost adequately. The one completeness defect is the league/tour inconsistency, which could cause an agent to invoke the tool with an invalid argument or misjudge the default tour.

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 introduces a 'tour' concept with 'atp (default) or wta' that conflicts with the schema's single 'league' enum of [tennis, wta] defaulting to tennis. There is no 'atp' value anywhere in the schema, so the text actively misleads an agent about the valid argument and the default.

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

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

States a specific verb and resource with scope: 'upcoming matches' meaning 'every scheduled or in-progress singles match in the next N days', and lists the returned fields (players, seeds, round, start time). The 'upcoming' framing implicitly separates it from get_matches/get_player_matches, but no sibling is named, so differentiation is left partly to inference.

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

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

'Use for upcoming matches' gives a clear selection context, and the 'scheduled or in-progress' qualifier tells the agent which match states qualify. There is no explicit when-not guidance or named alternative (e.g. get_matches for completed results), which keeps it below a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description need not repeat safety details. It adds useful behavioral context beyond annotations by disclosing the 3-credit cost and the league/tour handling for ATP versus WTA, including the shared-endpoint quirk for WTA.

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

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

The description is front-loaded with the core use case and packs in relevant metric details, cost, and parameter quirks without extraneous prose. It is somewhat dense and the ATP/league wording could be cleaner, but every part broadly serves the agent.

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 an output schema exists and annotations cover safety behavior, the description is complete for invocation: it describes the returned surface metrics, the season/career scope, by_season behavior, league handling, and cost. No critical invocation detail appears missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics for season, by_season, and league: it explains that season defaults to the whole career, by_season splits each surface by year, and WTA access on the shared endpoint requires league="wta". The ATP/WTA note is slightly confusing against the schema enum tennis/wta, but still adds value.

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

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

The description clearly states the resource: a player's record split by surface, including specific metrics returned. It is specific enough to distinguish this from general player stats or ratings, though it does not explicitly name sibling tools or explain when to use those alternatives.

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

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

It gives clear context for using the tool: for a player's surface-level record, for one season or the whole career, and with by_season to split each surface by year. It does not provide explicit when-not-to-use guidance or name alternatives like get_player_stats or get_ratings.

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 safety, and the description adds useful behavioral context: it costs 2 credits, draw defaults to main, tour defaults to atp, and WTA requires league='wta' on the shared endpoint. It does not contradict annotations.

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

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

The description is dense but well-structured: it front-loads the main purpose, then specifies draw, tour, endpoint nuance, and cost. Every sentence contributes useful information without waste.

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

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

Given the output schema exists, the description need not restate return values, but it still provides enough context about what is returned, defaults, cost, and endpoint handling. It is complete for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the schema documents the parameters. The description adds valuable meaning by clarifying the default draw, the tour values, and the non-obvious mapping of WTA requests to league='wta' on the shared endpoint.

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

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

The description states a specific verb+resource: retrieving a tournament's draw and results, including singles matches grouped by round, scores, seeds, and finalists. This clearly distinguishes it from sibling tools like get_match, get_matches, and list_tournaments.

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

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

It gives clear context for when to use the tool (for a tournament's draw and results) and explains the draw and tour options, including the shared endpoint nuance for WTA. It does not explicitly name alternatives or exclusions, but the scope is 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 cover readOnly/idempotent/non-destructive, so the description correctly focuses on what they don't say: results come back in calendar order, the season defaults to the current year, and the call costs 1 credit. Missing only pagination behavior, which is partly implied by the schema's next_offset note.

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

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

Three tight sentences: purpose first, then returned fields, then filters and endpoint nuance, with the cost note last. Dense but every clause carries information; no filler.

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

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

An output schema exists so returned fields need not be enumerated, yet the description still summarizes them at a useful level of detail. For a 6-param read-only list tool, the only real gap is explicit pagination guidance beyond the schema's offset note.

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 earns extra by clarifying the tour/league mapping — 'atp (default)' versus passing league: 'wta' on the shared endpoint — which the raw enum (tennis, wta) leaves ambiguous. It also restates the surface and status filter values usefully in context.

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

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

Opens with a specific verb+resource ('find tournaments') and immediately specifies the output scope: a season's tournaments in calendar order with dates, city, surface, Grand Slam flag, status, match count and champion. This cleanly distinguishes it from the singular sibling get_tournament.

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?

States 'Use to find tournaments' and gives concrete filter guidance (surface, status, season). It also resolves the ATB/WTA routing question by noting the shared endpoint requires league: 'wta'. It doesn't explicitly say when to prefer get_tournament for a single event, so not quite a 5.

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

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

Annotations already establish the safe read-only, idempotent profile, and the description goes well beyond them: result ordering (most-played first), the fields returned (matches, last match, rank), the null-rank boundary outside the top 100–150, and the 1-credit cost. Cost disclosure in particular is behavioral information no annotation carries.

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 primary purpose and packed densely with no filler; nearly every clause carries information. The tour/league sentence is the weakest part, reading as slightly tangled and introducing a 'tour' concept absent from the schema.

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

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

With an output schema present, return values need not be spelled out, and the description still summarizes them, plus defaults and cost. The one gap is the mismatch between the described 'tour: atp (default) or wta' and the schema, which exposes only a 'league' enum of tennis/wta — an agent may be unsure how to express 'atp'.

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 real semantics: accents are optional in names, country codes are three-letter (e.g. ITA), and it attempts to explain how the tour setting relates to the league parameter on the shared endpoint. The extra context outweighs the schema's own field 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?

Opens with a specific verb and goal ('Use to find a player's id') and names the two searchable dimensions (name, country code). This clearly separates it from get_player, which takes an id the agent presumably already has.

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

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

The phrase 'Use to find a player's id' implies the lookup-then-fetch workflow and steers toward the id-based sibling without naming it. Tour/league selection guidance is given, but there is no explicit exclusion telling the agent when not to search (e.g. when the id is already known).

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