The MCP tools
The Bonafide MCP server exposes three read-only tools.
bonafide_query Stable
Entity-aware natural-language query. The server resolves the hotel, brand, or destination you name, fetches matching documents across collections in parallel, scores them by relevance, and returns ranked results.
Arguments
| Argument | Type | Description |
|---|---|---|
task required | string | The natural-language question — e.g. "check-in time", "pet policy", "dining options". Put the specific entity in entity_name and any place in location when known, rather than relying on this field alone. |
entity_name optional | string | A specific hotel, brand, property, or destination to scope the query to. Pass a bonafideId if known (most precise); otherwise the entity or brand name, matched against name and alternateNames. Use this whenever the user names a specific entity — more reliable than putting the name in task. |
location optional | string | A place to scope the query to — a city, state, or country (e.g. "New York", "Florida"). Returns only entities in that place. Combine with entity_name to pinpoint a specific entity in a place, or to disambiguate a name used in multiple cities (e.g. entity_name: "Hampton Inn", location: "Maui"). |
max_documents optional | integer | Maximum results to return. Default 10. Use 5–10 for focused answers, 20+ for broad research. |
min_relevance_score optional | number | Floor on the relevance score, 0.0–1.0. Use 0.5 for broad recall, 0.7+ for high-confidence matches only. Omit to return all scored results. |
response_format optional | enum | "text" (human-readable, with citations) or "json" (machine-readable). Default "json". Use "text" when the result is shown directly to a user. |
entity_name and location are the preferred way to scope a query — more reliable than embedding names in task, especially for large brands with many properties.
bonafide_search_documents Stable
Structured browse/filter over the knowledge base. Use this for discovery (“show me all spa-related Q&A”) rather than asking a question.
Arguments
| Argument | Type | Description |
|---|---|---|
query optional | string | Free-text filter, e.g. "spa treatments", "pet policy". |
type optional | enum | One of source_document, qa_pair, prompt_template, derived_data, official_link. |
category optional | string | Industry category: Hospitality (hotels/resorts), CarRental, or DMO (tourism boards). For hotels and resorts, use Hospitality. |
limit optional | integer | Page size, 1–100. Default 10. |
offset optional | integer | Number of documents to skip for pagination. Default 0. |
bonafide_list_entities Stable
Paginated, scope-enforced roster of the properties and/or destinations under a brand. This returns entity metadata only — ids, names, types — not content; use bonafide_query for FAQ/content answers about an entity. Reach for this when you need the complete roster for a brand rather than bonafide_query’s relevance-capped top matches.
Arguments
| Argument | Type | Description |
|---|---|---|
brand required | string | The brand to list entities for. Pass a bonafideId (e.g. HO-PB246TNIXG6F5) for the most precise lookup; an exact name or alternateName matches case-insensitively. When exact resolution finds nothing, token-coverage matching is used — every distinctive word you supply must appear in the matched brand name (e.g. "Host Hotels" requires both “Host” and “Hotels” to appear in the candidate). On a genuine ambiguous tie, the response’s note field carries a disambiguation message. |
entity_type optional | enum | "property" (hotels/resorts only), "destination" (DMO destinations only), or "all" (both, combined). Default "all". |
limit optional | integer | Page size, 1–100. Default 50. |
offset optional | integer | Number of entities to skip for pagination. Default 0. Use with total_count in the response to page through large rosters. |
The response shape is { brand: { bonafide_id, name }, entities: [{ bonafide_id, name, entity_type, brand_id, sub_brand_id }], total_count, limit, offset, note? }, where total_count is the post-filter, pre-pagination count.
Result completeness — the note field
All three tools carry an optional note field that signals when a result is incomplete or empty, and it is load-bearing: a scoped miss is not evidence of global absence.
- A partial
bonafide_queryresult carries a note like"matched N entities; showing top Z"— the result set is capped, so don’t infer that an entity is absent just because it isn’t in the returned slice. - A zero-docs
bonafide_queryresult carries a note like"no entity named X within your scope"— this is a miss within your scope, not proof the entity doesn’t exist in the knowledge base globally. - When
entity_nameresolves to a brand rather than a specific property,bonafide_queryreturns a note like"'X' is a brand — returning brand-level facts; name a specific property for property-specific answers"— the result is brand-level, not a miss. - A zero-result
bonafide_search_documentscall includes a note confirming no documents matched your filters within scope — same caveat. - If the brand can’t be resolved in your scope,
bonafide_list_entitiesreturnstotal_count: 0,entities: [], and a note (e.g."No accessible brand found matching 'X'") — the brand isn’t accessible in your scope, which is distinct from the brand not existing at all. An in-scope brand whose roster is simply empty after filtering (e.g. anentity_typefilter with no matches, oroffsetpasttotal_count) also returnstotal_count: 0,entities: [], but with nonote— that’s a legitimate empty page, not a scope denial.
Always read the note field before concluding an entity or document doesn’t exist — treat an empty or partial result as scoped, not global.