Docteur Bet — football probabilities

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

Annotations already establish this is a safe, idempotent read, so the bar is lower. The description still adds real behavioral context beyond them: the 21-day window, nickname/alias handling across languages, the key returned field (match_id), and the multi-match ambiguity behavior. It does not cover result limits 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?

Three sentences, each carrying distinct information: what it finds and its time window, the optional narrowing and downstream routing, and the disambiguation rule. The core purpose and scope are front-loaded 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?

With no output schema, the description carries the burden of return values and does so by naming match_id and the candidate-match structure. Disambiguation behavior and the 21-day scope round it out. Minor gaps remain on ordering, result limits, or what happens when nothing matches.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value on top by showing that nicknames are accepted across languages ("PSG", "Man City", "Barça") and by framing date/opponent as optional narrowing filters. It never mentions the lang parameter's effect, which would have pushed this higher.

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+resource+scope with a downstream routing hint; only missing explicit contrast with the get_upcoming_matches sibling.

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

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

It clearly explains how to invoke it (narrow with opponent and date) and routes the agent downstream to get_match_probabilities with the returned match_id. It also gives a concrete ambiguity resolution procedure: if several teams match, ask the user which one they mean. No explicit when-not-to-use or comparison against get_upcoming_matches/get_team_strengths.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description needn't restate that. It adds genuinely useful context beyond the structured fields: the model is a free Dixon-Coles variant distinct from the premium app model, and it imposes an agent obligation to cite source, model, and calculation date.

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 return contents are front-loaded and the sourcing instruction follows; every sentence carries information. The parenthetical aside about the paid model is slightly wordy but earns its place by preventing model confusion.

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 usefully enumerates the returned markets, xG, exact scores and team strengths, and it supplies the match_id source and citation requirement. It is essentially complete for a single-argument lookup; only rate limits or summary/notice behavior remain unstated.

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

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

Schema description coverage is 100%, so both parameters (match_id, lang) are already documented, and the description only reinforces the match_id provenance. No added meaning for lang or any format/validation detail, so this sits at the baseline for a fully-covered 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?

Specific verb ('Returns the probabilities') plus a scoped resource ('one football match') and an explicit enumeration of what is returned (1X2, over/under, BTTS, xG, exact scores, team strengths). It also distinguishes itself from a similarly named model (the free Dixon-Coles vs. the Docteur Bet model reserved for value bets), so an agent can tell it apart from siblings like get_season_projection or get_team_strengths.

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 tells the agent where match_id comes from ('find_match or get_upcoming_matches'), which routes the caller correctly and implies this tool should be called after a lookup. It does not state when NOT to use it or contrast it against get_season_projection/get_team_strengths, so it stops short of full alternatives 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 behavior. The description adds substantive context beyond those: the underlying Dixon-Coles model, the free Docteur Bet source, the tens-of-thousands simulation basis, and the availability restrictions. It stops short of explaining pagination/response format, so it is not 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?

It is a single dense sentence with the main output front-loaded, followed by the availability caveat. Every clause carries information, though the model/provenance detail is slightly verbose for the core payload.

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 usefully enumerates the returned fields (title chances, CL/European places, relegation, projected points), which is what an agent needs. The availability caveat and list_competitions pointer round it out; only the response shape/size remains unstated.

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

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

Schema description coverage is 100% and both parameters (lang, competition) are fully documented in the schema, so the schema does the heavy lifting. The description only implies the competition argument ('table of a league') without adding format or matching details beyond the schema.

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

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

The description states a specific verb and resource ('Returns the current table of a league with a season projection') and enumerates the exact outputs (title odds, CL/European places, relegation, projected points). This is clearly distinguishable from siblings like get_match_probabilities or get_team_strengths.

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 scope conditions: not available for cups or leagues whose format the simulator does not handle, and routes the agent to list_competitions to check support. It does not, however, contrast the tool against sibling probability/strength tools, which is the only missing routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is freed to add semantics — and it does: it attributes the figures to the free Dixon-Coles model from Docteur Bet and explains the scale (1 = league average; a lower defence figure is better). It does not cover failure behavior for an unknown competition, 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?

A single front-loaded sentence that states the purpose first and then enumerates the returned figures; every clause earns its place. The nested parentheticals make it dense, 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 correctly carries the return-value burden, listing attack strength, defence strength, overall index, and the rank-vs-position gap, plus interpretation rules. It falls short only on edge behavior (what happens when the competition is unknown or has insufficient data).

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 (competition, lang) are already fully documented in the schema, and the description adds nothing about their format or behavior. 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 description names a precise resource and verb: it returns the power ranking of a competition, with attack/defence strength, an overall index, and rank-vs-table gap. This is plainly distinct from the match- and projection-oriented siblings (get_match_probabilities, get_season_projection), so an agent can route to it 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?

There is no explicit when-to-use or when-not guidance and no sibling is named as an alternative for related questions (e.g., season projections or match probabilities). The closest thing to guidance is the implicit framing of output content, which is descriptive rather than directive.

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 genuine behavioral context beyond that: which model generated the data, that only bets published pre-kick-off and then settled are included, and that individual bets are withheld as subscriber-only. It does not state a time window or refresh cadence, but the important disclosure is present.

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 clause, and the returned metrics are listed compactly. The two-sentence structure is efficient, though the parenthetical model distinction is slightly dense and could be tightened.

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 job of describing returns and does so by naming the exact aggregates and their per-country segmentation, plus what is excluded. Remaining gap: it never states the period covered or how the record is scoped, which an agent might reasonably want for a track-record tool.

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

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

Only one parameter (lang) with enum fr/en, a default, and 100% schema description coverage — the schema fully documents it. The description never mentions the language dimension or what it localizes ('summary and notices'), so it adds nothing beyond the schema. Baseline 3 per the high-coverage 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?

States a specific verb+resource ('Returns Docteur Bet's public track record') and enumerates the exact contents: settled value bets, wins/losses, bet count, average odds and yield per country's bookmaker market. The clause distinguishing Docteur Bet's own model from 'the free Dixon-Coles model' clearly separates it from the sibling model/probability tools.

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

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

The description gives clear context for use (aggregate public performance of published value bets) and a scope boundary — individual bets are subscriber-only and not returned — so the agent knows not to expect raw bet listings here. It does not explicitly name alternatives or state when to prefer it over, e.g., get_season_projection, but the usage context is unambiguous.

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 openWorldHint=false, so safety and idempotency are known. The description adds that probabilities come from a free Dixon-Coles model and are only present 'when published', which is useful conditional context, but it stays shallow on data freshness or rate limits.

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

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

One dense but well-structured sentence with the main action front-loaded and the input flexibility tacked on with examples. No wasted words, though the long trailing clause could be split for readability.

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?

Complete for a read-only list tool with full schema coverage and rich annotations. It clarifies the probability source and condition, which is important for interpreting output, though it does not mention pagination or return shape (no output schema exists, but the description sufficiently frames what fields appear).

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

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

Schema description coverage is 100%, so the parameters (days, lang, competition) are already fully documented. The description adds value on competition input flexibility (name, abbreviation, id) and points to list_competitions, but otherwise the schema does the heavy lifting, so baseline 3 is appropriate.

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

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

States a specific verb (Lists), resource (upcoming matches of one competition), and scope (over the next days, with 1X2 probabilities). Distinguishable from siblings like find_match or get_match_probabilities by focusing on a forward-looking competition-level list.

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?

Implies when to use it – for upcoming fixtures of a given competition with probabilities when published. Names list_competitions as the source for ids, but does not explicitly state when not to use it versus find_match or get_match_probabilities.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It does so by disclosing what data is published per competition (probabilities, full markets, season projections, team strengths), which is genuinely useful for an agent deciding what it can retrieve. No auth or rate-limit notes, so not 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?

Verb and resource are front-loaded, and the coverage list is parenthetical rather than a separate clause, keeping it to two sentences with no padding. The enumeration of leagues is long but earns its place by defining scope precisely.

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

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

With no output schema, the description carries the burden of explaining return content, and it does so by listing the four publication categories per competition. For a zero-required-parameter read-only list tool this is nearly complete; only output format/shape specifics are absent.

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

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

There is a single optional 'lang' parameter with 100% schema description coverage, so the schema fully documents it. The description adds nothing about language behavior, but per the baseline rule for high coverage this is adequate at 3.

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 ('Lists the football competitions Docteur Bet models') and enumerates the actual coverage domain, so an agent immediately knows this is a catalog of supported competitions rather than match data. It is clearly distinguishable from siblings like find_match or get_match_probabilities, which operate on individual matches.

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?

Ends with an explicit trigger: 'Call this when unsure whether a competition is covered.' That gives a clear when-to-use condition. It does not name an alternative tool or state when NOT to call it, 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.