The Tennis Desk

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

Goes well beyond the readOnly/idempotent annotations: it discloses that the Desk only drafts while the captain sends from their own phone or email, forbids the agent from sending or reading a teammate's contact details, and states the Desk Pass requirement per member per week. Those are exactly the constraints an agent cannot infer from annotations and would otherwise violate.

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

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

Purpose is front-loaded in the first sentence and the operational constraints follow in a logical order. Some sentences are densely packed and the Desk Pass/pricing sentence sits awkwardly mid-paragraph, but nothing is redundant.

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

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

For a 10-parameter tool with no output schema, the description covers the output (the list of unanswered players plus one drafted group message with deadline and grid link), the input shape, the deadline default, and the send/no-send boundary. An agent has everything needed to call it correctly and to avoid acting on the result itself.

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 every parameter is already documented, and the description largely restates it ('each match column's header, and each player's row with one cell per column'). It adds no format examples, ordering rules, or guidance on when to supply the many optional fields such as asked, signAs, matchId, or lineupNow beyond what the schema says.

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 resource: finds the players who have not answered the next match on the USTA NorCal availability grid, and adds that it also lists blank/maybe answers and drafts one group message. An agent can tell what it produces. It does not, however, distinguish itself from the closely named sibling plan_lineup_from_availability, which a reader would reasonably guess overlaps with this.

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?

'Call it when a captain asks who has not answered on NorCal, or wants reminder texts' gives a concrete triggering condition, and the input guidance ('pass the team and the grid as your agent read it') states a prerequisite. Missing is any explicit exclusion against plan_lineup_from_availability or plan_lineup, which is the main routing ambiguity here.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real behavioral context beyond them: values are computed in code from recorded lines (so they are authoritative and should be quoted verbatim), and omitting `phase` silently includes playoffs and sectionals. That default-inclusion trap is exactly the kind of non-obvious behavior worth disclosing.

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

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

Two sentences, no filler, with the core action stated first and the phase caveat appended where it matters. The opening clause ('in any league or season, in code from its recorded lines') is slightly dense but earns its place by establishing scope and authority.

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

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

With no output schema, the description correctly specifies the return as a single number drawn from a fixed set, and warns about the phase default. Minor gap: it never says what happens for a team that isn't 'covered' or how an ambiguous team name is resolved.

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 including the `kind` enum and `phase` values is already documented. The description restates the phase default and the kinds but adds no syntax or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('works out one number for any covered team') and enumerates exactly which four numbers it can produce, matching the `kind` enum. It does not name the closest sibling (query_team_record) so the agent must infer the split, which keeps it off a 5.

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 trigger: 'Call it whenever you would state a count, an average or a win rate, and quote its value exactly rather than working one out' — this tells the agent not to hand-compute. It also gives a concrete conditional for `phase` ('pass phase:regular season for a league record alone'). No named alternatives or exclusions, so not a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description still adds a genuinely useful caveat the annotations cannot convey: rankings use each player's current Desk level, not the level at the time of the match, which materially affects how results should be interpreted.

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

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

Two sentences, both earning their place: the first defines the computation and its temporal caveat, the second defines invocation triggers. Front-loaded with the core definition and free of filler.

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

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

With no output schema, ambiguity remains about the return shape – whether it is a ranked list with per-match scores, how many matches are returned, or how tie-breaking works. Otherwise the description plus the fully covered schema give an agent enough 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?

Schema coverage is 100%, so team, asked, season, and includeAllSeasons are already fully documented in the schema. The description adds the conceptual basis of the score (current Desk level, not historical) but contributes nothing about parameter behavior, and the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource: rank a team's recorded matches by lineup strength derived from current Desk levels. It implicitly distinguishes itself from roster-level siblings (compute_roster_strength, compute_aggregate) via the 'per match' framing, but never names an alternative tool outright.

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

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

It states concrete invocation triggers – 'which match had the strongest or weakest lineup' and 'how a team's line strength moved' – which map directly onto likely user phrasings. It offers no explicit when-not or named alternative, so routing against compute_roster_strength is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the automatic fallback to the prior season when no season has been played, and that stats aggregate across every league line a player appeared in. It stops short of describing error handling or empty-result behavior.

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

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

Three sentences: output definition first, then when to call with examples, then a behavioral caveat. No repetition of the title or restatement of annotations, and every sentence carries distinct 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?

No output schema exists, and the description compensates by enumerating the returned fields per level group. With annotations covering safety and the schema covering all four parameters, the remaining question an agent would have — when does this apply and does it work out of season — is answered.

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%, including a detailed explanation of the phase/league-name quirk, so the schema already carries parameter meaning. The description adds only the aggregation scope ('over every league line'), not syntax or format guidance for team, season, or asked. 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 ('splits a team's roster by published NTRP level') plus the exact output fields (players, wins, losses, win rate per level group), and the scope 'over every league line those players appeared in'. The clause 'for a roster's shape rather than its results' separates it from the record/standings siblings like query_team_record and compute_aggregate.

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 invocation triggers with two natural-language examples ('how strong is their 4.0 half', 'who carries this team') and a negative cue ('rather than its results'). It also covers a tricky precondition (works before a season is played). It does not name a specific alternative tool to use instead, which keeps it below 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered; the description adds the auth requirement ('Needs a signed-in member') and the concrete failure mode ('A key with no member gets the error member_required'), which is genuinely useful pre-call knowledge. It does not discuss rate limits or caching, but those are minor for a cheap read.

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?

Short sentences with the capability stated first, then the trigger, then the prerequisites — well front-loaded. The sentence 'It takes no arguments' is the one that fails to earn its place, being both redundant and misleading.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the four things reported (holds pass, renews/ends, forecasts left, when more come). Auth and error behavior are covered; only the optional `asked` parameter is left unaddressed.

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

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

The claim 'It takes no arguments' is inaccurate: the schema defines an optional `asked` parameter that the schema itself documents thoroughly (verbatim question, omit rather than invent). Saying the tool takes no arguments risks the agent silently dropping `asked`, so the description works against rather than alongside the schema here.

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

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

The description names a specific verb-and-resource pair ('Says whether the signed-in member holds the Desk Pass') and enumerates the exact facts returned: renewal/end date, remaining weekly forecasts, and reset timing. That scope is clearly distinct from the sibling forecast tools (query_team_forecast, query_forecast_results), which concern team or result data rather than the member's own quota.

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?

'Call it when someone asks about their Desk Pass or their forecasts' gives an explicit trigger condition. It stops short of saying when to prefer this over the forecast siblings, but the member-scoped phrasing effectively implies the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description earns credit by adding what annotations cannot: that the check is a pre-post validation, that submission happens outside the Desk, and what three facts the answer contains. It doesn't discuss failure modes or what happens on an invalid date, which keeps it out of the top band.

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

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

Five sentences, front-loaded with the check itself, then inputs, then outputs, then the operational boundary. Mostly earned, though 'the format and second-shift time if the captain has them' is wordier than needed and could collapse into a single clause.

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 nine parameters, no output schema, and a read-only advisory role, the description does the important work: it lists the three result dimensions an agent must report back on. It leaves the exact response shape implicit and doesn't say how date/opponent together identify an existing match, but an agent can call it correctly from this text plus the schema.

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

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

Schema description coverage is 100%, so every parameter, including the optional date/opponent match identifier and the verbatim 'asked' field, is already documented in structured form. The description only restates that team, match, date and time are passed, plus that format and second shift are optional when known. That is a marginal addition over 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?

The description names a specific verb and resource ('Checks a proposed date and time for a home match') and enumerates the three verdicts returned: whether the form offers the time, which formats are offered for the team's lines, and whether the team already plays that day. No sibling tool overlaps with this pre-flight validation job, and an agent can tell that 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?

'Call it when a captain asks whether a date works, or before an agent fills the post-dates form' gives two concrete triggering situations. It also draws the boundary that the Desk never acts on the USTA site, so the tool is advisory only. It stops short of an explicit when-not or a named alternative, but nothing in the sibling list plays this role.

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/idempotent annotations by disclosing the paywall lifecycle: free forecast first, then a degraded 'free part' with no chances for unplayed lines, and a `deskPass` whose `message` must be relayed to the person. It also names the two error conditions (free_forecast_used, desk_pass_required), which is exactly the kind of auth/rate context annotations cannot express.

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 what the tool does and what it returns before the calling guidance and the paywall mechanics. It is dense and slightly clunky in the middle ('the Desk's estimate of how they play now'), and the final sentence packs two error codes plus a gating rule, but nothing is truly wasted.

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

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

With six parameters, no output schema, and a paywall, the description covers what is returned qualitatively, how the free/paid split behaves, and the error surface. What is missing is the shape of results when no opponent is supplied versus when one is, leaving the agent to infer the return structure.

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

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

Schema coverage is 100%, so every parameter is already documented, including the 'never fill it in yourself' rule for `lineup` and the averaging effect of `unavailable`. The description restates those constraints rather than adding new meaning, 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 and resource ('Plans a doubles and singles lineup for a team the Desk covers') and enumerates what comes back: appearances, usual line, Desk level, per-line win chance, expected lines won. It never names the closest sibling (plan_lineup_from_availability), but the distinction is implied by the rule that `lineup` is only what the person states, so an agent can mostly 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?

Gives three literal trigger phrasings ('what lineup should we play against X', 'who has played most for us', 'how do we beat X') plus the gating rule that it needs a Desk Pass after the member's free forecast. No explicit when-not-to-use statement or named alternative, 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 cover read-only, idempotent, non-destructive, closed-world, and the description correctly does not contradict them. It adds genuinely useful behavior beyond them: the result carries lineup-form values and what to confirm with the member before Save, the Desk never acts on the USTA site so the member or their own agent presses Save, and win chances are gated behind a Desk Pass. Return-shape detail is implied rather than specified.

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 the prerequisite/ownership sentences are worth their space. However, the description re-enumerates all six answer strings that the schema already lists in full, and the 'Each line's win chance needs a Desk Pass after the member's free forecast each week' sentence is dense and hard to parse on first read.

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 seven parameters, a nested availability array, and no output schema, the description does more than most: it states what the tool returns (lineup form values plus confirmations), who performs the save, and the Desk Pass gating. The main omission is routing against the near-identical plan_lineup sibling, which an agent needs in order to choose 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 already documents all seven parameters including the nested availability item fields. The description reinforces verbatim passing ('in USTA's own words') and required inputs (team, match, each player's answer), but mostly restates what the schema says, including the six answer values already enumerated in the schema. Baseline 3 is appropriate.

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

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

States a specific verb and artifact (plans a lineup) plus the precise input source: availability a member's agent read on the USTA NorCal league site. It reads as a distinct capability, but it never mentions the sibling plan_lineup, so an agent must infer how this differs from that tool by name alone.

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 last sentence gives an explicit trigger: 'Call it when someone pastes or describes who can play a match and asks for a lineup.' The Desk Pass prerequisite ('Each line's win chance needs a Desk Pass after the member's free forecast each week') adds a real gate. It lacks an explicit when-not condition or a named alternative (plan_lineup), 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the model inputs (Desk level, pair synergy, availability, default level for unrated players), the entitlement rule (Desk Pass after the weekly free forecast), the `deskPass` response field and what to do with its message, and the exact error codes free_forecast_used and desk_pass_required. That is exactly the auth/gating context 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?

Purpose is front-loaded in the first sentence and gating/error details follow in a logical order with little filler. However, the sentence 'Past that, a call gets the free part, with no chance for anything still to be played, and `deskPass`…' is compressed to the point of ambiguity and costs clarity.

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

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

For a 4-parameter prediction tool with no output schema, it covers inputs, gating, degraded behavior, response fields, and error codes well. It never says what the probability result actually looks like (format, range, supporting fields), which is the main remaining gap.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: an unrated player name gets a default level rather than failing, and side sizes drive line_type inference. It does not clarify the `asked` field or name-lookup flexibility beyond the schema, keeping it at 4.

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 — 'Gives the home side's win probability for one line between named players' — with clear scope (one line, home perspective, named players). It does not explicitly differentiate itself from the sibling query_matchup, which also sounds matchup-related, so it stops short of a 5.

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 trigger phrasing: 'Call it when someone asks who would win, the odds of a matchup, or how a pairing stacks up.' That is a clear usage context, but there is no exclusion clause pointing away from query_matchup or compute_match_line_ratings, which an agent could easily confuse with this.

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 context beyond them, notably that this tool does not submit and the member keeps control of the final action. It also explains the comparative role of `posted` — surfacing every line where the reported and posted records differ. It doesn't say much about the return shape beyond that.

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

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

Front-loaded with purpose, then input guidance, then the boundary condition. Six sentences, all doing work, though the 'unless scoresFrom says otherwise' clause and the Submit sentence could be tightened without losing meaning.

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 9-parameter, nested-array preparation tool with no output schema, the description covers purpose, input shape, and output intent (list of differing lines) plus the safety boundary. Minor gap: nothing is said about the return payload's structure or about date/season/matchId interplay, though the schema descriptions handle those individually.

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 nine parameters, and the description's guidance on set orientation ('give the sets from the member's own side, unless scoresFrom says otherwise') largely restates what `scoresFrom`'s own description says. It does clarify intent for `posted` (a diff source) and the ordering of line data, but on balance it does not add substantial new 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 a specific verb and resource: it prepares the values for the score form on the USTA NorCal league site from member-reported scores. No sibling tool touches the score-entry form, and the closing line ('Call it when someone wants to enter or check a match score on NorCal') pins the use case unambiguously.

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

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

Explicit trigger given ('call it when someone wants to enter or check a match score'), plus the boundary that the Desk never acts on the USTA site, so the member or their own agent presses Submit. It stops short of naming when NOT to use it or which sibling to reach for instead, but no sibling is plausibly confusable.

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/idempotent annotations: it discloses the Desk Pass requirement, the degraded free-tier response ("no chance in it"), the `deskPass.message` field the agent must relay to the person, and what extra content a Pass unlocks. Gating, degradation and return content are all surfaced before the call.

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

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

Front-loaded with purpose, then outputs, then usage, then the Pass caveat — a sensible order with no filler. It is on the long side at four dense sentences, but each carries distinct information (outputs, routing, gating, fallback).

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?

No output schema exists, so the description carries the return-value burden itself and does so — listing the projected place, title chance, playoff chance and live playoff report. Combined with the Pass/free-tier explanation and input routing, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by stating the selection logic between parameters — team alone, league plus area, or neither for the member's own team — which complements the schema's per-field mutual-exclusion notes with the overall routing rule.

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 resource — projects how a league table could finish from remaining matches and line forecasts — and enumerates the outputs (likely place, chance to finish first, playoff chance). It is clearly a projection rather than a live-standings read, though it never names the adjacent query_league_standings or query_team_forecast tools it must be distinguished from.

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?

"Call it for a team's playoff chances or what it needs" gives an explicit invocation condition, and the three input routings (team, league+area, neither) are spelled out. It falls short of naming alternatives or stating when *not* to use it versus the plain standings/forecast 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 cover readOnly/idempotent/non-destructive, so the description correctly spends its space on caveats the annotations can't carry: that firstPlace assumes every scheduled match is played, that a season with no team is 'not found' and the answer lists available seasons, the 7-day Pacific-time briefing window, and the '*' default-scoring marker in results. It never states what happens when the club itself can't be resolved, so 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?

Purpose is front-loaded in the first sentence and the sibling routing follows immediately. Some duplication of the schema's briefing text and a couple of long, clause-heavy sentences cost it a point, but nothing is filler.

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

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

With no output schema, the description carries the return-shape burden and does so: teams, places, records, upcoming matches, results, head-to-head, plus the briefing variant. The only gap is the unmentioned `asked` parameter, which is minor given its optional, verbatim-question nature.

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

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

Schema coverage is 100% and the schema already documents club forms, season default and briefing behavior; the description mostly restates those. It does not mention the `asked` parameter at all, so it adds little beyond the structured fields.

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

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

States a specific verb and resource: it returns what a club's page shows — teams by league with table place and record, next matches, latest results, head-to-head records. It explicitly separates itself from query_club_teams ('for only its list of teams... query_club_teams is enough'), so an agent can route without opening either schema.

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

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

Gives concrete trigger questions ('how a club is doing, its record against other clubs, or where its teams stand') and names the narrower sibling for the subset case. Both when-to-use and when-to-use-something-else are 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 declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description still adds behavior the annotations cannot: it discloses what comes back (teams plus next fixture) and warns that omitting qualifier words changes the result set ('dropping them answers a different question'). It does not cover result ordering or what an empty result means, 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?

Three sentences, front-loaded with what is returned, then when to call, then the parameter trap. The final sentence is long but each clause carries a distinct instruction; little waste.

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

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

With no output schema, the description responsibly sketches the return ('the teams ... and which of them plays next'), and the annotations cover the safety profile for this read-only, idempotent tool. Missing only pagination/ordering behavior, which is minor for a per-club list.

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 3 is the floor; the description earns more by explaining the consequence of the qualifier parameter ('dropping them answers a different question'), which turns a formatting instruction into a decision rule. It does not explain the `asked` parameter's purpose, but the schema already does that verbatim.

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?

Names a specific verb and resource ('Returns the teams a named club fields this year') plus the added payload ('which of them plays next'). It also explicitly separates the tool from the sibling query_club by scope (whole club vs. club page/performance), so an agent can pick correctly without opening the schema.

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

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

States the trigger condition ('whenever someone asks about a whole club by name'), the ordering ('before you narrow the question to a single team'), and names the alternative with the condition that selects it ('For how the club is doing, call query_club'). This is exactly the when/when-not/alternative pattern.

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/idempotent annotations, it discloses that a signed-in member is required and that a key without a member returns the error member_required — exactly the kind of precondition an agent needs. It also states the fallback behavior (group filled from the member's team when filters are omitted), though it says nothing about result shape beyond 'top N' or pagination.

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 action, then usage triggers, then cohort definition, then auth. Four sentences with almost no waste; only the error-code sentence is arguably a footer rather than part of the narrative flow.

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 purpose, trigger phrases, cohort construction, defaults, and the auth failure mode for a 7-parameter tool with no output schema. The remaining gap is what the response actually contains (ranking entry, percentile, top-player list) — worth a line given no output schema exists.

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%, so baseline is 3; the description earns above that by explaining the joint semantics of ageBand/division/level — omitting them all silently defaults the cohort to the member's own team. That defaulting rule is the key behavioral nuance and is not 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 a specific verb and resource: it ranks a cohort by Desk level and returns the member's place within it. The scope is crisp enough to separate it from query_league_standings (team standings) and query_player_rating (single rating), though no sibling is named explicitly.

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

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

Gives concrete user-phrasings that should trigger the tool ('where do I stand', 'how do I compare to the top players', percentile, top players in an age group) plus how to define the cohort. It never names an alternative tool or an explicit when-not-to-use condition, so there is no exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral context the annotations do not: the result is an unfiltered whole census rather than a slice, and it discloses the return dimensions, which matters since there is no 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?

Three sentences, front-loaded with the definition before the call trigger and the no-argument rationale. Mild redundancy between sentence one and sentence two, which both re-list leagues, levels and areas.

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

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

For a simple zero-required-parameter read tool with no output schema, the description covers purpose, invocation triggers, and the shape of what comes back. The only real gap is the misleading claim about taking no arguments, which conflicts with the schema's "asked" field.

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 actively undercuts the schema by declaring "It takes no arguments" while the schema defines an optional "asked" parameter that must be passed verbatim when present. An agent trusting the prose would omit a field the schema explicitly instructs it to supply.

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 enumerates exactly what the tool reports (areas, leagues, levels, clubs, teams, seasons) plus the meta-question it answers. Its nature as a whole-census capability probe is distinct from the per-entity query_* siblings, though no sibling is named for contrast.

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?

"Call it whenever someone asks what you can look up, what data you have, or which leagues, levels or areas are covered" gives concrete trigger conditions an agent can pattern-match. There is no explicit exclusion or alternative named (e.g., read_docs), 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: results are restricted to already-played matches, the chance shown is the value logged the night before, and the response includes the match result and whether the team covered the line — valuable given there is no 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?

Front-loaded with the core purpose and organized as purpose → return shape → usage → boundary. It is slightly wordy and colloquial ("the Desk," "won the line"), and the already-played constraint is stated twice, but no sentence is filler.

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

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

With no output schema, the description does the necessary work of describing the return fields (logged chance, line outcome, match result) and the temporal boundary. The only gap is that "latest matches" leaves the count or recency window unspecified.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates the team default ("pass the team, or nothing for the member's own team") consistently with the schema but adds no new syntax or semantics, and the `asked` parameter is not addressed at all. Baseline 3 applies.

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

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

States a specific verb and resource: it returns a team's past matches that the Desk forecast, along with the logged pre-match chance and the outcome. The closing sentence separates it from the upcoming-match path ("never a chance for a match still to come, which comes with the Desk Pass"), though it names a product concept rather than the sibling tool get_desk_pass or query_team_forecast.

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 invocation contexts: "how the Desk's forecasts did for a team, or what the Desk gave a team in a past match." It also states an exclusion (upcoming matches are out of scope) and a default behavior (pass nothing for the member's own team). It stops short of explicitly pointing at the sibling to use for future forecasts.

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 safety profile is covered. The description adds useful behavioral context: the table is unofficial and rankings come from recorded results according to the league's own rule and tie-breaks.

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

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

The description is front-loaded with purpose and then moves through usage and parameter routing efficiently. It is somewhat dense in the first sentence and the final club/area warning is confusing, but overall it is appropriately sized.

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 query tool with complete input schema coverage and no output schema, the description is nearly complete: it explains what the table represents and when to use each input mode. It does not describe the return shape beyond 'table' and 'place', which is a minor gap.

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

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

Schema coverage is 100%, so the baseline would be 3, and the description does add routing guidance such as using `league` and `area` together for a whole league. However, it also says 'Never pass a club or an area as the team,' which directly conflicts with the schema's `team` description allowing 'Team or club name,' creating real ambiguity for invocation.

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

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

The description states a specific verb and resource: building the Desk's unofficial league table from recorded results using the league's own rule and tie-breaks. It also scopes the two modes clearly, a team's flight table versus a whole-league table, which is enough to distinguish it from projection or cohort-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?

It gives explicit triggers: standings, how a team finished, who won the league, or 'the table'. It also explains the invocation alternatives: pass a team name, pass nothing for the member's own team, or pass `league` and `area` for a whole league, with examples.

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, closed-world behavior, so the description doesn't need to re-state safety. It does add value by disclosing the returned content in detail (per-match level deltas and opponents' contemporaneous levels), which matters since there is no output schema. It stops short of noting scope limits, such as whether a missing season or a player with no matches yields an empty result or an error.

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 and return contents are front-loaded in the opening sentence, and the routing rule follows. It is two dense sentences with little wasted text, though the clause list of trigger phrasings is slightly verbose.

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

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

With no output schema, the description does the right work by describing what comes back, and it names the sibling it competes with. The only gap is edge-case behavior — empty seasons, ambiguous player names, or whether the 'asked' parameter affects results — which an agent might want before calling.

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 three parameters (asked, player, season) are already documented with usage notes in the schema. The description only echoes 'for one season' without adding format, fallback, or edge-case guidance beyond that. Baseline 3 applies when the schema carries the parameter burden.

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

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

The first sentence names a specific verb and resource — returns a player's match-by-match rating history for one season — and enumerates the contents (level before/after each match, other players on court with their levels). That is enough to tell it apart from query_player_history, which it names explicitly.

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

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

It gives concrete trigger phrasings (how a player's level changed, how they reached it, what one result did to it, show their matches) and an explicit routing rule: prefer this over query_player_history when the question is about the level rather than the results. Both when-to-use and which-alternative are 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds one genuinely new behavioral fact — every row carries an evidenceId, implying provenance-backed output — but says nothing about default season scoping or what 'recorded lines' contain. The 'in any season' claim also conflicts with the includeAllSeasons parameter's instruction to set it true ONLY for prior history, which suggests the default is not all seasons.

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

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

Two sentences, front-loaded with what is returned, then the call trigger — no filler. Small deduction because the 'in any season' phrase is imprecise and consumes space while creating ambiguity rather than removing it.

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

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

There is no output schema, so the description is the only place return shape could be explained; it names evidenceId but not the other line fields, and it does not reconcile the default season scope with includeAllSeasons. Adequate to select the tool, but thin for an agent that must reason about what comes back.

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 and every parameter (asked, limit, season, includeAllSeasons, team_a/team_b) is already documented in the schema. The description echoes the two-team and season ideas but adds no resolving behavior, format, or interaction detail beyond what the schema states.

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?

Names a specific verb and resource: it returns the recorded scorecard lines for two named teams that played each other, each tagged with an evidenceId. That is enough to distinguish it from predict_matchup (a forecast) and query_match_log (single-team log). The phrase 'in any season' is slightly at odds with the title's 'Recent results' and with the includeAllSeasons flag, which blurs the scope rather than sharpening 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?

'Call it for the head-to-head between two teams, or before you state a fact about it' gives a clear positive trigger, including a useful grounding/verification habit. It stops short of naming alternatives or exclusions (e.g., use predict_matchup for an unplayed fixture), so the agent must infer those from sibling names.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real context: it requires a signed-in member, explains the data provenance (affiliations), and names the exact failure mode 'member_required' when the key has no member. The only modest gap is that it says nothing about the shape or volume of the returned list.

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 sentences, each doing distinct work: identity/scope, positive trigger with example, exclusion and routing, then auth/error behavior. Front-loaded with the core definition and no filler.

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

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

For a two-optional-parameter, read-only, no-output-schema tool, the description covers scope, invocation trigger, exclusions, and the auth failure mode, which is everything needed to call it correctly. The only minor omission is any hint about what the returned team list looks like, though that is low-stakes for a list retrieval.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema itself, so the baseline is 3. The description reinforces the thisYear flag semantics ('for this year's') but adds nothing about the 'asked' parameter, which is the more unusual one (verbatim question text).

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 (returns the member's own teams) and immediately bounds the scope to teams they are on or have played for via affiliations. It also explicitly excludes questions that name a team, club or player, routing those to sibling tools, so it is distinguishable from the 28 siblings without opening a 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 an explicit trigger with a literal example ('what teams am I on'), states when-not (any question naming a team, club or player), names the alternative tool family for that case, and adds the thisYear:true flag for the current-season variant. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: results arrive as cited rows told from the player's perspective, the record is pre-aggregated by season/team/stage, and the tool has a hard data boundary on injuries and availability.

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

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

It is three sentences and front-loads the return shape before the triggering condition and the data-boundary warning. Some phrasing is ornate ('cited rows told from the player's side', 'the Desk'), which costs a little clarity but does not bury the actionable 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?

With five parameters, no output schema and rich annotations, the definition covers what is needed to choose the tool and set expectations for the response shape and the excluded data domain. A brief note on ordering or what restricts the returned rows would make it 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 description coverage is 100%, so every parameter (asked, limit, player, season, includeAllSeasons) is already documented with defaults, maximums and constraints. The description only hints at the season/team/stage aggregation logic and does not add syntax or interpretation guidance 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?

The description uses a specific verb and resource: it returns recorded lines a named player appeared in, as cited rows plus a record broken out by season, team and stage. That is clearly separable from sibling tools like query_match_log, query_player_rating and query_cohort_standing, which return different shapes.

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

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

It gives an explicit trigger – 'when someone asks about a player's results, form or history' – and an explicit exclusion, warning that injury and availability are not held by the Desk. It stops short of naming a sibling tool (e.g., availability_loop) as the alternative for availability questions, so it lands at 4 rather than 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds capability-boundary context the annotations cannot: no USTA band, and no bump prediction is published. Those are exactly the non-obvious behavioral facts an agent needs to avoid fabricating or over-querying, and they go beyond restating the annotation hints.

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

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

Three tight sentences, front-loaded with the return content, then the trigger, then the exclusions. Every sentence carries either routing or scope information; nothing is filler or restatement of the name.

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?

No output schema exists, and the description compensates by enumerating the returned fields (level, record splits, model card id, lines behind it). Combined with annotations covering safety and schema covering both parameters, an agent has everything needed to select and call this correctly.

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

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

Schema description coverage is 100%, so both `player` (name, page link, or number) and `asked` (verbatim question, omit rather than invent) are fully documented in the schema. The description adds only an indirect hint through "when someone asks"; it gives no format or fallback detail for an unresolvable player name, 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 and resource ("Returns the Desk's read of a named player") and then enumerates the payload: Desk level, record by season/team/stage/format, model card id and lines. It also explicitly separates itself from query_roster by saying the USTA band lives on that row, so the agent can distinguish it without opening the sibling 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 an explicit trigger ("Call it when someone asks how strong a player is, or about their rating, level, trend or bump risk") plus a when-not ("The USTA band is not here... it is the `rating` on a query_roster row") that redirects to the correct sibling. A final note ("The Desk publishes no bump prediction") preempts a query that would otherwise be misrouted here.

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 the temporal contract (weekly snapshots, as-of-day semantics, never today) and the payload content (the biggest driver, the delta between two days, the matches in between). What it lacks is any sense of how far back the series goes or how the result is shaped, which matters since there is no 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?

Front-loaded with the core behavior and the exclusion up front, and every clause carries operational information. The opening sentence is dense and slightly convoluted ('one a week, each as of its day'), and the third sentence partly re-covers ground already stated, but no sentence is expendable.

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

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

With no output schema, the description does the work of describing returns: a weekly series plus the dominant mover and the supporting matches. Two optional parameters and a clear boundary against project_standings round it out; only the lookback depth and output shape remain unspecified.

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

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

Schema coverage is 100% and both parameters are fully documented there. The description restates the team/default behavior ('Pass the team, or nothing for the member's own team') without adding format or resolution detail, and says nothing at all about the `asked` parameter. Baseline 3 applies.

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

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

States a specific verb and resource (a team's historical playoff chances), fixes the granularity (one per week, each as of its day), and names a sibling tool that covers the case it does not. An agent can distinguish it from project_standings 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 says when to call it ('how a team's playoff chances have changed, or what its chances were last week') and when not to ('It never gives today's chance'), routing the excluded case to project_standings. It even signals the Desk Pass requirement attached to that alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious behavior: omitting `season` silently returns the current season, and a `moreRows` signal requires a follow-up call with a larger `limit` capped at 60. The `moreRows` mention is slightly ambiguous since it is a response field, not a parameter, but the retry instruction is actionable.

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 front-loaded sentences: what it returns, when to call it, then parameter guidance. No filler. The pagination sentence is slightly awkward in referencing `moreRows` without saying where it appears.

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, no-output-schema lookup with fully documented params, the description covers the returned row shape, the evidenceId grounding, default season behavior, and the pagination loop. An agent has everything needed to call it and to interpret a truncated result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: the consequence of omitting `season` (current season) and the pagination escalation rule up to 60 rows. It does not address `asked` or `includeAllSeasons`, though the schema documents those adequately.

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 plus the exact row shape (one row per player with an evidenceId, name, NTRP rating, wins, losses, matches, Desk level), which is far more than the title alone. It does not name or contrast against near-neighbors like query_club_teams or query_team_record, so an agent must infer the distinction.

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 a clear trigger ('when someone asks who is on a team, or before you state a fact about a roster') and a conditional rule for `season`. It stops short of explicit when-not-to-use guidance or naming an alternative tool for related roster-adjacent questions.

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, closed-world and non-destructive behavior, and the description adds the useful negative capability (no win chance) plus the Desk Pass dependency for the alternative. It does not say what happens when all three optional parameters are omitted, which is a meaningful gap given zero required params.

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 what is returned, then usage, then the exclusion — a sensible order with no filler. The trailing Desk Pass explanation is slightly more than the routing need requires.

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

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

For a read-only lookup with no output schema, the description covers return shape, intent routing, and the alternative tool for win probability. The only material omission is the behavior when no team or player is supplied, which matters because no parameter is required.

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 routing meaning not present in the schema: team vs player selection depends on whether the ask is about a named team or is first-person. It does not clarify the role of `asked` beyond what the schema already says.

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

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

The description names a specific verb and resource (returns a team's or player's upcoming matches) and enumerates the returned fields (opponent, day, start time, home/away). It also carves out a boundary against project_standings, so the agent can distinguish it from the forecast/standings 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 gives concrete triggering phrasings ('next match', 'today's or tomorrow's match', 'the schedule') and routes parameter choice by intent: team for a named team, player for a first-person ask. It also states explicitly what it does not answer (team win chance) and names the tool that does, project_standings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: every line carries an evidenceId for citation and the record is pre-counted so the agent shouldn't recompute it. That citation and pre-aggregation guidance is the kind of context annotations cannot 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?

Three sentences, front-loaded with what is returned and followed by citations and the calling trigger. Minor awkwardness in 'the record, which is already counted,' but 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?

Even with seven parameters and no output schema, the description covers return contents (lines with evidenceIds, record, period matches, next matches) and the calling condition, while the fully documented schema handles the filtering details. Adequate for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so parameters like date, phase, season, and includeAllSeasons are already well explained in the schema. The description adds only a light hint about the whole-history scope; baseline 3 applies when the schema carries the 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?

Specific verb and resource: returns recorded lines, the team's already-computed record, every match in the period, and upcoming matches for a named team across any league/season. That scope meaningfully separates it from narrower siblings like query_match_log or query_team_forecast, though no sibling is named explicitly.

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

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

States a clear trigger: when someone asks about a named team's matches, results, or next match, or before asserting a fact about them. It lacks explicit when-not guidance or a named alternative for adjacent questions (e.g., forecasting vs. results), so it stops short of a 5.

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

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

Annotations already cover readOnly, idempotent and non-destructive, but the description adds genuinely non-obvious behavior: no Desk Pass required and the call does not count against the account's daily or monthly limit. It also discloses a fallback ('A page read_docs does not hold is answered with the pages it holds'), which prevents an agent from treating a miss as an error.

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 core action, then scope, then parameter hint, then cost profile — a sensible order with no filler. The multi-item list of doc topics is slightly long, but it is the one place where extra length helps an agent decide whether the tool can answer a question.

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 three-optional-parameter read tool with no output schema, the description covers purpose, scoping, fallback behavior and the quota exemption. Return shape is only sketched ('word for word', matching sections), which is the one remaining gap an agent might want.

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

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

Schema description coverage is 100%, and each parameter is already well documented in the schema, including examples and the `asked` verbatim rule. The description only restates which params to pass ('Pass `about`... and `pages` for a page you know'), adding little beyond the schema.

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

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

States a specific verb and resource ('Reads The Tennis Desk's own docs, word for word') and enumerates what the docs cover, so an agent knows exactly what content it returns. It explicitly separates itself from the rest of the toolset by scope: 'when someone asks about the Desk itself rather than a team, a player or a match.'

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 a clear trigger condition and an implicit exclusion (anything about a team, player or match goes elsewhere), plus guidance on passing `about` for topic search versus `pages` when a page is known. It does not name a specific sibling alternative such as read_research, so the routing is by exclusion rather than explicit hand-off.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds real value beyond them: it lists what each result contains (question, headline, answers, figures, cohort, measurement date) and notes it requires no Desk Pass, which matters because get_desk_pass exists as a sibling. It doesn't discuss result volume or limits on returned pieces beyond what the schema already states.

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?

Sentences are front-loaded and each carries distinct information: purpose, return contents, when-to-use, when-not, parameters, and access requirement. Slightly longer than strictly necessary, but there is no filler or repetition.

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

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

With no output schema, the description compensates by describing the shape of each returned piece and the cohort/measurement-date metadata. Combined with the when-not rule and the authentication note, an agent has everything needed to call this 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 reinforces intended values for `about` ('a few words on the question') and `pieces`, but never mentions the third parameter `asked`, leaving the verbatim-question convention to the schema alone.

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

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

The first sentence names a specific verb and resource (reads the Desk's published research) and narrows scope to players 'in general, word for word.' The later exclusion of 'one named player, team or match' implicitly separates it from query_player_history and query_team_record, though no sibling is named outright.

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

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

It gives an explicit use case ('when someone asks about players or teams in general, such as how often players move up or back down, or home advantage') and an explicit never-condition ('never call it for one named player, team or match'). It stops short of pointing to the specific alternative tool for those per-entity questions.

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 important behavior beyond the annotations: a Desk Pass is required, and without it the call returns only the free part plus a deskPass message to relay to the user. It also describes the substance of the return (ranked reads with evidence), while the annotations already cover read-only, idempotent, and non-destructive behavior.

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

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

Front-loads the purpose, then covers usage, parameters, scope exclusions, and the Desk Pass caveat in compact sentences. Every sentence adds useful 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?

Although there is no output schema, the description explains what the scout contains (ranked reads and evidence) and what happens without a Desk Pass. That is enough for an agent to decide whether and how to call it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a meaningful constraint by saying `team` must be a single team the Desk covers and may be passed by name or Desk page link; `asked` remains documented mainly 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 a specific verb and resource: writes a scout for one covered team, including ranked reads and evidence. It also distinguishes the single-team scope from a whole-club request, so an agent can tell when this tool is the right one.

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 when-to-use cases (a scout, a team breakdown, how to beat a named team) and a when-not case (never for a whole club). It does not name a specific sibling tool to use instead when the request is out of scope, 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.