MCP tools
How the tools work
Each tool runs the same service as the matching REST route, with the same validation, the same error codes and the same audit log. A tool acts on the project of the secret key the client connected with, and only on the indices in the key's index scope when it has one.
- Read tools work with any secret key. Write tools need a key with full access; a read-only key gets
403 FORBIDDENback as a tool error. - Writes to documents, reindex and suggestion rebuilds are asynchronous. The tool answers a
taskIdat once, andget_tasktells when the work is done:SUCCEEDED,PARTIAL,FAILEDorCANCELLED. - Search tools answer at most 10 hits, so a result fits the agent's context. Paging still works.
- A failed call is a tool result, not a crash. It carries the REST status and code, for example
400 PROFILE_INVALIDwith one issue per field, so the agent can fix its input and try again.
All tools
| Tool | What it does |
|---|---|
list_indices | List the indices of the project with status and document count |
get_index | One index: status, document count and versions |
create_index | Create an index; by default its mapping is inferred from the first upload |
get_mapping | The language and every field of an index with its flags |
update_mapping | Replace the mapping; the answer says whether a reindex is needed |
get_facets | The facets of an index, which profiles without their own show |
update_facets | Replace the index facets, labels and order included |
reindex | Rebuild the index into a new version and swap it in without downtime |
index_documents | Add or replace up to 1000 documents (asynchronous, returns a task id) |
delete_documents | Delete up to 1000 documents by id (asynchronous) |
get_task | Poll an asynchronous write: status, counts and per-document errors |
get_document | Read one stored document by id |
search | Search with a saved profile or an inline one, with filters, sort and facets |
list_profiles | The search profiles of an index and their profile keys |
upsert_profile | Create or replace a search profile |
preview_profile | Compare an unsaved profile with the saved one for the same query |
list_synonyms | The synonym rules of an index, page by page |
upsert_synonyms | Create or replace a synonym rule (equivalent or one way) |
delete_synonyms | Delete one synonym rule |
list_rules | The ranking rules of an index in the order they run, with what needs attention |
upsert_rule | Create or replace a ranking rule: pin, hide, boost or filter products for chosen searches |
delete_rule | Delete one ranking rule |
reorder_rules | Set the order ranking rules run in |
test_rule | Run a search with the rules that fire, and compare a draft rule before saving it |
suggest | Autocomplete a partial query, with facet hints |
rebuild_suggestions | Rebuild the autocomplete index from recent searches (asynchronous) |
get_search_analytics | Searches, zero-result rate, latency, top and zero-result queries |
Indices and mapping
list_indices, get_index, create_index, get_mapping, update_mapping, get_facets, update_facets, reindex.
An agent can create an index, read and change its fields and flags, set the facets every profile shows by default, and rebuild the index after a breaking mapping change. update_mapping answers a diff: an additive change applies at once, a breaking one leaves the index NEEDS_REINDEX until the agent calls reindex. A change that would break a profile, rule, facet, autocomplete field or data source is refused with 409 MAPPING_BREAKS_CONFIG, and the tool error lists each use, so the agent changes those first.
Create an index called products in German. Then show me its mapping after the first upload
and make brand and color facetable.
Make the title field use normalizeCodes, check whether that needs a reindex, and if it does,
start it and tell me when it is done.
Documents and tasks
index_documents, delete_documents, flush_documents, get_task, get_document.
An agent can add or replace up to 1000 documents per call, delete up to 1000 by id, read one stored document and follow a task to the end. Per-document errors appear on the task. flush_documents deletes every document of an index and cannot be undone: every version goes, the live one included, while the configuration and keys stay. See Delete all documents.
Upload the products in ./catalog.json in batches of 1000, wait for every task,
and list the documents that failed with the reason.
Search and profiles
search, list_profiles, upsert_profile, preview_profile.
An agent can search with a saved profile or with an unsaved one, compare an edited profile with the saved one for the same query, and save it once the results look right. upsert_profile replaces the whole profile, so the agent should read it with list_profiles first.
search takes the same body as the search API: filters with $or, $and and $not groups, fields to trim each hit to the fields the agent needs, and excludeIds. Asking for fewer fields keeps the answer short.
Search "oled tv" with the storefront profile. Then try the same profile with phrase boost 4
and typo tolerance 1, compare the top 10, and only save it if more TVs rank first.
Synonyms
list_synonyms, upsert_synonyms, delete_synonyms.
An agent can list synonym rules, add or change an equivalent rule (tv, television) or a one-way rule (telly => tv), and delete one. A change applies to the next search without a reindex.
Our shoppers write "sneakers" but the catalog says "trainers". Add a one-way synonym
and check that "sneakers" now finds products.
Ranking rules
list_rules, upsert_rule, delete_rule, reorder_rules, test_rule.
An agent can pin, hide, boost or filter products for chosen searches, schedule a rule for a campaign, set the order rules run in, and test a draft rule against the saved ones before saving it. list_rules also lists each rule's issues, for example a filter on a field that a later mapping change made unfilterable.
For the query "black friday", pin products tv-1, tv-7 and tv-3 in that order from
2026-11-27 to 2026-11-30. Test it first and show me the top 5 before and after.
Autocomplete and analytics
suggest, rebuild_suggestions, get_search_analytics.
An agent can try what the search box suggests for a partial query, rebuild the suggestions after a catalog change, and read the search analytics of a window of up to 90 days: searches, zero-result rate, latency, the top 50 queries and the top 50 that found nothing. Start relevance work from the zero-result list, or use the tune_relevance prompt, which runs the whole loop.
Which queries found nothing last week? For the top ten, propose synonyms or profile changes,
preview them and wait for my go before applying anything.
What the tools do not cover
Some work stays in the cabinet or the REST API: API keys, members and billing, deleting an index, full catalog sync with replace sessions, custom suggestions and the suggest config, and the synonym file import and export.
search tool runs with a saved profile are logged like storefront searches, so they show up in analytics and can feed autocomplete. preview_profile and test_rule are not logged.