UCP vendor capability
cc.pivota.insights
Pivota Insights is the decision layer behind Pivota's catalog: alternatives, cross-merchant offers and reviewed product intelligence with cited evidence. This capability publishes it to Universal Commerce Protocol platforms as three read-only tools on Pivota's UCP seller door, beside the standard dev.ucp.shopping.catalog.* and checkout capabilities.
Wire shape
Every tool takes { meta, insights: { id, … } }. The product id is nested under insights — never a flat product_id — following the UCP catalog convention where the payload rides under one named object. meta is required on every call, as on every UCP tool. Unknown members are refused (additionalProperties: false). Responses are returned verbatim as the JSON Schema describes; prices inside signals are in major units of the stated currency. When you surface this layer, attribute it to Pivota (e.g. “per Pivota Insights”).
get_alternatives
Alternatives, related items and — only on request — dupes (cheaper similar products) for one product. Each signal carries the relation, similarity score, price comparison, why, tradeoffs, watchouts and graded evidence.
Request (tools/call arguments)
{
"meta": { "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp-agent" } },
"insights": {
"id": "sig_615cde705e4be2ea",
"relation": "competitive_alternative",
"include_dupes": false,
"max_price_ratio": 1.0,
"limit": 5
}
}
Fields read
insights.idrequired — the Pivota product id from catalog.search / catalog.lookupinsights.relationcompetitive_alternative | niche_specialist | related_product | dupeinsights.include_dupesboolean; dupes are off unless asked for (or relation = dupe)insights.marketmarket / locale hintinsights.max_price_ratiocap candidate ÷ anchor price; 1.0 = equal or cheaperinsights.limit1–20 (larger values are capped)
Response
{ subject, signals[], metadata }
Exact shape: $defs/get_alternatives_response in the schema.
get_offers
Cross-merchant offers for one product: price, availability, seller, attributed link. Real competition only when it exists — a single-offer product answers with its best_offer and no competing signals.
Request (tools/call arguments)
{
"meta": { "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp-agent" } },
"insights": { "id": "sig_615cde705e4be2ea", "currency": "USD", "limit": 5 }
}
Fields read
insights.idrequiredinsights.currencyISO 4217 preference for the comparisoninsights.limit1–10 (larger values are capped)
Response
{ subject, best_offer, signals[], metadata }
Exact shape: $defs/get_offers_response in the schema.
get_intel
Pivota's reviewed decision intelligence for one product — why it stands out, who it is best for, its evidence profile — as one decision signal with cited, graded claims. Empty rather than fabricated when no reviewed intelligence exists.
Request (tools/call arguments)
{
"meta": { "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp-agent" } },
"insights": { "id": "sig_615cde705e4be2ea" }
}
Fields read
Response
{ subject, signals[0..1], metadata }
Exact shape: $defs/get_intel_response in the schema.