Hadacart KR/US product search and purchase links

find_purchase_candidates

Read-onlyIdempotent

Find products with original issued affiliate purchase links for the actual buyer country, currency, quantity and options. Compare dated pack unit prices; use responseMode brief. Zero candidates include noMatchGuidance.catalogCoverage counts: same discovery filters with only issued-link presence removed for counting, never whole-market stock/delivery or purchase fallback. Prefer responseMode brief for compact initial discovery; default full preserves existing clients. Add includeVerificationPlans true when source verification is the next step; original read-only plans remain unexecuted and preserve constraints, avoiding a full-detail lookup for those plans. Brief preserves candidate facts, all matched options and original issued links, omitting only repeated preparation/verification templates and related-guide lists, with unexecuted full-detail requests. Requires an original issued exact-product link record; zero-result originalIssuedRouteCheck distinguishes missing local route evidence from product existence, stock and final approval. No automatic bypass, link activation or substitute. Includes dated within-product recordedOptionIdentity and exact-plan SKU ambiguity evidence. Shared SKU never selects a unique size; keep variant ID and full option name. Unique recorded SKU is not global/current merchant identity or stock. Preserves maxOptionPrice as exact-selection item unitPriceCeiling, or an explicit unitPriceCeiling object (never both). A fresh above-ceiling exact-option price cannot pass because total budget is higher; no currency conversion or substitution. Optional purchasePreferences preserves buyer channel/payment/benefits and independently known store/order country in exact continuation plans. Recorded affiliate benefit restrictions select ordinary merchant verification while issuer URLs remain unchanged; commission exclusions do not forbid purchase. No inferred countries, payment acceptance or earned commission. Optional total budget {amount,currency} is assessed separately for each exact alternative and full merchant quantity; copied to preparation/revalidation/conditions continuation. No currency conversion, selection changes, delivered-budget guarantee or payment authority. Includes dated recordedReturnPolicy declarations or explicit unknown; no buyer return eligibility, current fee/refund quote or inferred return deadline. Compare Korean pack quantities per native reference unit or an exact Keychron option against a USD ceiling; working buyer-task request examples at https://hadacart.com/agents/tasks.json. Read-only bounded product shortlist. Optional optionQuery finds literal terms in the SAME recorded option name, with explicit seller/currency, matching IDs and dated source/price/availability scopes; product-level price/unit ranking is rejected with optionQuery. Not live inventory. Curated Korean/English shopping aliases and matchedQueryTerms preserve literal extra keywords; not general translation. Exact original affiliate URLs, snapshot evidence, same native-currency/unit ranking and explicit destination restrictions. Returned links are not clicks or orders; current option/stock/final total/AI commission recognition remain unverified. Preserve buyer benefits in the subsequent route assessment. On tool failure inspect isError and structuredContent.recovery for required fields and exact product-ID sources. KR/US recovery examples are diagnostic documentation only, never buyer defaults or automatic retries.

Input Schema

Name	Required	Description
`unit`	No
`limit`	No
`query`	Yes	Recorded product name, brand, merchant/category and identity-reviewed primary title and exact-product dated primary-source labels; literal reviewed weights, no general conversion or SKU/option matching. Use optionQuery for recorded exact options.
`budget`	No	Buyer spending ceiling in one explicit currency; preserved locally, never payment authorization or a delivered-total quote.
`category`	No
`currency`	Yes
`maxPrice`	No
`quantity`	No	Requested number of merchant listing configurations or packages, not individual contents. When omitted, quantity1 is explicitly an example. Preserved in read-only verification/preparation plans. Does not reserve stock, apply a merchant selection, change per-unit price ceilings or authorize payment.
`sellerId`	No
`productId`	No	Exact case-sensitive Hadacart catalog product ID. Applied together with every other filter; an unknown ID or mismatch returns zero candidates without falling back to title search. Not a provider variant ID.
`optionQuery`	No	Literal terms in one recorded option name. Requires sellerId; incompatible with product-price/unit filters. Revalidate exact option before budgeting or purchase.
`maxUnitPrice`	No
`purchaseMode`	No	Exact recorded advertised purchase mode. Unknown modes are excluded when supplied. Normal-purchase advertised price is not a rental/monthly quote or buyer-specific selected-option/final total.
`responseMode`	No	Use brief for candidate discovery with lower response volume. Retains all candidate facts, source dates, buyer constraints, destination/benefit/affiliate assessments and original issued URLs; omits repeated preparation/verification templates and related-guide lists. Full detail requests are returned without execution. Default full preserves existing clients. Neither mode verifies current stock, delivery, payment or revenue.
`maxOptionPrice`	No	Nonnegative ceiling on a dated exact Keychron option unit price. Requires optionQuery, sellerId keychron and USD; excludes unknown prices, shipping and tax. Zero candidate results include bounded optionBudgetEvidence for the same named option, preserving destination and buyer ceiling. Not current inventory, final total or buyer spending authorization.
`optionQueryMode`	No	Requires optionQuery. Default terms is literal-token discovery. exact matches the entire case-sensitive recorded option name, including spaces and punctuation; no trimming, normalization or variant substitution. terms allows up to100characters; exact allows up to200characters.
`productCondition`	No	Exact recorded merchant-declared product condition. Unknown or mixed/unclassified condition is excluded when supplied. Not independent inspection, grade equivalence, current availability or a selected-option guarantee.
`unitPriceCeiling`	No	Buyer ceiling per one exact selected merchant listing/configuration, in explicit native currency. Not a per-100g/reference-unit filter or total budget. Preserve quantity, option, benefits and currency; no conversion, current quote or payment permission.
`destinationRegion`	No
`referenceQuantity`	No
`destinationCountry`	Yes
`minPackageQuantity`	No
`maxSnapshotAgeHours`	No
`purchasePreferences`	No	Buyer choices for this product. Not payment credentials or authorization. Store/order country must be independently known; never inferred from destination. Preserve benefits even when commission is excluded.
`includeVerificationPlans`	No	With responseMode brief only, true includes original read-only source verification plans, preserving exact product/variant, quantity, destination, budget, per-unit ceiling and benefits. Avoid an extra full-detail query when the buyer or client wants source verification next. Plans may be unsupported or blocked; no source/affiliate/cart/payment request executes. Default false.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / includeVerificationPlans

Added value: +{
+  "description": "With responseMode brief only, true includes original read-only source verification plans, preserving exact product/variant, quantity, destination, budget, per-unit ceiling and benefits. Avoid an extra full-detail query when the buyer or client wants source verification next. Plans may be unsupported or blocked; no source/affiliate/cart/payment request executes. Default false.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / responseMode

Added value: +{
+  "description": "Use brief for candidate discovery with lower response volume. Retains all candidate facts, source dates, buyer constraints, destination/benefit/affiliate assessments and original issued URLs; omits repeated preparation/verification templates and related-guide lists. Full detail requests are returned without execution. Default full preserves existing clients. Neither mode verifies current stock, delivery, payment or revenue.",
+  "enum": [
+    "full",
+    "brief"
+  ],
+  "type": "string"
+}

First observedOct 21, 2026

TDQS

B3.2/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, yet the description adds substantial extra context: no link activation or substitute occurs, returned links are not clicks or orders, results are not live inventory, zero-result originalIssuedRouteCheck semantics, and failure handling via isError/structuredContent.recovery. It is genuinely informative beyond the annotations, though the density and repetition blunt the impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a wall of run-on, jargon-dense sentences that repeat the brief/full and read-only/no-execution points several times. The key action is front-loaded, but the remaining bulk is unstructured, so an agent must parse hard to extract usable rules.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 25-parameter, nested-object tool with no output schema, the description does cover the important behavioral envelope: what is returned, what is never executed, zero-match guidance, recovery on error, and budget/unit-price distinctions. Gaps remain around the un-documented filter parameters, which keeps it out of the top band.

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?

At 52% schema coverage across 25 parameters, the schema already documents the high-traffic fields (query, budget, quantity, productId, optionQuery, maxOptionPrice, unitPriceCeiling, purchasePreferences, includeVerificationPlans). The description adds real semantics, notably that maxOptionPrice maps to unitPriceCeiling and never both, and how budget applies per alternative. However, many parameters (maxPrice, maxUnitPrice, unit, limit, category, sellerId, destinationRegion, referenceQuantity, minPackageQuantity, maxSnapshotAgeHours) remain undocumented in either place.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence does state a concrete action (find products with original issued affiliate purchase links scoped by buyer country, currency, quantity and options), and 'Read-only bounded product shortlist' restates it plainly. But the jargon ('original issued affiliate purchase links', 'recordedOptionIdentity') obscures the intent, and nothing distinguishes this from the siblings find_buying_guides, get_product or search_products.

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?

There is embedded conditional guidance: 'Prefer responseMode brief for compact initial discovery', 'Add includeVerificationPlans true when source verification is the next step', and 'use optionQuery for recorded exact options'. These are parameter-level hints rather than tool-level routing, and the description never says when to pick this tool over the listed siblings.

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

All Hadacart KR/US product search and purchase links tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?