Skip to main content
Glama

govauctions.app

by app.govauctions
OverviewDiscussionsAdmin

Sold-price comps

get_sold_comps
Read-onlyIdempotent

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.

Input Schema

NameRequiredDescriptionDefault
qYesItem description, e.g. '2015 Ford F-150'
limitNoHow many underlying sales to return with include=comps. Capped by plan.
stateNoOptional 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.
countryNoUS
includeNoSet 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`.
categoryNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / country / enum
      Previous value: -[
-  "US",
-  "UK",
-  "CA",
-  "AU",
-  "DE"
-]New value: +[
+  "US",
+  "UK",
+  "CA",
+  "AU",
+  "DE",
+  "FR"
+]
  2. Changed2 schema fields changed
    • changedInput schema / properties / country / enum
      Previous value: -[
-  "US",
-  "UK",
-  "CA",
-  "AU"
-]New value: +[
+  "US",
+  "UK",
+  "CA",
+  "AU",
+  "DE"
+]
    • changedInput schema / properties / include / description
      Previous 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`."
  3. Changed2 schema fields changed
    • addedInput schema / properties / include
      Added 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"
+}
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "How many underlying sales to return with include=comps. Capped by plan.",
+  "type": "integer"
+}
  4. Changed2 schema fields changed
    • changedInput schema / properties / country / enum
      Previous value: -[
-  "US"
-]New value: +[
+  "US",
+  "UK",
+  "CA",
+  "AU"
+]
    • addedInput schema / properties / state
      Added 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"
+}
  5. First observed

TDQS

A4.1/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

All govauctions.app toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources