Skip to main content
Glama

Search buses

search_buses
Read-onlyIdempotent

Searches live Paytm bus routes and shows an interactive results card (operator, bus type, timings, rating, seats left, price). One-way, domestic, search only -- no seat selection or booking happens in chat. REQUIRED ARGS (same posture as search_flights): source, destination, and date are ALL mandatory. source/destination are free-text city names (e.g. 'Bengaluru', 'Hyderabad'); date is YYYY-MM-DD. There is no default date. The search runs for a date the traveller gave; a relative date they actually said ('tomorrow', 'next Friday') resolves to YYYY-MM-DD. When the date, source or destination is missing, the request is incomplete and the missing value comes from the traveller: a guessed today, tomorrow or weekend searches a day they did not ask for. With all three present, the traveller sees results only once the search runs. CITY DISAMBIGUATION: many Indian city names are ambiguous (e.g. 'Aurangabad' matches cities in Maharashtra, Bihar, Uttar Pradesh and West Bengal). An ambiguous name returns needsDisambiguation=true with sourceCityOptions / destinationCityOptions instead of a guess; the traveller picks one, and the search runs again with the chosen source_city_id / destination_city_id plus the original free-text source/destination. Filters: bus_type is 'AC' or 'Non-AC' when the traveller only named climate ('ac buses', 'non ac'), and a full type ('AC Sleeper', 'AC Semi-Sleeper', 'AC Seater', 'Non-AC Sleeper', 'Non-AC Semi-Sleeper', 'Non-AC Seater') only when they named a berth; a berth they did not name narrows the search wrongly. time_slot (early_morning 00:00-06:00, morning 06:00-12:00, afternoon 12:00-18:00, evening 18:00-24:00; no night slot), depart_after/depart_before (an hour or "HH:MM"; depart_before is exclusive, so 4-7 AM is 04:00 to 07:00, not 08:00). A window that crosses midnight is not one call. operators (list of operator names), max_price, min_rating, paytm_assured, boarding_point (matches by area name across all boarding points). Sort: recommended (default) | cheapest | fastest | earliest | rating. Invalid filter values are rejected with an error rather than silently ignored. Ratings below 15 reviews are not shown -- a missing rating means 'not enough reviews yet', not a bad bus. Named filters are sent to the Paytm wrapper (e.g. AC → is_ac) and the matching buses are shown. When those filters match nothing, the result says so; dropping the filters is the traveller's call, since an unfiltered search opens a second results card for the same query. Refining the search (only AC, cheaper, leaving after 9pm, better rated, etc.) is a new search with the changed filters and the same route and date, answered with new results rather than a pointer to the widget's chips. This tool lists a per-trip Paytm Checkin seat-layout URL as the dweb booking link (bookingUrl) and a matching seat deeplink for mweb/app (bookingDeeplink) -- there is no in-chat seat selection or payment; the traveller completes booking on Paytm Checkin. Questions about amenities, boarding/dropping points, or cancellation for a specific bus (or a tap on a card) are answered by get_bus_details with that card's tripRef, without a new search.

AI CARD SUMMARIES: the bus-search widget loads its one-line AI summaries itself (skeleton footers, then text or remove), so the results card is complete without another tool. Amenities and ratings come only from Paytm's data.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dateYesTravel date as YYYY-MM-DD. Mandatory — do not invent a date if the traveller omitted it; ask them first.
sourceYesDeparture city name, e.g. "Bengaluru".
sort_byNorecommended | cheapest | fastest | earliest | rating.recommended
bus_typeNo"AC" or "Non-AC" when the traveller only named climate, or a full type ("AC Sleeper", "AC Semi-Sleeper", "AC Seater", "Non-AC Sleeper", "Non-AC Semi-Sleeper", "Non-AC Seater").
max_priceNoBudget cap in INR (per traveller, starting fare).
operatorsNoRestrict to these operator names.
time_slotNoearly_morning [00:00, 06:00) | morning [06:00, 12:00) | afternoon [12:00, 18:00) | evening [18:00, 24:00). "early morning" is accepted. "night" is rejected. There is no overnight slot.
min_ratingNoMinimum star rating (buses with under 15 ratings are excluded from this filter -- their rating isn't shown either).
destinationYesArrival city name, e.g. "Hyderabad".
depart_afterNoEarliest departure, e.g. 18 or "18:00" (inclusive). 7, "7", and "07:00" are the same instant.
depart_beforeNoExclusive end, e.g. 7 or "07:30". "4–7 AM" is depart_after="04:00", depart_before="07:00". "00:00" means the end of this day. A window whose end is earlier than its start (22:00 to 04:00) is rejected; this search does not cross midnight.
paytm_assuredNoOnly Paytm Assured buses.
boarding_pointNoRestrict to buses with a matching boarding-point area.
source_city_idNoResolved Paytm city id for source -- only pass this after a prior call returned needsDisambiguation with sourceCityOptions, using the id the traveller picked.
destination_city_idNoSame, for destination.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
busesNo
searchYes
currencyNoINR
followupsNo
moreBusesNo
sortRanksNo
summariesNo
disclaimerNo
summariesPendingNo
sourceCityOptionsNo
totalBeforeFilterNo
serverProcessingMsNo
needsDisambiguationNo
destinationCityOptionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers substantial extra behavior on top: ambiguity returns needsDisambiguation with city options instead of a guess, invalid filters are rejected rather than ignored, ratings under 15 reviews are hidden not negative, filters that match nothing open a second results card, and booking happens off-chat via bookingUrl/bookingDeeplink.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and scope are front-loaded, and most sentences carry operational rules. It is nonetheless a dense block with some repetition (the no-booking constraint is stated twice, and city-disambiguation is restated at length), which costs it the top mark.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no prose, and the description still covers the tricky edge cases: disambiguation re-call with source_city_id/destination_city_id, filter rejection, empty-filter results, and where booking completes. Nothing an agent needs to invoke correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds decision rules the schema does not encode -- notably that bus_type should stay at climate level unless the traveller named a berth ('a berth they did not name narrows the search wrongly') and the exclusive end / no-midnight-crossing semantics for departure windows.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Searches live Paytm bus routes') and enumerates the result-card contents, plus an explicit scope statement ('One-way, domestic, search only -- no seat selection or booking'). It is clearly distinguishable from siblings like search_flights (same posture, different domain) and get_bus_details (per-trip questions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: get_bus_details answers per-bus amenities/boarding/cancellation questions 'without a new search', while refining filters is 'a new search with the changed filters and the same route and date'. It also states the mandatory-args precondition and that missing values must come from the traveller, not a guess.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources