The Concierge agent doesn't talk to a black box — it routes to one of these 44 named tools, each backed by a grounded data layer and a license-tagged source. Every tool is also a direct REST endpoint at /v1/agent/tool/<name>: call them individually for atomic lookups without going through the agent loop. Full input schemas at api.travelminds.ai/v1/agent/tools.
City-anchored lookups. Resolve names in any script, pull rich context, surface restaurants / hotels / state-tourism content tied to a place.
find_city
Resolve a city name (in any language script) to TravelMindsAI's canonical city UUID. Use this FIRST when the user mentions a city by name. Returns the canonical megacity ID if the user named a neighborhood (e.g. 'Brooklyn' resolves to NY…
POST /v1/agent/tool/find_city
get_city_context
Get rich grounded context for a city: master_score, top POIs, top hotels, top restaurants (Michelin tier first, then quality), nearest airport with IATA, transit stop count, India enrichments where applicable (ASI heritage, tourism circu…
POST /v1/agent/tool/get_city_context
place_lookup
Resolve a place name (neighborhood, suburb, district, town, populated place) to a canonical gazetteer record. Returns the canonical id, name, country, coordinates, population, feature class/code, and the linked parent_city_id if the plac…
POST /v1/agent/tool/place_lookup
entity_lookup
Look up a canonical entity by QID (e.g. 'Q90') or by name (e.g. 'Paris'). Returns canonical label, description, instance_of types, multilingual aliases (where loaded), and any platform entities that have been QID-matched to it. Use when…
POST /v1/agent/tool/entity_lookup
find_restaurants_in_city
Get restaurants in a city, sorted Michelin tier first then by quality. Use sparingly: get_city_context already returns top restaurants. Only call this if the user has dietary or cuisine constraints needing a longer list.
POST /v1/agent/tool/find_restaurants_in_city
find_hotels_in_city
Get hotels in a city, sorted by quality_class (premium then mid then budget). Same caveat as restaurants: get_city_context already returns the top set; only use when the user wants more options or a specific category.
POST /v1/agent/tool/find_hotels_in_city
find_state_tourism_content
Hybrid full-text search over authoritative state-tourism gov sources. Two corpora are searched in parallel and score-merged: (A) ~19K HTML pages from 37 official Indian state-tourism portals (plus the national incredibleindia.gov.in), an…
POST /v1/agent/tool/find_state_tourism_content
find_similar_cities
Find K cities most similar to a given city by travel-intent profile (not geographic distance). Backed by graph embeddings trained on POI/connectivity edges. Use when the user asks 'cities like X', 'alternatives to X', or you need compara…
POST /v1/agent/tool/find_similar_cities
Heritage-grounded discovery: UNESCO + ASI monuments, named tourism circuits, prior itineraries, seasonality, sentiment, and pair-suggestion.
get_circuit
Get a named tourism circuit (India OR global): name, description, member cities in order with coordinates, duration days, best season, cross-border flag, scope. India slugs: 'buddhist-circuit', 'golden-triangle', 'kerala-backwaters', 'co…
POST /v1/agent/tool/get_circuit
list_heritage_in_state
List ASI Centrally Protected Monuments in an Indian state (max 100). state_code is ISO-3166-2 (e.g. 'IN-BR' for Bihar, 'IN-UP' for Uttar Pradesh, 'IN-DL' for Delhi). Use only when the user wants heritage-rich planning in a specific India…
POST /v1/agent/tool/list_heritage_in_state
list_unesco_in_country
List UNESCO World Heritage Sites in a country (max 100). Optionally filter to in-danger sites only. Use for cross-border UNESCO context (e.g. Lumbini in Nepal for the Buddhist Circuit) or when the user asks specifically about UNESCO heri…
POST /v1/agent/tool/list_unesco_in_country
find_prior_itineraries
Retrieve gov-published tourism itineraries promoted from official state-tourism PDFs (license grade A). These are real, ground-truth itineraries published by state DMOs and the national portal — use them as priority anchors for the first…
POST /v1/agent/tool/find_prior_itineraries
find_pairs
Find POIs that pair well with a given POI or are clustered nearby in a given city. Backed by 1.5M PAIRS_WELL_WITH edges from our travel graph. Use when the user wants 'and what else is nearby' / 'what to combine with X'. Returns rows wit…
POST /v1/agent/tool/find_pairs
when_to_visit
Per-month seasonality scores (0..1) for a place by name+city. Backed by 9.7M BEST_SEASON edges from our travel graph. Use when the user asks 'what's the best time to visit X?' or is planning around a constraint (monsoon avoidance, festiv…
POST /v1/agent/tool/when_to_visit
get_sentiment
Get sentiment summary for a city: safety, crowdedness, friendliness signals where available. Use ONLY when the user is risk-sensitive (solo female traveler, seniors, families with very young children, post-conflict zones). India coverage…
POST /v1/agent/tool/get_sentiment
Traversals over the licensed travel graph: nearby POIs, themed clusters, multi-city routing, taxonomy expansion, and graph-ranked similarity.
nearby_pois
Top-K nearest POIs to an anchor POI. Reads the nightly materialised poi_neighbors_cache for sub-200 ms latency. Falls back to live graph query on cache miss.
POST /v1/agent/tool/nearby_pois
find_nearby_fsq_pois
Top-K POIs within a radius of a lat/lon point. Backed by the broad-coverage POI table (~32M commercial-OK rows) with a spatial index for sub-second lookups; complements the graph-backed nearby_pois which is narrower but richer.
POST /v1/agent/tool/find_nearby_fsq_pois
path_between
Shortest path between two POIs via NEAR edges. Returns the node sequence + total distance. Use to answer 'things to see between A and B'.
POST /v1/agent/tool/path_between
plan_route
Order a chosen set of POIs into an efficient visiting sequence that minimises total travel distance (a route optimiser over the stops, nearest-neighbour + 2-opt). Pass the poi_ids of the stops; returns the optimal order, per-leg distance…
POST /v1/agent/tool/plan_route
similar_destinations_via_graph
Cities similar to the anchor by flight-connectivity + theme overlap + circuit co-membership. Returns K cities with a weighted score and brief rationale.
POST /v1/agent/tool/similar_destinations_via_graph
find_similar_pois_by_slice
Top-K POIs most similar to an anchor POI, via the SIMILAR_TO edge precomputed from category-slice co-occurrence. Returns category-coherent recommendations (fine-dining restaurant → other high-rated dining). Sub-30 ms via direct edge trav…
POST /v1/agent/tool/find_similar_pois_by_slice
country_to_country_routing
End-to-end route across borders: anchor POIs in country A, themed cluster POIs in country B, and the flight route(s) or rail corridor between them. Relevant for cross-border circuit pitches (Buddhist Circuit India -> Nepal pilgrim flow).
POST /v1/agent/tool/country_to_country_routing
themed_clusters
Dense POI zones inside a city, ranked by POI count within a themed cluster boundary. Backed by BELONGS_TO_SLICE + PRIMARY_SLICE edges. Use to answer 'show me the food districts of Tokyo'. Optional time_slot personalizes to POIs open duri…
POST /v1/agent/tool/themed_clusters
expand_taxonomy
Walks the category-slice taxonomy from a starting category to surface adjacent categories. Used by 'more like this' discovery.
POST /v1/agent/tool/expand_taxonomy
Airport resolution and direct-route lookups for itinerary legs.
nearest_airport
Find the n closest airports (by haversine distance) to a TravelMindsAI city or to an arbitrary lat/lon. Returns airports sorted by distance with their IATA, name, country, and distance in km. Use when the user asks 'what's the closest ai…
POST /v1/agent/tool/nearest_airport
direct_flights_from
Return all direct flight destinations from a given airport. Each row contains dest_iata, destination airport name and city, destination country, the set of airlines flying the route, and the count of routes (which can exceed 1 if multipl…
POST /v1/agent/tool/direct_flights_from
direct_flights_between
Check whether direct flights exist between two airports and, if so, return the airline list with codeshare and equipment metadata. Returns an empty array when no direct flights exist (let the caller fall back to country_to_country_routin…
POST /v1/agent/tool/direct_flights_between
cities_with_direct_access_to
Return TravelMindsAI cities that have at least one airport with a direct flight to airports inside the target country. Useful for 'where can I easily fly into <country> from?' questions. Optionally restrict origins to a specific from_cou…
POST /v1/agent/tool/cities_with_direct_access_to
Reference data the agent uses without a network round-trip: visas, advisories, weather, currency, holidays, calendars, country info, local time.
visa_requirement
Look up the visa requirement for a country pair (passport country -> destination country). Backed by 79K country-pair edges. Use when the user is from one country and traveling to another, especially when planning multi-country itinerari…
POST /v1/agent/tool/visa_requirement
get_travel_advisories
Return active government travel advisories for a destination country. Source: published government advisories (US State Department, UK FCDO, Australia DFAT, India MEA, etc). License: gov-public-domain. Each row carries the issuing countr…
POST /v1/agent/tool/get_travel_advisories
get_airport_weather
Fetch current observed weather (METAR), forecast (TAF), and static airport metadata for a given airport by ICAO code. Use when the user asks about flight delays, visibility, wind, turbulence forecast, or runway/airport conditions. Return…
POST /v1/agent/tool/get_airport_weather
get_point_forecast
Fetch a weather forecast for ANY point on Earth (any lat/lon, not restricted to airports). Returns the next ~36 hours of hourly forecast: temperature, humidity, wind, precipitation, cloud cover, plus a 1/6/12-hour 'symbol code' summary (…
POST /v1/agent/tool/get_point_forecast
get_local_time
Resolve the IANA timezone name for any point on Earth and return current local clock time (or the local time at a specified UTC instant). Use when the user asks 'what time is it in <city>?', 'when does my flight arrive local time?', or t…
POST /v1/agent/tool/get_local_time
get_country_info
Resolve canonical metadata for an ISO-3166-1 alpha-2 country code: name, ISO-3 code, numeric code, official name, official currency (ISO-4217, via Babel/CLDR), official languages (ISO-639), and a human-readable display name in the locale…
POST /v1/agent/tool/get_country_info
convert_currency
Convert a monetary amount between currencies using European Central Bank reference rates. Returns converted amount + the exchange rate used + the rate's effective date. Use whenever the user asks 'how much is X EUR in INR?' or when an it…
POST /v1/agent/tool/convert_currency
convert_calendar
Convert a date between civil calendars: Gregorian, Julian, Islamic (tabular Hijri), Hebrew, Indian Civil (Saka), Persian (Jalali), Bahá'í. Use when the user asks 'what Hijri date is X?' or 'when is Y Hebrew date in the Gregorian calendar…
POST /v1/agent/tool/convert_calendar
get_public_holidays
Return the list of public holidays for a country and year, with optional sub-national (state/province) breakdown. Use when the user asks 'is X day a holiday in Germany?' or when planning whether a museum / government office / consulate w…
POST /v1/agent/tool/get_public_holidays
Vector search over curated narratives and points of interest — query by intent, not by name.
search_narratives_semantic
Semantic search over TravelMindsAI's curated city_narratives by cosine similarity to the user's query. Use when the user's intent is fuzzy or descriptive ('places that feel like Kyoto', 'cities with great street food at night') rather th…
POST /v1/agent/tool/search_narratives_semantic
search_pois_semantic
Hybrid BM25 + kNN search over points-of-interest . Use for 'find a [theme] in [city]' or themed-recommendation queries. Returns top-k POIs with score, theme, coordinates, and license. License filter is applied per the requesting plan.
POST /v1/agent/tool/search_pois_semantic
Question-answer and editorial layers with license-clean attribution.
qa_lookup
Look up Q&A pairs about travel from the StackExchange/CC-BY-SA knowledge base (2.31M docs). PLAN-GATED: only available to enterprise customers with the cc_by_sa_content opt-in tier. Returns each match with a CC BY-SA attribution line in…
POST /v1/agent/tool/qa_lookup
get_travel_qa
Top-K travel Q&A pairs for a city, drawn from a 3.5M-row structured travel-Q&A corpus linked to cities. Each row carries question + answer + category. Use to ground answers in pre-existing structured Q&A rather than synthesizing from scr…
POST /v1/agent/tool/get_travel_qa
get_wikivoyage_section
Returns a structured editorial travel section (eat/sleep/see/drink/do/get_around/get_in/activities/intro) for a city. Backed by 35K curated travel articles linked to cities. Best source for editorial travel prose with section-level struc…
POST /v1/agent/tool/get_wikivoyage_section
Hallucination-guard layer: verifiable claims are checked against ground truth before a response returns.
verify_with_ground_truth
INTERNAL-ONLY. Verify a claim against the internal ground-truth encyclopedic + travel-guide corpus. Returns URLs and confidence; never returns snippets or article bodies. Use only as a self-check against your own draft text. Do not quote…
POST /v1/agent/tool/verify_with_ground_truth
verify_narrative_grounding
INTERNAL-ONLY self-check. Given a draft narrative split into sections (overview, top_neighborhoods, food_scene, cultural_notes, getting_around) and a city_id, fetches the city's top-K POIs and checks that the narrative actually names a s…
POST /v1/agent/tool/verify_narrative_grounding