Skip to main content
Glama

Shopgoodwill Search

shopgoodwill_search
Read-onlyIdempotent

Search active auctions on shopgoodwill.com, the online auction site run by Goodwill member organizations, cameras, jewelry, watches, art, collectibles, electronics, clothing. Returns live listings with current bid price, bid count, buy-now price, category, end time and listing URL. Bids are served through a 5-minute result cache, so the current bid can be up to five minutes old: near the close of an auction treat it as a lower bound, never as the final price. Sourced from the shopgoodwill.com search API.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "nikon",
      "per_page": 5
    },
    "name": "shopgoodwill_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoResult page, starting at 1
queryYesSearch keywords, e.g. "nikon d750" or "sterling silver"
per_pageNoMax results to return, up to 40 (each source page holds 40 rows; use page to paginate)
max_priceNoMaximum current price in USD
min_priceNoMinimum current price in USD
category_idNoOptional ShopGoodwill category id to narrow results (e.g. 15 = Art, 99 = Books)
buy_now_onlyNoOnly listings with a Buy Now price

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, open-world and non-destructive, so the description earns credit for going beyond them: it discloses the 5-minute result cache, warns that the current bid can lag and should be treated as a lower bound near auction close, and names the upstream API. That staleness caveat is exactly the kind of behavior an annotation cannot express. It stops short of describing pagination limits or rate limits.

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?

Three front-loaded sentences: what it searches, what comes back, and the cache caveat that most affects interpretation. The trailing category list in sentence one reads as a slightly awkward tack-on, but nothing is redundant or padded.

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, the description compensates by enumerating the returned fields (current bid, bid count, buy-now price, category, end time, URL), and it adds the freshness caveat that governs how those values should be interpreted. An agent has everything needed to call and correctly reason about results.

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%, including per-parameter notes on page/per_page pagination and category ids, so the schema already carries the parameter burden. The description adds no parameter-level meaning beyond it — the prices, category and buy-now references appear only in the context of returned fields, not as input guidance.

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?

Opens with a specific verb and resource — "Search active auctions on shopgoodwill.com" — and enumerates the inventory (cameras, jewelry, watches, art, collectibles, electronics, clothing) plus the returned fields. The word "active" implicitly separates it from the sold/completed sibling, but that alternative is never named, so the differentiator must be inferred.

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 implied by "active auctions" and by the note that bids are served from a cache, which tells an agent this is for browsing live listings. However, there is no explicit when-to-use statement, no exclusion (e.g. use the sold search for completed prices), and no mention of when the sibling item-lookup tool would be preferable.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.