FormFav Horse & Greyhound Racing

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower, and the description still adds meaningful context: a tier gate ('Pro tier') and a data-freshness caveat ('~2019 data window') that an agent cannot infer from the schema. It does not discuss rate limits or result volume, but those are secondary for a read tool with an 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 summary sentence followed by a compact Args block; every line adds a constraint or default. The 'Returns career wins, win rate, and per-venue breakdown' sentence is mildly redundant given an output schema exists, but it is short.

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 3-parameter read tool with an output schema and safety annotations, everything an agent needs is present: tier requirement, matching semantics, enum values and defaults, a numeric range, and the staleness of the underlying 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 description coverage is 0%, so the description carries the full burden and does: jockey_name is case-insensitive with partial matching ('mcdonald' matches 'James McDonald'), race_code enumerates 'gallops'/'harness' with a default and greyhound exclusion, and window is bounded at 14-365 days. The 14-365 constraint appears nowhere in the schema and is a genuinely additive detail.

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 ('Get track-by-track performance statistics for a jockey') and names the returned content (career wins, win rate, per-venue breakdown). The jockey-specific scope cleanly separates it from the sibling get_trainer_stats.

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 real usage conditions: Pro tier required, partial name matching supported, race_code defaults to 'gallops' and is unavailable for greyhounds, and window is an optional recent-form modifier. It stops short of routing between siblings (e.g. when to prefer get_runner_profile over 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 and closed-world, so safety is covered. The description adds genuinely non-structured behavior: the date range window (30 days back to 7 days ahead) and the timezone default of Australia/Sydney, both of which affect whether a call succeeds or returns the expected day.

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 purpose sentence, then return summary, then workflow hint, then a clean Args block. Every line earns its place; the timezone guidance is slightly wordy but justified by the overseas-racing edge case it prevents.

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

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

An output schema exists, so explaining return fields is supplemental rather than required, and the description still summarizes them. Combined with complete parameter guidance, range limits, and workflow placement, an agent has everything needed to invoke 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 0%, so the description carries the full burden and does so: 'date' gets format YYYY-MM-DD plus a valid range, 'race_code' gets all three enum values and the default, and 'timezone' gets IANA format, examples, and the default. This is meaning an agent cannot get from the bare 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 with scope ('List race meetings for a date') and adds that it returns venue name, race count and status. It positions itself as the discovery entry point, which implicitly separates it from card/results/profile siblings, but it never names an alternative tool 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?

'This is typically the first call to make — use it to discover what tracks are racing on a date' gives clear when-to-use context and workflow position. It stops short of stating when-not-to-use or naming the downstream siblings (get_race_card, get_race_results) that this call feeds.

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, and the description still adds meaningful behavior: entitlement requirement (Pro tier), partial data availability, and the normalization rule that probabilities sum to 1.0 across runners. It does not cover latency, caching, or error modes, 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?

Front-loads the purpose and return shape, then the availability caveat, then a clean per-parameter block. No sentence is filler, and the one operational trap (timezone mismatch silently resolving to a different meeting) is called out where the parameter is described.

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

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

An output schema exists, yet the description still names the key return fields (winProb, placeProb, modelRank, confidence), and it covers everything else an agent needs: entitlement, parameter formats, availability limits, and the timezone alignment requirement with sibling calls.

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 0%, so the description carries the full parameter burden and does so thoroughly: date format with a range (30 days back to 7 ahead), track naming convention with examples, race number bounds (1-20), enumerated race_code values, country default, and an explicit cross-tool consistency rule for timezone.

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 ('Get ML win/place probability predictions for a race') and immediately scopes it with a tier qualifier. This is clearly distinguishable from siblings like get_race_card (entries) and get_race_results (outcomes), since it returns modeled probabilities rather than factual race data.

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 real usage context: Pro tier gating, the availability caveat ('Not all races have predictions — only those with sufficient runner data'), and the requirement that timezone match what was passed to get_race_card()/get_race_results(). It stops short of explicitly stating when to prefer this tool over those 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 establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: the full-field return payload and the timezone caveat that the default Australia/Sydney may shift the race day for overseas meetings, which is a genuine correctness trap an agent would otherwise hit.

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 and return contents, then a compact Args block with no filler sentences. The Args list largely restates the schema keys, which is redundant in principle but justified here given 0% schema coverage; length is appropriate for a six-parameter tool.

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

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

An output schema exists so return values need not be detailed, and the description still summarizes them. Combined with the prerequisite call to get_meetings(), the timezone disambiguation, and complete parameter documentation, an agent has everything needed to invoke this correctly on the first try.

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 0%, so the description carries the entire burden and does so: formats (YYYY-MM-DD, IANA timezone), value ranges (race 1-20), enum-like choices (gallops/harness/greyhounds, country codes), defaults (gallops, au, Australia/Sydney), case-insensitivity for track, and worked examples. Every one of the six parameters is meaningfully specified.

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 ('Get the full race form for a specific race') and immediately enumerates what comes back: runners with barriers, jockeys, trainers, form, and ratings. This distinguishes it cleanly from siblings like get_race_results (results, not pre-race form) and get_runner_profile (single runner, not the full field).

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 sequencing instruction: 'Use get_meetings() first to find available tracks for a date,' which names the sibling and the precondition. It does not, however, state when to prefer this over get_race_results or get_predictions for a given race, so the routing guidance is partial.

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 only cover the generic safety profile (readOnly, idempotent, non-destructive); the description adds far more: a 2-3 hour scrape cadence, the fact that 'pending' is expected and must not be retried, dead-heat position sharing, and a coverage caveat for US/Canada/Japan/France where results arrive ~2 hours late without margins. This is exactly the behavioral 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?

Front-loaded and tightly organized: semantics, then return-value branching, then latency behavior, then coverage caveats, then args. Dense rather than padded, though the coverage paragraph and a few parentheticals could be trimmed 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 6-parameter read tool with an output schema, everything an agent needs is present: argument semantics, how to branch on `outcome`/`position`/`resultStatus`, latency expectations, and geographic coverage limits. The output schema covers return shape, so the description correctly spends its words on behavior instead.

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 0%, so the description carries the full burden — and it does: date format and allowed range (30 days back to 7 days ahead), track case-insensitivity, race range 1-20 and omission semantics, race_code enum values, country codes with default, and the timezone's role in interpreting the date with its default. Nothing an agent needs to fill these fields is missing.

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

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

Opens with a specific verb+resource ('Get the result of a race, or of every race at a meeting') and immediately bounds scope (Pro tier, single race vs whole meeting). It names the sibling get_race_card() and states the argument/coverage relationship, so an agent can place it relative to the other eight tools 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 concrete operating guidance: omit `race` to fetch the whole card in one call instead of looping, reuse the same args as get_race_card(), and do not retry on 'pending'. It stops short of an explicit when-not-to-use / alternative-tool statement (e.g. 'use get_race_card for pre-race form'), leaving the routing to inference.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description's added value is the Pro tier requirement, the conditionStats full-career vs ~2019 window scope caveat, and null sections below sample-size thresholds. Those are genuinely useful quirks not available in structured fields, though nothing is said about rate limits or failure 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-loaded with purpose, then returned sections, then prerequisites, then caveats, then args — every line earns its place with no filler. The section list is dense but directly informs invocation expectations.

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

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

With an output schema present, return format needn't be explained, and the description still covers scoping, null-ability, Pro gating, and parameter sourcing. The main residual gap is how window interacts with the ~2019 vs full-career scope split between stat groups.

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 0%, so the description must carry the load — and it does: runner_id's provenance (search_runner results) and window's meaning, units, and 14–365 range, none of which appear in the schema. It could go further on how window interacts with the default career window.

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 ('Get the full statistics profile for a runner') and enumerates the returned sections, which cleanly distinguishes it from siblings like get_jockey_stats and get_trainer_stats. An agent can identify the scope 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?

Explicitly names the prerequisite path: 'Use search_runner() first to find the runner ID', which routes the agent to the correct sibling. It does not state when-not to call it (e.g., for non-Pro tiers or when only recent stats are needed), so it stops short of full when/when-not 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), yet the description adds substantial behavioral detail: return contents (win rates by barrier, advantage scores on a 0-1 scale), the default `distanceStats` payload and its band definitions per race code, greyhound box semantics, and the `distanceFilter` echo. This goes well beyond what structured fields disclose.

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 a well-organized Args block. It is long, but nearly every sentence carries domain information that the 0%-coverage schema cannot, so the length is largely earned; the per-race-code band enumerations are the densest part.

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 6-parameter, single-required-arg tool with no schema descriptions, this is complete: purpose, tier gate, all parameter meanings, and default response shape are all present. Return values are additionally described even though an 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 description coverage is 0%, so the description carries the full burden and does: track with concrete examples, race_code and country with their accepted values and defaults, window range (14-365), condition examples plus the constraint that it only applies with window, and the distance syntax including inclusive range format and its effect on the response.

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 ('Get barrier/box bias statistics for a track') and immediately scopes it as Pro tier. This is clearly distinct from sibling tools like get_jockey_stats or get_trainer_stats without opening any schema.

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

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

Gives a real usage rule — prefer the distance band or a `distance` scope over whole-track figures when advising on a particular race — plus a Pro-tier prerequisite. It does not, however, route the agent among sibling tools or say when a barrier-bias lookup is appropriate versus other stats tools.

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 read-only, idempotent and not open-world, so the bar is lower. The description still adds non-obvious behavioural context: the Pro-tier gating, the stale ~2019 data window, and fuzzy partial-name matching — all things the agent cannot derive from annotations or schema.

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

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

Front-loads the purpose and return content, then a compact Args block. The parameter list is somewhat redundant in form, but since the schema has zero descriptions it earns its place 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?

An output schema exists, so return values need not be explained, and the description covers gating, data staleness, matching behaviour and parameter ranges. It stops just short of stating error/empty-result behaviour for unmatched names, which is the only real 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 description coverage is 0% and no enums are declared, so the description carries the full burden — and it does: it documents case-insensitive partial matching for trainer_name, the three valid race_code values with 'gallops' as default, and the 14–365 day range for window. Without this text the parameters would be unusable.

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 ('Get') and resource ('track-by-track performance statistics for a trainer') and enumerates the return content: career runners, win rate, per-venue breakdown. The trainer focus separates it cleanly from the sibling get_jockey_stats.

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 '(Pro tier)' tag and the note that stats use a ~2019 data window imply context and eligibility, but the description never says when to prefer this over neighbours like get_runner_profile or search_runner, nor what to do when a trainer matches nothing.

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, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds real behavioral context beyond that: a Pro tier entitlement requirement and a hard 'minimum 3 characters' constraint on the query. It does not mention pagination or result limits, keeping it from a 5.

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

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

Front-loaded with purpose, then the return contents, then the hand-off tool, then the arg list. Every sentence earns its place, and the Args block is justified rather than redundant because the schema has zero parameter descriptions.

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

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

Despite an output schema existing, the description usefully previews the return shape (IDs, sire/dam for disambiguation, career starts) and closes the workflow loop to get_runner_profile. The Pro tier gate and query minimum length are the kinds of constraints an agent needs before calling, and both are present.

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 0% and there are no enums in the schema, so the description carries the full burden — and it does: query (partial name, min 3 chars), race_code with its three allowed values and the default of 'gallops', and country with four allowed codes. This supplies value the schema does not.

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 ('Search for a runner (horse/greyhound) by name'), names the resource domain, and distinguishes itself from the sibling get_runner_profile by clarifying that it returns IDs rather than full stats. An agent can pick between the two 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 clear context (search by partial name) and an explicit next step: 'Use the returned runner ID with get_runner_profile() for full stats.' That routing is genuinely helpful, but there is no stated when-not-to-use or comparison against other lookup siblings, 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.