Skip to main content
Glama
surplus-auctions-mcp

surplus-auctions-mcp

Get auction details

get_auction_details
Read-onlyIdempotent

Retrieve complete details for a specific GovDeals auction by ID or URL, including current bid, bid count, closing time, pickup location, condition, fees, and vehicle specs.

Instructions

Full details for one auction: current bid and bid count, exact end time, selling agency, pickup location, buyer's premium, reserve status, condition, description, and for vehicles/equipment the year, make, model, mileage, engine hours and VIN.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "auction_id": "<auction_id>"
    },
    "name": "get_auction_details"
  }
}

Input Schema

NameRequiredDescriptionDefault
auction_idYesAuction id as returned by search_auctions (e.g. "govdeals:13292-1554"), or a full GovDeals asset URL.

Output Schema

NameRequiredDescriptionDefault
idYesStable id to pass to get_auction_details, e.g. "govdeals:27018-390"
urlYes
cityYes
stateYesTwo-letter state where the item is located
titleYes
agencyYesGovernment agency selling the item
ends_atYesAuction end time, ISO 8601 UTC
vehicleYesPresent when the item looks like a vehicle or equipment
categoryYesCategory as labeled by GovDeals
currencyYes
quantityYes
warningsYes
bid_countYes
closes_inYesReadable time left, e.g. "4 min", "1h 20m", "2d 3h", "closed"
conditionYes
image_urlYes
is_closedYesTrue when the auction has already ended
extractionYesHow TinyFish produced this record: fetch = parsed from TinyFish Fetch; agent = TinyFish Agent; agent_fallback = Fetch parse failed and Agent was used (signals site drift).
hours_leftYesHours until the auction ends, computed when fetched
current_bidYesCurrent high bid (or starting bid if no bids) in USD
descriptionYes
reserve_metYes
starting_bidYes
payment_termsYes
pickup_locationYes
buyer_premium_pctYesBuyer's premium as a percent, e.g. 10 for 10%

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds what data comes back, but says nothing about failure behavior for an invalid or expired auction id, whether vehicle-specific fields are null for non-vehicle lots, or whether detail depth varies by source. It does not contradict the annotations.

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

Conciseness3/5

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

It is a single sentence with no filler, but a large share of its length is a field enumeration that largely restates what the output schema already exposes. The core intent ('full details for one auction') is front-loaded, but the tail of the sentence does little work.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only detail lookup with a full output schema and complete annotations, the definition covers what the tool returns and what the identifier looks like. The remaining gaps (behavior on stale/invalid ids, nullability of vehicle fields) are minor rather than blocking.

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

Parameters3/5

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

Schema coverage is 100% and the auction_id property already documents the expected format (e.g. 'govdeals:13292-1554') plus acceptance of a full GovDeals asset URL. The description adds nothing about the parameter, so the baseline 3 applies.

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 resource and scope: 'Full details for one auction,' followed by an enumeration of the returned attributes (current bid, end time, agency, VIN, etc.). An agent can immediately tell this is a single-record detail fetch, though the description never contrasts it with search_auctions or compare_auctions.

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?

Usage is only implied: 'one auction' suggests fetching a record you already have an id for. There is no explicit when-to-use statement, no mention of what to do first (search_auctions) and no note about when this is preferable to compare_auctions, which returns overlapping data for multiple auctions.

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