Paytm Travel

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and non-open-world, so the safety profile is covered. The description adds real contract detail beyond that: the [{tripRef, summary}] shape, the 15–30 word differentiating-line rule, and the omission rule for non-differentiating entries.

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

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

Two sentences, front-loaded with the most decision-relevant fact (legacy/superseded), then the payload contract. Dense but each clause carries weight; no filler.

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

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 not be described, and the description covers lifecycle status, payload format, and omission behavior. For a legacy passthrough helper this is nearly sufficient; the only gap is the semantics of the echoed inputs.

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

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

Schema description coverage is 0% with 6 parameters, so the description carries the burden. It names the echoed fields (search/buses/currency/followups/disclaimer) and documents the required summaries array's item structure, which the schema leaves as opaque additionalProperties. It still doesn't clarify the meaning or defaults of the echoed fields.

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

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

The description identifies a specific verb+resource and, unusually, states its lifecycle status ('Legacy, app-only helper superseded by the widget's get_bus_ai_summaries path'), which lets an agent distinguish it from siblings. The mechanism of 'apply' (what actually happens when summaries are applied) is still a bit opaque, keeping it below a 5.

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

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

It explicitly names the superseding alternative (get_bus_ai_summaries) and tells the agent this is app-only, has no UI template, and is not a chat tool, which is effective when-not guidance. It stops short of stating any condition under which this tool is the correct choice, so a 4 rather than a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds value beyond them: it discloses the reprice step and the response contents (total plus Paytm booking link), which the annotations do not. It does not mention latency or pricing-staleness caveats, so it stops short of 5.

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

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

Two tight sentences, front-loaded with what it does, then the trigger condition and the not-a-chat-tool boundary. Every clause carries information.

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

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

Output schema exists, so return values need not be explained, yet the description still summarizes them usefully. The main gap is provenance of the two offer tokens and any failure/expiry behavior on reprice, which a widget-side tool with rich annotations can afford to omit.

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

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

Schema coverage is 0% and neither parameter has a description, but the semantics are largely self-evident from the names and from the description's 'chosen onward + return flight pair' framing. It still never says where these tokens come from, which an agent would need to obtain them.

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

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

Specific verb (Computes the combined round-trip fare) plus resource (onward + return flight pair) and scope (reprices, returns total plus booking link). Clearly distinguished from siblings like search_flights or get_fare_family, which handle search and fare families rather than fare combination.

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

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

States when it fires: 'Called by the flight search widget when both legs are selected.' The 'not a chat tool' note heads off an obvious misuse, but no alternative tools are named (e.g., fare_calendar or get_fare_family) for related fare questions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so safety needs no restating. The description adds real value beyond them: the result is aggregate dates/days with no per-flight rows, and roundtrip requests also return a return leg. It stops short of noting data freshness/caching or how the range is bounded, which would be the remaining behavioral gap.

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

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

Front-loaded with the core purpose, then the boundary against search_flights, then format conventions. Every sentence carries signal, though the final sentence about the calendar rendering below the search_flights card is UI-implementation detail that is somewhat tangential to invocation.

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

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

With an output schema present, the description need not explain return values, and it still clarifies that results are fares-per-date rather than flight lists. Combined with full schema coverage and clear read-only annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every field including defaults and the trip_type semantics. The description reinforces the IATA and ISO conventions, which is mildly useful but largely repeats what the schema states, so it does not exceed the baseline.

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

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

States a specific verb and resource ('Shows a Paytm fare calendar: the cheapest flight fare for every date in a range') and draws the boundary against the sibling search_flights by stating it lists no individual flights. An agent can tell instantly which of the two flight tools to pick.

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

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

Explicit when-not guidance: 'requests to show or find flights are served by search_flights.' It also gives a concrete co-selection condition (short window, sort_by='cheapest' on a date in that window, same route), which tells the agent how this tool pairs with search_flights rather than replacing it.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world. The description adds real behavior beyond that: it prefers search_context to skip a second search, falls back to re-fetching the route, makes no bus-details calls, uses Azure OpenAI in-server, and accepts empty summaries when nothing differentiates. That is substantive disclosure, though it omits failure/timeout behavior.

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

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

It is a single dense paragraph with the most decision-relevant fact ('Internal') front-loaded and no filler sentences. Some clauses are long, but each carries information an agent would otherwise have to infer.

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

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 not be explained, and the description conveys the call path and constraints well for a widget-driven tool. Still, for an 18-parameter interface with zero schema coverage, the near-total absence of parameter guidance leaves the invocation contract incomplete for anything but the widget that constructs the payload.

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

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

With 18 parameters and 0% schema description coverage, the description carries the full burden but only addresses one input: search_context (its source and purpose). The remaining 17 parameters (trip_refs, cards, sort_by, price/rating filters, city ids, etc.) are undocumented in both schema and description. It does not compensate for the coverage gap.

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

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

The description states a concrete verb+resource: it builds 'differentiating one-liners' from the search payload, and it names the siblings it relates to (search_buses for search_context, no bus-details calls). The core purpose is clear, though the 'Internal: called by the widget' framing and Azure OpenAI mechanics somewhat bury the headline. An agent can tell what it produces, just not instantly.

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

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

The 'Internal: called by the bus-search widget after search results render' line implicitly signals this is not for direct agent invocation, which is useful routing context. However, it never states an explicit when-to-use vs alternatives for an agent, nor a clean 'do not call directly' instruction. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context beyond that: no seat map or payment happens here, and booking hands off to Paytm Checkin, which tells the agent not to attempt a booking flow in this tool.

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

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

Front-loads what the sheet shows, then usage, then required/optional params, then scope limits. It is dense but each clause carries information; the CTA enumeration is slightly list-heavy for a description.

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

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

With an output schema present, return values need not be described, and the description still covers the sourcing path (search_buses tripRef), the required vs optional inputs, and the downstream booking boundary. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the 3-baseline applies, and the description earns above it by adding origin and matching semantics: trip_ref is 'from the prior search_buses card, matched exactly' and summary/booking_url are described as forwarded values from that card rather than free-form input.

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

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

States a specific verb and resource — 'Shows the Bus Details sheet for one trip from search_buses' — and enumerates the payload (amenities, boarding/dropping points, cancellation slabs, rating, CTA). This clearly distinguishes it from search_buses and get_flight_details in the sibling set.

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

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

Explicitly names when to use it ('source for amenities, boarding/dropping points, cancellation policy, or details for a specific bus, including a tap on a bus card in the widget') and gives a clarifying exclusion ('without a new search_buses call'). It also bounds scope with 'No seat map or payment in chat'.

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

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

Annotations already cover readOnly, idempotent, non-destructive. The description adds significant behavioral context: tokens expire, exact character matching is required, a repeat call re-renders the same widget, and a rejected value needs a fresh search_flights. This goes well beyond the annotations.

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

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

A single dense paragraph of roughly 350 words. It front-loads purpose well, but lacks bullet points or clear sections, making it hard to scan. Much of the detail is necessary for a complex token-based tool, but the presentation is not concise.

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

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

Output schema exists, so return values need not be explained. The description covers input token nuances, when to use, follow-up chaining to get_flight_review, and scope (one result covers every fare on that flight). It is complete for a complex tool with output schema backing.

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

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

Schema coverage is 100%, so baseline 3. The description adds value beyond the schema by clarifying the two accepted token forms (long signed token vs short offerRef), exact matching rules, and that a round trip needs both tokens. It enriches understanding but does not exhaustively specify every edge case.

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

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

States a specific verb and resource: 'Fare family / branded fare selector for ONE specific flight' and details the return (every fare, recommended pick, reasons). Clearly distinguishes from get_flight_details by noting policy detail comes from there.

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

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

Explicitly says when to use: which fare to pick, typically straight after search_flights or when the traveller taps the fare CTA. Names get_flight_details as the alternative for policy detail and explains the follow-up flow to get_flight_review.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing value-validation behavior that annotations cannot express: exact character-for-character matching, expiry, rejection requiring a fresh search, and that an onward token is invalid for the return leg. This is genuinely additive, though it omits any rate-limit or error-response detail.

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

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

Front-loaded with purpose and usage before the input rules, and each sentence carries distinct information (contents, triggers, token forms, failure modes, expiry). It is dense and slightly long, but the only mild redundancy is restating that the search summary lacks these details.

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

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

With an output schema present the description need not explain return values, and it instead covers what the schema cannot: when to call, which token forms are valid, round-trip handling, and expiry behavior. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: the short `offerRef` is ~30 characters, a short value is a legitimate input rather than an internal id, the two tokens resolve identically, and matching is exact so retyped or merged values fail. This clarifies the accepted value forms in ways the schema description only gestures at.

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

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

States a specific verb+resource ('Fare options and travel policies for one flight') and enumerates the concrete contents (multi-fare upsell, baggage, cancellation, reschedule tabs). It also explicitly separates itself from search_flights by noting the summary 'carries none of these', so an agent can route without opening either schema.

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

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

Gives explicit trigger conditions: right after search_flights, or when the traveller taps Fare options in the widget, and states the identifiers already returned are enough without a new search. It effectively names search_flights as the prerequisite alternative rather than leaving it to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is already met. The description adds real behavioral context beyond that: the review call refreshes the fare before handoff, the total originates from this call, and the review page always precedes the Paytm handoff. It stops short of describing latency or failure modes, so 4 rather than 5.

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

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

Leads with what the page shows, then usage, then parameters — well front-loaded and dense with non-redundant facts. It is long, and the handoff-ordering point ('review page comes before any handoff') overlaps with the earlier 'refreshes the fare before handoff' sentence, costing it a point.

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

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

For a 7-param tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: workflow position, token semantics, the recommended-fare fallback, and round-trip handling. Return values can be left to the output schema.

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

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

Despite 100% schema coverage, the description adds meaning the schema does not: offer_token may be the long signed token or the short offerRef and "a short value is valid, not an internal id", it must be matched exactly, and omitting price makes the tool fetch the recommended best-value fare. It also explains price/fare_name are used verbatim and that Saver vs Flexi map to different Paytm ids.

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

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

Specific verb+resource: shows the flight details/review page for a selected fare, and enumerates what it renders (itinerary, fare breakdown, refundability, Book link). It explicitly positions itself relative to siblings (after get_fare_family, before Paytm handoff), so an agent can distinguish it from get_flight_details and get_fare_family without opening any schema.

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

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

Names the exact triggering utterances ("continue, review, see flight details for a chosen fare, or book after picking a fare") and the fare-family Continue CTA that lands here. It also states what is NOT needed (no new search or fare-family call to settle on a fare), giving both when-to-use and when-not.

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

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

Annotations already declare the full safety profile (readOnly=false, openWorld=false, idempotent=false, destructive=false), so the bar is lower. The description usefully adds caller provenance (only the fetch shim), the CORS-workaround motivation, and that the payload is pre-built, but it discloses nothing about auth requirements, rate limits, or the effect of the relayed POST on the ingest endpoint.

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

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

Two sentences, purpose front-loaded, zero filler. The caller restriction and the 'not a chat tool' caveat both earn their place by preventing misuse.

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

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 not be described, and annotations cover the safety profile. The remaining hole is the four fully undocumented parameters on a generic relay tool, which the description does not address.

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

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

Schema description coverage is 0% across four required parameters, so the description carries the burden and largely fails it. 'Already-built ... POST' weakly implies url/method/headers/body are passed through verbatim, but no parameter is explained, and the openWorldHint=false annotation sits awkwardly beside a caller-supplied url.

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

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

States a specific verb+resource: it relays an already-built POST to sig(-staging).paytm.com, and explicitly says it is not a chat tool. That cleanly separates it from every bus/flight sibling, which an agent would otherwise have no reason to confuse it with.

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

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

Gives both the when and the when-not: it is called only by pulse.js's fetch shim to bypass the widget sandbox's CORS block, and it is not for chat use. Nothing about selection is left to inference.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behavior: nearby airports excluded server-side and counted in search.excludedAlternateAirports, invalid filter values rejected with an error, round-trip pair validity rules (no overlap, ≥2h buffer), international itineraries only as pre-stitched combos, and that every filter is echoed in structured_content.search.

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

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

Front-loads purpose and filters before deep sections, and nearly every sentence carries actionable constraint detail (buckets, airports, budget, refinement). It is nonetheless very long and could be tightened, with some redundancy between the schema descriptions and the prose transport of the same rules.

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

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

Output schema exists, so return values need not be restated; the description instead covers the complex behaviors an agent needs — date resolution, time-window mapping, airport exclusion, budget scope, and refinement semantics. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning beyond it: time_slot buckets with no night slot and outbound-only scope, depart_before exclusivity with worked examples, midnight-crossing rule, return-leg equivalents, and that max_price is the COMBINED both-legs total on round trips.

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

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

Opens with a specific verb+resource+output: 'Searches live flights on Paytm and shows an interactive results card (airlines, logos, timings, stops, fares).' It explicitly claims the 'show/find/list flights' intent and distinguishes itself from fare_calendar, get_fare_family, and get_flight_details, so an agent can route without opening sibling schemas.

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

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

Gives trigger phrasing ('show me flights HYD to BLR'), an explicit exclusion ('fare_calendar on its own covers cheapest dates and lists no flights'), and named alternatives for fare-family and policy questions. It also states that refining results is a new search with changed filters, not a pointer to suggestion chips.

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