# Check a price

Assess whether a USD price is reasonable for a stated product or shopping requirement.

## What this endpoint does

Endpoint

```
POST https://mcp.gaisho.co/v1/tools/vet_price
```

Assess a quoted USD price for a specific product or a shopping requirement, with a price verdict, suggested action and supporting reasons. Use it to answer whether an offer is worth considering; use find_deals separately when the shopper wants places to buy.

- Check whether a quoted price for a named model is reasonable.
- Assess the total price of a multipack or measured quantity.
- Ask for a reference range when the shopper has not supplied a quote.

## Before you call

- Include the model, generation, size, condition and pack size when known. For a broad request, state the actual requirements instead of inventing a precise model.
- price is the final total to assess, not a per-unit price to be multiplied again. For two 500 ml bottles costing $18 in total, pass price: 18 and unit: {quantity: 1000, unit: ml}.
- Only provide known quantities. Empty packaging, explicit replicas, deposits or installment amounts, and damaged or parts-only products are not supported price assessments; the result explains this with unverifiable and action null.

Send a JSON object as the request body and authenticate with Authorization: Bearer <API key>. Amounts are in USD unless the result explicitly says otherwise.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| product | string | Required | Product URL, ASIN, GTIN, ID, model or description. Pass URLs and IDs alone. Must contain non-whitespace text; at most 2,000 characters (enforced by the service). |
| unit | object | Optional | Known total quantity covered by price; for example 1000 ml for two 500 ml bottles. |
| unit.quantity | number | When parent supplied | Total quantity covered by price. Must be greater than 0. |
| unit.unit | string | When parent supplied | Unit of measure for quantity, such as ml, g, count or item. Cannot be empty; up to 80 characters. |
| price | number | Optional | Total USD amount to assess, excluding tax and shipping. Must be greater than 0. |

## Example request

Set GAISHO_API_KEY in your server or local environment. These examples use a JSON POST request; Python uses the standard library and JavaScript uses Node.js fetch. The 60-second client timeout in Python and JavaScript is configurable, not a service latency guarantee.

cURL

```
curl --fail-with-body 'https://mcp.gaisho.co/v1/tools/vet_price' \
  -H "Authorization: Bearer $GAISHO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "product": "Bose QuietComfort Ultra Headphones (2nd Gen)",
  "price": 349
}'
```

Python

```
import json
import os
import urllib.error
import urllib.request

arguments = json.loads(r'''{
  "product": "Bose QuietComfort Ultra Headphones (2nd Gen)",
  "price": 349
}''')
request = urllib.request.Request(
    "https://mcp.gaisho.co/v1/tools/vet_price",
    data=json.dumps(arguments).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["GAISHO_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        payload = json.load(response)
    print(json.dumps(payload, indent=2))
except urllib.error.HTTPError as error:
    print(error.read().decode("utf-8"))
    raise
```

JavaScript

```
// Node.js 18+; keep this code and the key on your server.
const response = await fetch("https://mcp.gaisho.co/v1/tools/vet_price", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GAISHO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "product": "Bose QuietComfort Ultra Headphones (2nd Gen)",
  "price": 349
}),
  signal: AbortSignal.timeout(60_000),
});
const body = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${body}`);
}
const payload = JSON.parse(body);
console.log(payload);
```

## Common request patterns

### Evaluate a multipack total

The $24.99 covers the entire 81-load pack, not each load.

JSON request body

```
{
  "product": "Tide PODS Original, 81-load pack",
  "price": 24.99,
  "unit": {
    "quantity": 81,
    "unit": "load"
  }
}
```

### Request a reference without a quote

Omit price; do not pass zero as a substitute for a missing quote.

JSON request body

```
{
  "product": "Bose QuietComfort Ultra Headphones (2nd Gen)"
}
```

## Response fields

The HTTP response contains tool and a top-level summary. The other payload fields are inside result.

| Field | Type | Description |
| --- | --- | --- |
| tool | string | The tool called: vet_price. |
| result.verdict | string | good: good price; fair: reasonable; high: expensive; suspicious: unusually low and needs verification; unverifiable: unable to assess. |
| result.action | string \| null | buy_now, wait, compare, verify_seller, or null when no recommendation is available. |
| result.confidence | number | Confidence in the price judgment, from 0 to 1. |
| summary | string | A concise explanation of the judgment. |
| result.evidence | string[] | Supporting reasons. |

## Example response

Examples are illustrative and may omit optional detail fields. Prices are not live quotes; identifiers and example.com URLs are placeholders to replace, not usable product records.

HTTP 200 · illustrative, shortened

```
{
  "tool": "vet_price",
  "summary": "$349.00 is a reasonable price for Bose QuietComfort Ultra Headphones (2nd Gen).",
  "result": {
    "verdict": "fair",
    "action": "buy_now",
    "confidence": 0.65,
    "evidence": [
      "Same-model Bose QuietComfort Ultra Headphones (2nd Gen) reference: $359.99 for 1 headphone set; your quote is $10.99 lower."
    ]
  }
}
```

## How to read the result

- In REST, summary is at the top level; verdict, action, confidence and evidence are under result. MCP exposes the five fields together as the tool payload.
- verdict describes the price and action describes the next step. Read both with their explanation; do not turn a price judgment into a seller-trust judgment.
- Use confidence to guide wording: at least 0.75 permits a direct assessment; 0.45 to below 0.75 calls for a qualification based on the evidence; below 0.45 calls for any stated assumptions or limitations. It is not a calibrated probability of correctness.
- Evidence supports the judgment. A model-estimated reference is not a live seller offer; suspicious means an unusually low price needs verification, not that fraud is proven.

## Empty results and errors

| Situation | How to handle it |
| --- | --- |
| unverifiable with action null | This is an assessment outcome, not an HTTP failure. Read the explanation; provide missing product or quantity information when available. |
| No quoted price | The result is unverifiable with no purchase action; a reference range is provided when available. |
| suspicious or verify_seller | Inspect the listing and seller before paying. Use vet_seller when a seller check is needed. |
| compare | Use find_deals if the shopper wants alternative purchase options. |

A successful request can return no candidates, missing information or an unavailable assessment. Check the result before recommending a product. For request failures, use the error code and message; retrying the same invalid input will not fix it.

- [Error handling and retries](https://gaisho.co/docs/api#errors): HTTP statuses, structured errors, rate limits and quota responses.

## What to call next

- [Compare purchase options](https://gaisho.co/docs/api/find_deals): Find offers for the same product, compatible alternatives, or models with specification upgrades and downgrades.
- [Check a seller](https://gaisho.co/docs/api/vet_seller): Assess a seller or online store and return a trust assessment with supporting facts.
- [Get offer details](https://gaisho.co/docs/api/get_offer): Read a listing’s purchase URL, seller, price, coupon terms and stated product information.

- [Use this tool through MCP](https://gaisho.co/docs/mcp/vet_price): The same capability through the other connection.
- [REST API conventions](https://gaisho.co/docs/api): Authentication, response envelopes and request handling.