skipodds

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

With no annotations, the description carries the full burden. It discloses the read-only nature, the specific error behavior (fixture_not_found), and the interpretation of thin markets (low bookmaker count). This is rich behavioral context.

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: first defines the output, second gives usage guidance and alternatives, third covers error/edge cases. Every sentence earns its place with no fluff.

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

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

Given a simple 2-param tool with no output schema, the description fully covers what's returned, when to call, error behavior, and sibling differentiation. Nothing important is missing.

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

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

Schema coverage is 100%, with detailed descriptions for both id and sport including ordering guidance. The description adds no extra parameter meaning beyond referencing the fixture id in usage context, 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?

The description clearly states the tool returns 'One fixture in full' with specific contents (fair probability, fair odds, bookmaker count, last updated). It distinguishes from siblings by explicitly naming get_fixture_movement and implying list_fixtures as a prerequisite.

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 use (already have a fixture id) and when not (use list_fixtures first). Also gives an explicit alternative for price changes: get_fixture_movement.

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?

With no annotations, the description fully carries the burden. It discloses read-only nature, error behavior for unknown ids (fixture_not_found), interpretation of short series (recent survey, not failure), and ordering (oldest first). This goes well beyond basic expectations.

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 with no fluff. The first sentence immediately states what it returns, the second covers use cases and alternatives, the third addresses edge cases. Every sentence earns its 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?

Given three parameters, no output schema, and no annotations, this description is remarkably complete. It covers return content, order, use cases, read-only status, error handling, and a key interpretation caveat, enabling confident tool selection and invocation.

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 outer description adds minimal parameter-specific value, though the error note about id is a slight bonus, but not enough to raise the score given the schema already documents parameters thoroughly.

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

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

The description clearly states the tool returns a time series of one fixture's fair probability movements, distinguishing it from get_fixture (current price) and list_fixtures (listing). The verb 'moved' and resource 'fixture's fair probabilities' are specific and unambiguous.

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 use cases are given ('spot line movement, steam or drift', answer 'has this shortened since yesterday'), and an explicit alternative is named ('Use get_fixture instead for the current price alone'). This provides clear guidance on when to use this tool versus 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?

With no annotations, the description discloses read-only status, empty-list behavior instead of error, de-vigged probability methodology, and sport-by-sport recency windows. However, it claims '13 sports' while the schema enum lists 12 distinct sports (11 enum values plus default soccer), which is a minor factual inconsistency.

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 'START HERE' and packs relevant details (sports, bookmakers, de-vigging, recency, empty-list) into a dense paragraph without fluff. It earns its length.

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 complex read-only list with no output schema, the description explains return behavior (empty list, IDs), probability derivation, and how to discover competition slugs. The '13 sports' count inconsistency with the schema is a minor gap, preventing a perfect score.

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 covers all three parameters with descriptions; the tool description adds a tip that competition slugs appear on returned fixtures and that soccer is the default when sport is omitted. This enhances discoverability 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 clearly identifies the tool as listing upcoming and recent fixtures with fair win probabilities, and explicitly contrasts it with get_fixture (for existing ids) and list_tournament_outrights (for tournament winners), distinguishing it from all 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?

States 'START HERE' as the entry point, explains that fixture IDs feed into get_fixture/get_fixture_movement, and names alternatives for when you already have an ID or want outrights. Also gives recency windows and empty-list behavior.

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?

No annotations are provided, so the description carries full behavioral disclosure. It states the tool is read-only, explains the normalisation of probabilities, clarifies empty-list semantics (nothing priced, not an error), and specifies the error for an unrecognised key. It also warns that tournament_key is not an API key, adding useful behavioral context.

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 information-dense but not overly long; each clause adds value. The opening is a noun phrase rather than a verb-first sentence, but the structure flows logically from list behavior to per-tournament behavior to error conditions. Slightly verbose, but every sentence earns its place, so a 4 is appropriate.

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 two-mode tool with no output schema and no annotations, the description fully covers invocation patterns, return semantics, edge cases, and error handling. It gives the agent everything needed to select and call the tool correctly in context, including sibling differentiation and authentication clarification.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by instructing that tournament_key must be taken verbatim from a no-argument call and explicitly noting it is not an API key. This goes beyond the schema's parameter description, justifying a 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?

The description clearly states the tool lists golf tournament outright-winner probabilities, normalised across the priced field. It explicitly distinguishes from soccer via list_tournament_outrights, and the name itself conveys the resource. This is a specific verb+resource with sibling differentiation.

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 instructions are given: call with no arguments to list tournaments, then pass a tournament_key to get details. It also clarifies when not to use it (soccer → use list_tournament_outrights) and explains edge cases like empty lists and unrecognised keys. This is exemplary usage 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses key behavioral traits: probabilities are normalised across teams that can still win, eliminated teams are dropped, the field sums to 100%, the operation is read-only, and an unrecognised competition slug returns an empty field instead of an error. This goes well beyond a generic safety hint.

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 five sentences long, yet every sentence carries distinct, high-value information: core definition, usage context, sport exclusions, error behavior, and read-only status. It is front-loaded with the main purpose and structured logically without repetition or 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?

Despite having no output schema and no annotations, the description provides complete context for an agent to both select and invoke the tool correctly. It covers market semantics, sport applicability, alternatives, the optional parameter behavior, and edge-case error handling. Sibling tool names further reinforce the mental model.

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 the input schema already states that omitting the competition returns every competition and allows slug discovery. The description adds only an example slug ('premier-league-2026') and reinforces soccer-only scope, which is useful but does not substantially extend the schema semantics. 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?

The description clearly identifies the resource ('outright winner probabilities for a soccer competition') and the action ('list'), with a scope qualifier ('normalised... eliminated teams are dropped'). It also distinguishes from sibling tools by naming list_fixtures for individual matches and list_golf_tournaments for golf.

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 explicitly states when to use this tool ('Use for "who wins the league/cup"') and exactly when not to, naming alternatives: list_fixtures for individual matches and list_golf_tournaments for golf. It even instructs the agent to state that the other eleven sports have no outright market rather than retrying, which is exceptional guidance.

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