PinnWire — Pinnacle Odds, Price Drops & No-Vig Fair Prices

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it names the source (Pinnacle), the time buffer, the returned concepts (drop percentage and nvp), and explicitly cautions that nvp is an estimate and that the signal does not prove informed money. This helps the agent set expectations without needing to call the tool.

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 dense but every clause contributes meaning: the core purpose is front-loaded, the nvp definition is justified by its use cases, and the limitations are stated explicitly. No filler or redundant restatement of the tool name exists.

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 there is no output schema, the description does a good job naming the expected returned fields: from/to decimal prices, drop %, and nvp. It also provides the time buffer and caveats. A minor gap is that the exact output shape, ordering, or grouping of records is not specified, but this is not critical for selecting and invoking the 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 description coverage is 100%, so all four parameters are already documented. The description adds broader context around drops and nvp, but it does not add parameter-specific semantics beyond what the schema provides. This matches 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?

The description clearly identifies the tool as returning recent Pinnacle price drops, with an explicit definition of what counts as a drop: outcomes whose odds shortened. It is readily distinguishable from sibling tools like get_live_odds or get_prematch_lines because it focuses specifically on drops/steam moves rather than general odds.

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 conveys when the data is useful (recent Pinnacle drops, roughly last 3 hours) and what it cannot do (does not compare sportsbooks or prove informed money). However, it never explicitly tells the agent when to prefer this tool over siblings such as get_live_odds or get_prematch_odds, leaving the choice 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?

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds context about the data being current full odds and the event categories, but it does not describe the response format or any edge-case behavior. With the annotation handling the safety profile, a 3 is appropriate.

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 two concise sentences: the first front-loads what the tool does and the second gives the usage condition. Every word earns its place, and there is no redundancy with the schema or annotations.

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 one-parameter, read-only tool, the description covers what the tool does, which event types it applies to, and where to get the event_id. The lack of an output schema makes 'full odds detail' somewhat underspecified, but nothing needed to invoke the tool correctly 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% and event_id is described as 'Event id from another odds tool.' The description adds value by naming get_live_odds / get_prematch_odds as the source tools and by specifying that lookup is by event_id, giving the agent more actionable guidance than 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 description states a specific operation: retrieving current full odds detail for one event by event_id, and it names the covered event types (live, prematch, special). This distinguishes it from the sibling list tools like get_live_odds and get_prematch_odds, which return collections of events rather than a single event's detail.

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 tells the agent to use get_event after get_live_odds / get_prematch_odds returns the id, establishing a clear call sequence. It does not enumerate exclusions or alternative tools for other data types, but the primary workflow is clearly conveyed.

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 readOnlyHint=true, the safety profile is already covered. The description adds valuable behavioral nuance by clarifying that generated_at is response time rather than the source odds tick, and that last_odds_update_seconds_ago represents feed-update age. This helps avoid misinterpretation of the returned timestamps.

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 a single focused statement followed by a brief, important clarification. It wastes no words and front-loads the core purpose ('Current feed status') before giving field-level detail.

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?

Since there is no output schema, the description carries the burden of explaining return values. It covers the main fields and the timestamp semantics, which is sufficient for a no-parameter health-check endpoint. It may not describe possible status values or formatting, but this is a minor gap given the tool's simplicity.

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 input schema has zero parameters, so there is nothing to document. The baseline for zero-parameter tools is 4, and the description does not conflict with or need to compensate for any parameter details.

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 exactly what the tool returns: current feed status with events in store and feed-update age. This clearly distinguishes it from the sibling tools, all of which relate to odds, drops, events, or sports lists.

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 provides no explicit guidance on when to use this tool versus alternatives. There are no when-to-use or when-not-to-use statements, and no mention of sibling tools. Usage must be inferred entirely from the name and the word 'status'.

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 carry readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context about market coverage and Pinnacle as the reference source, but it doesn't address latency/freshness timing, pagination behavior, or whether results are limited by max_events beyond the schema. This is adequate but not rich.

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 the core purpose and each sentence has a role: source credibility, return contents, use cases, exclusions. The 'sharp bookmaker' phrase is slightly promotional but earns its place by explaining why Pinnacle specifically matters; overall compact and structured.

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 only 3 params, 100% schema coverage, and a read-only annotation, the description needs to carry the output/use-case burden, and it does by naming market types and typical applications. It could add a note on response shape or default pagination, but max_events already documents limits, so the definition is complete enough for an agent to invoke 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 description coverage is 100%, so the baseline is 3: every parameter (sport_id, max_events, include_specials) is already documented clearly in the schema. The description's mention of 'optional props & specials' reinforces include_specials but adds no essential meaning 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 opens with a specific verb and resource: 'Current live (in-play) sports betting odds from Pinnacle' and enumerates the returned market types (moneylines, spreads, totals, team totals, specials). It distinguishes itself from siblings by emphasizing live/in-play and explicitly disclaiming historical archive and bet placement, so an agent can tell it apart from get_prematch_odds and similar 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?

Use cases are explicitly listed — live odds displays, +EV screens, model features, Pinnacle leg of cross-book comparison — and exclusions are stated ('Not a multi-book aggregator, historical archive, or bet-placement tool'). It doesn't name sibling tools like get_prematch_odds as the alternative, relying on 'live' vs 'prematch', so it falls just 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context—'current', 'compact', 'no period structure', and the optional market_type filter—but it does not disclose response format, default behavior when no filter is supplied, or pagination limits. This is acceptable but not deeply transparent.

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 a single compact sentence that front-loads the core purpose and ends with the optional parameter, which mirrors how an agent would read it top-down. No filler or redundant explanation.

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?

The tool is simple and the description covers the core use case, but with no output schema the description should ideally say more about the shape of the returned lines—e.g., whether both sides are included, what fields appear, or how 'compact' affects the structure. Without that, an agent can select the tool confidently but may be uncertain about parsing 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%, so event_id and market_type are already well documented. The description repeats the enum values and calls market_type a 'filter', which aligns with the schema's 'Limit the response to one market type' but adds no new semantic detail. A baseline score of 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 states a specific resource ('one prematch event'), a concrete data type ('current full-game lines'), and a defining characteristic ('no period structure'), making it clear what the tool returns. It also names the optional market types, further specifying scope. This distinguishes it from live-odds or period-based sibling tools even without naming them 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?

The description implies usage for a single prematch event with compact full-game lines, and the 'no period structure' note hints at when not to use it. However, it does not explicitly mention alternative sibling tools or state when to prefer get_prematch_odds or get_live_odds, leaving the routing decision mostly 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 provide readOnlyHint=true. The description adds useful behavioral context: it returns current snapshots, callers may store them for their own analysis, and it is explicitly not a historical archive. It does not detail rate limits or update cadence, but the bar is lowered by the read-only annotation.

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 primary purpose and scope. The use-case phrase and the non-archive clarification are both informative and earned; there is 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 partially compensates by referring to get_live_odds for shape, which is a sibling the agent can inspect. It covers currentness, sport-scoping, and snapshot storage, but does not state response fields or refresh behavior on its own.

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 are already fully documented. The description adds no parameter-specific meaning beyond the schema, making the baseline 3 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 names a specific verb and resource: it returns current prematch Pinnacle odds for one sport. It also distinguishes itself from live odds by saying 'prematch' and from a historical archive by explicitly stating 'this is not a historical opening/closing-odds archive.'

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 clear context on when to use the tool: for current prematch odds, handicapping, EV screens, and model features. It states an exclusion ('not a historical opening/closing-odds archive'), though it does not explicitly name alternatives like get_live_odds or get_prematch_lines.

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 description adds the operational detail that the tool does not consume API quota, which goes beyond the readOnlyHint annotation and addresses rate-limit concerns. It also specifies the exact number of covered sports, giving concrete 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?

Two short sentences deliver the purpose, usage timing, and a behavioral note with no wasted words. The key mapping purpose is front-loaded before the quota note.

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 zero-parameter, read-only tool with no output schema, the description provides enough information for an agent to know when and why to call it. The mapping to sport_id values and the prerequisite relationship to odds tools make the tool fully understood.

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 tool has zero parameters, and the schema coverage is 100%, so there is no parameter information needed. The description appropriately focuses on the tool's purpose rather than parameter details.

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 a specific verb and resource: mapping the 13 covered sports to sport_id values. It distinguishes the tool from sibling odds tools by positioning it as a prerequisite mapping step, so an agent can immediately understand its role.

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 says to use this tool 'before calling the odds tools,' providing clear context for when it should be invoked. It does not mention alternatives or exclusions, but none of the sibling tools appear to offer the same mapping functionality.

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