AirTreks MCP

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it explains the routing logic (splitting into ticketable segments, carrier recommendations) and the domain constraint that alliance fare rules are deliberately bypassed. It omits any note on latency, cost, or output volume, which keeps it from a 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?

Front-loaded with the core action, then scope, then trigger conditions — good ordering. The 'This is how AirTreks consultants build 90% of itineraries' sentence is promotional and does not change an agent's decision, keeping it just under a 5.

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?

No output schema exists, so the description carries return-value burden, and it does indicate the output shape (individually-ticketable segments with carrier recommendations). Combined with full schema coverage on inputs, an agent has enough to invoke correctly; only the absence of explicit alternatives keeps it from 5.

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 100%, so the schema already documents pax, budget, cities, and preferences in detail. The description adds no parameter-level meaning (no format hints, no ordering caveats beyond what the cities description already says), so the baseline 3 applies.

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 — 'Break a complex multi-city itinerary into individually-ticketable segments with carrier recommendations' — and immediately scopes what kind of routes it handles (mixed carriers, LCCs, Gulf bridge connections, surface sectors). An agent can distinguish this from itinerary_quote or route_suggest without opening a 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 triggering conditions: 'Use this for any route with 4+ stops, backtracking, or region combinations that alliance fares can't cover.' That is strong when-to-use guidance, but it does not name an alternative tool (e.g., fare_product_match or itinerary_quote) for the cases this tool does NOT cover, so the routing decision is only half-specified.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, closed-world read. The description adds the inputs it weighs, but discloses no return format or limits beyond the structured fields.

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 with the core purpose front-loaded and the decision factors following. No wasted words, though it could be marginally tighter.

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 read-only recommendation tool with no output schema and full parameter coverage, the description conveys what is needed to call it correctly. Minor gap: it does not clarify how its recommendation relates to sibling quote/validate tools.

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 100%, so all three parameters are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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 specific verb (recommend) and resource (fare product type for a route) and enumerates the concrete outputs (RTW, Circle Pacific, Circle Atlantic, Open Jaw, Custom Multi-City). It is clear, though it does not explicitly distinguish itself from sibling tools like fare_quote or route_validate.

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?

Usage is only implied: the description notes what factors it 'considers' (stop count, direction, backtracking), which hints at when it applies. It gives no explicit when-to-use statement or named alternatives, so this stays at minimum viable.

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 readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond the structured fields: a departure date is mandatory for every flown leg, and long multi-continent itineraries can return unpriceable because the tool prices a single fare rather than split tickets. It stops short of noting latency or how partial failures are surfaced, which keeps it at a 4.

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?

Three sentences, front-loaded with the capability, then the routing rule, then the failure mode. Every sentence carries distinct information and none restates the title or annotations.

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-parameter read tool with an output schema absent, the description covers purpose, selection, prerequisites, and known failure modes, which is nearly everything an agent needs. It does not sketch the shape of a fare result (e.g. that multiple options come back), though maxOptions partially implies it.

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 100%, so cabin enums, '000' overland markers, and pax limits are already documented in the schema. The description only reinforces the flown-leg date requirement and adds nothing about syntax or formats beyond that, so baseline 3 applies.

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 ('Get live, bookable-quality fares for one specific itinerary') and pins the scope to actual flights and actual prices for given dates. It also implicitly separates itself from the ballpark sibling route_estimate, so an agent can route correctly without reading 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 an explicit trigger ('once the customer has settled on cities and dates and wants real numbers') and an explicit alternative with its own condition ('use route_estimate instead when dates are still open'). Nothing about tool 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes further by describing the analytic output ('dead legs', 'hub routing fixes', 'proven carrier combinations'), which no structured field provides since there is no output schema. It stops short of explaining result format or whether 'dead leg' is rendered as a boolean, list, or verdict.

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?

Three sentences, zero filler, and the core action is front-loaded before the diagnostic details. Efficient and readable; only the trailing geographic clause is somewhat loose and could be tightened.

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 read-only diagnostic tool with 100% schema coverage and no output schema, the description supplies the missing piece: what the analysis actually yields (dead legs, hub fixes, carrier combos). An agent can decide to call it and know roughly what comes back. It lacks a note on whether this substitutes for or complements fare_quote/route_validate.

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 100%: from/to IATA codes and the optional alliance preference are fully documented in the schema with examples. The description adds no parameter-level meaning such as valid alliance values beyond 'star'/'oneworld' or how alliance interacts with hub selection. Baseline 3 applies when the schema does the heavy lifting.

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 gives a specific verb+resource ('Check the best connection between two airports') and then enumerates concrete outputs: dead-leg identification, hub routing fixes, and carrier combinations. That is far more informative than the bare name. It never names or contrasts a sibling (route_validate, route_suggest, plan_route), so it stops short of the top score.

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?

'Essential for transpacific, kangaroo, and intra-Asia routing' gives geographic context for when the tool matters. However, it offers no when-not conditions, no prerequisites, and no explicit routing to alternatives among the many route/fare siblings. Usage is implied rather than prescribed.

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 mark this as non-read-only, non-idempotent, and non-destructive. The description adds critical behavioral context beyond that: the call takes about a minute, returns a quoteReference immediately, the separate status call waits for the result, and the reference is the only way to retrieve the quote.

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?

Every sentence earns its place: purpose, when to use versus fare_quote, async behavior, and reference retention. The most important selection constraint and workflow are front-loaded, with 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?

For a complex async tool with no output schema and full schema parameter coverage, the description explains what is returned at a high level, the quoteReference handoff, and the required follow-up status call. Nothing essential for correct invocation or retrieval 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 description coverage is 100%, so parameters such as cities, dates, cabin, and traveller counts are already well documented in the schema. The description adds no additional parameter syntax or formatting meaning beyond the schema, which meets the baseline for high coverage.

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: pricing a complete multi-stop or round-the-world trip, returning multiple ticketing options with actual tickets. It explicitly distinguishes itself from sibling fare_quote and names itinerary_quote_status for the follow-up call.

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 to use this for trips that will not go on a single fare, especially 3+ stops, and to use fare_quote when one specific itinerary on one ticket is wanted. It also directs the agent to call itinerary_quote_status immediately with the returned reference.

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 only the safety profile (readOnly, non-destructive, closed-world), so the description adds real behavioral context: a blocking wait of up to ~40 seconds, a possible 'pending' terminal state, zero cost, and no searching side effects. These traits are exactly what an agent needs to avoid mis-handling the call, and none are derivable from 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?

Four short sentences, front-loaded with the fetch action and immediate call timing, then the wait/pending behavior and the retry-vs-restart rule. No filler; every clause carries operational meaning.

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 no output schema, the description compensates by describing both return shapes (finished options vs. status 'pending') and the retry policy. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to invoke and loop 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 description coverage is 100% and the single parameter is already documented as the quoteReference returned by itinerary_quote. The description repeats that provenance but adds no format, length, or reuse semantics beyond the schema, so the baseline 3 is appropriate.

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 (fetch) and resource (the result of an itinerary_quote) plus the key input (quoteReference it returned). It is clearly distinguished from the sibling itinerary_quote that produces the reference, so an agent can route between the two 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?

Explicitly says to call it straight away, that it blocks ~40 seconds while pricing, and that on 'pending' the agent should call again rather than starting a second quote. The when-to-use and the when-not-to-restart guidance are both stated, not inferred.

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 the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, yet the description adds real substance: it discloses the internal evaluation set, direction detection, backtracking analysis, alliance feasibility, surface sectors, and carrier selection. It does not describe the response shape or any cost/latency 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?

Front-loaded with the entry-point role, then capabilities. Four sentences are mostly load-bearing, though the closing 'The customer doesn't need to know...' sentence is more marketing than instruction and could be trimmed.

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?

There is no output schema, so the description must carry more of the return-value burden; it says it 'recommends the best approach' but never sketches what a recommendation contains. Still, for a read-only planning tool with fully documented params and clear annotations, an agent has enough to invoke it 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 description coverage is 100% and all four parameters are documented in-schema, so the baseline of 3 applies. The description only gestures at the 'cities' input ('Give it your cities') and adds nothing about pax, budget, or preferences beyond what the schema already states.

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 ('plan') and resource ('multi-city route') and positions itself as the umbrella entry point that internally evaluates Star Alliance RTW, oneworld RTW, and custom mixed-carrier builds. This implicitly distinguishes it from narrower siblings like custom_route_build, route_suggest, and route_validate.

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 primary entry point for any multi-city trip' gives a clear condition for reaching for this tool, and the closing line clarifies it should be preferred when the trip type is unknown. No explicit when-not guidance or named alternative is given, so it falls short of 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 establish the read-only, non-destructive, non-open-world safety profile, so the description's added value is its disclosure of provenance and limitations: a range 'drawn from what AirTreks customers have actually paid,' 'not a live quote,' and 'will not reflect today's availability or seasonality.' That is meaningful behavioral context beyond the structured 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?

Front-loads the core capability, then the usage trigger, then the caveat about being a historical range rather than a live quote. Sentences are purposeful, though the description runs a bit long and the final clause restates the earlier 'range from past bookings' 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?

With no output schema, the description usefully describes the return: a 'per-person range in USD with how much history sits behind it,' and explains the historical-data caveat and absence of date/passenger requirements. For a 2-parameter read-only tool this is largely complete, with only minor detail left implicit.

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 100%, so the schema already documents both parameters in detail (cabin enum and defaults, cities ordering, '000' overland marker, min/max items). The description only restates the gist ('give it the cities,' no dates or passenger details) and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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: 'Get a price range for a multi-city or round-the-world trip,' scoping it to a defined trip type rather than generic travel pricing. It does not explicitly name or contrast the sibling quote tools (fare_quote, itinerary_quote), so it falls short of full sibling differentiation.

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 a clear triggering condition: 'Use it when someone asks what a trip will cost and you don't have exact dates yet,' and reinforces it with 'needs no dates and no passenger details.' It does not explicitly name the alternative tools or say when NOT to use it beyond the live-quote contrast, so it stops short of 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds value beyond them by disclosing the return behavior: up to 3 templates plus bookability ratings, which tells the agent the output is small, curated, and advisory rather than an exhaustive 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?

Three short sentences, front-loaded with the action and inputs before the output shape. The closing 'Great for trip planning inspiration' is soft marketing framing but still carries a usage signal, so it is not pure waste.

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 read-only suggestion tool with no output schema, the description adequately covers what comes back (up to 3 templates with bookability ratings). The main omission is how to choose this over the several sibling routing tools, but nothing needed 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 description coverage is 100%, so all five parameters (regions, alliance, maxStops, tripType, direction) are already documented with enums and value hints. The description only restates regions/direction/alliance and adds no syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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 ('Get suggested') and resource ('multi-stop flight routings') and enumerates the input dimensions (regions, direction, alliance). It is clear, though it does not name or contrast itself with siblings like plan_route or custom_route_build, which an agent might reasonably confuse with 'suggest'.

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?

'Great for trip planning inspiration' implies an exploratory, non-committal use case, which is useful context. But there is no explicit when-to-use vs when-not, and no pointer to which sibling to choose when the user wants an exact itinerary or a booked quote.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safe, non-mutating profile is covered structurally. The description adds real operational context beyond that by naming the analyses it runs (dead legs, poison carriers, bookability), though it says nothing about cost, latency, or what the warning output looks like.

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?

Three sentences with no filler, front-loaded with the core action and followed by the specific checks and the usage cue. Every sentence carries distinct information and nothing repeats the title or schema.

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 read-only validation tool with no output schema, the description covers purpose, checks performed and workflow placement adequately. It stops short of describing the shape of the feasibility result or warnings, which is the only remaining gap given no output schema exists to carry that.

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 100%, so all three parameters (cities, alliance, carriers) are already documented in the schema with formats and examples. The description adds no additional parameter meaning such as ordering requirements tying carriers to legs, so the baseline 3 applies.

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 (validate) plus resource (multi-city flight routing for feasibility) and enumerates the concrete checks performed: alliance carrier rules, dead legs, poison carriers, bookability. It does not name any sibling explicitly, so an agent must infer the distinction from 'before building an itinerary' rather than a direct contrast with custom_route_build or plan_route.

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 clear sequencing guidance: 'Use this before building an itinerary to catch routing problems early,' which tells the agent when in the workflow to call it. It offers no explicit when-not condition and never names an alternative tool to use instead, so the guidance is contextual rather than routing.

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 declare destructive=true, openWorld=true and idempotent=false, so the risk profile is already flagged; the description usefully adds that a human consultant takes over externally and that plan_route runs automatically to attach routing analysis. It does not warn about duplicate/irreversible submissions or whether the request can be withdrawn, which would matter for a non-idempotent external write.

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?

Four sentences, front-loaded with purpose then behavior, usage trigger, and requirements — no filler or marketing padding. The final requirements sentence is dense but each clause carries a constraint the agent needs.

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 15-parameter tool with no output schema, the description covers required fields, the discovery call pattern, and the external consequence of submission. It stops short of describing the success response or error behavior, which is the main remaining gap.

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 constraints beyond the schema: 'at least 2 cities', '3-letter IATA codes', 'a departure date for every leg', and the meta-instruction to call without questionsAnswers first. Those additions clarify how to populate required arrays that the schema alone leaves ambiguous.

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 ('Submit the customer's trip to AirTreks') plus the defining consequence (a human consultant takes over). This is clearly distinguishable from the sibling tools (fare_quote, plan_route, route_validate), and it even names plan_route to explain that it is invoked internally rather than by the agent.

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?

'Use this when the customer is ready to get a real quote' gives a concrete triggering condition, and the two-call questionsAnswers flow is spelled out precisely. It does not, however, state when NOT to use it (e.g. for pure pricing, use fare_quote/itinerary_quote), so the agent must infer the boundary against the other quote tools.

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