DocsSupported query contract
Docs
Supported query contract
How to write Compass Search requests so agents get predictable, evidence-backed restaurant results.
Supported search shapes
| Field | Type | Notes |
|---|---|---|
| Discovery | query | Cuisine, dish, dietary, neighborhood, city, and general discovery phrases such as vegan ramen in Brooklyn or vegan pizza in Portland. |
| Named restaurants | query | Known restaurant or chain names can be searched when the restaurant is present in the current Compass corpus. Missing corpus coverage returns ordinary ranked results, not an invented match. |
| Location | location | Use structured location.lat, location.lng, and optional location.radius_m for near me, nearby, around me, or radius-sensitive workflows. |
| Profile fit | user_profile | Use user_profile.diet, exclude_cross_contamination, and dietary_rules to request conservative per-result fit guidance. |
| Evidence depth | X-Compass-Mode | Use fast for compact result lists and rich for fuller evidence, score dimensions, query interpretation, and metadata. |
Boundaries
| Field | Type | Notes |
|---|---|---|
| No location guessing | contract | Queries like near me require structured coordinates. Compass does not infer a user location from text alone. |
| No universal natural-language promise | contract | Compass supports common restaurant-agent phrasing, but free-form instructions should be converted into the documented request fields when possible. |
| No certification facts | contract | Public restaurant responses do not expose halal-certified, kosher-certified, allergen-safe, or free-from facts at launch. |
| Unknown is valid | decision | When evidence is insufficient, stale, conflicting, or safety-sensitive, Compass returns conservative unknown guidance instead of pretending certainty. |
| Current corpus limits | coverage | If a named restaurant is absent from the current corpus, Search cannot invent it. Treat this as a coverage gap, not a formatting error. |
Recommended agent pattern
| Field | Type | Notes |
|---|---|---|
| 1 | parse | Extract cuisine, dish, named restaurant, city, coordinates, radius, and user profile from the user request. |
| 2 | structure | Send coordinates and radius in location, not only inside the query string, whenever the result set must be geographically bounded. |
| 3 | call | Use Search for discovery, Enrich for a known restaurant record, and Decision for profile-specific fit on a known compass_id. |
| 4 | explain | Show confidence, reason codes, source freshness, and verification guidance when the answer is safety-sensitive or evidence is incomplete. |