Live listings, sold prices and resale scores from GovAuctions.app, the public surplus-auction site.
Scored across 9 tools
Most tools have clearly distinct purposes: get_listing (by id) vs search_listings (search), get_api_usage (quota) vs get_comp_coverage (data coverage). The comps family (get_sold_comps, get_sold_comps_batch, get_sold_history, get_price_trend) overlaps conceptually, but descriptions carefully distinguish aggregate percentile ranges, individual archived sales, temporal trend, and the batch wrapper.
Every tool follows a consistent snake_case verb_noun pattern (get_*, search_listings), with get_sold_comps_batch cleanly extending get_sold_comps. The single search_ verb is used appropriately for the one query-style tool.
Nine tools is well-scoped for a market-data API, covering listing lookup/search, comps in multiple views, coverage, scoring, and quota without redundancy. No tool feels padded.
The surface thoroughly covers the domain: live listings, id lookup, comps (single/batch/history/trend), coverage, flip score, and usage. Minor gaps exist — no way to enumerate supported markets/categories or browse the archive directly (the latter noted as intentional).
This key's usage for the current month: total calls and the separate valuation allowance (which comps, sold history, trend and flip-score draw down), plus the reset date. Call it to pace a long run instead of hitting a 429 mid-task. Every other signed-in tool result already carries the same numbers in _meta.usage, so this is rarely needed. Free: it does not count against either allowance. Requires sign-in or an API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety (read-only, idempotent, closed-world). The description adds quota behavior ('Free: it does not count against either allowance'), the auth requirement (sign-in or API key), and the failure mode it prevents (429). That is substantive behavioral context the annotations do not provide.
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 return payload, then the when/when-not guidance, then cost and auth. Five sentences, all of which carry distinct, actionable information; nothing is padding.
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, but the description enumerates the returned fields and the reset date, and covers auth and cost. An agent has everything needed to decide whether to call it and what it will get back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema has nothing to explain and the baseline is 4. The description correctly spends no words on inputs.
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 returns: total calls and the separate valuation-allowance breakdown (which comps, sold history, trend, flip-score draw down) plus the reset date. No sibling tool covers usage or quota, so it is unambiguously distinguishable from the get_*/search_* family.
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 use case ('pace a long run instead of hitting a 429 mid-task') and an explicit when-not: 'Every other signed-in tool result already carries the same numbers in `_meta.usage`, so this is rarely needed.' The alternative source of the data is named, not left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How much sold-price data we hold per category for a market, and which categories can never be priced. Check this before building on the comps tools — it is the honest answer about what we cannot do. Works signed out.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | US |
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 genuinely new context: 'Works signed out,' which tells the agent no auth is required, and warns that some categories can never be priced. It does not describe granularity of the coverage figures or latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the return content, then usage guidance, then the auth note. No filler; every clause carries information an agent needs.
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 correctly takes on describing the return content (per-category data volume and unpriceable categories) and auth requirements. It stops short of specifying the metric's form (counts vs. percentages) or whether results are per-country granularity, which would matter for a coverage check.
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% and the description only alludes to a market scope ('per category for a market') without naming the country parameter, its six-value enum, or the US default. With one optional parameter entirely undocumented outside the raw schema, the description fails to compensate for the coverage gap.
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 and scope: sold-price data volume per category for a market, plus which categories can never be priced. The framing 'before building on the comps tools' cleanly separates it from siblings like get_sold_comps and get_sold_history, which return comps rather than coverage metadata.
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 call it ('Check this before building on the comps tools') and why ('the honest answer about what we cannot do'). It gives clear context but no explicit when-not or named alternative for the case where coverage is already known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GovAuctions Flip Score resale signal for one live lot, from any source, in any market with sold-price comps (valued against that market's comp archive): estimated value, effective bid, discount, and the link to the lot on its source site. Pass the lot id as it appears in a govauctions.app lot URL. Requires sign-in or an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond them: the sign-in/API-key requirement and the dependency on the market's sold-price comp archive. It stops short of describing behavior when comps are absent for a lot.
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 what the tool produces, followed by the id-format instruction and the auth prerequisite. The middle clause ('from any source, in any market with sold-price comps (valued against that market's comp archive)') is dense but each element carries 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 one-parameter read tool with no output schema, the description covers the return payload shape, the id convention, and the auth requirement. Remaining gaps are edge-case behavior (missing comps, invalid ids) rather than anything blocking a correct call.
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?
With a single parameter and 0% schema description coverage, the description compensates by specifying the expected format: the lot id as it appears in a govauctions.app lot URL. That is the one detail an agent could not infer from the bare string 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 resource and what it returns (estimated value, effective bid, discount, source link) and constrains scope to one live lot with sold-price comps. It implicitly separates itself from raw-comp siblings like get_sold_comps, but never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a prerequisite ('Requires sign-in or an API key') and implies applicability (single live lot, any source/market that has comps), which hints at when the tool works. It does not say when to prefer this over get_sold_comps, get_price_trend, or get_listing, nor what happens when no comps exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one live GSA listing by its id (facts only). Works signed out.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
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 value beyond that: it discloses the auth requirement ("Works signed out") and that only currently live listings are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core operation front-loaded and the scope/auth caveats appended compactly.
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 single-record read with no output schema, the description covers purpose, scope (live), and auth. Only the id format and behavior on a missing/non-live id are left unstated.
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 0% and the single parameter is documented only as a string. The description repeats the schema ("by its id") without adding format, source, or valid-value guidance, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get one live GSA listing by its id") which clearly separates it from the batch/list sibling search_listings. The "facts only" qualifier hints at scope but is vague and could be read as excluding analytical fields.
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?
"Works signed out" gives a useful precondition, but there is no explicit when-to-use guidance or naming of the alternative (e.g. search_listings when the id is unknown). Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Month-by-month median sale price for an item, plus the first-to-last change — 'is this category softening?'. Computed from the same comps as get_sold_comps, so it never contradicts that range. Returns an empty series when too few months clear the sample threshold. Requires sign-in or an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Item description, e.g. 'forklift' | |
| state | No | Optional 2-letter state/region code. | |
| country | No | US | |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely non-structured context: the sign-in/API-key requirement and the empty-series behavior when too few months clear the sample threshold. No pagination or size limits are mentioned, keeping it short of 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?
Three dense sentences with the core output front-loaded, followed by the consistency guarantee, edge-case behavior, and auth requirement. Every sentence earns its place 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?
With no output schema, the description does the work of describing the return shape (month-by-month series plus change, possibly empty), which is what an agent needs to interpret results. The remaining gap is parameter-level detail, especially the undocumented category filter.
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 50% (category has no description, state/country are thin), and the description adds nothing about what the parameters mean or how filtering works. With a documented gap in the schema, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource ('Month-by-month median sale price for an item, plus the first-to-last change') and explicitly distinguishes itself from the sibling get_sold_comps by stating it uses the same comps. An agent can tell exactly what it produces versus the comps tools.
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?
Frames the use case ('is this category softening?') and clarifies the relationship to get_sold_comps, which helps selection. It stops short of stating when to prefer this over get_sold_history or get_comp_coverage, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sold-price comps for a described item, computed across the full government-surplus market in any market listed in country. Signed out: coverage (how many comparable sales, confidence, a coarse price band) plus categoryStats, the 25th/median/75th percentile of every sale in the item's category (in state when it has enough sales). Signed in or with an API key: the 25th/median/75th percentile for this item itself. liveListingsUrl links to the live auctions for the same item. A miss says which kind it is: reason insufficient_comps (too few comparable sales yet) is worth retrying, reason category_not_priceable (real-estate) never is — that category cannot be priced from a title. A catch-all category such as miscellaneous is not refused: it is dropped and the item is priced on its title alone, with requestedCategory and categoryDropped echoed back — check the resolved category and confidence before trusting the range. A miss can still carry categoryStats when the item's category is clear, and retryHint when the query was a long listing title: retry with just the brand and model.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Item description, e.g. '2015 Ford F-150' | |
| limit | No | How many underlying sales to return with include=comps. Capped by plan. | |
| state | No | Optional 2-letter state/region code for a regional range. Falls back to the national range when that state has too few sales; the response's `scope` field says which you got. | |
| country | No | US | |
| include | No | Set to "comps" to also return the individual sales the range was computed from (title, final price, sale month, state). Requires a key; the number returned is capped by plan. Not served for EU markets (DE, FR, NL, PL): the range is returned with `compsWithheld: true`. | |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: signed-out vs signed-in result differences, EU withholding via `compsWithheld`, catch-all category dropping with `requestedCategory`/`categoryDropped` echo, and distinct miss reasons with retry semantics. This is exactly the value-add layer the annotations cannot express.
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-loads what the tool returns before the failure semantics, and nearly every sentence carries operational information. It is dense and em-dash-heavy with some long run-on sentences, which costs it a point but not readability.
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 and 6 params, the description carries the full return-shape burden and does so: `categoryStats` percentiles, `liveListingsUrl`, `confidence`, `scope`, `requestedCategory`/`categoryDropped`, `compsWithheld`, `retryHint`, and the two miss reasons are all explained. An agent can interpret a response without guessing.
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 undocumented `category` param by explaining the catch-all drop behavior, plus clarifies `country` scoping, `state` fallback (also echoed in `scope`), and `include=comps` requiring a key and being withheld in EU markets. It adds real meaning over the schema, though it does not touch `limit`.
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 ('Sold-price comps for a described item') and scopes it precisely ('full government-surplus market in any market listed in `country`'), which an agent can act on directly. It does not name or differentiate itself from nearby siblings like get_sold_comps_batch or get_sold_history, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives strong conditional guidance for the failure path (retry on `insufficient_comps`, never on `category_not_priceable`; retry a long listing title with brand+model) and explains tier gating. It never says when to pick this tool over get_price_trend, get_flip_score, or get_sold_comps_batch, so tool-selection guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_sold_comps for a list of items in one call. Each query is either a string ('2015 Ford F-150') or an object with its own q/category/country/state. Each item costs one valuation lookup, exactly as if sent alone; an item that comes back without a range is not charged. If the monthly allowance runs out part-way, the items already priced are returned and batch.truncated names the rest. Batch size is capped by plan (10 on the free allowance). Requires sign-in or an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Default 2-letter state/region code for every query. | |
| country | No | Default market for every query. | US |
| queries | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: billing semantics, the uncharged-no-range rule, partial-allowance truncation with `batch.truncated` naming the remainder, plan-based caps, and auth requirements. This is exactly the extra behavioral detail annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, front-loaded with purpose before cost, truncation, caps, and auth. Every sentence carries a distinct operational fact 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?
With no output schema, the description still discloses the key return behavior (partial results plus `batch.truncated`), plus cost, caps, and auth. Nothing an agent needs to invoke 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 67%, so the schema documents most fields; the description still clarifies the string-vs-object duality of each query and that objects carry their own q/category/country/state, implying per-item override of the top-level defaults. It adds real meaning over the raw oneOf structure, though it doesn't spell out default inheritance explicitly.
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?
Opens with a specific verb+resource scoped to a batch ('get_sold_comps for a list of items in one call'), which immediately distinguishes it from the singular get_sold_comps sibling. An agent knows exactly what it does and how it differs from the single-item 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 strong operational context: per-item cost equals a standalone lookup, uncharged items without a range, plan-based batch caps (10 free), and sign-in/API-key requirement. It doesn't explicitly say 'use get_sold_comps instead when you have one item,' but the batch framing makes the alternative obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The individual archived sales behind an item: title, final price, sale month and state, plus the range they produce. Use when you want the evidence rather than just the number. Query-anchored — describe an item; there is no way to list the archive. Requires sign-in or an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Item description, e.g. '2015 Ford F-150' | |
| limit | No | How many sales to return. Capped by plan. | |
| state | No | Optional 2-letter state/region code. | |
| country | No | US | |
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent/no-destruction profile, and the description adds genuinely new context: it requires sign-in or an API key, results are capped by plan, and there is no listing mode. These are behavioral constraints the annotations do not express.
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 dense sentences with the return contents front-loaded, then usage, then the query-anchored constraint and auth note. Every clause carries information; only the 'range they produce' phrasing is slightly vague.
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 compensates by enumerating the returned fields (title, final price, sale month, state, range) and the auth/plan constraints. Only the exact shape of the produced range and per-param defaults are left implicit.
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 60%, so several parameters (q, limit, country, category) rely on their own schema text. The description corroborates 'state' as the sale's state/region and frames q as an item description, but adds little syntax or format detail 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?
Names a specific resource (individual archived sales behind an item) and enumerates its content (title, final price, sale month and state, range). It implicitly distinguishes itself from get_sold_comps with 'the evidence rather than just the number,' but never names the sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when you want the evidence rather than just the number' gives clear selection context, and 'Query-anchored — describe an item; there is no way to list the archive' rules out a browsing use case. It stops short of explicitly naming get_sold_comps as the alternative when a single number suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search live GSA federal-surplus auction listings (facts only — no images). Filter by state, category, keyword, price, or distance from a US ZIP code. Works signed out (up to 25 rows per page). Raw listings cover sanctioned federal sources; sold-price comps span the full market.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Title keyword | |
| zip | No | US 5-digit ZIP to search around. Limits results to lots within radiusMiles, orders them nearest-first, and adds distanceMiles to each. | |
| sort | No | Result order. Default is soonest-ending (nearest-first when `zip` is given). Use `newest` to order by the lot's own listing date, newest first - that is the ordering a recurring "what is new" check needs, because under the default a brand-new lot can sit anywhere in the results. | |
| limit | No | Rows per page. Signed out, capped at 25. | |
| state | No | 2-letter state code | |
| offset | No | ||
| source | No | gsa | |
| country | No | US | |
| category | No | ||
| priceMax | No | ||
| priceMin | No | ||
| radiusMiles | No | Radius from `zip`, in miles (default 100, max 500). Requires `zip`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context: no images in results, works without auth, 25-row signed-out cap, and the data-coverage note about sanctioned sources vs full-market comps. The final clause is slightly cryptic but still informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core purpose front-loaded and filters/preconditions following. Efficient overall, though the trailing sold-price-comps clause is somewhat tangential to the tool's own behavior and could be trimmed.
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 12 optional params, no output schema, and full annotation coverage, the description supplies the essentials: what it searches, how to filter, auth/page constraints, and result scope. It is only lightly thin on pagination and return-shape expectations.
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?
With 50% schema description coverage, the description helps by enumerating the filter surface (state, category, keyword, price, distance/ZIP) and the signed-out row cap. However it leaves sort, offset/pagination, source, and country behavior entirely to the schema, so it only partially compensates for the coverage gap.
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 ('Search live GSA federal-surplus auction listings') and immediately scopes it with 'facts only — no images' and the filterable dimensions. This clearly separates it from singular retrieval siblings like get_listing and from the comp/history tools.
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's role (filter-based discovery of live listings) and notes signed-out access, but it never states when to prefer it over siblings such as get_listing, get_sold_comps, or get_sold_history. Usage is inferable rather than explicit.
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.
get_sold_comps_batchsearch_listings1 field changedInput schema / properties / limit / descriptionAdded value: +"Rows per page. Signed out, capped at 25."get_comp_coverage1 field changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU",
- "DE"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE",
+ "FR"
+]get_price_trend1 field changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU",
- "DE"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE",
+ "FR"
+]get_sold_comps1 field changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU",
- "DE"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE",
+ "FR"
+]get_comp_coverage1 field changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE"
+]get_price_trend1 field changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE"
+]get_sold_comps2 fields changedInput schema / properties / country / enumPrevious value: -[
- "US",
- "UK",
- "CA",
- "AU"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU",
+ "DE"
+]Input schema / properties / include / descriptionPrevious value: -"Set to \"comps\" to also return the individual sales the range was computed from (title, final price, sale month, state). Requires a key; the number returned is capped by plan."New value: +"Set to \"comps\" to also return the individual sales the range was computed from (title, final price, sale month, state). Requires a key; the number returned is capped by plan. Not served for EU markets (DE, FR, NL, PL): the range is returned with `compsWithheld: true`."search_listings1 field changedInput schema / properties / sortAdded value: +{
+ "description": "Result order. Default is soonest-ending (nearest-first when `zip` is given). Use `newest` to order by the lot's own listing date, newest first - that is the ordering a recurring \"what is new\" check needs, because under the default a brand-new lot can sit anywhere in the results.",
+ "enum": [
+ "ending-soonest",
+ "newest"
+ ],
+ "type": "string"
+}get_api_usageget_comp_coverageget_price_trendget_sold_comps2 fields changedInput schema / properties / includeAdded value: +{
+ "description": "Set to \"comps\" to also return the individual sales the range was computed from (title, final price, sale month, state). Requires a key; the number returned is capped by plan.",
+ "type": "string"
+}Input schema / properties / limitAdded value: +{
+ "description": "How many underlying sales to return with include=comps. Capped by plan.",
+ "type": "integer"
+}get_sold_historysearch_listings2 fields changedInput schema / properties / radiusMilesAdded value: +{
+ "default": 100,
+ "description": "Radius from `zip`, in miles (default 100, max 500). Requires `zip`.",
+ "maximum": 500,
+ "type": "number"
+}Input schema / properties / zipAdded value: +{
+ "description": "US 5-digit ZIP to search around. Limits results to lots within radiusMiles, orders them nearest-first, and adds distanceMiles to each.",
+ "type": "string"
+}get_sold_comps2 fields changedInput schema / properties / country / enumPrevious value: -[
- "US"
-]New value: +[
+ "US",
+ "UK",
+ "CA",
+ "AU"
+]Input schema / properties / stateAdded value: +{
+ "description": "Optional 2-letter state/region code for a regional range. Falls back to the national range when that state has too few sales; the response's `scope` field says which you got.",
+ "type": "string"
+}get_flip_scoreget_listingget_sold_compssearch_listingsUS government surplus auctions: search live lots by ZIP radius, sold prices and Flip Scores.
Government Auctions MCP — physical-asset auctions (surplus, seized, forfeited,
US Auctions MCP — every live US auction lot in the consolidated index, government AND commercial…
Collector-car auction history, live listings, bid trails, and market statistics for AI agents.
Add one secure layer between your agents and this server.
