Tool reference

Check Product Fit

Use before a shopping, browser, or commerce agent recommends, shortlists, compares, or purchases a product.

Overview

check_product_fit $0.05 USDC MCP: check_product_fit SDK: checkProductFit()

Fetches a public product page and returns conservative product-fit signals for budget, must-have terms, avoid terms, compatibility, use case, shipping, and availability constraints.

POST /v1/check-product-fit POST /x402/v1/check-product-fit

When an agent should use it

  • Check whether a product page appears to satisfy a buyer's budget and must-have constraints before recommending it.
  • Flag avoid terms, compatibility uncertainty, or missing shipping details in an agent shopping workflow.
  • Attach source snippets, confidence, and content hashes to product shortlisting or purchase decisions.

Input fields

Schema ref: #/components/schemas/CheckProductFitInput

FieldRequiredTypeDescription
productUrl required string Public HTTP or HTTPS product page URL to fetch. Localhost, private IPs, link-local addresses, embedded credentials, unsafe redirects, and non-http(s) schemes are rejected.
constraints optional object Buyer constraints to evaluate against fetched product-page text.
strictness optional string Extraction strictness. Allowed values: low, medium, or high. Higher strictness favors fewer guesses and more null fields when policy language is unclear.
maxSnippets optional integer Maximum number of evidence snippets to return. Claim verification allows 1 to 8; commerce extraction allows 1 to 10.
includeRawText optional boolean When true, include raw extracted text in the response. Defaults to false to keep responses compact and avoid returning unnecessary page text.

Output fields

Schema ref: #/components/schemas/CheckProductFitOutput

FieldRequiredTypeDescription
fit_score required number Number from 0 to 100 summarizing supported product-fit signals. It is not a guarantee that the product satisfies the buyer.
verdict required string Claim-check result. Allowed values: supported, contradicted, not_addressed, or unclear.
matched_constraints required array Constraints that appear supported by fetched page text.
unmet_constraints required array Constraints that were contradicted, not found, or could not be evaluated from fetched page text.
concerns required array Conservative concerns such as avoid terms, over-budget signals, blocked pages, or missing product content.
price_detected required string,null First conservative page price mention detected from fetched text, or null when no price is supported.
compatibility_notes required array Supported or missing compatibility notes derived from fetched page text.
shipping_or_availability_notes required array Shipping, delivery, stock, or availability snippets found on the page.
extracted_snippets required array Short source snippets used by the extraction. Empty array means no concise supporting snippet was available.
confidence required number Number from 0 to 1 expressing how strongly the extracted signals support the result. Lower confidence means the caller should treat the output as tentative or seek review.
content_hash required string Hash of the fetched page content for comparison, caching, and lightweight audit trails.
fetched_at required string ISO timestamp when Primitive402 fetched the source page.
source_url required string Original URL submitted by the caller.
final_url required string,null Final fetched URL after safe redirects. Null means no final URL was available.
raw_text optional string Raw extracted page text. Present only when includeRawText is true.

curl example

curl -s https://primitive402.dev/v1/check-product-fit \
  -H 'content-type: application/json' \
  -d '{
  "productUrl": "https://example.com/products/daypack",
  "constraints": {
    "budgetMax": 120,
    "currency": "USD",
    "mustHave": [
      "water resistant",
      "laptop sleeve"
    ],
    "avoid": [
      "final sale"
    ],
    "compatibleWith": [
      "15 inch laptop"
    ],
    "useCase": "commuting",
    "locationOrShipping": "ships to United States"
  },
  "strictness": "medium",
  "maxSnippets": 5
}' | jq

TypeScript SDK example

import { createNano402Client } from "@nano402/api/sdk";

const client = createNano402Client({
  baseUrl: "https://primitive402.dev"
});

const result = await client.checkProductFit({
  "productUrl": "https://example.com/products/daypack",
  "constraints": {
    "budgetMax": 120,
    "currency": "USD",
    "mustHave": [
      "water resistant",
      "laptop sleeve"
    ],
    "avoid": [
      "final sale"
    ],
    "compatibleWith": [
      "15 inch laptop"
    ],
    "useCase": "commuting",
    "locationOrShipping": "ships to United States"
  },
  "strictness": "medium",
  "maxSnippets": 5
});
console.log(result);

Example response snippet

{
  "fit_score": 82,
  "verdict": "good_fit",
  "price_detected": "$89",
  "confidence": 0.76
}

Safety notes

  • All requested URLs are checked with SSRF protection before fetching.
  • The response contains fit signals, not a guarantee that a product satisfies the buyer's needs.
  • When product, price, compatibility, or shipping language is unclear, Primitive402 returns concerns, unmet constraints, unknown verdicts, or low confidence instead of guessing.

Common errors

  • 400 invalid_request: request body failed validation.
  • 402 payment_required: the x402 route was called without a valid payment header.
  • 429 rate_limited: rate limit exceeded. Free /v1/* routes are development endpoints; use the /x402/v1/* paid alias for production or agent usage.
  • 500 internal_error: unexpected server error.

Discovery

Back to tool library

Catalog viewer x402 catalog viewer Bazaar viewer Discovery readiness Quality benchmarks OpenAPI viewer /catalog.json /x402/catalog.json /x402/bazaar.json /openapi.json