MagicMarkets

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

Annotations already declare idempotent, non-destructive, and write-operation traits. The description adds useful behavioral context that stopping the heartbeat does not close any orders, narrowing the side-effect scope beyond the annotations. It still omits auth or return semantics, though an output schema exists.

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, front-loaded sentence that states the action and the key non-effect. Every word earns its place with no 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 one-parameter mutation with annotations and an output schema, the description is nearly sufficient. The main gap is the lack of routing guidance relative to sibling heartbeat tools such as refresh_heartbeat.

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 the single heartbeat_id parameter is fully documented in the schema. The description adds no extra syntax, format, or constraint details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States a specific verb 'Stop' and resource 'heartbeat', and clarifies that it does not close orders, which distinguishes it from close_order and close_all_orders. It does not explicitly differentiate from refresh_heartbeat or create_heartbeat, so it falls 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?

There is no when-to-use or when-not-to-use guidance; the description only states the effect. The agent must infer that this tool is for ending an existing heartbeat rather than creating, listing, or refreshing one.

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

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

Annotations already declare destructiveHint, idempotentHint, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new operational context: that bulk cancellation should be confirmed with the user and that event filtering has a dependency. It does not describe failure modes or partial-cancel behavior.

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

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

Two short sentences that front-load the primary action, then layer the scoping rules and the safety instruction. No filler or restated framing.

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 two-parameter bulk mutation with full annotation coverage and an output schema, the description covers scope, filtering dependencies, and the confirmation requirement. Nothing an agent needs before invoking 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 description coverage is 100%, so both parameters are already documented, including the 'requires sport' constraint on event_id. The description repeats rather than extends that information, so the baseline of 3 applies.

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

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

States a specific verb ('Cancel') and resource ('every open order') with explicit scope, and the 'every' distinguishes it from the sibling close_order which handles a single order. An agent can route correctly without opening either schema.

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

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

Gives clear operating conditions: narrowing by sport, and that narrowing by event requires the sport. It also flags the confirmation prerequisite. It does not explicitly name close_order as the single-order alternative, so sibling differentiation relies on the 'every' wording rather than an explicit pointer.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing the failure semantics for settled orders, though it says nothing about permissions or the effect on associated funds/positions.

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, zero filler, with the core action front-loaded and the error condition following. Nothing could be cut without losing information.

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?

Output schema exists, so return values need not be explained, and annotations cover the destructive/idempotent profile. For a one-parameter mutation the description is nearly sufficient, with only permission requirements left unspecified.

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

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

Schema coverage is 100% with a single required order_id already documented as 'Order ID to cancel.' The phrase 'by ID' adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Cancel'), resource ('order'), and scope ('one ... by ID'), which cleanly separates it from the sibling close_all_orders. An agent can identify the operation without opening the schema.

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

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

The settled-order failure condition ('Already-settled orders return an order_closed error') tells the agent when the call will not succeed. It does not explicitly name close_all_orders as the alternative for bulk cancellation, so routing guidance is implicit 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description still adds real context beyond them: betslips are short-lived, carry no price at creation, and wait_seconds controls polling for the quote, which explains the non-obvious latency behavior.

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

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

Roughly three sentences, front-loaded with the core action and followed by lifecycle and parameter guidance. Efficient, though the bet_type-from-list_event_offers point slightly duplicates the schema description.

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 and annotations cover safety, so the description only needs to cover the lifecycle and usage context it does cover well (one-selection scope, no cost, expiry, polling). Minor gaps remain on expiry duration and failure behavior, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so parameters are already documented (including bet_type 'copied from list_event_offers' and wait_seconds 'Poll up to this long for a quote'). The description largely restates the bet_type and wait_seconds semantics rather than adding new syntax or constraints, so baseline 3 is appropriate.

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

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

States a specific verb (create) plus resource (betslip) and scopes it precisely as 'register interest in one selection so it gets quoted'. This clearly distinguishes it from siblings like place_order and get_betslip.

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

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

Explicitly frames it as 'step one of two', notes that a betslip 'costs nothing and commits nothing, but an order needs one', and instructs taking bet_type verbatim from list_event_offers. This gives clear when-to-use and prerequisite context, though it never names place_order as the follow-up tool.

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

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

Annotations already declare readOnly=false, idempotent=false, openWorld=true, and destructive=false. The description adds critical behavioral context beyond that: if not refreshed before expiry, every open order is closed automatically, and it gives the valid timeout range.

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?

Four short sentences, each carrying necessary information. The purpose and risk are front-loaded, followed by the timeout constraint and the refresh instruction.

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 output schema and annotations, the description is complete enough: it explains the tool's behavior, the consequence of inaction, the parameter bounds, and the refresh alternative. Nothing essential for correct invocation 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 the single timeout parameter is already fully described in the schema. The description repeats the 10-300 second range but adds no syntax or meaning beyond what the schema provides.

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 ('Start a dead-man's switch') and explains the effect in the same sentence. It names the sibling tool refresh_heartbeat as the refresh path, so an agent can distinguish create from refresh without opening schemas.

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 implies the use case: arm the switch and refresh it with refresh_heartbeat before expiry. However, it does not explicitly state when not to use it or mention cancel_heartbeat as the way to disarm it.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context that the returned amounts are denominated in USDT and identifies the specific balance components, but it does not disclose other behavioral details like freshness or source of funds.

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, front-loaded sentence with no wasted words. It efficiently states what is returned and the unit of measurement.

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 tool with rich annotations and an output schema, the definition is complete enough: it says what is retrieved and in what currency. No additional prerequisites or return-format details are needed.

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 zero parameters, so there is no parameter semantics to explain. The baseline for zero-parameter tools is 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 ('Get') and resource ('account balance') and enumerates the returned components: balance, stake committed to open bets, and smart credit. It is clear what the tool does, though it does not explicitly contrast itself with related tools such as get_position or list_orders.

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 guidance on when to use this tool versus alternatives and no prerequisites. The purpose is self-evident, but there is no explicit usage context or exclusion criteria.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds genuinely non-obvious behavior: quotes are delivered asynchronously and a fresh betslip is usually unpriced, which changes how an agent should call it.

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 sentences with zero waste. The core action is stated first, and the timing caveat plus the wait_seconds remedy follow immediately.

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

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

An output schema exists, so return values need not be described. For a two-parameter read tool, the description covers the async timing gotcha and the remedy; only explicit sibling routing 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%, so baseline is 3. The description goes beyond the schema by explaining why wait_seconds exists (polling for a price that lands asynchronously), giving the parameter a purpose the terse schema hint does not.

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

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

States a specific verb and resource ('Get a betslip and its current price list'), which is clear and concrete. It does not explicitly name the sibling it differs from (e.g., list_betslips), though the singular/plural distinction is inferable from the name.

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

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

Gives an actionable usage condition: quotes arrive asynchronously, so a fresh betslip is normally unpriced and wait_seconds should be set to poll. It does not state when-not-to-use or name an alternative tool, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful context beyond that: the target denomination (USDT) and the fact that this is a low-cost/lightweight call suitable for API-key validation.

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, zero filler, and the primary purpose is front-loaded ahead of the secondary hint. Every clause earns its place.

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

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

With an output schema, rich annotations, and zero parameters, the description only needs to convey purpose and usage, which it does. Minor omission: no note on rate limiting or freshness of the rates, but nothing essential for correct invocation 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?

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter semantics for a zero-argument 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?

States a specific verb and resource ('Get exchange rates to USDT'), so the agent knows exactly what comes back at the top level. It doesn't need sibling differentiation because no sibling tool overlaps with exchange-rate retrieval.

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?

Provides a clear secondary use case: it is 'the cheapest way to verify the API key works,' which tells the agent when to reach for it during connectivity/auth checks. It stops short of naming when-not-to-use or alternatives, but the context is concrete.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context: request_uuid lookups only work for six hours and are useful for reconciling timed-out placements.

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 sentences, front-loaded with the primary lookup modes and immediately followed by the key constraint. Every sentence earns its place and nothing is repeated verbatim from the schema.

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 a simple read lookup with an output schema and rich annotations; the description covers both parameters and the important request_uuid time boundary. No auth, return-value, or rate-limit detail is necessary given the structured fields already present.

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

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

Schema description coverage is 100%, so the schema documents both parameters and sets a baseline of 3. The description adds semantic value beyond the schema by explaining the six-hour validity window for request_uuid and its role in checking timed-out placements.

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, and identifies the two lookup modes (by order_id or request_uuid). 'Get one order' naturally distinguishes it from the sibling list_orders, so an agent can select it without opening the schema.

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

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

It gives clear context for when request_uuid lookup is valuable: within six hours after placement and as a safe way to verify a timed-out placement. It does not explicitly name alternatives such as list_orders, but the use case is specific enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the football-only cashout constraint and the aggregate nature of the result, but that constraint is also repeated in the include_cashout_info schema description, so the added behavioral value is modest.

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, front-loaded with the core purpose before the filtering and scope caveats. No filler, though the final sentence is thin on 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?

An output schema exists, so return-value explanation is not needed, and annotations carry the safety profile. The description covers what the tool returns conceptually and the key filtering/cashout caveats, leaving only minor gaps such as pagination or result-size behavior.

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 documented in the schema itself. The description only alludes to event narrowing and cashout scope, both of which are already in the schema descriptions, so baseline 3 applies.

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

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

Specific verb ('Get') plus resource ('aggregate profit/loss position over matching orders') with an extra detail about the payoff grid per scoreline. This clearly distinguishes it from get_order (single order) and get_balance (account balance). It does not explicitly name any sibling, so it falls 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?

Gives usable context: 'Narrow it to one event for a readable result' tells the agent when the unfiltered call is impractical, and the football-only caveat scopes cashout usage. It stops short of naming alternatives or stating when not to use the tool, so no 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that betslips are short-lived, which contextualizes the ephemeral nature of the data, but doesn't explain return format or pagination behavior. With annotations handling safety, this extra context merits a 3.

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 with no waste, front-loading the main action before the ephemeral note. Every sentence earns its place.

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

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

An output schema exists, so the description needn't explain return values. For a zero-parameter read-only listing tool with full annotations, the description is nearly complete, only lacking explicit sibling differentiation and usage context.

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?

No parameters exist, so the baseline is 4. The description appropriately doesn't discuss parameters since there are none.

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 ('list') and resource ('IDs of currently open betslips'), making the action clear. Sibling tools like get_betslip and create_betslip are differentiated by the listing aspect, though the description doesn't explicitly contrast with them.

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—this tool is for listing open betslip IDs—but there is no explicit guidance on when to use this versus get_betslip or other listing tools. No alternatives or exclusions are mentioned.

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?

Beyond the annotations, it discloses the operational lifecycle: opening the WebSocket, registering the event, reading the offer snapshot, and disconnecting. It also explains offer granularity, that back and lay are separate offers, and that prices are ordered best first and already on the tick schedule. These details materially improve invocation correctness.

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?

It is front-loaded with the core purpose and then adds only high-value operational and workflow details. Every sentence contributes to correct tool selection or invocation.

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 has annotations covering safety and openness, an output schema covering return values, and 100% schema description coverage. The description adds the remaining critical context: WebSocket lifecycle, offer structure, price ordering, and the handoff to create_betslip.

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 schema already documents all four parameters. The description adds conceptual context about offers covering (sport, event_id, bet_type) triples, but it does not extend the meaning of limit or market_type 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 states a specific verb and resource: 'List the priced bet types on one event, with the stake available at each price.' It clearly scopes the operation to a single event and explains that offers are priced bet types, distinguishing it from broader event-listing siblings.

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

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

It gives clear downstream usage context by instructing the agent to pass a returned bet_type verbatim to create_betslip and never construct one by hand. It does not explicitly compare against alternatives such as validate_bet_type or list_events, but the workflow guidance is strong.

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

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

Annotations already declare read-only, open-world, non-destructive, non-idempotent, so the safety profile is covered. The description adds genuinely valuable behavior beyond that: it explains the WebSocket open/read/disconnect mechanism, warns it costs a few seconds, and discloses that the returned set is partial — none of which the annotations convey.

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 tight sentences with zero filler: purpose, mechanism/cost caveat, and the partial-set caveat plus next-step pointer all front-loaded in useful order.

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?

Output schema exists so return values need no explanation; annotations cover safety. Combined with the latency and partial-snapshot caveats, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema description coverage is 100%, so all four parameters (limit, sport, search, in_play) are already documented with defaults and formats. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'List the events that currently have live prices.' It also discloses the non-obvious mechanism (WebSocket snapshot) and routes to the sibling list_event_offers, so an agent can distinguish it from other list_* tools without opening schemas.

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

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

Gives clear context: the snapshot is not the full fixture list, only events currently priced, and directs the agent to pair the returned sport/event_id with list_event_offers. It stops short of explicit when-not-to-use guidance, but the partial-coverage warning effectively tells the agent what this tool is not for.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds only the 'active' scoping behavior, without mentioning pagination, auth needs, or result ordering, which is a modest addition.

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, front-loaded sentence with no filler. Every word earns its place.

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

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

Given the tool is a zero-parameter list operation with rich annotations and an output schema, the description is nearly complete. It could clarify what 'active' means or how results are ordered, but an agent can invoke it correctly as written.

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 the baseline is 4. The schema and description agree that no parameters are needed, and the description correctly adds no misleading parameter information.

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 ('List ... heartbeats') and adds scope ('active'). It distinguishes the tool from mutation siblings like create_heartbeat and cancel_heartbeat, though it does not explicitly contrast with them.

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?

There is no guidance about when to use this tool versus alternatives such as refresh_heartbeat or cancel_heartbeat. The agent can infer it is for listing, but the description provides no context or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful domain fact that amounts are in USDT, but omits pagination behavior, sorting, and authentication 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 with no wasted words. The core action is front-loaded, and the currency note is a relevant detail that earns its place.

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

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

Given the rich schema (9 fully documented optional params), the presence of an output schema, and annotations that cover safety, the description is largely sufficient for invocation. The main gap is explicit usage guidance versus siblings, which is captured in a separate dimension.

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 schema already documents all nine parameters thoroughly. The description adds no parameter-specific semantics beyond 'optionally filtered,' so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'List orders, optionally filtered.' This clearly distinguishes it from the singular get_order sibling, but it does not explicitly name alternatives or clarify scope beyond basic filtering.

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 offers no when-to-use guidance versus siblings like get_order, close_order, or list_betslips. 'Optionally filtered' implies that filters can be applied but does not explain when or why to choose this tool.

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?

Goes well beyond the annotations by disclosing that the call spends real money, that price is snapped to the tick schedule (down for back, up for lay) and that the snapped value is what the order executes with, and that request_uuid is what makes a retry after a timeout safe. The idempotency statement is a caller-supplied mechanism rather than a claim that the tool is inherently idempotent, so it complements rather than contradicts idempotentHint=false and destructiveHint=true.

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?

Six sentences, each carrying distinct information, with the destructive warning front-loaded right after the purpose. Dense but purposeful; the only mild cost is that the prerequisite, snapping, and idempotency rules arrive in a fairly packed block.

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

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

An output schema exists, so return values need not be described. Given the tool is destructive, open-world, and money-spending, the description supplies exactly the missing context an agent needs: custody of funds, prerequisite betslip, price-snapping semantics, idempotency strategy, and human confirmation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine meaning on top: it explains the snapping behavior that governs what the supplied 'price' actually becomes, and the idempotency role of request_uuid. It does not cover duration, exchange_mode, or the accept_* flags, which is why this is a 4 rather than a 5.

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

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

States a specific verb and resource ('Place an order against a betslip') and immediately distinguishes itself from the sibling create_betslip by naming it as a prerequisite. An agent can tell this is the execution step, not the betslip-creation step, without opening either schema.

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

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

Gives explicit preconditions ('Requires an existing betslip from create_betslip'), an explicit instruction ('Always pass request_uuid'), a user-facing workflow rule ('Confirm the stake with the user before calling this'), and points to get_order as the follow-up retrieval path. Nothing about when to reach for this tool is left 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful context by naming the consequence avoided (dead-man's switch firing), but does not explain auth needs, how much expiry is extended, or side effects of repeated calls.

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 front-loaded sentence with no filler. It conveys the action and its purpose efficiently, and every clause earns its place.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to explain purpose and effect, which it does. The main remaining gap is usage context versus sibling heartbeat operations, but that is a minor omission for a simple one-parameter mutation.

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

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

Schema description coverage is 100% and heartbeat_id is already documented in the input schema. The description adds no extra meaning for the single parameter, so the baseline 3 applies.

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

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

States a specific verb ('Extend') and resource ('a heartbeat's expiry'), and the dead-man's switch clause clarifies the intended effect. This distinguishes it from sibling operations like create_heartbeat, cancel_heartbeat, and list_heartbeats without 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?

The description implies when to use it ('keeping the dead-man's switch from firing') but does not explicitly compare it to alternatives such as cancel_heartbeat or create_heartbeat. Prerequisites and when-not-to-use conditions are absent, leaving usage 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 establish read-only, idempotent, non-destructive, and local behavior. The description adds important behavioral detail beyond annotations: it runs locally with no API call, and off-tick prices are rounded so they never tighten the limit, with direction-specific rounding rules.

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?

Four sentences, each earning its place: purpose, local execution, rounding behavior, and usage context. The core purpose is front-loaded and no sentence 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?

Given the existence of an output schema, the description need not explain return values. It covers what the tool does, how it behaves locally and with off-tick prices, and when to use it, leaving no critical gap for an agent.

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

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

Schema coverage is 100%, so the input schema already documents price, bet_type, and direction thoroughly. The description reinforces the direction-based rounding logic but adds little parameter meaning beyond what the schema and its descriptions already 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?

States a specific verb+resource: snapping a decimal price onto the API's tick schedule, and names the outputs (tick size and implied probability). This is clearly distinguishable from order-placement siblings such as place_order, even though no sibling is named 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?

Provides a clear usage context: 'Use this to know the price an order will actually run with.' It does not mention when not to use it or name alternatives, so it falls short of the explicit when/when-not/alternative standard.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and non-destructive behavior, so the safety profile is covered. The description adds substantial behavioral and domain context beyond annotations: parse failure semantics, the grammar tokens, direction meanings, example bet_type strings, Asian handicap scaling, and the rule that handicaps refer to the home team.

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 purpose and usage, then moves to grammar and examples. Despite being dense, every sentence earns its place by adding syntax, examples, or domain rules needed to invoke the tool correctly.

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 output schema exists, the description need not explain return values, but it still notes the human-readable description and win/loss grid. With annotations covering safety and schema covering parameters, the added grammar and examples make the definition complete for correct invocation.

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

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

Schema description coverage is 100%, but the description adds significant grammar-level semantics for the bet_type parameter that the schema does not provide. It explains the first token direction ('for' to back, 'against' to lay), market arguments, and concrete examples including Asian handicap integer scaling.

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: validate a bet_type string against a sport and return its human-readable description plus win/loss grid. It clearly distinguishes this validation utility from sibling tools like place_order and list_event_offers.

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 sourcing guidance to copy bet_type values verbatim from list_event_offers rather than constructing them, and it explains that an error means the string did not parse. However, it does not explicitly state when-not to use this tool or contrast it more broadly with alternatives.

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