Skip to main content
Glama
surplus-auctions-mcp

surplus-auctions-mcp

Search government surplus auctions

search_auctions
Read-onlyIdempotent

Find active GovDeals government surplus auctions by keyword, state, category, price, or closing time; returns normalized listings with current bid, end time, and location, sorted by soonest ending.

Instructions

Search active government surplus auctions on GovDeals. Returns normalized listings (title, current bid, end time, location) sorted by soonest ending, plus a per-site status. Use get_auction_details for mileage, VIN, buyer's premium and pickup info.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_auctions"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum results to return (default 10)
stateNoTwo-letter US state where the item is located, e.g. TX. Omit to search nationwide.
keywordNoWhat to look for, e.g. "pickup truck", "F-150", "excavator", "laptop"
categoryNoItem category. "vehicles" and "trailers" are filtered natively on GovDeals; other categories are matched by keyword.
max_priceNoOnly auctions whose current bid is at or below this many USD
min_priceNoOnly auctions whose current bid is at least this many USD
ending_within_hoursNoOnly auctions closing within this many hours (max 336, i.e. 14 days)

Output Schema

NameRequiredDescriptionDefault
auctionsYes
warningsYes
total_returnedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so safety is covered. The description adds value beyond that: it discloses the normalization of listings, the sort order (soonest ending), and the inclusion of a per-site status in the response, which signals multi-site fan-out and possible partial results.

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

Conciseness5/5

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

Two sentences, front-loaded with purpose, then return shape, then the handoff to the detail tool. No redundant restatement of the name or annotations.

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?

Seven optional parameters with full schema coverage and an output schema mean the structured fields carry the detail load. The description covers what is missing from those: sort order, response contents, per-site status, and the sibling handoff for extra fields.

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 description coverage is 100%, so every parameter including the category enum and the price/hour bounds is already documented in the schema. The description adds only the salient default sorting and output fields, not syntax or interaction guidance for the filters, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (active government surplus auctions on GovDeals), names the return fields and sort order, and distinguishes the tool from get_auction_details, which covers mileage/VIN/premium/pickup. An agent can tell what this returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description directs the agent to get_auction_details for detail-level fields, giving a clear boundary against the main sibling. It does not address the other siblings (list_ending_soon, compare_auctions) or state when not to search, so explicit exclusions are absent.

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