BRIJ lets your assistant search and book real travel, starting with flights, paid in USDC on Solana. Fares are held in escrow and refunded automatically if a booking fails.
Scored across 11 tools
The generic x402 tools and travel-specific tools form mostly distinct pipelines, with descriptions clearly sequencing discover/prepare/execute versus search/intent/book/poll. Minor potential overlap remains because call_paid_api_endpoint could theoretically invoke a travel endpoint, but the specialized travel tools have distinct escrow and booking semantics.
Snake_case is used throughout, and the travel tools share a clear travel_ prefix with mostly verb_noun suffixes. Minor deviation: travel_offer_details is noun-style rather than verb_noun, and the generic tools omit the domain prefix, so naming is not perfectly uniform.
11 tools is well within the productive range for a server combining generic x402 payment flow and a flight-booking lifecycle. Each tool maps to a discrete step, with no obvious redundancy.
The travel surface covers search, offer inspection, intent creation, booking, status polling, order retrieval, and refund, forming a near-complete lifecycle. Gaps are minor and largely out of scope: no change/cancel-flight operation, no ancillary purchase, and no generic payment receipt history tool.
Pay for and call any full x402 API endpoint URL with the user's BRIJ wallet. This is the generic execution tool: no provider-specific connector is required.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body for the target API. You may pass a JSON object directly; BRIJ will serialize it. | |
| method | No | HTTP method for the target request. Defaults to GET. | |
| headers | No | HTTP headers for the target request. For JSON APIs, include content-type: application/json and accept: application/json. | |
| target_url | Yes | Full paid x402 endpoint URL to call, for example https://travel.brij.fi/air/search. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the critical trait that real funds move via the user's BRIJ wallet, but says nothing about payment authorization, spend limits, cost confirmation, idempotency, or what happens on a failed/declined payment - all essential for a tool that spends 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?
Two short sentences with zero filler; the core action and the generic-vs-connector distinction are both 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 need not be explained, but for a payment-executing tool with no annotations the description should say more about the payment flow and its position between prepare_paid_api_call and the result. It is minimally adequate but leaves meaningful gaps around cost and failure behavior.
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 target_url, method, headers, and body are already documented with format guidance and an example. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair ('pay for and call') and resource ('any full x402 API endpoint URL'), and explicitly positions itself as the generic execution path that requires no provider-specific connector, which separates it from the travel_* siblings. It does not name the closely related siblings (find_paid_api, prepare_paid_api_call), so the differentiation from those is left implicit.
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 phrase 'This is the generic execution tool: no provider-specific connector is required' implies when this tool is appropriate, but it never states the relationship to find_paid_api (discovery) or prepare_paid_api_call (preparation) or when those should be used instead. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the connected BRIJ wallet address and USDC balance before or after paid API calls.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full disclosure burden. 'Show' implies a non-mutating read and 'connected BRIJ wallet' hints that a wallet must already be connected, but the description never explicitly states read-only behavior, whether auth/connection is required, or what happens when no wallet is connected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action, the returned data, and the timing context with no filler. Nothing wastes the agent's attention.
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 no explanation, and with zero parameters there is no input contract to clarify. The description supplies all the remaining context (what is shown, in what denomination, and when to call it) needed to invoke 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The schema (additionalProperties: false, empty object) is trivially complete.
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?
Names a specific verb (Show) and precise resources (connected BRIJ wallet address and USDC balance), so the agent knows exactly what comes back. It is clearly distinguishable from the sibling payment-flow tools (prepare_paid_api_call, call_paid_api_endpoint) because it is a pure inspection call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before or after paid API calls' gives clear situational context for when to reach for this tool relative to the paid-call siblings. It stops short of explicit exclusions or naming an alternative, so it is strong context but not a full when/when-not rule set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the best paid API provider for a user intent. Returns a small domain-based menu. Next call prepare_paid_api_call with provider_domain and intent.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes | Natural language description of what the user wants to do, for example search flights from Madrid to Barcelona. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden alone. It does disclose the return shape ('a small domain-based menu') and the key downstream input (provider_domain), which is genuinely useful, but says nothing about cost, authentication, rate limits, or whether the underlying paid APIs are actually invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose and followed immediately by the return shape and the next call. No filler; the only slight weakness is that the final sentence compresses two facts (next tool plus its required arguments) into one line.
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 single-parameter discovery tool with an output schema, the essentials are covered: what it finds, what it returns, and how to continue. It stops short of noting the wallet/cost implication that the sibling check_wallet_balance hints at, which would help an agent plan the paid flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is only one parameter, so the baseline is 3. The description's phrase 'for a user intent' reinforces the schema's natural-language intent semantics but adds no format, length, or example guidance beyond what the schema already gives.
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 ('Find the best paid API provider for a user intent') and names the follow-up tool, which distinguishes it from call_paid_api_endpoint and prepare_paid_api_call. It does not explain how it relates to the domain-specific travel_* siblings, so differentiation is partial rather than complete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use: it is the discovery step whose output feeds prepare_paid_api_call with provider_domain and intent, so the agent knows what to do before and after. No explicit when-not conditions or alternative discovery paths are stated, which keeps 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.
Prepare the exact paid API call recipe for one provider domain and intent. Returns target_url, method, required fields, examples, and next intent. Then call call_paid_api_endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes | Supported intent returned by find_paid_api, for example search_flights. | |
| provider_domain | Yes | Provider domain returned by find_paid_api, for example travel.brij.fi. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. Calling it a 'recipe' preparation step and deferring the actual execution to call_paid_api_endpoint usefully implies this tool has no side effect, but it never states whether preparation costs anything, requires wallet balance, or how long the recipe stays valid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core purpose, then the return shape, then the follow-up call. No filler or redundant phrasing.
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 enumerating the returned fields is a harmless bonus rather than a necessity. The workflow chain is complete, and the only gap is unstated preconditions such as whether a funded wallet is needed before preparing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters are already documented with examples ('search_flights', 'travel.brij.fi'). The description adds only the framing that there is exactly one provider domain and one intent per call, which the schema largely conveys, so 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 description states a specific verb and resource ('Prepare the exact paid API call recipe') and scopes it to 'one provider domain and intent', so the agent knows exactly what is produced. It positions itself in the workflow by naming the endpoint call that follows, though it never explicitly contrasts itself with find_paid_api, which is only implied through the parameter descriptions.
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?
'Then call call_paid_api_endpoint' gives an explicit next-step instruction, and the inputs are anchored to values produced by find_paid_api, forming a clear chain of usage. There is no explicit when-not-to-use guidance or statement of prerequisites (e.g., wallet balance), so it stops short of full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pay the escrow and request booking with passenger details. Booking is ASYNCHRONOUS: a successful response means the request was accepted, not that the ticket is issued. After this call, poll travel_get_booking_intent until intent.status is 'booked' (ticketed) or 'refunded' (booking failed and escrow was auto-refunded). Pass passengers as an array with LEAD FIRST — the lead receives all emails and refund requests authenticate against the lead's family name. The count MUST equal the offer's passenger_count (= adults searched); duplicate travellers (same name + birth date) are refused with 400 duplicate_passenger. Round-trip offers cover both directions with a single /air/book and a single escrow. The airline rejects malformed passenger fields (title not lowercase, gender not m/f, phone not E.164, …) with a 400; fix the field per the response and retry. Three 409 codes are checked BEFORE x402 settlement (refusal is free, no USDC spent): intent_expired (booking window closed — start a fresh travel_search_flights → travel_create_booking_intent flow), offer_expired (the offer left the airline's inventory — same fix, re-search), offer_repriced (live airline price no longer matches the intent; detail carries expected_ticket_amount and current_ticket_amount — quote the delta to the user and, if they accept, re-run travel_create_booking_intent so the escrow is sized to the new price). If a prior /book succeeded for this intent, retrying returns 409 booking_already_requested — do not retry; poll travel_get_booking_intent instead.
| Name | Required | Description | Default |
|---|---|---|---|
| intent_id | Yes | Booking intent ID returned by travel_create_booking_intent. | |
| passengers | Yes | Passenger list, 1 to 9 entries, LEAD PASSENGER FIRST. Must contain EXACTLY as many entries as the offer's passenger_count (= adults searched); a mismatch is rejected. The lead passenger (index 0) receives all booking emails, and refund requests authenticate against the LEAD's family name. Duplicate travellers (same given_name + family_name + born_on) are refused with 400 duplicate_passenger. All refunds are all-or-nothing per booking; there is no per-passenger cancellation. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. Discloses asynchronous nature, escrow payment, free refusal before x402 settlement, auto-refund on failure, duplicate passenger rejection, malformed field 400s, and the three pre-settlement 409 codes. Rich behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and async behavior, then groups passenger requirements and error codes. Length is justified by the tool's complexity, though the passenger paragraph largely restates schema content, preventing a top score.
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 no annotations but an output schema, the description supplies the missing behavioral context: async resolution, polling sibling, escrow semantics, and full error taxonomy. Complete enough 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% and already documents intent_id and all passenger constraints (lead first, count, duplicates, all-or-nothing refunds). The description repeats these passenger semantics without adding new parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action: pay escrow and request booking with passenger details. Distinguishes from sibling travel_create_booking_intent by indicating this is the booking request step and names travel_get_booking_intent for polling. Very clear.
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 detailed when/when-not guidance: after intent creation, poll travel_get_booking_intent after this call, and explicit remediation for 409 codes (re-search, re-create intent, do not retry already-requested). Names alternatives travel_search_flights and travel_create_booking_intent for expired intents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reserve an escrow booking intent for a flight offer. Costs 0.10 USDC, paid automatically via the user's BRIJ wallet. Call this AFTER travel_search_flights and the user has picked an offer. Returns intent_id and customer_support_code to pass into travel_book_flight. Returns 409 identity_documents_not_supported if the chosen offer required passenger identity documents (travel_search_flights already filters these out — this only fires when an offer_id is passed from outside the search flow).
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | Offer ID returned by travel_search_flights (the opaque id field on each search result). Pass exactly the value the API returned. | |
| refund_wallet | No | Optional Solana wallet that receives a refund if the booking fails. Defaults to funding_wallet. | |
| funding_wallet | No | Solana wallet that will fund the booking escrow. Defaults to the user's BRIJ wallet if omitted — that's almost always what you want. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations the description carries the full burden, and it delivers: cost (0.10 USDC), automatic payment via the BRIJ wallet, and a specific error contract (409 identity_documents_not_supported with the condition that triggers it). It omits idempotency/duplicate-intent behavior and any expiry on the intent, which is material for a paid escrow mutation.
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 action, cost, and sequencing. The final 409 sentence is long but earns its place by explaining the edge case that only fires outside the normal search flow.
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?
Complete for the task: sequencing, cost, payment source, downstream handoff, and the failure mode are all covered, and an output schema already documents the return values so the description need not expand on them.
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%, including wallet defaults, so the baseline is 3. The description adds no syntax or format detail for offer_id or the wallet params beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb + resource ('Reserve an escrow booking intent for a flight offer') and distinguishes itself from travel_search_flights and travel_book_flight by naming both siblings and its position between them.
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 states when to call ('AFTER travel_search_flights and the user has picked an offer') and what to do with the result (pass into travel_book_flight). It does not name a true alternative tool or an explicit when-not-to-use case, so it falls just 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.
Fetch the current state of a booking intent. Free (no x402 payment). Use this to poll status after travel_book_flight: 'active' means the booking worker has not yet ticketed (keep polling); 'booked' means the airline has issued the ticket and airline_order_id is populated (call travel_get_order for airline details); 'refunded' means booking failed and the escrow was returned to refund_wallet — refund_reason explains why. This endpoint does NOT return customer_support_code or passenger PII; both are only returned once, at intent creation and /book time.
| Name | Required | Description | Default |
|---|---|---|---|
| intent_id | Yes | Booking intent ID returned by travel_create_booking_intent. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the call is free (no x402 payment) and spells out the three status values and their operational meaning. It also makes a useful negative disclosure (no customer_support_code or passenger PII; those are only returned at creation and /book). It stops short of stating auth/permission needs or error behavior for an invalid intent_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose, then the cost note, then state semantics, then the negative disclosure. Every clause earns its place — the state glossary directly drives agent polling behavior and the 'free' note matters given the paid-endpoint siblings.
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 fields needn't be enumerated, yet the description still explains the meaningful state values and what is deliberately absent from the response. The only gap is that it says nothing about failure modes for an unknown or expired 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?
Only one parameter and schema description coverage is 100%, so the schema already defines intent_id and its origin (returned by travel_create_booking_intent). The description adds no syntax, format, or lifecycle detail about the parameter beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch the current state of a booking intent') and immediately differentiates it from siblings by naming travel_book_flight, travel_get_order, and the creation endpoint. An agent can tell this is a read-only status poll rather than the create/book/order tools 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?
Explicitly says when to use it ('poll status after travel_book_flight') and routes onward: call travel_get_order for airline details once 'booked'. It also encodes the decision logic per state ('keep polling', 'booking failed'), which is exactly the when/when-not guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the airline order (PNR, booking reference, ticket total) for a booked intent. Free (no x402 payment) but requires the customer_support_code from travel_create_booking_intent. Call this after travel_get_booking_intent shows status='booked' and airline_order_id is populated.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Airline order ID (for example ord_0000000000000000000000). Available on the intent as airline_order_id once the booking worker has synced with the airline. | |
| support_code | Yes | customer_support_code returned by travel_create_booking_intent. Required to authorize reading the airline order. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose two key traits: it is free (no x402 payment) and it requires authorization via the customer_support_code. It does not discuss failure modes (e.g. what happens if the order is not yet synced) or rate limits, so it falls short of fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with zero filler: the first delivers purpose plus cost and auth, the second delivers the ordering precondition. Front-loaded and every clause 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?
For a 2-param read tool with full schema coverage and an output schema, the description covers purpose, cost, auth source, and the sequencing precondition. Nothing an agent needs to call 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% and both schema descriptions already state the provenance of order_id (from airline_order_id) and support_code (returned by travel_create_booking_intent). The description's mention of support_code adds no meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (airline order), and enumerates what the caller gets back (PNR, booking reference, ticket total). It is clearly distinguishable from sibling reads like travel_get_booking_intent because it names the airline-order artifact rather than the intent.
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 gives the precondition: call after travel_get_booking_intent shows status='booked' and airline_order_id is populated. It also distinguishes the sibling it follows (travel_create_booking_intent supplies the support_code) and notes the cost model is free/no x402 payment, so no alternative paid path is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drill into ONE flight offer: re-fetches it live from the flight provider and returns it with CURRENT price + expires_at, plus available_services — the purchasable ancillaries (checked bags with weight limits and per-unit prices) on that exact fare. Costs 0.01 USDC. Use when (a) the user asks how much an extra checked bag costs on a specific offer — the one ancillary question travel_search_flights cannot answer — or (b) the search is a few minutes old and you want to revalidate the price before creating a booking intent (cheaper and quota-friendlier than re-searching). Services are INFORMATIONAL: this API cannot add them to the order — use their prices only to reason about which fare to pick. A stale or unknown offer_id returns 404 and the payment is never settled (refusals cost nothing); offers expire roughly 20–30 minutes after search, so on 404 fall back to travel_search_flights.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | Offer ID from travel_search_flights (the opaque id field on each search result). Pass exactly the value the API returned. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so admirably: it discloses the 0.01 USDC cost, that stale/unknown ids return 404, that payment is never settled on refusal, that offers expire in 20–30 minutes, and that services are informational and cannot be added to an order. This is unusually complete behavioral context.
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?
Dense but front-loaded, leading with the core action and price mechanism before the usage scenarios. It is longer than typical, yet nearly every sentence conveys actionable information (cost, 404 behavior, expiry, informational constraint), so little 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 so return values need not be re-explained, yet the description still names the key fields (current price, expires_at, available_services) and covers the failure mode and cost. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single offer_id parameter is fully documented in the schema itself, which already explains it is the opaque id from search results. The description adds no format or syntax detail beyond that, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Drill into ONE flight offer: re-fetches it live...') and explicitly distinguishes itself from travel_search_flights by noting it answers the ancillary question the search tool cannot. An agent can tell exactly what it does and does not do.
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 two explicit conditions for use — (a) ancillary cost questions and (b) revalidating a few-minutes-old price before a booking intent — plus a named alternative for the fallback case ('on 404 fall back to travel_search_flights').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File a manual refund request for a booked intent (status=booked, escrow already captured). Costs 0.10 USDC. This is NOT an instant refund — it opens a ticket that a human operator reviews; eligibility and any airline penalty are decided off-band. For active intents (status=active, escrow not yet captured), do not call this: the booking worker refunds those automatically to the refund_wallet. Requires the support_code from travel_create_booking_intent and the passenger family_name sent to travel_book_flight.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | Free-text explanation of why the refund is requested. Max 1000 characters. Refunds are all-or-nothing per booking; per-passenger cancellations are not supported. | |
| contact | No | Optional reply-to (email or phone) the operator can use to follow up. Max 320 characters. | |
| intent_id | Yes | Booking intent ID whose refund is requested. | |
| family_name | Yes | Family (last) name of the LEAD passenger (the first entry sent to travel_book_flight — index 0). For multi-passenger bookings this is NOT any traveller's family name, only the lead's. Compared case-insensitively. | |
| support_code | Yes | customer_support_code returned by travel_create_booking_intent (for example BRIJ-K7MQ-T9RV). The API rejects the request with 403 if it does not match this intent. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does: it discloses the 0.10 USDC cost, that the result is a ticket rather than an instant refund, that a human operator decides eligibility and airline penalties off-band, and that refunds are all-or-nothing. That is exactly the kind of non-obvious behavioral context an agent needs before spending 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?
Four sentences, front-loaded with the core action and cost, then the critical caveat, then the exclusion, then the inputs. No sentence is redundant and none repeats the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need no explanation, and annotations are absent but the description compensates with cost, latency/process semantics, prerequisites, and failure context. Nothing an agent needs to decide whether and how to call this is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool provenance the schema cannot: support_code must come from travel_create_booking_intent and family_name must be the lead passenger's from travel_book_flight. It adds meaning for two of five parameters without restating types or limits.
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 (file a manual refund request) and narrows it to booked intents with escrow already captured. It distinguishes itself from the automatic path taken for active intents, so an agent can separate this tool from travel_get_booking_intent and the booking worker's behavior 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?
Explicit when-to-use (status=booked, escrow captured), explicit when-NOT (active intents are refunded automatically to refund_wallet, do not call this), and names the sibling tools that supply the required credentials. Prerequisites are spelled out via the support_code and family_name provenance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search live flight offers on travel.brij.fi (BRIJ Flight API). Free for users on BRIJ Wallet (sponsored preview, no USDC charged, up to 20 searches per account per 24h). ALWAYS call with cheapest_per_itinerary=true and a reasonable limit (10–20) unless you have a very specific reason not to: the ungrouped view is a flat price-sorted list of fare instances and a small limit on it silently discards every pricier fare variant on every flight (Comfort/Flex/refundable/business/premium-economy are ALL more expensive than Basic, so with limit=30 ungrouped you get 30 Basic/Lite offers and mistakenly conclude "no refundable exists"). The grouped view is lossless per flight: each returned offer's fare_options array carries EVERY fare variant of that physical itinerary (offer_id, brand, price, refundable, changeable, checked_bags_included), cheapest first — this is the correct source for "is there a refundable option?", "cheapest with a checked bag?", "business class?". Filters (max_stops, max_price, departure_after/before) apply BEFORE sort and limit, so "limit=5 + sort=duration + max_stops=0" means "the 5 fastest directs". Supports 1 to 9 adults and an optional cabin_class filter; pass return_date for a round trip (both directions priced together, booked in ONE /air/book, escrow amount = round-trip total; max_stops=0 then requires BOTH legs direct). Every offer carries a passenger_count (must match the passengers array sent to travel_book_flight) and a slices array (one entry per direction — the journey-level departing_at/arriving_at describe the OUTBOUND only for backward compatibility; slices is canonical for round trips). Offers that require passenger identity documents (identity_documents_required=true) are filtered out — POST /air/intents refuses them; dropped_identity_documents in the response counts how many. Truly non-stop means BOTH stops=0 AND technical_stops=0. Offers sharing the same comparison_key are the same physical itinerary (joins all directions on round trips). For extra-bag prices on a specific fare or a fresh price for a minutes-old offer, call travel_offer_details (0.01 USDC). Seat maps and full legal fare-rule text are not exposed. null/empty everywhere means the airline did not disclose the value — unknown, never zero or false. Each offer has an opaque id to pass into travel_offer_details or travel_create_booking_intent next.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional ordering. Ascending only. Exactly one of: price (default), duration (fastest first), departure (earliest local outbound first), emissions (lowest CO2 first, unknown values sort last). | |
| limit | No | Optional cap on the number of offers returned (offers are always sorted cheapest first before the cap). Defaults to 25; upstream can return several hundred offers so keeping a limit is important. | |
| adults | No | Number of adult passengers, 1 to 9 (airline maximum per booking). Defaults to 1 if omitted. The offer is priced for exactly this many travellers and travel_book_flight must later supply exactly this many passengers. | |
| max_price | No | Optional decimal cap on total_amount in the offer currency, e.g. "250.00". | |
| max_stops | No | Optional. Maximum plane changes PER DIRECTION. 0 = directs only (a round trip qualifies only if BOTH legs are direct). Technical stops without a plane change do not count. Omit for any. | |
| cabin_class | No | Optional cabin filter. Must be exactly one of: economy, premium_economy, business, first. Defaults to economy when omitted. | |
| depart_date | Yes | Outbound departure date in ISO 8601 format (YYYY-MM-DD), for example 2026-12-15. | |
| origin_iata | Yes | Departure airport or city. Accepts a 3-letter IATA airport code (CDG, ORY, JFK, ...) OR a 3-letter IATA metropolitan city code (PAR, LON, NYC, TYO, CHI, WAS, ROM, MIL, SAO, BUE, STO, MOW, IST, ...). Pass the city code when the user names the city; pass the airport code only when they specify an airport. | |
| return_date | No | Optional return date in ISO 8601 format (YYYY-MM-DD). When set, the search returns round-trip offers priced for BOTH directions and booked in one /air/book call — the escrow amount is the round-trip total. Omit for one-way. | |
| departure_after | No | Optional. Outbound departs at or after this time, LOCAL to the departure airport, HH:MM. Example: "12:00". | |
| departure_before | No | Optional. Outbound departs at or before this time, LOCAL to the departure airport, HH:MM. Combine with departure_after for a window (e.g. afternoon = departure_after 12:00, departure_before 18:00). | |
| destination_iata | Yes | Arrival airport or city. Accepts a 3-letter IATA airport code OR a metropolitan city code, same rule as origin_iata. | |
| cheapest_per_itinerary | No | Strongly recommended to set true. When true, the response groups by physical itinerary and each returned offer carries fare_options — the FULL list of fare variants for that flight (offer_id, brand, price, refundable, changeable, checked_bags_included). That is the correct way to answer "are there refundable / premium / with-checked-bag fares on this flight?" — do NOT set false to get variants, it does the opposite. When false (default upstream), the response is a flat list of individual fare instances sorted by price ascending; combined with a limit it returns only the N cheapest fare-instances, so the pricier variants (Comfort, Flex, refundables, business) fall off the tail. Setting it false is almost never what you want. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so: it discloses the sponsored free tier with a 20 searches/account/24h cap, that filters apply BEFORE sort and limit, that identity_documents_required offers are filtered out with a dropped_identity_documents counter, that null/empty means unknown (never zero/false), and that seat maps and legal fare-rule text are not exposed. That is substantial behavioral context beyond 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?
It is front-loaded with the purpose and the key instruction (cheapest_per_itinerary=true), but it is very long and heavily overlaps with the input schema's own parameter descriptions (the cheapest_per_itinerary, max_stops, and return_date explanations are largely duplicated). Several sentences earn their place; the redundancy against structured fields does not.
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 13 parameters, an output schema, and no annotations, the description is complete enough to call the tool correctly: it covers rate limits, pricing behavior, round-trip semantics, canonical vs backward-compatible fields (slices vs journey-level times), and the identity-document filtering. Nothing an agent needs 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 3 is the baseline, but the description adds real meaning beyond the schema: it explains WHY cheapest_per_itinerary matters (grouped fare_options vs lossy flat list), that max_stops=0 on a round trip requires BOTH legs direct, and that passenger_count must match the passengers array sent to travel_book_flight. These are semantic connections the schema does not draw.
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 opens with a specific verb+resource ('Search live flight offers on travel.brij.fi (BRIJ Flight API)') and clearly differentiates from siblings by naming travel_offer_details, travel_create_booking_intent, and travel_book_flight as the downstream steps. An agent can tell what this tool does versus the other travel_* tools 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 prescriptive guidance: 'ALWAYS call with cheapest_per_itinerary=true and a reasonable limit (10-20)', with a named exception ('unless you have a very specific reason not to'). It routes the agent to travel_offer_details for extra-bag prices or refreshed pricing, stating the 0.01 USDC cost, and explains when to pass return_date. This is genuine when/when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
call_paid_api_endpointcheck_wallet_balancefind_paid_apiprepare_paid_api_calltravel_book_flighttravel_create_booking_intenttravel_get_booking_intenttravel_get_ordertravel_offer_detailstravel_request_refundtravel_search_flights
Add one secure layer between your agents and this server.