---
name: suredone-product-search
description: Compose and check SureDone product search queries using the authenticated account's live field catalogue and non-executing validator. Use for inventory searches or product scopes, not order or page queries.
---

# SureDone product search

Use the [product grammar reference](https://docs.suredone.com/product-search.md) and current [API reference](https://docs.suredone.com/v3.json). Do not infer syntax from SQL, Lucene, or another platform.

## Procedure

1. Use the customer's configured SureDone connection. If none is available, explain that the live catalogue and validator require authentication; do not request credentials in a prompt or claim validation occurred.
2. Fetch `GET /v3/search/fields` for that account. Resolve each intended field from this response, including channel instance and custom fields. If the requested concept has no matching field, ask for the intended mapping instead of guessing. Do not carry a previous tenant's catalogue into this request.
3. Compose the query from the user's intended conditions, using ASCII spaces between conditions. Spaces mean AND; a parenthesis group with space-separated alternatives means OR. The words AND and OR are text, groups cannot nest, and a single-condition group is not an OR group. Double quotes preserve phrases but do not imply equality. Inspect pasted text for non-ASCII separators or a byte-order mark; never silently normalize an existing query. Explain when the requested boolean structure cannot be expressed.
4. Check operands against the reference. Backslashes do not escape quote or asterisk phrase delimiters, and paired asterisks cannot protect an embedded double quote. Do not invent an escape when the intended literal cannot be expressed. A column comparison uses a bare catalogue field name, not `$field`; quoting a field name does not make it a literal. Empty operands, product types, and percent/asterisk characters also have nonstandard behavior. Preserve the user's intended meaning instead of approximating it.
5. Call `POST /v3/search/validate` with JSON containing only `query`. The 4096-byte limit is measured in UTF-8. Interpret both errors and warnings; `valid` only summarizes the errors. Review suggested corrections against the user's intent rather than applying them blindly. Fix and revalidate up to three times. Errors, unresolved warnings, unavailable validation, or unrepresentable intent stop execution. An intentional warning may be acknowledged only when the original request and parser-defined semantics establish that it is appropriate; report that warning with the query. A match count cannot resolve a finding. Refresh the catalogue and revalidate if its fields change.
6. If the user asked to read matches, use the reviewed query in `GET /v3/search/items/{query}`, encoding the whole query as one path segment. Keep pagination bounded and report the returned page and count honestly. A clean query matching zero products is a valid result, not a reason to remove conditions automatically. If the user only asked for a query, return the query and its validation result without searching.

Validation does not execute a search and does not authorize product changes, export jobs, automation runs, or plan execution. Preserve an existing saved query until the user asks to replace it. Never log API tokens, raw customer records, or credentials in task evidence.
