US government surplus auctions: search live lots by ZIP radius, sold prices and Flip Scores.
Scored across 7 tools
Each tool has a clearly distinct role: live listing search, single listing retrieval, deal scoring, sold-comp aggregates, raw sold-lot history, batch comps, and API quota usage. The sold_comps/get_sold_history distinction is explicitly explained as aggregate statistics versus actual sold lots, so an agent can reliably choose between them.
Names are all snake_case and readable, but the convention is mixed: get_listing, get_sold_history, get_api_usage, and search_listings are verb-first, while flip_score, sold_comps, and sold_comps_batch are noun-first. The batch tool is predictably named, but there is no single consistent verb_noun pattern across the set.
Seven tools is well-scoped for an auction listing and comps API. Each tool earns its place: search, get, score, comps, history, batch, and quota usage cover the core workflows without redundant surface area.
The read-only auction research surface is largely complete: live listing search, single-listing lookup, deal scoring, aggregate comps, raw sold history, batch comps, and API usage are all covered. Minor gaps remain, such as no tool to enumerate categories, sources, or tracked item slugs that other tools reference.
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 27 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 | Default: relevance (best match) when a query is given, otherwise ending_soon | |
| limit | No | Results per page, default 25 | |
| query | No | Keyword search, e.g. 'forklift'. Model numbers match across spellings (f150, F-150, F 150) and common brand short forms are included (CAT, JD, Chevy, VW, IH). | |
| 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?
With no annotations, the description carries the full burden. It usefully discloses the corpus size and source breadth, but says nothing about result shape, freshness, bid/price fields, rate limits, or whether expired listings appear — gaps an agent must discover by calling 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 dense sentences with the scope and filter axes front-loaded and no filler. 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?
Given 9 parameters, no annotations, and no output schema, the description should say more about what a result record contains and how paging behaves. Corpus size and source count are helpful, but the definition remains thin for a primary search entry point.
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 description enumerates the supported filter axes (keyword, category, state, ZIP-radius, price), mapping to 5 of 9 parameters, while the schema already documents query matching and sort defaults at 56% coverage. It adds little beyond the schema and does not compensate for the undocumented params (page, radius_miles bounds, min-price absence).
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 ... live US government surplus auction listings') plus concrete scope: 90,000+ listings across 27 official sources. The word 'live' implicitly separates it from the sold-history siblings (sold_comps, get_sold_history), but no sibling is named explicitly, so it stops 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?
Usage is only implied: an agent can infer this is for active auctions and that sold_comps/get_sold_history cover completed sales. There is no explicit when-to-use, when-not-to-use, or named alternative, and no note on whether this tool returns comps data at all.
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.
search_listings3 fields changedInput schema / properties / query / descriptionPrevious value: -"Keyword search, e.g. 'forklift'"New value: +"Keyword search, e.g. 'forklift'. Model numbers match across spellings (f150, F-150, F 150) and common brand short forms are included (CAT, JD, Chevy, VW, IH)."Input schema / properties / sort / descriptionAdded value: +"Default: relevance (best match) when a query is given, otherwise ending_soon"Input schema / properties / sort / enumPrevious value: -[
- "ending_soon",
- "newest",
- "price_low",
- "price_high",
- "most_bids",
- "best_deals"
-]New value: +[
+ "relevance",
+ "ending_soon",
+ "newest",
+ "price_low",
+ "price_high",
+ "most_bids",
+ "best_deals"
+]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.
Auction houses, online auctions and government surplus.
US Auctions MCP — every live US auction lot in the consolidated index, government AND commercial…
Government Auctions MCP — physical-asset auctions (surplus, seized, forfeited, tax-deed) that…
Add one secure layer between your agents and this server.
