BRIJ Travel

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

Goes well beyond the annotations by disclosing the x402 settlement flow, escrow semantics, the two-step challenge/sign/retry pattern, the async booking worker, that funds stay in the wallet on validation failure, that excess funds remain refundable to refund_wallet, and that travel documents are refused BEFORE payment (400 codes). It also explains auto-refund if the airline never issues the ticket — rich behavioral context the readOnlyHint/openWorldHint flags cannot convey.

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?

Information-dense and roughly front-loaded (payment mechanics first, lowcost-travel caveat last), but it duplicates schema content — the trip.com nationality/passport requirement appears in both description and schema — and carries awkward mid-sentence line breaks. Some sentences could be trimmed without loss.

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, paid, asynchronous write operation with an output schema present (so return values need not be described), the description covers the payment handshake, async booking, retry, and refund behavior thoroughly. Minor gaps remain around explicit permission/wallet prerequisites and any polling cadence, but nothing essential to calling 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 passengers, intent_id, and x402_payment are already fully documented in the schema. The description reinforces passenger-list ordering ('lead first') and the trip.com document fields, but largely restates what the schema already says, so it sits at the baseline for high-coverage schemas.

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 action sequence: pay the ticket into the intent's escrow via x402 and request booking. It clearly sits downstream of intent creation ('The intent id travels in the request body', 'Id returned by POST /air/intents'), which distinguishes it from brij_create_flight_intent. It stops short of naming a sibling outright, but the verb+resource is unambiguous.

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?

Offers concrete operating instructions: 'Call it once without payment to get the payment requirements, sign them with your wallet, and call again with the payment', retry 'the same /book call' if booking fails, and polling GET /air/intents/{intent_id} until booked or refunded. It never explicitly states a when-not or names an alternative tool, so routing relies on the reader inferring the intent-creation prerequisite.

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?

With annotations only flagging it as a non-readonly, open-world, non-idempotent write, the description adds substantial context: payment goes only into the purchase's escrow, all checks (guests, unchanged price, nothing booked yet) run before settle, booking happens at Duffel after funding, and a failure is refunded in full with confirmation emailed. That is exactly the behavioral detail an agent needs before committing money.

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?

The key constraint (pay only the purchase into escrow) is front-loaded, which is good. However, the text repeats itself across three fragments — 'Pays the stay into the intent's escrow with x402', 'Pay the hotel escrow and name the guests', and 'Paid x402 endpoint: the intent's escrow amount' — and mixes prose with endpoint-style notes, making it longer than needed.

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 payment-bearing booking tool the description covers the money flow, pre-settle validation, post-settle booking, polling target, and failure/refund path, and an output schema exists so return values need no explanation. The one gap is the missing explicit pointer to brij_create_hotel_intent as the source of intent_id.

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 baseline is 3. The description restates what the schema already documents (guests lead-first with at least one per room, E.164 phone, special_requests forwarded to the hotel) and adds only the 'ask the guest by name' framing. Little meaning is added beyond the structured 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 states a specific compound action: pay the stay's escrow via x402 and book it, naming guests. It distinguishes itself from the intent-creation and order-polling siblings by explicitly directing the agent to poll brij_get_hotel_order until confirmed. It never names brij_create_hotel_intent as the prerequisite step, leaving the intent_id provenance to the 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?

Clear operational sequencing: collect guests (lead first), email and phone in E.164, ask the guest for each by name, then poll brij_get_hotel_order until confirmed or failed. It gives the 'ask by name, never as contact details' instruction, which is genuinely actionable. It stops short of explicit exclusions, e.g. that an intent must already exist or that this should not be called before brij_quote_hotel/brij_create_hotel_intent.

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 only flag readOnly=false, idempotent=false, openWorld=true; the description goes far beyond them, disclosing the escrow payment model, human approval before card payment, capture gated on the merchant's confirmation email, automatic refund otherwise, and the exact 400 error codes raised before settle. This is precisely the money-movement context an agent needs and cannot get from 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-loaded with the payment model and the operator-specific passenger rules, and the 'Fund the escrow and name the travellers' line anchors the body. There is real redundancy — gender/document rules appear in the opening paragraph and again in the body/schema — and the final settle-and-refund sentence is a long run-on, but no sentence is 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 mutation tool that moves money, the description covers the input party constraints, conditional field requirements, error behavior, the re-read/approval/settle sequence, and the refund fallback. With an output schema present it needn't describe return values, so nothing an agent needs to call it safely 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 would be 3, but the description adds cross-field semantics the schema cannot express: passengers must be exactly the fare-priced party (the search's adults) with the lead first, and each optional field is conditional on the quote's `requires` list. It largely restates the per-field operator rules already in the schema, which keeps it from a 5.

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+resource ('you pay only the purchase itself, into its escrow') and immediately scopes it to bus intents via x402, distinguishing it from the create_*_intent, quote_bus and buy_train/buy_flight siblings. An agent can tell this is the payment step of the bus flow without opening the 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?

'Fund the escrow and name the travellers' plus the intent_id/escrow framing make the preconditions clear (a priced intent must already exist). The per-operator conditionals ('when the quote's requires lists contact.phone', 'For buses in Türkiye…') give concrete when-to-send rules, but it never explicitly names the preceding sibling tools (brij_create_bus_intent / brij_quote_bus) or states when not to use 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 only give the generic safety profile (not read-only, open world, non-idempotent, non-destructive). The description goes far beyond: escrow funding semantics, the 409 ship_to_changed refusal when region/ZIP diverge from the quote, every refusal happening before settle, human approval, card payment, merchant confirmation email as escrow proof, and automatic refund after 6 h. This is unusually rich behavioral disclosure for a mutation 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?

The content is comprehensive but the opening is awkward and redundant — 'you pay only the purchase itself, into its escrow' is immediately restated by 'Pays into the intent's escrow with x402.' Mixing transport framing ('Over MCP:', 'Paid x402 endpoint:') with operational detail dilutes the front-loading of the core action.

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?

Given an output schema exists, the description need not explain return values, and it covers everything else an agent needs: prerequisites, escrow/refund timing, error conditions, and where to poll status. Nothing material is missing for correct invocation.

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 baseline is 3, but the description adds real meaning: region and postal_code must equal the quoted values or the call 409s, notify_email is optional and scoped to order contact only, and x402_payment exists for clients that cannot set _meta. That is genuine value beyond the schema.

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 — pays the intent's escrow for a product purchase and funds it with shipping details — and distinguishes itself from siblings by naming the escrow model that separates it from brij_quote_product and brij_create_product_intent. An agent can tell this is the payment step, not the quoting or intent-creation step.

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 description supplies the prerequisite (intent_id from the intent endpoint) and a downstream pointer (read progress with POST /shop/orders), and explicitly ties behavior to the analogous sibling brij_book_flight. It does not spell out the full when-not-to-use path versus brij_quote_product / brij_create_product_intent, so it falls short of explicit 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?

Far exceeds what annotations convey: it discloses that all validations refuse before settle, names specific 400 error codes (contact_phone_required, contact_postal_code_required, document_required), describes the human approval step, card payment, capture-only-on-merchant-confirmation-email, and automatic refund otherwise. This tells the agent the financial and failure semantics of a money-moving call, which annotations (destructiveHint=false, openWorldHint=true) alone do not.

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, but the opening two sentences are partly redundant ('you pay only the purchase itself, into its escrow' / 'Pays into the intent's escrow with x402'), and the payment-flow sentence is a semicolon-chained run-on that is hard to parse. Nearly every clause carries real information, so it is dense rather than padded, but the structure costs readability.

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 money-spending, non-idempotent, open-world tool, the description covers prerequisites, conditional parameters, error paths, approval, capture, and refund behavior, and an output schema already handles return values. Nothing an agent needs in order to call it safely 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; the description earns more by tying parameters to runtime triggers ('when the quote's requires lists contact.phone'), naming the operators that cause them (OUIGO, Eurostar, Renfe, FlixBus Türkiye/India), and warning that a missing value yields a specific 400 rather than a late failure. It also enforces ordering ('lead first') and cardinality ('exactly the party the fare was priced for').

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 action on a specific resource: pays the escrow for a train booking intent with x402 and names the travellers. The analogy to brij_book_flight and the reference to the intent/quote pipeline make clear this is the terminal purchase step, not search, quote, or intent creation. It does not explicitly contrast itself with brij_quote_train or brij_get_train_order, but the resource scope is unambiguous.

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 through references to prior artifacts ('the intent's escrow', 'the search's adults', 'the quote's requires'), and the agent must infer the sequence: search_trains → quote_train → create_train_intent → buy_train. There is useful conditional guidance (contact.phone, contact.postal_code, document triggers) but no explicit 'call this after X, not instead of Y' statement.

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?

Beyond the annotations, the description discloses substantial behavior: the cancellation is immediate and irreversible, the refund amount equals whatever the cancellation timeline returns plus the service fee minus 2% of the stay (2–5 USDC), the refund goes to the wallet set at intent creation, and non-refundable rates return only part of the fee. It also covers auth inputs (support code + lead guest family name) and rate limiting. Minor gap: it does not reconcile 'cannot be undone' with destructiveHint=false, which an agent could read either way.

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?

The critical warning ('Confirm with the guest first: it cannot be undone') is front-loaded, which is good, but the text is cluttered with x402/HTTP-API pricing boilerplate that is explicitly irrelevant to MCP calls, and it repeats the title verbatim as its own sentence. The refund mechanics are dense but useful; the payment plumbing 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?

For a three-parameter mutation with full schema coverage, an output schema, and annotations, the description supplies what those fields cannot: irreversibility, refund calculation, refund destination, and cost model. An agent has enough to decide and call correctly; only the destructiveHint tension and prior-step prerequisites (intent must exist) are 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 coverage is 100%, so all three parameters are already documented with their origins (intent creation response, lead guest family name). The description adds only modestly, restating that the support code and lead-guest family name are required headers and noting where the refund wallet comes from. Baseline 3 applies when the schema carries the parameter burden.

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 and resource ('Cancel a hotel booking and file its refund') and specifies the two-part behavior: cancellation happens at the hotel immediately and a refund is filed per the cancellation terms. It does not explicitly name or differentiate itself from the refund-request siblings (brij_request_*_refund), though no hotel-specific refund sibling exists, so the scope is largely unambiguous.

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 gives a clear operational precondition: 'Confirm with the guest first: it cannot be undone,' which tells the agent to verify intent before calling. It does not state when *not* to use it or point to an alternative path (e.g., checking order status via brij_get_hotel_order first, or handling a refund without cancelling), so guidance is strong on preconditions but silent on alternatives.

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 write/openWorld/non-idempotent profile, and the description usefully adds context beyond them: MCP calls are free but rate-limited, the x402 $0.10 USDC price applies only to the HTTP surface, escrow creation locks a quote, and the returned customer_support_code must be retained. It stops short of warning that the non-idempotent flag means repeat calls create separate escrows/charges.

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?

The primary purpose statement is not front-loaded — it appears after pricing and parameter guidance. Content is redundant (offer_id and customer_support_code are each mentioned twice) and the trailing 'Identical to POST /air/intents...' fragment is confusing rather than informative for a bus endpoint.

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 needn't be explained, and annotations carry the safety profile. The description covers cost model, workflow sequencing, and support-code handling, but for a funds-locking mutation it omits irreversibility/idempotency implications and misplaces the domain reference (/air) for a bus tool.

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% with only 3 params, so the schema already documents funding_wallet and refund_wallet fully. The description only restates that offer_id is the quote's offer_id, adding no syntax or constraints beyond what the schema already says ('sent back EXACTLY as received'). Baseline 3 for full coverage with minimal added meaning.

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 core sentence 'Create the escrow for a quoted journey' gives a specific verb and resource, and the title 'Lock a bus quote' plus the 'Next: brij_buy_bus' pointer position it clearly in the quote→intent→buy sequence distinct from brij_quote_bus and brij_buy_bus. However, the purpose sentence is buried after pricing/param notes, and the reference to 'POST /air/intents' in a bus tool muddies the resource identity.

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?

'Next: brij_buy_bus' explicitly signals the downstream step, and requiring the offer_id from the quote implies this must follow brij_quote_bus. But there is no explicit when-to-use statement, no when-not, and no prerequisite framing (e.g. 'call this after quoting, before paying') 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the payment model (free over MCP, x402/PAYMENT-SIGNATURE for HTTP, 402 without payment), escrow semantics, the unrecoverable customer_support_code, affiliate referral freezing, and specific failure modes (409 fare_menu_expired, 409 fare_check_failed, 409 browser_booking_unavailable, 404 offer_not_found). This is exactly the behavioral context annotations cannot carry.

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?

Critical warnings are front-loaded well (free-over-MCP, KEEP customer_support_code, Next step), and the failure-mode detail is justified by complexity. However, the core purpose is restated three times ('Creates the escrow for one offer', 'Create an escrow-backed booking intent from a selected offer', 'Creates the local booking intent'), and the lowcost block is dense and unordered, so not every sentence earns its place.

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-value explanation is not required, yet the description still flags the must-keep customer_support_code. Combined with the payment requirements, escrow-vs-funding distinction, referrer behavior, and the full set of supplier-specific error paths, an agent has everything needed to invoke this tool correctly and recover from failure.

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 value: it documents the optional 'referrer' field, which does not appear in the input schema at all, and explains offer_id semantics ('send back EXACTLY as received', the trailing '@s<search>' tying it to the buyer's search). That is meaning beyond the schema, though funding/refund wallet semantics are left to the schema.

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: 'Creates the escrow for one offer' / 'Create an escrow-backed booking intent from a selected offer.' It distinguishes itself from the sibling it feeds into by naming the next step ('Next: brij_book_flight') and clarifying that it 'does not fund the escrow, pay the airline, or issue a ticket.' An agent can tell it apart from brij_book_flight and brij_get_flight_offer_details 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?

Explicit routing: 'Next: brij_book_flight' after intent creation, and a clear negative boundary ('This does not fund the escrow, pay the airline, or issue a ticket') that separates it from the booking tool. It also gives conditional usage for the lowcost variant, including when to re-open fares, retry offer-details, or fall back to a fastbooking offer. Alternatives and preconditions are spelled out rather than implied.

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?

Beyond the annotations it discloses real consequences: this moves funds into escrow, the escrow amount is the quote's ALL-IN total, and customer_support_code is single-read and unrecoverable but required for brij_book_hotel, order lookup, and cancellation. It also clarifies cost mechanics (free over MCP, rate-limited; $0.10 USDC only on the HTTP x402 path) and confirms it is the same operation as POST /air/intents, which is genuinely useful context an agent would otherwise have to guess.

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?

The actual purpose statement is buried in the middle of the paragraph, after a pricing preamble and before a near-duplicate pricing sentence at the end ("Free over MCP..." vs "Paid x402 endpoint: $0.10 USDC"), so the same cost caveat is stated twice. Parameter advice, pricing, purpose, and the next-step pointer are interleaved rather than front-loaded or grouped.

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 3-parameter mutation tool with an output schema, the description covers the workflow, the money semantics, the immutability of customer_support_code, and pricing — the things an agent can't get from structured fields. Only the missing sibling exclusions keep it from being fully complete.

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 schema already documents funding_wallet, refund_wallet, and the exact offer_id semantics including the refund_wallet default. The description only adds that offer_id belongs to the hotel quote, which is marginal beyond what the schema says; 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 sentence "Create the escrow for a quoted hotel stay" names a specific verb (create) and resource (escrow for a hotel stay), and the opener "Lock a hotel quote" plus "Next: brij_book_hotel" make the position in the quote → intent → book sequence unambiguous. An agent can distinguish this from brij_quote_hotel and brij_book_hotel 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?

It states the prerequisite (must follow a hotel quote), the flow position ("Next: brij_book_hotel"), and a hard usage rule for offer_id ("sent back EXACTLY as received... never reassembled by hand"). It doesn't explicitly name the sibling alternatives (e.g. why not brij_create_flight_intent or brij_book_hotel directly), so it falls just short of full routing guidance.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true): it discloses the MCP vs HTTP cost model and rate limiting, escrow amount derivation from the quote's total_amount, the ~20-minute quote expiry with a 409 error, and the fact that customer_support_code is required later for reads and refunds and cannot be re-read. That is exactly the operational context an agent needs and annotations cannot carry.

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?

The purpose sentence is buried after a pricing/persistence preamble, and the customer_support_code warning is stated twice (opening fragment and closing paragraph). The content is valuable but the ordering is not front-loaded and there is mild redundancy.

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 explanation, and the description covers cost, expiry, error handling, workflow position, and the refund path. Minor gap: it references POST /air/intents and /air/* offer sources for a product tool, a copy-paste artifact that could momentarily confuse an agent about the endpoint family.

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: it pins offer_id to the quote's offer_id, restates the request body shape {funding_wallet, refund_wallet?, offer_id}, and ties the escrow amount to the quote's total_amount — an input-to-effect mapping the schema does not express.

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 — "Create the escrow for a quoted product" — and the title/slug make the product variant distinguishable from brij_create_flight_intent and brij_create_train_intent. It also situates the tool in the workflow (offer_id from quote, next step brij_buy_product), so an agent can place it 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 a clear before/after context: offer_id must come from the quote step, and the next call is brij_buy_product, plus explicit retry guidance for the 409 offer_expired case (~20 min). It never states the negative case (that this is not for flights/trains), leaving sibling exclusion to the name and title.

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 write/open-world/non-idempotent profile, and the description adds real value beyond them: MCP calls are free but rate-limited, the HTTP endpoint costs $0.10 USDC, an escrow is being created, and customer_support_code must be persisted. It does not describe reversibility of the escrow lock.

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?

The text is jumbled and poorly front-loaded: the actual purpose ('Create the escrow') appears third, pricing is split across two spots, and 'customer_support_code' is stated twice ('KEEP customer_support_code from the answer' and 'Persist customer_support_code'). The 'Identical to POST /air/intents' line is likely a copy-paste error that adds noise.

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 explained. The description covers pricing model, sequencing, and key parameter handling, which is nearly complete for a financial intent tool. The only blemish is the misleading /air/intents reference for a train endpoint.

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 schema fully documents all three parameters. The description reinforces that offer_id must be the quote's offer_id, but adds no syntax or format detail beyond what the schema already carries, matching the baseline for full schema 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?

The core purpose is stated with a specific verb and resource: 'Create the escrow for a quoted journey.' It also implies the train-specific scope through 'Next: brij_buy_train'. However, it never explicitly distinguishes itself from create_flight_intent / create_product_intent siblings, and it confusingly cites POST /air/intents for a train tool.

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 provides clear sequencing: use the offer_id from the quote and 'Next: brij_buy_train', which routes the agent through the workflow. It does not, however, state any when-not-to-use condition or the alternative siblings to pick instead.

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, idempotent, non-destructive, open world), yet the description still adds real operational context: MCP calls are free and rate-limited while the x402 price applies only to the HTTP API, plus concrete result caps (up to 8 cities at 2+ characters, up to 8 hotels from 3 characters). Those caps and the cost/rate-limit distinction are not derivable from any structured field.

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?

The content is delivered twice in near-identical form (a pricing/summary paragraph, then a restatement with the same limits and the same 'Optional: ... location' note), so roughly half the text is duplication. Leading with x402 pricing and an HTTP-vs-MCP caveat buries the actual purpose for a one-parameter lookup tool.

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-value explanation is optional, yet the description still names the returned fields (hotels[]: accommodation_id, name, address). For a single-parameter, read-only suggestion tool this covers what an agent needs, with only matching semantics and empty-result behavior 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 coverage is 100% and the single parameter q is already documented as 'the start of a city name.' The description adds genuine meaning beyond that — the 2-character minimum for city matches and the 3-character threshold that unlocks hotel-by-name matches from the same input — but leaves prefix-vs-substring matching and case sensitivity unstated.

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 and resource — suggest cities (city_id) and, from 3 characters, hotels by name (accommodation_id) — and names the downstream consumer, brij_search_hotels, which separates it cleanly from siblings like brij_get_hotel_rates or brij_quote_hotel. The title ('Find a city for a hotel search') understates the hotel-lookup half, but the body corrects that.

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 implied rather than stated: the call exists to supply city_id/accommodation_id to brij_search_hotels, and the description notes that search_hotels also accepts a typed city name as location. That hint gestures at an alternative path but never says explicitly when to look up an id versus passing a free-text location, nor when this tool should be skipped.

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 genuinely useful behavior: MCP calls are free but rate-limited (vs the $0.01 USDC x402 HTTP path), the required header X-Customer-Support-Code, and the status lifecycle purchasing → ordered → confirmed | refunded. That lifecycle detail is context beyond anything the annotations carry.

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?

The purpose is buried behind a pricing disclaimer, then restated, then followed by more pricing, producing a jumbled front-load. Every element is relevant, but the ordering wastes the reader's first sentence on billing mechanics rather than what the tool returns.

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 annotations cover the safety profile. The description supplies the auth header and status flow, but the rail/bus resource mismatch and absence of when-to-use routing leave the definition only adequately complete for a read-only status lookup.

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 two parameters are already documented. The description restates that intent_id goes in the body and customer_support_code goes in a header, which adds minor transport detail but little semantic meaning beyond the schema.

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+resource ('booking status and reference'), but it names the resource as 'Rail' while the tool name, title ('Bus booking status'), and siblings (brij_get_flight_order, brij_get_train_order) all indicate this is the bus variant. An agent can infer the general purpose but the resource label is inconsistent with the tool's own identity.

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?

There is no explicit when-to-use guidance and no alternatives named. The closest sibling, brij_get_intent, and the order-retrieval siblings for other modes are never referenced, so the agent must infer that this is the post-purchase status lookup rather than an intent or quote call.

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 substantial behavioral context beyond them: caching (~5 min per offer_id), staleness windows (20-30 min, 409 fare_menu_expired), the 202 fares_pending flow with Retry-After, 404 semantics where 'the payment is never settled', latency expectations (20-45s cold read), and the informational-only services caveat.

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 routed well, but the definition is long for a one-parameter read tool and repeats fare-menu and pricing detail across paragraphs. The edge-case coverage (202/409/404, caching, latency) justifies most of the length, though some sentences could be tightened without information loss.

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-value documentation is not required, and the description still covers pricing, failure modes, caching, freshness, and booking handoff. Nothing an agent needs to invoke this correctly appears to be 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% and only one parameter exists, so the schema already documents offer_id. The description still adds value by explaining the id's provenance ('id from POST /air/search'), the browser-tier composite format ('<tier>:<flight>##<n>'), and where the id is consumed next (POST /air/intents).

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 and resource: 'Drill into one offer: fare menu, bag prices, live price.' It distinguishes itself from brij_search_flights by framing the tool as a per-offer drill-down and revalidation step, so an agent can tell it apart from siblings without reading the 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 enumerates the two use cases — answering ancillary/conditions questions ('how much is an extra bag', 'is this fare refundable') and revalidating a single offer after a search — and states it is 'cheaper and quota-friendlier than re-searching,' naming the alternative it replaces.

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, openWorld), and the description adds substantial behavior beyond them: the customer-support-code auth gate, the x402/$0.01 USDC payment context, MCP-side rate limiting, and detailed refusal semantics (401/403 for missing or wrong code, 404 for unknown order, none of which are charged since they occur before settlement). That is a materially richer picture than the annotations alone.

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?

The purpose statement is pushed to the second sentence by a lengthy pricing caveat, and the payment story is repeated (free over MCP, then the $0.01 USDC x402 note, then the refusal-charging rule). The error-semantics content earns its place, but the pricing digression is partly about the HTTP API rather than this MCP tool, which dilutes front-loading.

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 needn't be explained, yet the description helpfully enumerates them anyway and adds error-path semantics and auth requirements. Rate limits are mentioned but not quantified, and the description is otherwise complete for calling the tool 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% and both parameters are documented in the schema, so the baseline is 3. The description only echoes the code's origin ('returned at intent creation') and says nothing about order_id format or where to obtain it that the schema doesn't already state, so it adds little on this dimension.

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 and resource: 'Fetch airline order status,' and clarifies it returns booking reference and order status for any fulfiller. The word 'airline' distinguishes it from the product/train order siblings without needing their schemas. It stops short of an explicit sibling comparison beyond mentioning the PNR alternative, so it is clear but not maximally differentiated.

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 gives a concrete routing rule: 'If all you need is the PNR, GET /air/intents/{intent_id} carries it for free as booking_reference,' which maps to the brij_get_intent sibling and states the condition that selects it. It doesn't spell out when not to use this tool versus the train/product order siblings, but the core when-to-use guidance is present.

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?

Adds substantial behavior beyond the annotations: idempotent merged-and-deduplicated full-list reads, safe to retry, rate-limited rather than x402-priced, and the 5-minute expiry yielding 410. It also explains the authorization model (unguessable search_id) and the status:enriching lifecycle, which the readOnly/idempotent hints do not convey.

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 free/rate-limited clarification and the core polling instruction, then layers lifecycle details. Slightly verbose with repeated emphasis on 'free' and the payment model, but nearly every sentence carries actionable 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?

With an output schema present, return-value detail is unnecessary, and the description covers the remaining gaps: polling cadence, terminal status, expiry, idempotency, and how gained offers feed the unchanged purchase tunnel. Nothing an agent needs to poll 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 single search_id parameter is already documented. The description adds meaning the schema lacks: that search_id is the authorization token and expires ~5 minutes, which affects how the agent should treat the value.

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 (poll a progressive flight search for still-arriving offers) and explicitly positions it as the companion to the initial POST /air/search. An agent can distinguish it from brij_search_flights 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 when-to-use (poll until status: complete), the cadence (respect poll_after_ms, ~5s), and the failure/expiry condition (search_id expires ~5 min, then 410 and a new search is needed). It also clarifies the search itself must be initiated elsewhere first.

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, openWorld and non-destructive, so the safety profile is covered; the description still adds real value with the rate-limiting note, the auth/header requirement, and the full status state machine including when escrow is captured. The HTTP-vs-MCP pricing preamble is partly noise for an MCP caller, which keeps it off 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?

The core is front-loaded and dense with useful information, but the opening parenthetical about x402 pricing and MCP-vs-HTTP billing is context that does not help an agent decide or call the tool. The semicolon-separated state chain is compact but slightly cryptic on first read.

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 the description need not enumerate return fields, and it still explains the status lifecycle and that the booking object carries hotel, dates, guests, key collection and cancellation terms. Authentication and rate limits are noted, leaving little an agent needs that 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 the baseline is 3: both parameters are already documented in the schema, including that intent_id comes from POST /hotels/intents. The description's only added semantic is that customer_support_code travels as an X-Customer-Support-Code header, which is a small increment over the schema.

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?

"Get a hotel booking's status and reference" gives a specific verb and resource, and the state-machine sentence makes clear this is a status-poll on an existing booking rather than a search or a rate lookup. It does not explicitly name the near neighbours (brij_get_intent, brij_get_hotel_rates), so an agent must infer the boundary from the hotel/booking wording.

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 implied: an agent learns the tool needs an intent_id from POST /hotels/intents and returns a status progression, so polling after intent creation is the obvious use. There is no explicit when-to-use versus brij_get_intent or when-not-to-use (e.g. after cancellation), and no stated prerequisites beyond the support code.

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 bar is lower, and the description still adds real behavior: MCP calls are rate-limited rather than charged, refusals are free, and critically 'Rates paid at the hotel are not listed', which signals a coverage limitation an agent could otherwise misinterpret as an empty result. The dense enumeration of the response shape adds less value since an output schema exists.

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?

The first third of the text is x402/MCP billing boilerplate that the agent cannot act on and that precedes the actual purpose statement, so the definition is badly front-loaded. It then spends further sentences restating the return shape in prose even though an output schema is present.

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 one-parameter read tool, the essentials are all present: where hotel_id comes from, what the call yields, which field to pass onward, and the notable gap that pay-at-hotel rates are excluded. The only shortfall is that this is achieved through verbose duplication of structured fields rather than focused new information.

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?

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. The description only echoes the origin of hotel_id ('from POST /hotels/search'), matching rather than extending the schema text. 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?

The sentence 'List the rooms and rates of one searched hotel' gives a specific verb and resource, and the prerequisite ('hotel_id from POST /hotels/search') together with 'Next: brij_quote_hotel' separates it cleanly from the search and quote siblings. It loses a point because the actual purpose statement is buried behind pricing/billing boilerplate that has nothing to do with what the tool does.

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 description establishes the position in the workflow: it consumes a hotel_id produced by hotel search and feeds a rate_id into brij_quote_hotel. That is clear context for when to call it. It stops short of explicit exclusions, e.g. it never says to call brij_search_hotels first if no hotel_id exists, or that this is not the tool for booking.

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, idempotent, non-destructive), and the description adds substantial context beyond them: MCP calls are free but rate-limited rather than x402-priced, the status transitions to booked only after escrow capture, and booking_reference holds the airline PNR once ticketed.

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 paragraphs, mostly front-loaded and information-dense. The pricing/rate-limit note leads before the core purpose, which slightly buries the one-line 'Fetch a booking intent by id', but nothing is wasted.

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, yet the description still supplies the lifecycle semantics an agent needs (polling, status=booked, terminal condition of booking_reference present, and the instruction to relay it to the traveller). Nothing required to invoke or interpret this tool 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?

The single parameter has 100% schema description coverage, so the schema already explains that intent_id is the id returned at creation. The description only adds that the same id space spans all four intent types, which is marginal value beyond the schema.

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 ('Fetch a booking intent by id') and explicitly scopes it to flight, train, bus and product intents, which cleanly separates it from the vertical-specific siblings like brij_get_flight_order and brij_get_bus_order.

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 concrete usage trigger: poll it after /air/book to watch status move to booked. It stops short of naming when to prefer this over the per-vertical order tools or when not to call it, so it is clear context without explicit exclusions.

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 genuinely new behavioral context: MCP calls are rate-limited rather than paid, auth failures are free (401 missing / 403 mismatch), and the full order state machine including when tracking_number appears. This is well beyond what the annotations carry.

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 purpose, but the x402 pricing/header paragraph is largely irrelevant to an MCP caller and consumes space before the useful lifecycle detail. The state-machine sentence at the end is the most valuable and is buried.

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 explanation, and the description covers auth requirements and the status lifecycle. It is complete enough to invoke correctly, with only sibling routing left unaddressed.

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. The description only maps intent_id to the request body and customer_support_code to a header, which is marginal added meaning over a schema that already documents both.

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: 'Merchant order status: order number, shipping, tracking.' The word 'Merchant' plus the field list distinguishes it from the sibling flight/train order tools and from brij_get_intent, though it never names those siblings explicitly.

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?

Conveys the context implicitly (this is the post-order status check, and the lifecycle purchasing → ordered → confirmed → shipped → refunded signals when it becomes relevant), plus the MCP-vs-HTTP pricing distinction. But it never says 'use this rather than brij_get_intent' or when NOT to call 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 declare readOnly, openWorld, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: MCP calls are free but rate-limited, the HTTP endpoint has a different x402 price, and the status transitions are purchasing → ordered → confirmed/refunded.

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?

The description is short but poorly front-loaded: it opens with MCP pricing instead of the tool's purpose. The paid x402 endpoint sentence is relevant mainly to the HTTP API and may distract an MCP agent, though the status lifecycle fragment is useful.

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 rich annotations, full schema coverage, and an output schema, the definition does not need to explain return values. However, it does not route the agent to this tool over brij_get_intent or explain when a train order status check is appropriate, leaving a notable workflow 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 both parameters are already documented in the input schema. The description maps intent_id to the body and customer_support_code to a header, but adds no format, validation, or source details beyond what the schema provides.

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 clearly states the tool retrieves rail booking status and reference, which is specific enough to distinguish it from flight/product order tools by resource. It does not explicitly name sibling alternatives, but 'Rail booking status and reference' is a clear purpose statement.

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 description gives the status lifecycle but no explicit guidance on when to use this tool versus alternatives such as brij_get_intent or the flight/product order equivalents. It also does not state prerequisites like needing an intent_id from brij_create_train_intent beyond what the schema already says.

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/open-world, so the bar is lower and the description adds real value on top: no auth required, MCP calls are rate-limited rather than x402-priced, and the api tier refreshes at most daily. The tier-coverage semantics (observed vs. true span) are disclosed as a caveat. It doesn't quantify the rate limit, 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?

Useful but verbose: 'Free over MCP (…free). Free, no auth.' repeats the free/no-auth point, and the x402 pricing parenthetical reads as vendor boilerplate before the actual purpose. The core catalog semantics are buried in the middle sentence rather than front-loaded.

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 needn't be explained, and indeed they aren't. Crucially, the description supplies the semantic meaning of the 'source'/tier values in the response — knowledge the schema alone could not convey — which is exactly the right thing to include. What's missing is any sense of response shape/size, though that is partially covered by 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify, and it correctly avoids inventing one.

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: lists supported airlines as an aggregate carrier catalog across fulfiller tiers. It also distinguishes its role from the search path by noting that bookability is determined by POST /air/search rather than this catalog. Sibling differentiation is implied rather than named (e.g. vs brij_search_flights), keeping it just short of 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?

The description sets clear context — use this to see which carriers are recognized, and use search results to determine actual bookability ('what is bookable for a route is what POST /air/search returns'). It clarifies the free/no-auth, read-only nature of the call. It stops short of an explicit 'use this when X, use Y when Z' routing statement.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety story is covered structurally. The description genuinely adds behavioral context the annotations cannot convey: MCP calls are free but rate-limited, quotes expire in roughly 20 minutes, refusals cost nothing, and 202/409/422 each have defined meanings. However, the x402 pricing block ($0.25 USDC, HTTP body shape) is aimed at the HTTP API rather than this MCP tool and muddies rather than clarifies the cost model the agent actually faces.

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?

The operative guidance (free, rate-limited, journey_id source, retry, next step) is front-loaded and useful. But the middle section duplicates itself, naming journey_id's origin twice (brij_search_buses and POST /rail/search), and the "Paid x402 endpoint: $0.25 USDC. Body: ..." block describes a different transport than the one this tool uses, diluting focus for an MCP caller.

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, yet the description still names the key return fields (offer_id, breakdown, total_amount ALL-IN, requires [person], expires_at) so the agent knows what it must carry forward to brij_create_bus_intent. Retry semantics, error codes, expiry window, and prerequisite are all present, leaving nothing an agent needs to call this correctly unstated.

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 earns above baseline: it explains that omitting fare defaults to the cheapest, that the 422 options_required response enumerates on-sale fares under detail.options, and that max_total_usd produces a 409 over_budget refusal. These are behavioral consequences of parameters, not restatements of the schema text.

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 ("Quote a journey's exact all-in price at merchant checkout") and distinguishes the tool from its quote/search/intent siblings by naming journey_id's source (brij_search_buses) and the next step (brij_create_bus_intent). An agent can place this tool in the flow without opening any other 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?

Provides explicit flow guidance: take journey_id from brij_search_buses, hand off to brij_create_bus_intent, and retry with identical arguments after retry_after when the result is pending. It also states the escape hatch for 422 options_required (retry with fare). It stops short of explicitly excluding the train/hotel quote variants, but the bus-specific naming makes the routing unambiguous.

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?

With annotations already declaring readOnly/idempotent/non-destructive, the description adds substantial context beyond them: MCP calls are free but rate-limited, the x402 price ($0.01 USDC) applies only to the HTTP API, refusals are free, and it enumerates the full return payload including the offer_id format 'hotel:<quote_id>'. The word 'lock' creates minor ambiguity about whether inventory is held since annotations say readOnly, but the quoting flow makes clear the actual booking happens in brij_create_hotel_intent.

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?

Core purpose and next-step routing are front-loaded, but the description is bloated by a long run-on sentence enumerating guest data to collect (guest ID names, email, phone with country code) that this tool does not accept as parameters and belongs to the intent step. The x402 pricing caveat is repeated in two places, and the second half restates return fields already implied earlier.

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 and annotations carry the structural burden and the description still thoroughly explains what the agent will receive. It is nearly complete; the only unresolved point is whether 'lock' implies a hold on inventory or expires, which matters for how the agent should frame urgency to the guest.

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; the description adds value by embedding rate_id in the call chain (rates endpoint → quote → intent) and specifying the exact string form of the derived offer_id. It does not add format or validation details beyond 'exactly as received', which 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 and resource ('Lock one hotel rate and get its exact all-in price') and disambiguates from its neighbors by naming the follow-on tool brij_create_hotel_intent and describing the returned offer_id. An agent can distinguish this from brij_get_hotel_rates and brij_create_hotel_intent without opening the 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 prescribes the next step ('Next: brij_create_hotel_intent with offer_id') and the prerequisite display step (show price, amount due at hotel, cancellation terms before creating the intent). The gap is that the upstream tool for obtaining rate_id is referenced only as the HTTP endpoint 'POST /hotels/rates' rather than the sibling tool brij_get_hotel_rates.

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?

Goes well beyond the readOnly/idempotent annotations: MCP calls are free but rate-limited (the $0.25 USDC x402 charge applies only to the HTTP API), a cold quote takes 30-60s, nothing is charged on 202, every refusal is free, and the returned offer_id is valid only ~20 minutes. That is exactly the operational context an agent needs and cannot infer from 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?

The content is dense and mostly earns its place, but it is badly front-loaded: the first paragraph is billing and retry mechanics while the actual purpose appears in paragraph two. The pending-retry instruction is also stated twice (once as 'retry_after', later as 'Retry-After (15s)'), wasting space and introducing naming inconsistency.

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, open-world, browser-scraping quote tool this is nearly complete — pricing model, latency, error taxonomy, offer lifetime and fee/FX breakdown are all covered, and an output schema exists so return shapes needn't be spelled out. The remaining gap is that 'a supported merchant' is never resolvable (404 merchant_not_supported with no way to discover the supported list), and the next step is given as an HTTP path rather than the MCP sibling.

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 genuine meaning: `options` is tied to the 422 options_required flow that enumerates in-stock values, `quantity` is bounded 1-10, and `max_total_usd` is explained via the 409 over_budget refusal. It does not add anything for `ship_to` beyond the schema, and it omits the requirement that the later buy use the same postcode (that lives only in the schema).

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 second sentence states a precise verb+resource+scope: 'Exact all-in price to buy one product on a merchant's website,' which cleanly separates it from the quote_bus/quote_train siblings and from the create_*_intent tools. The verb 'quote' and the qualifier 'all-in' also distinguish it from a bare product-page price.

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 gives concrete when-to-retry rules (202 quote_pending → wait Retry-After 15s → resend the SAME request; 422 options_required → ask the user, then retry with `options`) and maps refusal codes to conditions. It never explicitly names a sibling as the follow-up step, though — it points at the HTTP endpoint 'POST /shop/intents' rather than brij_create_product_intent, which is a weaker hand-off for an agent operating purely over MCP.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses cost model (free over MCP, rate-limited instead), retry semantics that match idempotentHint, quote expiry (~20 min), that refused quotes are free, and the concrete failure modes 422 options_required, 409 over_budget and 202 quote_pending. This is the kind of operational context an agent could not infer from 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?

The content is dense and useful, but the front-loading is wrong: the first two sentences are pricing and retry boilerplate, and the actual purpose appears third. Packing server routes, dollar amounts and three error codes into flowing prose makes it harder to scan than a short structured list would be.

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 three-parameter, read-only quoting tool with an output schema, this covers nearly everything an agent needs: input provenance, output handoff to the intent step, retry and error paths. It slightly over-explains the return payload (offer_id, breakdown, total_amount) that the output schema already defines, and the MCP-vs-HTTP pricing sentence risks confusing rather than informing.

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 baseline is 3. The description adds only marginal meaning over the schema, since the fare examples ('Standard', 'Flexible'), the 'default: cheapest' behavior, and the max_total_usd / 409 over_budget relationship are all already present in the parameter descriptions.

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 second sentence states a specific verb and resource: 'Quote a journey's exact all-in price at merchant checkout', and the surrounding flow (journey_id from POST /rail/search, offer_id to POST /rail/intents) makes clear it is the rail-pricing step. Sibling differentiation comes largely from the title ('train journey') rather than the body text, which spends its first sentence on pricing and retry meta before naming the action.

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 places the tool explicitly in a workflow chain: take journey_id from search, pass the resulting offer_id to POST /rail/intents, and it names POST /shop/quote as an equivalent alternative. Retry conditions are spelled out for each status (pending/retry_after, 202 quote_pending, 422 options_required with fare). What is missing is an explicit statement of when NOT to use it (e.g. that it does not reserve or book).

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so safety is largely covered. The description adds genuinely useful behavior beyond that: MCP calls are free but rate-limited, and refunds undergo manual review rather than being immediate. It stops short of describing turnaround or outcome semantics, which would justify 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?

The first sentence front-loads pricing that is explicitly irrelevant to MCP callers ('the x402 price quoted below applies to the HTTP API only'), which is wasted space for an agent using the MCP tool. Two of the three sentences are spent on billing/API-parity detail rather than the refund action.

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 and 100% param coverage, the description does not need to describe return values. It supplies the key missing behavioral context (manual review, rate limits, auth-code header mapping), leaving mainly the 'rail' mislabel and lack of turnaround expectations as gaps.

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 are already documented in the schema, including the case-insensitive family-name comparison and the optional contact field. The description only maps two parameters to their HTTP header equivalents (X-Customer-Support-Code, X-Passenger-Family-Name), which adds marginal value over the schema 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 ('Ask for a refund on a rail booking'), clearly distinguishing a refund-request operation from the sibling purchase/quote/intent tools and from the flight/train/product refund variants. However, it mislabels a bus refund as a 'rail booking', which is a factual slip that slightly undermines precision even though the tool name is unambiguous.

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?

No guidance on when to use this versus brij_request_train_refund or brij_request_flight_refund, nor on prerequisites (e.g., that intent_id and customer_support_code must first come from an intent-creation call). The 'manual review' note implies a workflow but does not state any selection criteria.

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?

Goes well beyond the annotations, which only declare readOnly=false, destructive=false, idempotent=false and openWorld=true. The description discloses payment/auth mechanics (PAYMENT-SIGNATURE header, 402 without payment, rate limiting on MCP), the persisted-and-paged-operator side effect, the 202 Accepted response, an explicit warning that it is NOT a guarantee of refund, and the 409 behavior for active-state intents. That is exactly the operational context annotations cannot carry.

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 free-MCP/paid-HTTP distinction and then proceeds in short, purposeful paragraphs; the refund-eligibility caveat and 409 rule are given their own lines. Slightly weakened by the initial pricing paragraph creating mild internal tension with the later 'Paid x402 endpoint' sentence, costing a point but not readability.

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 needn't be spelled out, yet the description still explains the 202/402/409 responses and the manual-operator follow-up. Combined with prerequisites, auth headers and the multi-passenger rule, 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, but the description adds real meaning: it identifies customer_support_code as travelling in the X-Customer-Support-Code header and tied to intent creation, and clarifies that passenger_family_name is the LEAD passenger's family name at position 0 of the /air/book list for multi-passenger bookings. That resolves an ambiguity the schema alone does not.

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 ('Request a manual refund after the intent has been booked') and immediately scopes it as manual post-capture processing, which separates it from the automatic refund path and from the train/product refund siblings. An agent can identify the operation without opening the 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?

Explicit preconditions ('after the intent has been booked') and an explicit when-not with the alternative ('For pre-capture states (active), the booking_sync worker handles refunds automatically; this endpoint returns 409 use_automatic_refund'). It also names the required X-Customer-Support-Code header precondition. 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 already declare non-read-only, open-world, non-idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond them: MCP calls are rate-limited rather than charged, the operation goes through manual review, and it is behaviorally identical to POST /air/refund-requests with specific auth headers.

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?

The core instruction is front-loaded, but the pricing/rate-limit aside and the HTTP-endpoint equivalence consume several sentences that are only loosely relevant to invoking the MCP tool, diluting the description's focus.

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. Given a 5-param mutation with full schema coverage, the description covers cost model, review process, auth prerequisites, and usage trigger, leaving little an agent would need beyond what is present.

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 all five parameters, including the case-insensitive surname comparison. The description only adds that customer_support_code and passenger_family_name correspond to HTTP headers, which is marginal value over the schema.

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: 'Ask for a refund on a purchase (manual review).' The 'product' framing in the name/title implicitly separates it from brij_request_flight_refund and brij_request_train_refund, but the description never explicitly names those siblings for contrast, so it stays at 4.

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 it for a parcel that never arrived after its delivery estimate' gives one concrete trigger condition and notes manual review, but there is no explicit when-not guidance and no routing to alternatives such as brij_request_flight_refund for non-parcel cases.

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?

With annotations declaring readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, the description adds genuinely new context: the request goes through manual review, MCP calls are rate-limited rather than priced, and specific auth headers are required. It does not, however, say whether a refund request can be withdrawn or how long review takes.

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?

The description opens with pricing/billing framing ('Free over MCP... x402 price quoted below') rather than the action, so the front-loaded content is the least decision-relevant part. The body is short and the endpoint equivalence line is compact, so waste is limited but structure is suboptimal.

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 covers the key behavioral facts an agent needs (manual review, rate limiting, auth headers). It is slightly incomplete on what the request lifecycle looks like after submission, but overall adequate for a 4-required-parameter mutation.

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 are already documented in the schema. The description only restates the support-code and family-name inputs in HTTP-header form, adding no new meaning about formats, constraints, or relationships.

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 sentence 'Ask for a refund on a rail booking (manual review)' gives a specific verb, resource, and processing mode, and the rail qualifier cleanly separates it from brij_request_flight_refund and brij_request_product_refund in the sibling list. An agent can identify the tool's job without opening the 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?

There is no statement of when to use this tool versus its flight/product refund siblings, nor any prerequisite guidance (e.g. that an intent must first exist). The reference to the equivalent HTTP endpoint and required headers is endpoint trivia, not selection guidance.

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 (readOnly/idempotent/openWorld/non-destructive) are consistent, and the description adds real context beyond them: MCP calls are free but rate-limited, the x402 price applies to the HTTP API only, a repeated search_pending retry costs nothing, and refusals are free. It does not clarify why 'rail merchant' language appears in a bus tool, but behavioral disclosure is otherwise strong.

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?

The text is long and poorly front-loaded, opening with pricing/rate-limit caveats rather than what the tool does. It carries HTTP-API-specific details (POST /rail/quote, x402 pricing) and a duplicated 'Search trains, or long-distance buses with mode=bus' line that reads like leftover content from another tool and does not belong here.

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 and full annotation coverage, the description goes beyond requirements by describing the journeys[] shape, price_from vs total_from semantics, and the 202 pending flow. It is broadly complete, though the phantom 'mode' parameter and the train-boundary ambiguity leave small gaps.

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 schema already documents all five parameters; the description largely repeats them (origin/destination as station or city names, depart_date format, adults 1-9). It also references an optional 'mode' parameter that does not exist in the input schema, which adds confusion rather than meaning. 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?

The opening line clearly scopes it to long-distance buses (Flixbus) and distinguishes from brij_search_trains, which is good. But a later fragment — 'Search trains, or long-distance buses with mode=bus' — and repeated 'rail merchant' language muddy whether this tool also searches trains, leaving the tool's boundary ambiguous. The core purpose is legible but not cleanly stated.

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 alternative (brij_search_trains), gives the follow-up step (brij_quote_bus with the journey_id), and explains the retry path for a search_pending answer ('call again with the same arguments after retry_after'). There is no explicit when-not-to-use beyond the sibling mention, keeping it 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 cover safety (readOnly, idempotent, non-destructive, open-world), yet the description adds substantial behavioral context beyond them: the MCP-is-free-vs-x402-HTTP pricing model, load-multiplied price dynamics and stale-challenge warnings, progressive 'enriching' status with polling cadence, null/empty meaning 'undisclosed' rather than zero, and the ~300 KB payload warning. These are genuine operational traits not derivable from 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?

The definition is extremely long and not front-loaded: the actual purpose appears after payment mechanics, and x402/sponsorship pricing is restated across multiple paragraphs that are largely irrelevant to the MCP caller ('Free over MCP'). Much of the response-shape discussion is redundant with the existing output schema, so many sentences do not earn their place.

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 13-parameter, high-complexity tool with an output schema present, the description is more than sufficiently complete — it covers progressive enrichment, grouping semantics, truncation pitfalls, and data boundaries. If anything it over-delivers on return-content detail that the output schema already carries, rather than leaving gaps.

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 baseline is 3; the schema already documents sort, limit, max_stops, cabin_class, etc. The description nonetheless adds real semantic value beyond the schema — the filter-before-sort/group/limit ordering, the 'fastest directs' combination, and the rationale for the cheapest_per_itinerary anti-pattern — which lifts it above 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?

The definition states a specific verb+resource ('Search live flight offers') and differentiates from siblings by routing to brij_get_flight_search_updates for enriching results and POST /air/offer-details for single-offer drill-down. However, the purpose statement is buried mid-paragraph behind several sentences of x402 pricing and rate-limit text, so an agent must read well past the opening to learn what the tool does.

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 alternatives and the conditions that select them: poll brij_get_flight_search_updates while status=enriching, use offer-details for ancillaries/seat maps/fare rules, and use cheapest_per_itinerary=true when answering refundable/bag/cabin questions. There is no explicit 'do not use when' clause, but the routing guidance is concrete and actionable.

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?

Beyond the annotations, the description discloses that MCP calls are free but rate-limited (the $0.10 x402 price applies only to the HTTP API), that refusals are free, and that a 5 USDC + 2% (capped at 30) conversion markup is folded into total_from. That is meaningful pricing and limits context the annotations do not carry. It omits pagination/result-cap behavior in prose (the 50-hotel cap appears only in the schema).

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?

The core purpose sentence is buried third, behind a pricing caveat and a forward reference to the next tool. A chunk of the text describes the paid HTTP API body format, which is only partly relevant to an MCP caller. The content is useful overall but not front-loaded or 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?

For a 14-parameter search tool with annotations and an output schema, the description covers addressing modes, date constraints, pricing semantics, and the natural next step. It explains return semantics (hotels[], price_from vs total_from vs due_at_hotel_from) even though an output schema exists. Minor gap: the 50-hotel result cap is not surfaced in the description.

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 all 14 parameters well. The description's parameter prose (rooms 1-4, adults 1-8, child_ages, free_cancellation_only, stars, sort, 30-night max) largely restates the schema rather than adding new meaning. 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?

"Search hotels for dates and a party in one city" gives a specific verb, resource, and scope, and the description names the follow-up tool (brij_get_hotel_rates with a hotel_id). It is distinguishable from brij_find_hotel_places by referencing city_id/accommodation_id as inputs, though the boundary between the two is implied rather than stated.

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?

Clear routing context: resolve places first via GET /hotels/places, then call this tool, then pass hotel_id to brij_get_hotel_rates. It also lays out alternative addressing modes (city_id, accommodation_id, location name, or lat/long + radius). It does not explicitly say when NOT to use this versus brij_find_hotel_places, 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description layers on genuinely new behavior: pricing ($0.25 USDC on HTTP), that MCP calls are rate-limited rather than charged, that a 202 search_pending costs nothing and a repeat is free, and that refusals are free. This is exactly the kind of operational context annotations cannot carry.

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?

The cost/retry information is front-loaded well, but the bus scope is stated twice in conflicting ways ('Trains only — long-distance buses are brij_search_buses' vs 'or long-distance buses with mode=bus'), and the pricing/margin parenthetical is dense. Every sentence is informative, but the internal tension costs it.

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 search tool with an output schema already defined, the description still supplies the operational envelope an agent needs: cost, free-vs-rate-limited path, pending/retry semantics, and how to carry journey_id forward. Nothing required 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 baseline is 3, and the description adds real meaning beyond it: price_from is merchant currency while total_from is all-in USDC (ECB conversion + margin + 4 USDC + 3%), and journey_id must be echoed exactly to POST /rail/quote. It loses a point for referencing a mode=bus parameter that does not exist in the input schema, which could mislead the agent.

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 ('Search trains') and explicitly distinguishes from the sibling it could be confused with: 'long-distance buses are brij_search_buses.' An agent can route correctly without opening either schema. The one blemish is the later 'or long-distance buses with mode=bus', which muddies the clean scope statement, but the primary purpose is unambiguous.

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 alternative (brij_search_buses) and the condition that selects it, plus a concrete retry protocol for the search_pending case ('call again with the same arguments after retry_after'). It also states the cost model (free over MCP, rate-limited) so the agent knows when to prefer this over the paid HTTP path.

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