US government surplus auctions: search live lots by ZIP radius, sold prices and Flip Scores.
Scored across 7 tools
Most tools target distinct purposes (live search, single fetch, deal score, quota, sold data). However, sold_comps, sold_comps_batch, and get_sold_history overlap around sold-auction data, and an agent must read carefully to know that sold_comps returns aggregates/percentiles while get_sold_history returns raw lots and sold_comps_batch is just a batched variant.
Conventions are mixed: get_listing, get_sold_history, get_api_usage use a get_ verb prefix, while flip_score, sold_comps, sold_comps_batch, and search_listings use noun/noun_verb forms. Names remain readable and snake_case throughout, but there is no single predictable pattern.
Seven tools is well-scoped for a listings/comps API. Each tool maps to a clear capability (search, fetch, score, comps stats, comps history, batch comps, quota) with no filler.
The surface covers the core lifecycle: discovery (search_listings), retrieval (get_listing), valuation (flip_score, sold_comps, get_sold_history, sold_comps_batch), and operational quota (get_api_usage). Minor gaps like watchlist/save or category-listing tools exist but are workable around.
BidProwl's deal score for a live listing, with its condition-adjusted tier.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and largely fails: it does not say whether the call is read-only, whether scoring requires a live/active listing, how fresh the score is, or whether it can fail for expired listings. The only behavioral hint is the mention of a condition-adjusted tier, which implies an output shape but no operational 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?
One short sentence with no filler, front-loading the owner and the returned value. It is efficient, though the fragmentary phrasing trades clarity for brevity.
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 tool with no annotations, no output schema, and an undocumented required parameter, the description should do more. It never defines what a 'condition-adjusted tier' is, what scale the score uses, or what the caller receives, leaving core calling context 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 0% for the single required 'id' parameter, so the description must compensate. Saying 'for a live listing' implies the id is a listing identifier and that the listing should be live, which adds modest meaning, but it does not give the id format or confirm it is not a score id or user id.
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 identifies the resource it concerns (a live listing) and the value it produces (BidProwl's deal score plus a condition-adjusted tier), so an agent knows the general subject. However, it is phrased as a noun fragment without a verb, leaving unclear whether it fetches, computes, or caches the score, and it does not distinguish itself from siblings like get_listing or sold_comps.
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 statement of when to use this tool versus get_listing, sold_comps, or search_listings. A reader can guess it is used when a deal score is wanted, but no condition, prerequisite, or alternative is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This API key's plan, monthly call limit, calls used, calls remaining and when the quota resets (first of next month, UTC). Free to call: it does not count against the quota.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: read-only introspection of quota state plus the cost trait (free, quota-exempt) and the reset rule (first of next month, UTC). It does not state auth/permission requirements, but for a key-scoped read endpoint that is a small residual gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences; the returned fields are front-loaded and the cost/reset caveat follows. Every clause carries information the agent would otherwise have to guess.
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?
No output schema exists, so the description correctly compensates by enumerating the return values and the reset semantics. For a zero-parameter read tool, nothing needed 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 zero parameters, so there is nothing for the description to disambiguate beyond confirming the scope is implicitly the calling key. Baseline 4 applies for a parameterless 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 names the exact resource (this API key's quota) and enumerates the returned facts: plan, monthly limit, calls used, calls remaining, and reset timing. It is unambiguous and clearly distinct from the listing/comps siblings, though the verb itself is only implied by the tool name rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear call-time guidance by stating the call is free and does not count against the quota, which tells the agent it can invoke this liberally for diagnostics. There is no explicit when-not or alternative-tool comparison, but no sibling covers this capability, so the omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single listing by its BidProwl id or slug.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and discloses almost nothing: no indication of read-only nature (implied by 'Fetch' but not stated), no authentication requirements, and no error behavior for an unknown or expired listing id.
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 tight sentence with no filler, and the lookup-key detail is front-loaded immediately after the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description is minimally adequate, but it leaves return shape, not-found handling, and auth expectations unaddressed since no structured field covers them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description alone must explain the single 'id' parameter. It does add real meaning by noting the key may be a BidProwl id OR a slug, but gives no format, prefix, or example to disambiguate the two.
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 (Fetch) and resource (a single listing) and pins the lookup key to a BidProwl id or slug, so an agent can distinguish it from the multi-result sibling search_listings. It does not, however, explicitly name or contrast itself with any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance and no exclusions. It never says to prefer search_listings for querying and to use this only when a concrete id/slug is already known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The actual sold lots behind a comps number, newest close first: title, final price (cents), close date, state, source, BidProwl link. Pass one of category, item (tracked item slug) or q (free text, matched like a listing title), plus optional state. Paginate with cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Pro: free text, e.g. 2015 ford f150 | |
| item | No | Pro: tracked item slug, e.g. forklift | |
| limit | No | Default 25 | |
| state | No | ||
| cursor | No | next_cursor from the previous call | |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It usefully reveals sort order ('newest close first'), the return fields, and cursor-based pagination, but says nothing about auth requirements, rate limits, result caps, or what happens when none of category/item/q is supplied.
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?
Compact and front-loaded: the what, the returned fields, the parameter rule, and pagination in three tight sentences. Some of the parenthetical slugs duplicate the schema's own descriptions, costing a little density.
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 6-param, no-required, no-output-schema, no-annotation read tool, this is close to complete: it defines the payload shape in lieu of an output schema and the parameter-selection rule. The remaining gaps are edge behavior when no selector is passed and any rate/auth constraints.
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 description compensates for the gaps: it explains item is a 'tracked item slug', q is 'free text, matched like a listing title', and cursor is the pagination handle. It adds meaning beyond the schema for the highest-ambiguity params, though category and limit go unmentioned.
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 ('the actual sold lots behind a comps number') and immediately frames the distinction from the sibling sold_comps by positioning itself as the raw-lot view rather than the aggregate comp. It also enumerates the returned fields, so an agent knows exactly what payload to expect.
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 selection guidance — 'Pass one of category, item ... or q ..., plus optional state' — and says how to paginate. It does not, however, contrast when to prefer this over sold_comps or sold_comps_batch, so the agent must infer the drill-down-vs-aggregate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search 90,000+ live US government surplus auction listings from 26 official sources. Supports keyword, category, state, ZIP-radius, and price filters.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | Center a radius search on this ZIP | |
| page | No | ||
| sort | No | ||
| limit | No | Results per page, default 25 | |
| query | No | Keyword search, e.g. 'forklift' | |
| state | No | 2-letter US state code | |
| category | No | ||
| radius_miles | No | ||
| price_max_usd | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the data source (26 official sources) and freshness ('live'), which is genuinely useful, but says nothing about read-only nature, auth requirements, rate limits, pagination caps, or result shape for a 9-parameter search endpoint.
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 tight sentences with zero filler, and the scale/source claim is front-loaded before the filter capabilities. Nothing repeats the schema verbatim.
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 9-parameter tool with no annotations and no output schema, the description should cover pagination behavior, sort semantics, and roughly what a returned listing contains. It addresses only the filter surface, leaving the agent to guess at result shape and paging constraints.
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 only 44%, so the description must compensate, and it does partially: naming keyword, category, state, ZIP-radius, and price filters maps onto query, category, state, zip/radius_miles, and price_max_usd. However it adds no meaning for the undocumented page, limit, and sort parameters (the sort enum in particular), leaving real gaps.
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 (Search) and a precisely scoped resource (90,000+ live US government surplus auction listings from 26 official sources). The word 'live' implicitly distinguishes it from the historical-data siblings (sold_comps, get_sold_history), so an agent can route correctly 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?
The description lists supported filters but never states when to choose this tool over siblings like get_listing (single-listing detail) or sold_comps (historical prices), nor any exclusions or prerequisites. Usage must be inferred entirely from the tool name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sold-price stats from 250,000+ closed government auctions, nearly all from the last 12 months. Category+state aggregates, or exact percentile comps for a live listing via listing_id.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | ||
| category | No | ||
| listing_id | No | Pro: exact comps for this live listing |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses data provenance and recency (250,000+ closed government auctions, nearly all within 12 months), but says nothing about auth needs, rate limits, result size, or behavior with a partial parameter 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?
Two dense sentences with the data scope front-loaded and the two usage modes stated immediately after. No filler, no restatement 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 tool with no annotations and no output schema, the description is adequate but leaves gaps: it doesn't clarify parameter-combination validity, output shape, or how it differs from sold_comps_batch. An agent would need to guess at some calling conventions.
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% (only listing_id is documented in the schema), so the description must compensate. It adds real meaning by pairing state+category as an aggregate query and tying listing_id to exact percentile comps, but leaves unclear whether state or category can be used alone or what happens with all three combined.
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 resource (sold-price comps/statistics) with provenance and defines two distinct modes: state+category aggregates versus listing_id percentile comps. It does not, however, contrast itself with siblings like sold_comps_batch or get_sold_history, so an agent cannot fully disambiguate from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through parameter-mode pairing ('Category+state aggregates, or exact percentile comps for a live listing via listing_id'), which tells the agent which inputs select which behavior. There is no explicit when-to-use guidance for the single-listing case versus sold_comps_batch, and no statement of what happens when no parameters are supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Up to 25 sold_comps lookups in one call (100 on Pro+), each costing one API call. Each query is a listing id, a tracked item slug ("forklift"), a category ("vehicles"), or text naming a tracked item ("2015 Ford F150"). Item-level and per-listing answers need Pro or Pro+; categories work on every plan. Amounts are in cents.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Default 2-letter state for item and category queries | |
| queries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the batch cap (25, or 100 on Pro+), the per-query API cost, the plan requirements for different query types, and that amounts are in cents. It omits error/partial-failure behavior, which keeps 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?
Four tight sentences, front-loaded with the batch limit and cost, then query formats, then plan gating. Every sentence carries 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?
No output schema and no annotations, so the description must stand alone, and it covers limits, cost, plan gating, query formats, and units. It could say more about output shape or how partial failures are handled, but the essential call-time information is 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 50% and the undocumented 'queries' parameter is precisely what the description explains — listing id, tracked item slug, category, or free text naming a tracked item — with concrete examples. The 'state' default is already in the schema, so the description compensates for the coverage gap well.
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+resource+scope: 'Up to 25 sold_comps lookups in one call', which cleanly separates it from the single-lookup sibling sold_comps. It does not name the sibling explicitly, so it stops just short of 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?
Plan gating ('Item-level and per-listing answers need Pro or Pro+; categories work on every plan') gives real context for when the tool functions, but there is no explicit statement of when to prefer this over sold_comps versus making repeated single calls. Usage is implied by 'in one call' rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
flip_scoreget_api_usageget_listingget_sold_historysearch_listingssold_compssold_comps_batchLive listings, sold prices and resale scores from GovAuctions.app, the public surplus-auction site.
US Auctions MCP — every live US auction lot in the consolidated index, government AND commercial…
Government Auctions MCP — physical-asset auctions (surplus, seized, forfeited,
GSA Auctions API MCP — US federal government surplus auctions (keyed).
Add one secure layer between your agents and this server.
