predictDEX

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

The description adds substantial behavioral context beyond the annotations: the token expires after 30 days, works only for the submitted address, provides gasless account setup via predictDEX's signer, grants no custody, and does not bypass region restrictions. These details meaningfully inform safe usage, and there is no contradiction with the annotations.

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 action and result, with caveats placed at the end. Every sentence earns its place and there is no filler or redundant restating of the title.

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 three-parameter, no-output-schema tool, the description covers the input flow, the returned artifact, and important boundary conditions. Minor gaps are the lack of an explicit prerequisite pointing to get_agent_challenge and the absence of details about how the returned token is delivered or used, but the description is strong enough for an agent to safely call the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description refers broadly to the 'signed attestation' and 'your address only', which lightly contextualizes the parameters, but it does not add meaning beyond what the schema already documents for address, message, and signature.

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 ('Submit the signed attestation') and a concrete outcome ('Returns a 30-day agent token that unlocks gasless Polymarket account setup'). It clearly distinguishes itself from siblings like get_agent_challenge, which only provide the challenge material, while attest_agent consumes the signed proof and produces the token.

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 usage context is implied rather than stated: the mention of a 'signed attestation' suggests this is the second step after obtaining a challenge, but the description does not explicitly say 'after get_agent_challenge' or name alternatives. It also does not give when-not-to-use conditions, so the agent must infer the flow from the sibling list.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and non-execution. The description adds the crucial context that 'Opening it executes nothing,' reinforcing the non-executing nature. It also implies the output is a URL, adding value beyond annotations.

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 concise sentences: the first explains what the tool produces, the second clarifies when to use it. Every word earns its place, and the critical usage guideline is 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?

Given the tool's simplicity (creating a URL) and the rich schema and annotations, the description covers all essential aspects: purpose, usage context, and behavioral safety. No output schema is present, but the description adequately implies the return is a URL, which is sufficient.

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 all parameters are documented in the schema. The description doesn't add extra parameter-level detail, but it does clarify the overall purpose and that the tool generates a link, adding context beyond the schema. Since schema coverage is high, a 4 is justified for the added contextual value.

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 function: creating a pre-filled URL for a trade ticket, listing the exact fields (event, market, outcome, side, amount). It distinguishes itself from siblings by emphasizing it is a URL for human review, not an order execution.

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

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

Explicitly says when to use it: 'when you have no wallet or need human confirmation.' This contrasts with other tools that likely execute trades (e.g., quote_order), providing clear usage boundaries.

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 safety. The description adds valuable behavioral context: the 10-minute validity window and the required signing/usage flow, which are not present in the annotations. This enriches the agent's understanding beyond the structured hints.

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

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

The description is two concise sentences, front-loaded with the core return value and immediately followed by the actionable next steps. Every sentence earns its place, with 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 read-only tool with a single parameter, the description fully explains what to do with the result (sign and pass to attest_agent) and the time constraint. No additional information is necessary for an agent to call it correctly, given the annotations and schema already cover safety and parameter 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?

Schema coverage is 100%, and the single parameter 'address' is clearly described as 'Your 0x wallet address' in the schema. The description does not add any further semantics about the parameter format or constraints, so it meets the baseline for well-covered schema without adding extra value.

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

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

The description states exactly what the tool does: returns a specific canonical attestation message for the provided address. It names the exact message type and explicitly references the sibling tool attest_agent, making it distinguishable from all other siblings 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 gives clear usage context: obtain the message, sign it with EIP-191 personal_sign within 10 minutes, then pass it to attest_agent. This implies the intended workflow and references the follow-up tool, though it doesn't explicitly state when not to use this tool or mention alternatives beyond attest_agent.

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 behavior, so the bar is lower. The description adds useful behavioral context by revealing the full scope of the response and the optional inclusion of recent trades, which helps set agent expectations beyond the annotations.

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 that lists exactly what the agent will get, with no filler or repetition. Every item in the enumeration earns its place by clarifying the tool's output.

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

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

With no output schema, the description carries the burden of explaining return contents, and it does so comprehensively: markets, outcome names/prices, token ids, tick size, min order size, rules, resolution, and status. Combined with rich annotations and clear schema descriptions, nothing essential is missing 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 coverage is 100%, so the baseline is 3. The description reinforces the 'slug' lookup and 'recent trades' inclusion, but it does not add meaningful parameter semantics beyond what the input schema already documents.

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

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

The description clearly identifies the resource ('Full event by slug') and enumerates its contents, distinguishing it from market-query tools like get_orderbook or get_price_history. The title 'Get one event' reinforces the singular retrieval purpose.

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 schema's slug description tells the agent to source the slug from search_markets, giving clear prerequisite context. The description signals the right time to use the tool (when full event detail is needed), though it never explicitly states when not to use it or names alternatives.

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 and idempotentHint=true, so the safety profile is covered structurally. The description adds the ranking context (profit/volume/window) but no additional behavioral details such as default limit, ordering, or pagination. No contradiction with annotations 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 10-word sentence that front-loads the resource and ranking criteria. There is zero filler and every word contributes meaning.

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

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

For a simple read-only tool with full parameter documentation and helpful annotations, the description is complete: an agent knows what the tool returns and can infer the call shape. No output schema exists, but the return value is self-evident from the description.

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%, with each parameter (limit, metric, window) fully documented. The description's mention of 'profit or volume over a window' reinforces the role of metric and window but adds little beyond what the schema already states. The baseline of 3 is appropriate.

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

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

The description states exactly what the tool does: returns top Polymarket traders ranked by profit or volume over a window. It specifies a clear resource and the two dimensions of ranking, making it easy to distinguish from sibling tools like get_orderbook or get_price_history. The title reinforces the verb-resource pairing.

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 alternative tools are mentioned. Usage is only implied by the tool's obvious purpose, with no explicit conditions, exclusions, or prerequisites. This falls short of the standard set by the get_calls example.

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

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

Annotations already cover safety with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by specifying 'Live', scoping to a single outcome token, and describing the returned data, though it does not disclose potential staleness, precision behavior, or formatting details.

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 that leads with the key resource ('Live order book') and follows with concrete content details. It contains no filler and every phrase 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 only one required parameter, a complete schema, and annotations covering read-only behavior, the description adequately conveys scope and return contents. The explicit listing of bids, asks, spread, midpoint, and last trade is especially valuable since no output schema exists, though depth behavior could have been slightly more explicit.

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 tokenId and depth are already fully documented in the input schema. The description's phrase 'one outcome token' maps back to tokenId but adds no new parameter semantics, 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?

The description names a specific verb ('get'), resource ('order book'), and scope ('for one outcome token'), and lists the returned fields: bids and asks, spread, midpoint, and last trade. This makes it clearly distinguishable from siblings like get_price_history or quote_order.

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?

No explicit when-to-use or when-not-to-use guidance is provided, and no sibling tool is named as an alternative. The 'Live order book' phrasing implies the use case of current market depth, but an agent must infer when this is preferable to get_price_history or quote_order.

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, so the safety profile is covered. The description adds that it returns open positions and the specific fields, which is useful but doesn't disclose additional behavioral traits like pagination, ordering, or whether the address can be an EOA or deposit wallet (though the schema mentions 'owner EOA or Deposit Wallet'). No contradiction with annotations.

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 sentence that front-loads the resource ('Open positions of a Polymarket trading account or its owner address') and then lists the returned fields. No wasted words.

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 read-only tool with one parameter and no output schema, the description is mostly complete. It names the key return fields and the accepted address types. It could mention whether positions are filtered by market status or if there is pagination, but given the simplicity and annotations, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the single 'address' parameter. The description adds that the address can be an owner EOA or Deposit Wallet, which is a small semantic addition beyond the schema's '0x address (owner EOA or Deposit Wallet)'. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns open positions of a Polymarket trading account or owner address, and lists the key fields (size, average price, current price, value, P&L). It uses a specific verb ('Get') and resource ('positions of a wallet'), which is clear. It doesn't explicitly differentiate from siblings, but no sibling appears to overlap directly with positions.

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 the tool is for reading positions for a given address, and the schema requires an address. It doesn't explicitly state when to use this tool versus alternatives, but the context is clear enough: it's the only positions-related tool among siblings. No exclusions or alternative routing are provided.

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 non-destructive behavior, so the safety profile is covered. The description adds only the 'over a range' scoping, which is present in the schema. It doesn't describe response format or what happens when range is omitted, but it does not contradict annotations.

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 with no filler or redundancy. The key scope ('one outcome token', 'over a range') is front-loaded. 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?

For a simple read-only tool with full schema coverage and safety annotations, the description is sufficient. Minor gaps: it doesn't mention that range is optional or the response shape, but these are not critical 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%: both tokenId and range are described. The description's phrase 'one outcome token over a range' merely restates the schema, adding no new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the resource (price history), the scope (one outcome token), and the filtering dimension (over a range). This distinguishes it from siblings like get_orderbook or get_leaderboard without needing to open 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 description implies usage: an agent would use this when needing historical price/probability data for a token. However, it provides no explicit when-to-use or when-not-to-use guidance, and no alternatives 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?

Annotations already establish this as a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond that: the tool is non-custodial, the agent signs with its own key, and it returns setup artifacts rather than executing a trade. No contradiction with annotations.

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 dense sentence that front-loads the core value ('Everything an agent with its own wallet needs to trade') and then itemizes the contents. Every clause earns its place, with 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 zero parameters, no output schema, and rich annotations, the description covers the essential content: chain, collateral, builder code, signer URL, attestation steps, fees, and SDK snippet. It could briefly mention the output format or how the snippet is returned, but for an informational tool this is nearly 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?

The tool has zero parameters, so the baseline is 4. There is nothing for the description to clarify about parameter meaning, and the empty schema is consistent with a static informational tool.

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 the tool provides a complete trading setup package: chain, collateral, builder code, signer URL, attestation steps, fees, and a TypeScript snippet. The verb is implicit but the resource is concrete, and the title 'How to trade through predictDEX' reinforces the purpose. It is clearly distinct from sibling tools like get_orderbook or create_trade_link.

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 phrase 'Everything an agent with its own wallet needs to trade' gives clear context about the intended user and scenario. However, it does not explicitly state when to use this tool versus alternatives such as create_trade_link or attest_agent, nor does it mention any exclusions or prerequisites beyond having a wallet.

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 readOnly/idempotent/non-destructive, so the description adds useful behavior beyond them: it uses the live book, returns average and worst price, shares, cost, payout, fees and warnings. It doesn't mention potential auth/rate-limit quirks, but with the annotations covering safety, the extra context is sufficient.

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 dense sentences, front-loaded with purpose, followed by the only cross-parameter semantic that could trip an agent (amount units). 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?

There is no output schema, so the description compensates by enumerating the main return concepts (prices, shares, cost, payout, fees, warnings). With 100% schema coverage for parameters, it is sufficiently complete, though a note on warning/error conditions would make it stronger.

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 schema already covers most parameter descriptions at 100%, but the description adds 'all-in' clarification for a market BUY amount and reinforces that market SELL and limit amounts are in shares. This is a small but real increment over the schema's 'USD for a market BUY, shares otherwise'.

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: 'Preview an order against the live book without placing it.' This clearly distinguishes quote_order from execution tools and sibling read tools like get_orderbook by emphasizing preview (quote) semantics, fee-inclusive output, and non-execution.

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: use this to preview an order before committing, and 'without placing it' draws the line against execution. It does not explicitly name an alternative order-placement tool or list exclusion conditions, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context about the return structure (markets with outcomes, token ids, bid/ask, tick size, URL) and the live nature of odds, which goes beyond annotations. No contradictions found.

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 exactly two sentences with zero redundancy. It front-loads the primary purpose ('Find events and their markets') and packs the filtering and return details efficiently. Every word contributes.

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 7 parameters and no output schema, the description adequately explains what the tool returns (markets with odds, token IDs, etc.). It does not cover pagination defaults or behavior, but the schema specifies offset and limit defaults, so nothing critical is missing. For a search tool, this is sufficiently 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 100%, so the schema documents all 7 parameters. The description adds minimal value beyond the schema: it mentions filtering by query, category, sort, and status, and references predict://categories for slugs. This is a small enhancement, but not enough to raise above the baseline 3.

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 it finds events and markets with live odds, using a specific verb 'find' and resource 'events and their markets'. It differentiates from siblings like get_event, get_orderbook, and get_price_history by being a search tool rather than a retrieval-by-ID tool.

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 explains filtering options (query, category, sort, status) and gives a concrete example of a category reference (predict://categories). However, it does not explicitly state when to prefer this over alternatives like get_event (e.g., when you have a specific event ID), so it falls short of full exclusion guidance.

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