ParlayAPI

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

No annotations are provided, so the description carries the burden. 'Get info' implicitly indicates a read-only operation, but the description does not explicitly state that it has no side effects, does not consume credits, or that no additional authentication is needed. It is adequate for a zero-parameter info endpoint but leaves these behaviors implicit.

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 sentence that front-loads the action and resource, then enumerates the return fields in a compact, readable list. Every word earns its place; there is no filler or redundancy.

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 the tool has no parameters and an output schema exists, the description is nearly complete. It names the key return categories, which is sufficient for an agent to select and call it. It could be slightly richer by explicitly confirming the operation is read-only, but that gap is minor for this simple endpoint.

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, so there is nothing to document. The baseline for 0 params is 4, and the description appropriately focuses on return content rather than inputs. No parameter ambiguity exists.

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 action ('Get info about the API key currently in use') and specifies the exact resource and output categories (tier, credits remaining, billing period). It is clearly distinguishable from the sibling tools, none of which concern account or API key information.

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 makes its use case evident: any time an agent needs details about the current API key's tier, credits, or billing cycle. There is no explicit comparison to alternative tools, but since none of the siblings provide account information, no exclusion is necessary. Clear context, though not formally worded as 'use when...'.

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 behavioral burden and does so thoroughly. It discloses the scanning behavior, no-vig grading, +EV filtering, ranking logic, edge_alerts return, scoping to user books, and the player-props-only restriction. This gives the agent a realistic model of what the tool does beyond the bare 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?

The description is well structured: the purpose is front-loaded, the sibling relationship is explained next, and the Args block maps directly to the schema. Every sentence adds substantive information, with 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?

For a discovery tool with an output schema present, the description covers input semantics, scope, exclusions, and sibling alternatives completely. An agent has everything it needs to decide when to invoke the tool and how to populate parameters 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%, but the description documents all five parameters with defaults, allowed values, and semantic context. For example, it explains that min_edge is a percentage against the no-vig fair line and that books overrides region, which is far more useful than the bare schema names.

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 clear value proposition ('What should I bet right now? Ranked +EV plays for a sport') and names the resource and action precisely. It explicitly identifies itself as the discovery counterpart to parlayapi_verdict, which differentiates it from the closest sibling without requiring schema inspection.

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 states exactly when to use this tool: for discovery across the whole board, filtering to +EV plays at the user's books, and ranking by edge. It also provides clear exclusions and routes users to parlayapi_verdict for game moneylines, giving explicit when-to-use and when-not-to-use 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the output granularity ('one row per game / market / side with the bookmaker offering the best price') and that bookmakers restricts the search to selected books. It does not disclose tie-breaking when prices are equal, odds format (decimal vs American), or data freshness — all behaviors a line-shopping bot would reasonably care about.

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 crisp introductory sentences followed by a compact three-line args block. The purpose and return shape are front-loaded, and every sentence adds distinct information — no filler and no repetition of schema titles.

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 lookup with an output schema present, the description covers purpose, output shape, and all parameters. Remaining gaps — tie-breaking for equal best prices and odds format — are minor and arguably covered by the output schema. It omits auth and rate-limit notes, but that is consistent with the sibling set.

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 the description fully compensates: sport_key gets a concrete example ('baseball_mlb'), market gets the valid value list ('h2h | spreads | totals') that the schema lacks as enums, and bookmakers gets both semantics ('Restrict the search to these books') and optionality. Every parameter is meaningfully documented beyond its bare title.

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: 'Find the best (highest) price for each outcome across bookmakers.' The return shape ('one row per game / market / side with the bookmaker offering the best price') further pins down behavior and structurally separates it from raw-odds siblings like get_odds and price-difference tools like find_arbitrage. It does not explicitly name a sibling to distinguish from, so differentiation is structural rather than explicit.

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 for line-shopping bots' gives a concrete scenario indicating when this tool shines, which is a real usage signal. However, it never states when not to use it or names alternatives such as find_arbitrage, consensus, or get_odds for related-but-different needs. Usage context is implied rather than explicit.

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 carries the full burden of behavioral disclosure. It goes beyond a bare statement by revealing that the operation is public, requires no API key, and what the coverage gates actually measure. It does not mention rate limits or detailed response behavior, but the output schema fills part of that gap.

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 compact, front-loaded with the primary purpose, and every sentence contributes useful context: what the tool returns, access requirements, and what the coverage gates mean. There is no fluff 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?

For a simple public read operation with an output schema and optional parameters, the description provides adequate high-level context. However, it falls short on parameter semantics and does not explicitly guide the agent on when to use this tool versus related siblings like source_quality.

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 compensate for the undocumented parameters include_warn and window_minutes. It does not explain either parameter; the closest hint is that 'freshness' checks relate to a time window, but no concrete mapping is provided.

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: 'Return public per-book coverage gates.' It then adds what those gates represent—whether sources survive freshness, normalization, database, REST-shape, and stream-shape checks—which distinguishes it from sibling tools like parlayapi_source_quality or odds-related 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?

It clearly states 'No API key required' and that the data is public, which helps an agent know access is unauthenticated. However, it does not explicitly say when to prefer this tool over alternatives or when not to use it, so the usage guidance is mostly implied rather than stated.

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. It transparently states that a URL is generated and includes billing details (monthly tiers with prices). However, it doesn't disclose whether it creates a Stripe Checkout session as a side effect, requires authentication, or imposes any conditions on the email address.

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 short sentences plus a clean tier list. The primary action is front-loaded, and every line contributes information (purpose, tier options, billing cycle). No filler or redundancy.

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-parameter tool with an output schema, the description covers the core purpose and parameters well. However, it doesn't clarify whether the email must belong to an existing user, how this checkout link relates to signup or magic_link flows, or whether generating the URL has any side effects. These gaps make it slightly incomplete.

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 compensate. It does so effectively for the 'tier' parameter by enumerating valid values and prices (starter $5, pro $20, etc.) and clarifying they are monthly subscriptions. The 'email' parameter is only implied as 'the user,' though its schema title 'Email' is self-explanatory.

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's action: 'Generate a Stripe Checkout URL the user can click to upgrade.' The verb and resource are specific, and the word 'upgrade' signals a difference from sibling tools like signup or magic_link, though it doesn't explicitly name alternatives.

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 context ('upgrade') and provides tier options with pricing, which guides parameter selection. However, it doesn't explicitly state when to use this tool versus siblings like parlayapi_signup or parlayapi_magic_link, nor does it mention exclusions or prerequisites such as requiring an existing account.

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 carries the full behavioral burden and does real work: it discloses the exact output composition (average, best, and worst price per event/market/player/line) and proactively calls out an edge case — soccer and 3-way markets return separate home/draw/away consensus rows. It omits data recency and pagination details, but the operation is clearly non-destructive and the get-style behavior is 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 purpose is front-loaded in the first sentence, followed by a tight return-value summary and a compact Args block. Every sentence earns its place; the only mildly expendable phrase, 'a sharp baseline for line-shopping,' doubles as usage context, so nothing is wasted.

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 description is sufficient for calling the tool: both parameters are documented, the output shape is stated, the 3-way market special case is covered, and the existing output schema supplies the rest of the return contract. The main gap is missing sibling differentiation — with 20 sibling tools including get_odds, best_line, and find_arbitrage, one sentence on when to choose consensus over those would fully close the loop.

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%, yet the Args section fully compensates: sport_key receives realistic examples ('baseball_mlb', 'soccer_epl') and markets receives both a format rule (comma-separated market_keys) and an example ('moneyline,totals'), plus explicit optionality. Both parameters gain meaning that the bare schema — type, title, default — does not provide.

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 precise verb+resource construction: 'Get consensus (average) odds across all bookmakers per market.' The notion of a consensus average across all bookmakers inherently distinguishes it from siblings like parlayapi_best_line (single best price) and parlayapi_get_odds (raw odds), and the stated return scope (average, best, worst per event/market/player/line) removes any ambiguity.

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?

Usage context is implied via 'a sharp baseline for line-shopping' — an agent can infer this tool is for market-wide price comparison. However, there is no explicit when-to-use/when-not-to-use statement and no named alternatives among the 20 siblings (best_line, find_arbitrage, get_odds), so routing to this tool over its neighbors relies on 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?

No annotations are provided, so the description carries the full burden. It discloses the core detection rule (<100% implied probability), market support (home/draw/away including draw-anchored arbs), and the rationale/risk behind exclude_exchanges (no-volume asks). It does not discuss rate limits or execution caveats, but it transparently explains the main behavioral guarantees and caveats.

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?

First sentence front-loads the tool's purpose; the next sentence gives the underlying arbitrage rule; the Args block is compact and each line adds information not present in the schema. 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 an output schema present, the lack of an explicit return-value description is not a gap. The description covers the one required arg, all defaults, optional filters, supported market types, and a practical caveat about exchange asks, so an agent has enough 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 0%, yet the Args block documents all four parameters with concrete examples (sport_key 'soccer_epl'), units and default values (min_profit '1.5 for 1.5%', default 0), optionality, and delimiter format for markets. This fully compensates for the empty schema descriptions.

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?

First sentence names an exact verb ('Find') and resource ('guaranteed-profit arbitrage opportunities across bookmakers'), and the body's 'combined implied probability under 100%' distinguishes it from related valuation tools like find_ev or find_middles. The distinction is functional rather than by name alone.

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?

Describes clear use-case context: locating locked-in-profit arbs, including 3-way soccer/draw markets and optional exchange exclusion. It does not explicitly name when to prefer parlayapi_find_ev or parlayapi_find_middles, so it earns a 4 rather than a 5, but an agent can infer the right selection from the stated purpose.

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 carries the full burden; it usefully explains the no-vig derivation, default Pinnacle baseline, and the special three-way soccer handling. It does not address read-only status, rate limits, data freshness, or prerequisites, though these are less critical for a search-like 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 front-loaded with the core purpose and follows with a clearly formatted Args section; the extra sentence on three-way soccer earns its place. Slight redundancy exists between the opening summary and the second sentence's restatement of the comparison.

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 4-parameter lookup tool with an output schema, it provides the algorithm, defaults, accepted value examples, and a market-specific edge case. It omits only minor operational details such as where sport_key values come from and how soft books are selected, which are inferable from sibling tools.

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?

Even though schema coverage is 0%, the Args section explains all four parameters with meanings, defaults, and examples: sport_key shows concrete formats, sharp_book names the default, min_edge gives a 3% example, and markets clarifies formatting. This fully compensates for the empty schema descriptions.

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 and object: 'Find positive-EV bets vs a sharp book's no-vig fair line.' The second sentence elaborates the exact comparison (soft book odds vs sharp no-vig fair probability), which clearly sets it apart from siblings like find_arbitrage or find_middles.

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 makes the intended use explicit: detect +EV prices against a sharp book's no-vig line, with a soccer three-way nuance. It does not explicitly name sibling alternatives or say when not to use it, but the search/analysis context is clear enough to separate it from arbitrage and middles.

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 of behavioral disclosure. It explains what the tool scans, what a middle is, and what each result contains, including the economic fields. It does not mention rate limits, auth needs, or whether it reads live odds, but for a search/find tool the disclosed behavior is substantive and non-misleading.

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 longer than strictly necessary, but every major section earns its place: the concept explanation, the scan scope, the output summary, and the parameter semantics. The main purpose is front-loaded and the Args section is cleanly structured, though the extended example sentence could be trimmed without losing much value.

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 four-parameter find tool with an output schema, the description covers the key context: when to use it, what it scans, what results contain, and what each parameter means. It does not enumerate all possible market_keys or failure modes, but those are not essential given the output schema and examples.

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 document the parameters. It does so thoroughly: sport_key has examples, min_gap has units and default, markets explains comma-separated format and gives example values, and include_props explains what it controls and its default. This fully compensates for the absent schema descriptions.

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: 'Find cross-book middle opportunities.' It then defines the concept precisely with a concrete example and names the exact scan scope (game totals, spreads, player-total props), making it easy to distinguish from other sports-betting 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 clearly implies when to use the tool: when the user wants middle opportunities across books. However, it does not explicitly compare with sibling tools like parlayapi_find_arbitrage or parlayapi_find_ev, nor does it state when not to use this tool. The usage context is clear, but alternatives are not addressed.

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 the burden of behavioral disclosure. It states the scope ('from all configured bookmakers') and the output type ('game-level odds'), which is useful, but it does not disclose behaviors like data freshness, pagination, or whether the call is a live versus cached read.

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 compact and well-structured: a one-sentence purpose followed by a tight Args list. Every line contributes necessary information without unnecessary prose.

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 that an output schema exists, the description does not need to explain return values. It covers all input parameters and the core behavior. It is slightly incomplete only in lacking alternative-tool routing and any caveats about bookmaker configuration or data availability.

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 the description fully compensates by documenting every parameter: sport_key examples, comma-separated markets, accepted regions, optional bookmakers with examples, and odds_format choices. This adds substantial meaning beyond the bare schema titles and defaults.

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: 'Get game-level odds for a sport from all configured bookmakers.' This clearly identifies the tool's function and scope, and the phrase 'game-level odds' helps distinguish it from sibling tools like parlayapi_get_props.

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 no explicit guidance on when to use this tool versus alternatives such as parlayapi_best_line, parlayapi_consensus, or parlayapi_get_props. Usage context is only implied by the tool name and resource scope, not stated.

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 transparency burden. It clearly discloses the tool is public and requires no API key, which is important behavioral information. It could further describe read-only/non-destructive behavior, but 'pricing table' strongly implies a safe retrieval.

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, purposeful sentences with no filler. The core function is front-loaded, and the use case plus authentication note are included efficiently in the second sentence.

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 zero-parameter read-only lookup, the description is complete. It states what is returned, that no auth is needed, and the practical scenario for calling it. The output schema covers any return-shape details.

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, so there is nothing for the description to clarify about inputs. The description appropriately adds no param-related noise. Per the baseline for no-parameter tools, this earns 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 states a specific verb ('Return') and a concrete resource ('current public pricing table'). It is immediately clear what the tool does and there is no ambiguity with any of the listed sibling 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 explicitly states when to use the tool: 'Use this when an agent needs to explain which tier unlocks a workflow before sending a checkout link.' It also clarifies that no API key is required, giving clear access conditions.

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 the full burden of behavioral disclosure. It only states that the tool gets prop odds and documents parameters; it does not mention response structure, data freshness, whether odds are live, or any side effects of include_futures. This is minimal disclosure beyond the obvious read operation.

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 efficient: one purpose sentence followed by a cleanly formatted Args block with examples. Every line earns its place and there is minimal fluff. The formatting is scannable and front-loaded.

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 don't need to be described, but the description lacks guidance on which sibling tools to use for non-prop odds or how bookmaker coverage is determined. For a five-parameter tool with no annotations, the parameter documentation is strong, but the missing sibling context and operational details make it only moderately complete.

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%, but the description fully compensates by explaining every parameter with concrete examples: sport_key values, comma-separated market keys, bookmaker names, player name filtering, and the default behavior of include_futures. This adds substantial meaning beyond the bare input schema and leaves no parameter ambiguous.

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+resource statement: 'Get player prop odds for a sport.' This clearly identifies the tool's function and narrows its scope to player props, which helps differentiate it from general odds tools. However, it does not explicitly name or contrast with sibling tools like parlayapi_get_odds, so the differentiation is implicit rather than stated.

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 parameter examples (markets, bookmakers, player) imply use cases such as filtering by market or player, but the description never states when to choose this tool over alternatives like get_odds, best_line, or consensus. There is no explicit when-to-use/when-not-to-use guidance, leaving the decision 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?

With no annotations, the description must carry the burden, and 'List' reasonably communicates a read-only operation with no side effects. However, it does not disclose the effect of the active_only parameter or the default filtering behavior, and it gives no indication of output shape beyond sport keys.

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 short, front-loaded with the primary action, and then immediately gives the practical usage context and concrete examples. Every sentence earns its place and there is no redundant 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?

This is a low-complexity list tool with one optional parameter and an output schema, so the description does not need to detail return values. It gives enough context for an agent to use the tool in a workflow, though mentioning the active_only default would make it fully complete.

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 should compensate for the single active_only parameter, but it never mentions it. The phrase 'available sport keys' only weakly implies active-filtering behavior, leaving the agent to infer parameter semantics from 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 clearly identifies a specific verb ('List'), a resource ('available sport keys'), and their purpose in subsequent calls, with concrete examples like baseball_mlb. It does not explicitly differentiate itself from sibling list-like tools such as parlayapi_live_sports, so it stops just short of a 5.

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 these in subsequent calls' gives clear workflow context and signals that this tool is a prerequisite for callers needing sport keys. It does not state exclusions or compare against alternatives, but the intended usage 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?

With no annotations provided, the description carries the behavioral burden. It discloses that no API key is required, that this is a public endpoint, and that it returns a preview payload. It also explicitly calls out the tool's limitation as a demo surface. It does not mention rate limits, data freshness, or mutation behavior, but for a read-oriented public preview endpoint this is reasonably 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 three concise sentences. The opening line delivers the core action, the second provides key auth and content details, and the third sets expectations. Every sentence earns its place without redundancy 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?

The description provides the essential operational context: what the tool returns, that it is public, and that it is not for paid odds use. Since an output schema exists, return-value documentation is not required here. The only notable gap is the absence of parameter semantics and potential rate-limit or freshness caveats, but the tool is simple enough that the overall picture is largely complete.

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 the description does not mention the 'limit' or 'sport_key' parameters at all. The parameter names offer some self-evident meaning, but there is no explanation of accepted sport_key formats, how limit interacts with results, or defaults. The description fails to compensate for the missing schema documentation.

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: 'Return the public best-line command center payload.' It further clarifies what it contains (current games, participating books, best available real prices) and frames it as a discovery/demo surface. It distinguishes from 'paid odds endpoints' as a category, but does not name sibling tools explicitly, so it falls just short of full 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?

The description gives clear context: it is a public, demo, and discovery surface, and explicitly states it is 'not a substitute for the paid odds endpoints.' This conveys when not to use it, but it does not name specific alternative tools or provide a direct when-to-use comparison, so it lacks explicit sibling routing.

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 carries the behavioral disclosure burden. It usefully states that no API key is required and that the result is meant to feed the exact sport_key into a subsequent call. It does not mention rate limits or matching behavior, but for a read-only search tool the key behavioral details are 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?

The description is three short, purposeful sentences. The main capability is front-loaded, followed by the auth note and the practical use case. There is no filler or redundancy.

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-parameter search tool with an output schema, the description covers the what, why, and auth requirement. The main gap is the undocumented 'limit' parameter and a lack of guidance on fallback behavior if no match is found, but these are minor 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?

Schema description coverage is 0%, so the description must compensate. It clearly implies that 'q' accepts natural-language names for teams, players, or leagues, but it never explicitly maps parameters and says nothing about 'limit.' The parameter names are partly self-explanatory, but coverage is incomplete.

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 action and resource: 'Search live teams, players, and sport keys.' It also clarifies the tool's role as a natural-language resolver that supplies the exact sport_key for downstream calls, which differentiates it from sibling tools like parlayapi_list_sports and parlayapi_live_sports.

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 states exactly when to use the tool: when the user refers to a team, player, or league by natural-language name and the agent needs to resolve it to a sport_key. It does not explicitly mention alternatives or when not to use it, but the intended context is clear enough.

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 the burden of behavioral disclosure. It states that no API key is required and clearly indicates this is a read-only listing operation ('List... returns...'). It also reveals what the response contains: sport keys, live event counts, and book counts. It does not discuss rate limits or error behavior, but these are not critical for a simple zero-parameter list.

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 three short sentences with no filler. The primary action is front-loaded in the first sentence, the authentication requirement is a single clear note, and the return contents and purpose are compactly covered.

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 tool with an output schema and no annotations, the description is complete: it states scope, auth requirements, response contents, and intended use. The only minor ambiguity is the exact meaning of 'retail /live surface,' but the rest of the description compensates by explaining what the agent can discover.

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 are no parameters in the input schema, so the baseline is 4. The description cannot add parameter-level meaning, but it usefully describes what the invocation will return, which is the only relevant semantic information for a parameterless call.

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: 'List currently active live sports on the retail /live surface.' It clearly distinguishes this from siblings like parlayapi_list_sports by emphasizing 'currently active' and by stating it returns live event and book counts, not just sport names.

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?

Usage is implied through the phrase 'so agents can discover what is active right now,' which tells the agent when this tool is useful. However, it does not explicitly mention when not to use it or name alternatives among the many sibling tools, such as parlayapi_list_sports or parlayapi_live_search.

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 carries the transparency burden. It discloses the key behavioral trait that response is always ok=true to prevent account enumeration, and that the link is delivered by email. It does not mention rate limits or link expiration, but covers the most important behavioral nuance.

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 short sentences with no filler. The core action is front-loaded and the important anti-enumeration behavior is presented immediately after.

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 single-parameter email/send tool with an output schema, the description covers the essential behavior and purpose. It could be more explicit about what happens when the email does not exist (i.e., no email is sent), but the anti-enumeration statement implies this.

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 must add meaning. It does clarify that the email parameter is the recipient and is checked against existing accounts, and it explains the enumeration-protection behavior. It does not specify format or additional constraints, but this is a single simple string parameter.

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?

Description uses a specific verb ('Email') and resource ('magic-login link for an existing ParlayAPI account'), making the action unmistakable. It also implicitly differentiates from sibling parlayapi_signup by targeting existing accounts.

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 what the tool does but gives no explicit guidance on when to choose it over alternatives such as signup or account_info. No conditions, prerequisites, or exclusions are stated.

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 disclosure burden. It explicitly lists the outputs: no-vig fair price, best book for the whole slip, EV, weakest leg, same-game correlation warnings, and payout when stake is provided. It also discloses the book-scoping behavior and the optional book parameter. It does not mention side effects, but 'grade' clearly implies an analysis-only operation.

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 well-structured and front-loaded: the first line states the core purpose, the next paragraph summarizes outputs, and the Args section gives parameter details. The example leg objects are somewhat verbose but necessary because the legs parameter is otherwise opaque. There is little wasted text.

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 tool with no annotations, the description is largely complete: it covers the legs object shape, the 2–12 leg constraint, book scoping, and optional stake/book parameters. The output schema covers return values, so the description does not need to detail them. The main incompleteness is the total omission of 'kelly' and 'bankroll', which prevents full understanding of all available controls.

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 is the only source of parameter meaning. It richly documents legs with a worked example and field list, and it explains region, books, stake, and book. However, the schema includes 'kelly' and 'bankroll', which are completely absent from the description, leaving the agent to guess their purpose. This is a clear gap in an otherwise strong parameter explanation.

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 ('Grade') and a clear resource ('multi-leg parlay'), and directly states the decision being made: 'should you bet it, and at which book?'. It distinguishes itself from the sibling parlayapi_verdict by explicitly focusing on 'multi-leg' and by referring to each leg as a parlayapi_verdict bet.

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 clearly indicates when to use the tool: when evaluating a parlay of 2–12 legs. It also provides practical guidance on book scoping, mentioning both parlayapi_set_bettable_books and passing region/books directly. The note that 'a real parlay is one slip, not best-of-each' is an implicit exclusion of using per-leg best-price tools, though it does not explicitly name alternative sibling 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?

With no annotations, the description carries the behavioral disclosure burden. It reveals the stateful nature ('Remember'), the downstream effect on parlayapi_verdict, and the parameter precedence rule ('Overrides region'). It does not explicitly mention whether calling again replaces or merges the stored books, but the core side effect is clearly communicated.

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 tool's purpose and side effect, then gives a brief when-to-use trigger, then a compact Args section. Every sentence earns its place, and the example input makes the intent instantly clear.

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 description covers when to call, what the tool does, parameter values, and precedence, while the output schema covers return values. Minor gaps exist around whether repeated calls overwrite the saved list and whether there are constraints on valid book keys, but overall the agent has enough 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 0%, so the description must compensate. It does so thoroughly: region values are enumerated, books format is specified with an exact CSV example, and the relationship between the parameters ('Pass region OR an exact books list' and 'Overrides region') is explained. This is much more useful than 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?

The description clearly states the tool remembers the user's bettable books and tells how that affects parlayapi_verdict's recommendations. This specific verb+resource combination distinguishes it from the siblings, which compute odds or verdicts rather than store user preferences.

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 explicitly says 'Call this once when a user tells you where they bet' and gives a concrete user utterance as an example. It also clarifies the tool exists so the user no longer needs to pass region/books on every call, though it does not name an exclusionary alternative because no close sibling exists.

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 behavioral burden, and it handles this well. It discloses idempotency, the security decision not to expose existing API keys, the exact return payload, and the post-signup configuration step the agent should perform.

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 appropriately detailed without being bloated. It front-loads the core purpose and outputs, then covers edge-case behavior, usage guidance, and parameter details; every sentence adds practical value.

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 description is complete for an agent to call the tool correctly: it explains when to call it, what it returns, how idempotency behaves, and what to do with the result. Since an output schema exists and the description also summarizes the return values, nothing critical 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 0%, but the description fully compensates by explaining all three parameters: email is the user's email, intended_use is an optional analytics line, and agent_id identifies the calling agent with a default. This adds real semantic value beyond 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?

The description states a specific action ('Create a free-tier ParlayAPI account'), names the resource, and describes the outputs (API key, magic-login URL, Stripe upgrade URL). It also distinguishes itself from account lookup/retrieval tools by focusing on new account creation.

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 it 'when a user wants to start building with ParlayAPI and does not have a key yet,' which is a clear selection criterion. It also covers the idempotent existing-account case, but it does not explicitly compare against sibling tools like parlayapi_magic_link or parlayapi_account_info, leaving some alternative-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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It usefully states that the data is 'public' and requires 'No API key,' and the verb 'Return' implies a read-only operation. However, it does not disclose response shape, rate limits, or any caveats about freshness calculation, though the output schema may cover structure.

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 tight sentences with no filler. The core purpose is front-loaded, and the usage hint follows immediately without unnecessary elaboration.

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 a low parameter count, an output schema, and a clear use case, the description is adequate for default-invocation scenarios. However, the lack of parameter semantics and any behavior around freshness windows leaves the tool incomplete for agents that need to customize the call.

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 the description does not explain what 'limit' or 'minutes' control. The defaults in the schema are not enough for an agent to know whether 'minutes' is a freshness window, a cache age, or something else. This is a significant gap.

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: 'Return public per-source freshness and quality metadata.' This clearly distinguishes the tool from the many odds, betting, and account-related siblings, making its purpose immediately obvious.

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 explicit context for when to use it: 'Use this to prove that rows are flowing from each source before choosing books for a customer workflow.' It does not name alternatives or state when not to use it, but the intended usage situation is clear enough.

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 carries full behavioral burden and discharges it: it details output contents, the bettable-books scoping with a remembered per-key setting, the price-overrides-book behavior, the Kelly stake suggestion, and the edge_alert for anomalous prices. It also implies no bet placement by framing the result as a recommendation.

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?

Although long, the length is justified by 14 parameters and no schema descriptions. The hook, output summary, use-when guidance, Args block, and edge_alert note are each information-dense and front-loaded; 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?

For a high-complexity tool with no annotations and 0% schema coverage, the description is complete: it explains the verdict categories, parameter semantics, defaults, scoping/state, and special edge_alert behavior. An output schema exists, and the description also summarizes key return fields, so an agent has enough to select and call the tool 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 must explain all 14 parameters, and it does: each Args entry includes meaning, format, defaults, and cross-parameter interactions (team vs home/away, price overrides book, books overrides region). Examples like '-110 or 1.91' and 'draftkings,fanduel,novig' add usability beyond 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?

The description states a clear verb plus resource: it gives a one-call BET/LEAN/FAIR/PASS verdict for a specific bet, listing concrete outputs (fair price, best price/book, EV grade, line-shopping nudge). It also differentiates from sibling analysis tools by saying it replaces stitching /ev, /consensus, and /best-line together.

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 explicitly says 'Use this when a user asks whether a specific bet is worth making, or whether they're getting a good number' and contrasts with assembling the result manually from other tools. This is clear when-to-use guidance with named alternatives.

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