Bettrails

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, yet the description adds real behavioral context beyond them: the returned link hands the user to Bettrails, requires confirmation with a free account (auto-created if needed), and Bettrails itself delivers the notifications. That external-flow disclosure is exactly what an agent needs and is not in the structured fields.

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

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

Front-loaded with the purpose, then the kinds, then the flow — a sensible order. The kinds sentence is dense and slightly run-on, but every clause conveys required parameter combinations or timing semantics that earn their place.

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

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

For a 7-parameter, no-output-schema tool with enum-heavy params, the description covers purpose, per-kind required inputs, timing behavior, and the post-link user flow. The only real gap is the unmentioned language parameter and the exact shape of the returned link, both minor.

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?

At 57% schema coverage the description does meaningful work: it maps which parameters belong to which kind (esoccer_duel = league + player1 + player2; basket_duel = league nba|euro|ggl + player1 + player2; esports_team = game + team), which the schema only states generically. It omits the `language` parameter entirely, leaving that one to the schema description.

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

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

The first sentence states a precise verb+resource+outcome: 'Get a link so Bettrails notifies the user before a match starts.' It is instantly distinguishable from siblings like esoccer_head_to_head, esoccer_player, read_page and search, which have no notification-subscription behavior.

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 explains the conditions that select each mode (esoccer_duel fires ~10 min before next duels, esports_team fires 1 hour before each match plus the result), giving clear usage context. It does not, however, explicitly say when to prefer this tool over the sibling head-to-head or player tools it overlaps with.

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

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

The annotations already establish a safe, idempotent, non-destructive read (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds real context beyond that: the default window resolution rule (last 6 months when it leaves >=10 duels, otherwise full record), the semantics of last_n being applied after period, and the scope limit 'statistics only: no odds, no betting advice'. Return format and pagination are not described, keeping 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?

Purpose and triggers are front-loaded, which is good, but the middle is a long comma-spliced enumeration of every computed statistic that reads more like a spec dump than selection guidance. It is defensible for a data-heavy tool, yet several clauses do not earn their place for the select-and-invoke decision.

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 must carry return-value burden, and it largely does by listing the statistics returned and the default time-window behavior. It omits how results are structured (e.g. the bettrails.com links implied by the language param), leaving a small gap for a 9-parameter, no-output-schema tool.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds value by explaining filter interactions the schema does not spell out as a set: the clubs filter (club1/club2 or clubs_of_last_duel=true keeping only duels with the latest meeting's clubs) and the fact that period/last_n compose. It does not add syntax beyond the schema, so 4 rather than 5.

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

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

The description names the exact resource (head-to-head record between two eSoccer players) and enumerates the concrete outputs it computes (win/draw splits, goal averages vs league, goal distribution, BTTS, streaks, latest and next duels). This is specific enough that an agent can separate it from esoccer_player (single-player) and search 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?

It supplies explicit trigger phrases the tool is meant to answer ('who usually wins between X and Y', 'h2h', 'how many goals in X vs Y', 'and in the last month?'), which is strong context for selection. It stops short of naming alternatives or stating when NOT to use it (e.g. vs esoccer_player for single-player questions), so it does not reach the top band.

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 the safety profile is covered. The description adds genuinely useful context beyond that: the data-window rule (last 6 months when at least 15 matches exist, otherwise full career), the disclosure that a free sample of member data may be included, and the explicit "statistics only, no odds, no betting advice" scope limit. It does not cover pagination or auth needs, 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?

The core identity sentence is front-loaded and dense with information, and the intent examples and scope disclaimer each earn their place. The long comma-separated metric list is a little run-on, but nothing is clearly 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?

There is no output schema, so the description must carry the return-value burden, and it does: it enumerates the returned statistics in detail, states the lookback window, and flags the member-data sample. An agent has everything needed to call it and interpret the 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 description coverage is 100%: the league enum values are individually expanded, player nickname format is given, and the language default is stated, all in the schema itself. The description adds no further parameter meaning beyond restating the same Bettrails data window. Baseline 3 is appropriate 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 states a concrete resource (an eSoccer player profile) and enumerates the exact metrics returned (ELO, league position, win rate, goals per match, form, opponents, next match), so the agent knows precisely what comes back. It never names or excludes the closely-related sibling esoccer_head_to_head, so sibling differentiation is left to inference. Clear but not fully disambiguated.

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 quoted example intents ("how is X playing", "is X in form", "who does X play most", "when does X play next") give strong, concrete signals for when to reach for this tool. There is no explicit when-not guidance and no pointer to esoccer_head_to_head for the head-to-head case, 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 establish this as a safe, idempotent, non-open-world read. The description goes further by disclosing the return shape ('clean text', 'text and tables'), that embedded links surface as [/path] and are themselves readable, and that content is statistics-only with no odds/betting. This is genuine behavioral context beyond the annotations, though pagination or rate-limit behavior is not mentioned.

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 before enumerating sections and example paths. The dense mid-sentence path list is long but each cluster carries navigational value for a path-driven tool, so it is defensibly sized rather than padding.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately ('clean text', 'text and tables', links as [/path]). Combined with the annotations, an agent has enough to invoke it correctly; only return-size/pagination details 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?

Schema coverage is 100%, so the baseline is 3. The description adds real meaning for the path parameter by mapping the site's taxonomy (hubs, leagues, today, teams, players, etc.) across each section, which helps the agent choose valid paths. It slightly duplicates the schema's example paths and does not describe the language enum 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 ('Read any public page of bettrails.com as clean text') and enumerates the exact site sections that are covered. It also implicitly differentiates from the sibling search tool by noting that specific player/team/tournament pages must be found via search. An agent can tell this is a page-fetching tool distinct from esoccer_player/alert_link 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?

Gives concrete starting-point paths (/hoy, /lol/hoy, /jugadores, /records) that show how and contextually why to call it, and routes one case to a named alternative ('Pages of a specific player... can be found with search'). It lacks explicit when-not-to-use exclusions or guidance on preferring the specialized esoccer_head_to_head/esoccer_player tools over reading a page.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description adds value beyond them by disclosing the return shape ("Returns the matching pages") and the follow-up workflow ("readable with read_page"). It does not mention result limits or pagination, 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?

One dense sentence that is front-loaded with the verb and scope, followed by the return/follow-up note. The long enumeration is justified for disambiguating a universal search, though it reads as a run-on rather than crisp clauses.

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 compensates by describing results as pages readable via read_page and by giving concrete query examples ("snak", "caps", "lost vs troy"). Scope, usage condition, and output handling are covered; only result limits/pagination are 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?

Schema description coverage is 100%: the query, league enum meanings, and language default are all documented in the schema itself. The description only echoes "by name" and does not add format, matching behavior, or filtering nuances beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Search) and enumerates the exact resource scope: eSoccer players/matches/ELO, head-to-head pages, NBA 2K players, esports teams/players, champions, heroes, agents, maps, tournaments, countries. This breadth contrasts implicitly with the narrow sibling tools (esoccer_player, esoccer_head_to_head), so an agent can tell this is the broad entry point.

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

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

"Useful when the exact name, league or game is not known (the same nickname can exist in several leagues)" gives a clear selection condition. It stops short of explicitly naming the alternatives (e.g., use esoccer_player when the league is known), so it is clear context without full when-not routing.

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