<tool_description>
Search and discover products, recipes AND services in the Nexbid marketplace. Nexbid Agent Discovery — search and discover advertiser products through an open marketplace. Returns ranked results matching the query — products with prices/availability/links, recipes with ingredients/targeting signals/nutrition, and services with provider/location/pricing details.
</tool_description>
<when_to_use>
Primary discovery tool. Use for any product, recipe or service query.
Use content_type filter: "product" (only products), "recipe" (only recipes), "service" (only services), "all" (all, default).
For known product IDs use nexbid_product instead.
For category overview use nexbid_categories first.
</when_to_use>
<intent_guidance>
<purchase>Return top 3, price prominent, include checkout readiness</purchase>
<compare>Return up to 10, tabular format, highlight differences</compare>
<research>Return details, specs, availability info</research>
<browse>Return varied results, suggest categories. For recipes: show cuisine, difficulty, time.</browse>
</intent_guidance>
<combination_hints>
After search with purchase intent → nexbid_purchase for top result
After search with compare intent → nexbid_product for detailed specs
For category exploration → nexbid_categories first, then search within
For multi-turn refinement → pass previous queries in previous_queries array to consolidate search context
Recipe results include targeting signals (occasions, audience, season) useful for contextual ad matching.
</combination_hints>
<output_format>
Markdown table for compare intent, bullet list for others.
Products: product name, price with currency, availability status.
Recipes: recipe name, cuisine, difficulty, time, key ingredients, dietary tags.
Services: service name, provider, location, price model, duration.
</output_format>
Parameters (13)
querystringrequired
Natural language product or recipe query
content_typestring
Filter by content type: product, recipe, or all (default)
intentstring
User intent for the search
budget_max_centsinteger
Maximum budget in cents (e.g. 20000 for CHF 200)
budget_min_centsinteger
Minimum budget in cents
currencystring
Currency for budget filtering
geostring
ISO 3166-1 alpha-2 country code (default: CH)
categorystring
Filter by product category
brandstring
Filter by brand name
max_resultsinteger
Maximum number of results (1-50, default: 10)
previous_queriesarray
Previous queries in this search session for multi-turn refinement (oldest first, max 10). Example: ["running shoes", "waterproof only"]
agent_idstring
Agent identifier — used for analytics-attribution (e.g. "claude-3.5", "gpt-4o", "perplexity"). Optional but strongly recommended so publishers/advertisers can see which AI agents drive their traffic.
session_idstring
Session token to correlate multiple tool-calls from the same conversation. Optional. Useful for multi-turn analytics.
nexbid_product
<tool_description>
Get detailed product information by ID from the Nexbid marketplace. Returns full product details including price, availability, description, and purchase link.
</tool_description>
<when_to_use>
When you have a specific product UUID from a previous nexbid_search result.
Do NOT use for browsing — use nexbid_search instead.
</when_to_use>
<combination_hints>
Typically called after nexbid_search to get full details on a specific product.
If user wants to buy → follow with nexbid_purchase.
</combination_hints>
<output_format>
Full product details: name, description, price, currency, availability, brand, category, purchase link.
</output_format>
Parameters (3)
product_idstringrequired
Product UUID
agent_idstring
Agent identifier for analytics-attribution.
session_idstring
Session token for multi-turn correlation.
nexbid_categories
<tool_description>
List all available product categories in the Nexbid marketplace with product counts. Optionally filter by country.
</tool_description>
<when_to_use>
When user wants to explore what is available before searching.
Use BEFORE nexbid_search to help narrow down the query.
</when_to_use>
<combination_hints>
nexbid_categories → nexbid_search with category filter for targeted results.
Good starting point for browse intent.
</combination_hints>
<output_format>
List of categories with product counts. Optionally filtered by country.
</output_format>
Parameters (1)
geostring
ISO 3166-1 alpha-2 country code to filter categories
nexbid_purchase
<tool_description>
Initiate a purchase for a product found via nexbid_search. Returns a checkout link that the user can click to complete the purchase at the retailer. The agent should present this link to the user for confirmation.
</tool_description>
<when_to_use>
ONLY after user has expressed clear purchase intent for a specific product.
Requires a product UUID from nexbid_search or nexbid_product.
ALWAYS confirm with user before calling this tool.
</when_to_use>
<combination_hints>
nexbid_search (purchase intent) → nexbid_purchase → present checkout link to user.
After purchase → nexbid_order_status to check if completed.
Use checkout_mode=wallet_pay when the user has a connected wallet with active mandate.
</combination_hints>
<output_format>
For prefill_link (default): Checkout URL that the user clicks to complete purchase at the retailer.
For wallet_pay: Intent ID and status for mandate-based authorization.
Include product name and price for user confirmation.
</output_format>
Parameters (8)
product_idstring
Product UUID to purchase. Mutually exclusive with line_items.
quantityinteger
Quantity for single-item purchase (default: 1, ignored in cart-mode)
line_itemsarray
Array of line items for cart purchase. Mutually exclusive with product_id.
cart_idstring
Optional cart UUID. Server generates one if omitted.
cart_total_max_centsinteger
Cart-level hard-bound on total amount (only with line_items)
cart_ttl_secondsinteger
Cart mandate lifetime in seconds (default 900, max 3600)
checkout_modestring
Checkout mode. Default: prefill_link. wallet_pay requires a connected wallet with active mandate.
publisher_content_idstring
Optional UUID of the publisher content (recipe, editorial, review, etc.) that surfaced this product to the user. When set, a successful purchase emits a premium-tier enriched_snippet_impression and the publisher gets credited 90% of the conversion value. Pass-through from nexbid_search, where it is returned alongside each product as `match_publisher_content_id` (when applicable).
nexbid_order_status
<tool_description>
Check the status of a purchase intent created via nexbid_purchase.
</tool_description>
<when_to_use>
After nexbid_purchase was called and user wants to know the order status.
Requires the intent_id UUID returned by nexbid_purchase.
</when_to_use>
<combination_hints>
Always follows nexbid_purchase. No other tool needed after this.
</combination_hints>
<output_format>
Current status (pending/completed/expired), checkout link if still active.
</output_format>
Parameters (1)
intent_idstringrequired
Purchase intent UUID from nexbid_purchase
list_products
<tool_description>
Search for products in the Nexbid marketplace. Alias for nexbid_search with content_type='product'.
</tool_description>
<when_to_use>
When an agent needs to discover products (not recipes or services).
Convenience alias — delegates to nexbid_search internally.
</when_to_use>
<combination_hints>
list_products → get_product for details → create_media_buy for advertising.
For recipes/services use nexbid_search with content_type filter.
</combination_hints>
<output_format>
Product list with name, price, availability, score, and link.
</output_format>
Parameters (6)
querystringrequired
Natural language product query
categorystring
Filter by product category
brandstring
Filter by brand name
budget_max_centsinteger
Maximum budget in cents
geostring
ISO 3166-1 alpha-2 country code
max_resultsinteger
Maximum results (1-50, default: 10)
get_product
<tool_description>
Get detailed product information by ID. Alias for nexbid_product.
</tool_description>
<when_to_use>
When you have a product UUID from list_products or nexbid_search.
</when_to_use>
<combination_hints>
list_products → get_product → create_media_buy or nexbid_purchase.
</combination_hints>
<output_format>
Full product details: name, description, price, currency, availability, brand, category, link.
</output_format>
Parameters (1)
product_idstringrequired
Product UUID
list_inventory
<tool_description>
List available publisher inventory slots for programmatic media buying. Returns ad slots with pricing, rules, and capacity info.
</tool_description>
<when_to_use>
Before create_media_buy — discover which slots are available.
Use to browse publisher ad inventory for campaign planning.
</when_to_use>
<combination_hints>
list_inventory → get_inventory_item for slot details → create_media_buy to bid.
Filter by publisher_id, slot_type, or pricing_model for targeted results.
</combination_hints>
<output_format>
Inventory slots with: name, type, floor price, pricing models, capacity, status.
</output_format>
Parameters (5)
publisher_idstring
Filter by publisher UUID
slot_typestring
Filter by slot type
pricing_modelstring
Filter by pricing model
geostring
ISO 3166-1 alpha-2 country code
max_resultsinteger
Maximum results (default: 20)
get_inventory_item
<tool_description>
Get detailed information about a specific publisher inventory slot, including rules and active buy count.
</tool_description>
<when_to_use>
After list_inventory to get full slot details before bidding.
Check capacity (active buys vs max_concurrent) before create_media_buy.
</when_to_use>
<combination_hints>
list_inventory → get_inventory_item → create_media_buy.
Shows brand/category allowlists, blocklists, and current utilization.
</combination_hints>
<output_format>
Full slot details with rules, pricing, capacity, and active buy count.
</output_format>
Parameters (1)
inventory_idstringrequired
Inventory slot UUID
create_media_buy
<tool_description>
Create a media buy (bid on publisher inventory). Validates rules, runs auction scoring, and returns approval/rejection status. AdCP-compatible first-price sealed-bid auction.
</tool_description>
<when_to_use>
When an advertiser wants to place a bid on a publisher inventory slot.
Requires inventory_id from list_inventory/get_inventory_item.
ALWAYS confirm with user before calling — creates a binding commitment.
</when_to_use>
<combination_hints>
list_inventory → get_inventory_item → create_media_buy → submit_creatives → activate.
If rejected: check rejection_reason and adjust bid/brand/category.
Score formula: 0.3*bid + 0.3*quality + 0.2*quality + 0.2*context.
</combination_hints>
<output_format>
Media buy ID, status (approved/rejected), auction score, rejection reason if applicable.
</output_format>
Parameters (18)
inventory_idstringrequired
Target inventory slot UUID
advertiser_idstringrequired
Advertiser account UUID
bid_centsintegerrequired
Bid amount in cents
pricing_modelstringrequired
Pricing model for the buy
creative_refstring
Creative asset URL or reference
creative_dataobject
Creative metadata (JSON)
budget_centsintegerrequired
Total budget in cents
start_datestring
Campaign start date (ISO 8601)
end_datestring
Campaign end date (ISO 8601)
brandstring
Advertiser brand name (for rules check)
categorystring
Product category (for rules check)
quality_scorenumber
Quality score 0-1 (default: 0.5)
context_relevancenumber
Context relevance 0-1 (default: 0)
campaign_idstring
Parent campaign UUID. When set, the campaign's default pacing + frequency cap cascade into this buy unless explicitly overridden.
pacing_strategystring
Override pacing strategy. Falls back to campaign default, then "even".
frequency_cap_sessionany
Per-session impression cap for this buy. NULL means defer to inventory cap. Falls back to campaign default, then 3.
agent_mandateany
Optional signed agent mandate (ADR-066). Verified by the auction-entry gate.
<tool_description>
Submit or update creative assets for an existing media buy. Required before activation.
</tool_description>
<when_to_use>
After create_media_buy returns approved status. Upload creative before activating.
</when_to_use>
<combination_hints>
create_media_buy (approved) → submit_creatives → activate.
Creative types: banner, native, snippet, video, text.
</combination_hints>
<output_format>
Updated media buy with creative info attached.
</output_format>
Parameters (4)
media_buy_idstringrequired
Media buy UUID
creative_typestringrequired
Creative type (e.g. "banner", "native", "snippet")
creative_refstring
Creative asset URL
creative_dataobject
Creative metadata (JSON)
activate
<tool_description>
Activate an approved media buy to start serving. Requires creative to be submitted first.
</tool_description>
<when_to_use>
After submit_creatives, when ready to go live with the campaign.
</when_to_use>
<combination_hints>
submit_creatives → activate → track_enriched_snippet (for enriched snippet buys).
Can be paused later with pause, or cancelled with cancel.
</combination_hints>
<output_format>
Activated media buy with won_at timestamp.
</output_format>
Parameters (1)
media_buy_idstringrequired
Media buy UUID to activate
pause
<tool_description>
Pause an active media buy campaign. Can be reactivated later.
</tool_description>
<when_to_use>
When an advertiser wants to temporarily stop a running campaign.
Only works on active campaigns.
</when_to_use>
<combination_hints>
activate → pause (temporary) or cancel (permanent).
Paused campaigns can be reactivated with activate.
</combination_hints>
<output_format>
Updated media buy with paused status.
</output_format>
Parameters (2)
media_buy_idstringrequired
Media buy UUID to pause
reasonstring
Reason for pausing
cancel
<tool_description>
Cancel a media buy campaign. This is a terminal state — cannot be reactivated.
</tool_description>
<when_to_use>
When an advertiser wants to permanently stop a campaign.
Cannot be undone. Use pause for temporary stops.
</when_to_use>
<combination_hints>
cancel is terminal. For temporary suspension use pause instead.
Remaining budget is released.
</combination_hints>
<output_format>
Updated media buy with cancelled status.
</output_format>
Parameters (2)
media_buy_idstringrequired
Media buy UUID to cancel
reasonstring
Reason for cancellation
list_media_buys
<tool_description>
List media buys with optional filters. View campaign history for advertisers or publishers.
</tool_description>
<when_to_use>
To view existing media buys (campaigns). Filter by advertiser, publisher, status, or date.
</when_to_use>
<combination_hints>
list_media_buys → get_campaign_report for performance data.
list_media_buys → get_compliance_status for compliance check.
</combination_hints>
<output_format>
List of media buys with ID, status, bid, budget, spent, and dates.
</output_format>
Parameters (6)
advertiser_idstring
Filter by advertiser UUID
publisher_idstring
Filter by publisher UUID
statusstring
Filter by status
date_fromstring
Filter from date (ISO 8601)
date_tostring
Filter to date (ISO 8601)
max_resultsinteger
Maximum results (default: 20)
get_campaign_report
<tool_description>
Get aggregated performance report for a media buy. Shows spend, impressions, clicks, conversions with time-series breakdown.
</tool_description>
<when_to_use>
To check campaign performance metrics after activation.
Supports period filtering and granularity control.
</when_to_use>
<combination_hints>
list_media_buys → get_campaign_report for performance analysis.
Pair with get_compliance_status for full campaign overview.
</combination_hints>
<output_format>
Totals (spend, impressions, clicks, conversions) + time-series breakdown.
</output_format>
Parameters (3)
media_buy_idstringrequired
Media buy UUID
periodstring
Reporting period (default: all)
granularitystring
Report granularity (default: day)
get_compliance_status
<tool_description>
Check nDSG/GDPR/EU AI Act compliance status for a media buy. Verifies privacy-native architecture compliance.
</tool_description>
<when_to_use>
Before activating a campaign or for compliance audits.
Checks: no cookies, no fingerprinting, contextual targeting, data residency, revenue transparency, consent basis, agent transparency.
</when_to_use>
<combination_hints>
create_media_buy → get_compliance_status → activate (if compliant).
Use for regulatory reporting and audit trails.
</combination_hints>
<output_format>
Overall compliance status + individual check results with details.
</output_format>
Parameters (1)
media_buy_idstringrequired
Media buy UUID to check
settle
<tool_description>
Settle pending payments for media buys. Supports manual CSV export, Stripe invoice (Phase 2 stub), and x402 micropayments (Phase 2 stub).
</tool_description>
<when_to_use>
When a publisher wants to collect earned revenue or an advertiser needs to settle outstanding charges.
Use method='manual' for CSV export. Stripe and x402 are stubs (Phase 2).
</when_to_use>
<combination_hints>
get_campaign_report → settle (after verifying amounts).
Filter by media_buy_id, publisher_id, or period.
</combination_hints>
<output_format>
Settlement totals (gross, platform fee, net), entry count, and method-specific data (CSV for manual).
</output_format>
Parameters (5)
media_buy_idstring
Settle specific media buy
publisher_idstring
Settle all for a publisher
period_startstring
Period start (ISO 8601)
period_endstring
Period end (ISO 8601)
methodstringrequired
Settlement method
track_enriched_snippet
<tool_description>
Track delivery of an enriched snippet and bill the advertiser. Creates a ledger entry and decrements the media buy budget.
</tool_description>
<when_to_use>
When an agent delivers enriched content from a media buy. Each delivery is billed by snippet tier:
- basic: 10¢, standard: 50¢, rich: 150¢, premium: 300¢ (CHF centimes).
</when_to_use>
<combination_hints>
activate (enriched_snippet buy) → track_enriched_snippet per delivery.
get_campaign_report shows cumulative tracking.
</combination_hints>
<output_format>
Event ID, charged amount, platform fee, net payout, remaining budget.
</output_format>
Parameters (6)
media_buy_idstringrequired
Media buy UUID
snippet_typestringrequired
Enriched snippet tier
agent_idstring
Agent identifier
data_fieldsarrayrequired
Data fields delivered in the snippet
brand_content_idstring
Brand content UUID that was delivered. When provided, the snippet is also recorded in enriched_snippet_impressions for analytics.
signals_usedobject
Publisher signals that triggered this snippet (e.g. nx_category:food). Stored as JSONB on the impression row.
The open infrastructure for agent-native commerce.
Protocol Commerce is an open initiative to create standardized, auditable, and interoperable protocols for AI agent-driven commerce. This repository contains the specification, SDKs, and technical manifesto.
AI agents are becoming the primary interface for product discovery and purchase. The protocols powering this shift — OpenAI's ACP, Google's UCP — are proprietary and platform-controlled. Publishers have no representation. There is no open standard.
Any MCP-compatible LLM (Claude, GPT-4, Gemini) can directly search, browse, and purchase products through the Nexbid marketplace.
Why Formal Verification?
Nexbid is the only commerce platform whose core security properties are mathematically proven in Lean 4 — not just tested, but proven correct for all possible inputs.
