{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Agent Tool Call — kwery Docs","siteUrl":"https://docs.kwery.co","description":"How to expose kwery as a tool call for an AI agent — the contract, response shape, timing, and error handling."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"using-kwery-as-an-agent-tool-call","__idx":0},"children":["Using kwery as an agent tool call"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An AI agent that reasons about prices needs a tool that answers one question quickly: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what does"," ","this product cost on that marketplace right now?"]}," kwery answers it with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /job"]}," ","request every other integration uses, plus one flag, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]},", that turns the asynchronous job into"," ","a single request-response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide shows the tool definition for a merchant or shopping agent built on frameworks such as"," ","Anthropic's Claude Commerce Agents blueprint. Nothing here is agent-specific on the API side."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"contract","level":2,"__idx":1},"children":["The tool contract "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One identifier in, one scored result out, inside one HTTP request."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tool parameter"},"children":["Tool parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Maps to"},"children":["Maps to"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Marketplace to check"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google"]},", … see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sources"},"children":["Sources"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Marketplace region"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["per-source list on each source page"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifier type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gtin"]}," is simplest when the catalogue carries EAN/GTIN codes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exactly one value"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]},"; more than one returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"error\": true, \"message\": \"too many values\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hold the request open"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," = the maximum (120 s), or a number of seconds"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.kwery.co/job \\\n  -H \"Authorization: Bearer $KWERY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"source\":\"idealo\",\"country\":\"de\",\"key\":\"gtin\",\"values\":[\"4006381333962\"],\"wait\":true}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API key is sent as a Bearer token or in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},", see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"response","level":2,"__idx":2},"children":["What comes back "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the lookup finishes inside the wait window, the response is the job object ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}," ","array"]},", identical to what ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /job/{id}/download"]}," serves. Each result carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", the"," ","parsed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," for that value, and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/trust"},"children":["trust score"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trust.score"]}," with its"," ","components ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completeness"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price_integrity"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_contamination"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freshness"]},","," ","and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flagged_offers"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Feed the price and the trust score into the agent's decision step together. A low ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity"]}," or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price_integrity"]}," component is the signal to route the recommendation to a human rather than act"," ","on it, which maps onto the approval gate most agent harnesses already have for pricing changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the marketplace is slow and the wait elapses first, the response is the job object with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait_timed_out: true"]},". Nothing is lost: keep waiting on the same job with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /job/{id}?wait=60"]},", which returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}," inline as soon as the job finishes, or poll"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /job/{id}"]}," and download as described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/getting-started#poll"},"children":["Getting started"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"timing","level":2,"__idx":3},"children":["Timing expectations "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]}," answer is synchronous, not instant. A live lookup is one to three requests to the"," ","marketplace through a proxy, roughly 5–15 seconds on idealo and Amazon and longer on Google."," ","Results served from kwery's cache return immediately. Design the tool's timeout for the 120 s"," ","maximum, and treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait_timed_out"]}," as \"continue waiting\", not as an error."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"errors","level":2,"__idx":4},"children":["Errors the agent must handle "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validation problems come back as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 200"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"error\": true"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},", for"," ","example an unsupported ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," pair or a malformed identifier. Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," before"," ","reading anything else. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," means the key is wrong, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["402"]}," means the organisation is out of"," ","credits. Details in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors-and-limits"},"children":["Errors & limits"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"mock","level":2,"__idx":5},"children":["Prototyping against the mock server "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/getting-started#mock-server"},"children":["mock server"]}," does not run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]},": by default it returns"," ","the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asynchronous"]}," job object. Ask it for the settled shape instead by naming the example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s -X POST https://docs.kwery.co/_mock/api-reference/job \\\n  -H \"Authorization: Bearer test123\" \\\n  -H \"x-redocly-response-body-example: wait\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"source\":\"idealo\",\"country\":\"de\",\"key\":\"gtin\",\"values\":[\"4006381333962\"],\"wait\":true}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This returns the job plus an inline ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["results"]}," array with a scored result, the same shape the"," ","live API returns when the lookup settles. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait_timed_out"]}," as the example name to see the"," ","other branch. The download mock (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /_mock/api-reference/job/{id}/download"]},") returns the same"," ","result items. Swap the base URL and the key when going live."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"batches","level":2,"__idx":6},"children":["Catalogue-wide sweeps "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]}," is for one identifier in the middle of a conversation. When the agent needs a whole"," ","catalogue priced, submit without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Batch API"]},": up to 1 000 values per job, poll, then download. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/getting-started"},"children":["Getting started"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stream API"]},": up to 100 000 values per job, results pushed to your endpoint as signed"," ","webhooks while they complete. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["Webhooks"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credits are the same either way, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/pricing"},"children":["Pricing"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://kwery.co/use-cases/ai-shopping-data-api"},"children":["See the AI Shopping Agent use case →"]}," ","Integrating with Claude specifically? ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://kwery.co/resources/claude-merchant-agent-pricing-data"},"children":["See the integration guide →"]}]}]},"headings":[{"value":"Using kwery as an agent tool call","id":"using-kwery-as-an-agent-tool-call","depth":1},{"value":"The tool contract","id":"contract","depth":2},{"value":"What comes back","id":"response","depth":2},{"value":"Timing expectations","id":"timing","depth":2},{"value":"Errors the agent must handle","id":"errors","depth":2},{"value":"Prototyping against the mock server","id":"mock","depth":2},{"value":"Catalogue-wide sweeps","id":"batches","depth":2}],"frontmatter":{"seo":{"title":"Agent Tool Call — kwery Docs","description":"How to expose kwery as a tool call for an AI agent — the contract, response shape, timing, and error handling."}},"lastModified":"2026-09-14T12:09:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/agent-tool-call","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}