Midpoint Card Prices

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds real methodology: the 50% gem-rate assumption, the requirement that both PSA 9 and PSA 10 prices exist to exclude thin-market outliers, and the default $25 fee. It stops short of describing result size or how the limit interacts with ranking, but the substantive behavioral disclosure is strong.

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 tightly packed sentences with the primary trigger front-loaded and zero filler. Dense but every clause carries information; only minor cost is that the methodology clause sits mid-paragraph rather than being separated for scanability.

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 documentation is unnecessary, and the description still notes it returns card ids for grading_roi. Combined with the annotations, the trigger, the exclusion, and the ranking methodology, an agent has everything required to select and call this 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 75%, so parameter docs do most of the work, but the description still adds meaning: the fee is framed as an assumption used inside the profit formula (not just a number), and the both-prices requirement explains why some cards are silently absent. The 'limit' parameter and the exact gem-rate composition are not explained 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?

States a specific verb and resource ('ranks priced cards by expected net profit'), names the exact ranking criterion (50% gem rate, half PSA 10/half PSA 9, minus raw and fee), and explicitly carves out the sibling use case ('Do not use for a single named card'). An agent can distinguish it from grading_roi, search_cards, and get_card_prices without opening any 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?

Opens with an explicit trigger ('Use this when the user asks which cards in a game, sport or set have the biggest payoff from grading'), states the exclusion ('Do not use for a single named card'), and names the downstream tool ('Returns card ids for grading_roi'). When-to-use, when-not, and the alternative path are all present.

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?

Adds value beyond annotations by disclosing data provenance ('real sold listings, refreshed daily') and geographic/currency context (USD market values), which annotations don't cover. Annotations already declare read-only/idempotent safety, so the remaining gaps (e.g., how stale a card is) are minor.

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, front-loaded with the trigger condition, then the data scope, then the exclusion. Every sentence carries distinct information with 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?

Given an output schema is present, the description needn't explain return shape; it covers trigger, prerequisites, data provenance, and exclusion. An agent has everything needed to select and invoke 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 coverage is 100% and the schema itself documents card_id format with examples. The description reinforces the dependency ('Requires a card id from search_cards') but 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 precise verb+resource ('full current value of a specific card') and enumerates exactly what is returned: ungraded by condition and graded by company/grade. Distinguishes itself from siblings like search_cards and get_price_history by scope (full ladder vs. history vs. name search).

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 states when to use it ('user wants the full current value') and when not to ('Do not use to search by name'), and names the prerequisite source for the card id (search_cards). Routing 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the return payload is dated USD values confined to a 7-180 day window, and the grade parameter selects a raw vs graded series.

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

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

Three sentences, front-loaded with the usage trigger, followed by return shape and the exclusion. No filler, no repetition of the tool 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?

With annotations covering safety and an output schema covering the response shape, the description only needs to cover usage, prerequisites and exclusions, which it does. Minor gap: it does not clarify units/frequency of the dated values or whether the series is daily granularity, though it implies coverage of the last 7-180 days.

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 67%, and the schema already documents grade ('PSA grade... omit for raw') and card_id. The description restates the 7-180 day bound already present as min/max and the raw/PSA distinction already in the schema, so it adds little parameter-level meaning beyond the structured fields.

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 (price history) and scope: dated USD market values for the last 7-180 days, for raw or PSA-graded series. It distinguishes the tool from a simple price lookup by framing it as a trend over weeks/months, though it never names the nearest sibling (get_card_prices) as the contrasting snapshot 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?

Gives a clear trigger ('when the user asks how a card's price has changed over weeks or months, or wants a trend'), a negative boundary ('Do not use for forecasts'), and a prerequisite (requires a card id from search_cards). It stops short of naming an alternative tool, so the agent must infer what to use for snapshots or forecasts.

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 value beyond that by disclosing the payload contents (raw and PSA 10 USD prices per card) and the provenance of the set_id input, though it says nothing about result volume or how the default limit interacts with a large set.

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 tightly packed sentences: use case first, prerequisite second, exclusion and alternative last. Every clause carries routing or prerequisite information, and 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?

An output schema exists, so return values need no elaboration, and the two required parameters are both addressed through the set_id prerequisite. For a read-only list tool with full annotation coverage, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 50%: sort and set_id carry inline descriptions, while game is a self-evident enum and limit is bounded by default/minimum/maximum. The description reinforces the set_id provenance and the price output but adds no syntax, format, or interaction detail 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?

The description states a specific verb and resource — retrieving the cards in a given set along with their prices — and explicitly names the sibling tool it is not (search_cards). It also distinguishes its two primary use shapes (most valuable cards vs. full priced checklist), so an agent can separate it from get_card_prices, list_sets, and search_cards without opening a 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?

Usage conditions are explicit: use it for valuable cards in a set or a priced checklist, and do not use it for a single named card — call search_cards instead. The prerequisite (a set id obtained from list_sets) is also stated, leaving nothing to inference about when to reach for this tool vs. its siblings.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, so the safety profile is covered. The description adds genuinely useful scope context: the output is an economic model (per-outcome net profit, expected value, break-even gem rate) and it explicitly disclaims condition assessment, which prevents a false expectation. It does not mention fee-tier behavior beyond what the schema says, keeping it from a 5.

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 trigger is front-loaded in the first clause, followed by the output inventory and the prerequisite/disclaimer. The long enumeration of return values partially overlaps the output schema, but each clause is informative and nothing is padded.

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 description need not enumerate return values in detail; it instead supplies the missing decision context (when to call it, what card id source is needed, what it does not do). Combined with rich annotations and 100% schema coverage, an agent has everything required to select and invoke it correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, including the grading_fee default and comparison tiers. The description adds no syntax or format detail beyond restating that a card id from search_cards is required, so the schema is doing the heavy lifting.

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 decision verb ('whether a card is worth grading') plus the concrete artifact returned (raw vs PSA 9 vs PSA 10 prices, gem premium, break-even rate, verdict). It is clearly distinguishable from sibling list/price tools like get_card_prices and best_cards_to_grade because it is scoped to a single card's grading economics.

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 an explicit trigger ('when the user asks whether a card is worth grading, submitting to PSA/CGC/BGS/SGC/TAG, or what a PSA 10 adds') and an explicit exclusion ('does not assess the condition of the user's copy'), plus a prerequisite (card id from search_cards). It stops short of routing the agent between this and the bulk sibling best_cards_to_grade, so it is not a full 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, idempotentHint, and non-destructive, so safety is covered. The description adds genuinely new behavioral context absent from structured fields: the fixed liquidity and price floors that define the result set. It does not discuss result ordering or pagination, but the output schema exists to cover returns.

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 use condition, with the qualifier threshold embedded inline. Dense but every clause carries selection-relevant information; 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 filtered-list tool with an output schema and full safety annotations, the description supplies the essential use case, the liquidity criteria, and the sibling routing. The one gap is the undocumented 'limit' parameter, which neither the schema nor the description explains.

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?

Only 50% of the schema carries descriptions: the 'game' enum is documented, but 'limit' (default 15, max 50) has no description anywhere. The description's thresholds ($5, 25 sales) are fixed filters rather than parameters, so they add scope context but not parameter meaning. A baseline 3 fits when the schema does half the work.

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 resource ('recent gainers' / cards rising in price) with precise scope conditions: at least 25 recorded sales/year and a raw price of at least $5, across all games and sports. It explicitly contrasts itself with the sibling trending_cards, so an agent can distinguish the two 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 explicit when ('flipping or selling decisions'), an alternative plus its selection criterion ('Better than trending_cards'), and an explicit exclusion ('Do not use for a single named card'). This is the full when/when-not/alternative triad.

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 is covered. The description adds a behavioral trait not in structured data — results are returned newest first — which matters for list ordering. It stops short of describing pagination or the limit cap.

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, purpose front-loaded, with the exclusion clause last. Every sentence earns its place and no filler is present.

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 needn't be explained, and the description covers purpose, ordering, and the sibling relationship. It is nearly complete, with only minor gaps around how limit/paging behaves for a listing tool.

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

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

Schema description coverage is only 33%: the game enum and limit bound are structurally expressed but not explained, and only query carries a schema description. The description's inline examples ('Evolving Skies', '2019 Panini Prizm') illustrate the kind of values query accepts, adding marginal meaning, but it never mentions the game or limit parameters.

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 (list sets/expansions) and explicitly frames the purpose as finding a set id for a given game or sport. It also distinguishes itself from siblings by naming get_set_cards as the downstream call and clarifying it is not a pricing 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?

Gives explicit when-to-use ('before calling get_set_cards', 'when the user asks which sets exist') and an explicit when-not ('Do not use to price a single card'), plus an alternative destination tool. Nothing 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds substantive context beyond them: corpus size (1.5M+ cards across named games/sports), that prices come from 'real sold listings' in USD, and that both ungraded and PSA 10 values are returned. It slightly overlaps the output schema by naming returned card ids, but that framing is chaining guidance rather than redundant return documentation.

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?

Front-loaded with the decision rule, then capability, then chaining and exclusions — every sentence carries information. The middle corpus-enumeration sentence is long but dense with disambiguating games/sports, so little could be cut without losing selection signal.

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 search tool with an output schema and full annotations, the description covers the remaining burden: when to reach for it first, what corpus it spans, what currency and grade tiers it returns, and which tools to chain into. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 75% and the query parameter already carries examples ('Umbreon VMAX Evolving Skies', '1986 Fleer Jordan') and set_id points to list_sets. The description's 'by name, set, number and year' largely restates what the schema demonstrates and says nothing about the game enum or the limit bounds (default 10, max 50). 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 and resource (search cards) plus the exact intent it serves: 'when the user names a trading card and wants its value, price, or whether to grade it.' It also distinguishes itself from siblings by positioning as the entry point that feeds get_card_prices, grading_roi and get_price_history.

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

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

Explicit when-to-use ('use this first when the user names a trading card') and explicit when-not ('not for sealed product, for cards you already have an id for, or for price prediction'). The exclusions map directly to siblings like get_card_prices and get_set_cards, so an agent can route without guessing.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the price basis (PSA 10 where available, raw otherwise), what the percentage is measured against, and the 300% data-quality cutoff that silently removes rows. It does not explain result ordering beyond 'biggest' or any paging behavior, keeping it out of 5 territory.

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

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

Three sentences, front-loaded with the trigger, then output semantics, then exclusions. No filler and no repetition 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?

An output schema exists, so return-shape detail is unnecessary. What an agent still needs -- when to call it, what the numbers mean, what is filtered out, and when to look elsewhere -- is all 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 coverage is 75% and already documents game, direction and min_market_usd separately. The description adds meaning the schema does not: the rank metric is PSA 10 when present and raw otherwise, which is what ties min_market_usd's raw-price filter and the 'biggest gainers' ordering together.

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 resource (cards), a specific qualification (30-day price movers), and the exact user intents it serves (rising, hot, spiking, crashing, trending). It is clearly distinguishable from siblings like get_price_history and liquid_movers 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 trigger conditions plus two exclusions ('Do not use for a single named card or for long-term history'), which is stronger than most definitions. It stops short of naming the sibling tool to use instead in those cases, so it is not a full 5.

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