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

With no annotations, the description carries the full behavioral burden. It discloses that nothing progresses until answered, the cart expires, and passing the wrong round could seat the wrong leg on a return trip. This is strong context, though it does not mention authentication or explicit irreversibility of the action.

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 longer than average but every section earns its place: purpose, urgency, kind-specific parameter rules, and the round warning. The structure is front-loaded and the all-caps urgency line effectively highlights the critical consequence without being vague.

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 6-parameter, no-output-schema action tool, the description covers the full calling context: when to call, what values to source, which parameters apply per kind, and what could go wrong. The agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds meaning well beyond it: kind-specific rules for seat vs extra, skip/confirm combinations, the example seat shape {'d':'12A'}, and the critical requirement to pass round from awaiting_choice to avoid wrong-leg answers. These are exactly the semantics an agent needs 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 opens with a specific verb and resource: 'Answer the question a paused booking is waiting on.' It ties directly to get_flight_booking's awaiting_choice and makes clear this is the action tool that resolves a paused checkout, distinguishing it from the surrounding flight/hotel search and booking siblings.

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 clearly states when to use the tool: when get_flight_booking returns awaiting_choice and after the traveller has been asked. It even instructs the agent to present options and time left before calling. It does not name alternatives or exclusions, but no sibling tool serves this purpose, so the context is sufficient.

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 no annotations, the description carries full behavioral disclosure and does so thoroughly. It explains that nothing is charged, the setup is a 0.00 Revolut flow, a human must approve in-browser, no endpoint mints a token from card details, retired Stripe lanes now fail, and this tool does not create a billing account.

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 longer than average but every section earns its place: purpose, invocation, human-approval requirement, two connection methods, retired fields, and exclusion from billing. It is well-structured and front-loaded, though slightly verbose in the first sentence.

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?

Despite no annotations and no output schema, the description fully equips an agent to invoke the tool correctly: what it does, what it returns, what the user must do, what not to do, what is retired, and how it relates to connect_payment. Nothing essential 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 schema has zero parameters and the description explicitly instructs 'Call with no arguments,' removing any ambiguity. It also describes what the call returns, which is useful given there is no output 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 clearly states the tool's purpose: connect a card so the server can search and book, returning instructions and an add_card_url. It also differentiates from connect_payment explicitly. The opening phrase 'Explain how to connect a card' is slightly indirect about what the tool itself does, but the intent 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?

The description gives explicit when-to-use guidance: call with no arguments, require a person to approve in a browser, never ask for card numbers, and do not automate the step. It also names connect_payment as a sibling and explicitly warns not to use it for this purpose.

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 no annotations, the description carries the full burden and excels. It discloses charges ('nothing from LetsFG'), the two result variants (success with order_id, incomplete with booking_url), and warns that incomplete is a normal, non-retryable outcome. It also requires 'REAL passenger details' and explains why (names match passport, email receives e-ticket), providing safety context not inferable from 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 description is compact (~130 words) and uses labeled sections (FLOW, CHARGES, RESULT, SAFETY) to front-load critical information. Every sentence earns its place, with no filler or repetition of schema content.

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?

It covers flow, charges, result handling, and safety requirements. The result handling for incomplete bookings is exactly the kind of edge-case detail an agent needs, and the absence of an output schema is compensated by explicit example JSONs. No significant gaps remain for the agent to execute the booking safely and 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. The description adds meaningful context: 'passengers with id from search' ties params to search_flights output, and 'names must match passport' clarifies the given_name/family_name fields while 'email receives the e-ticket' explains contact_email/passenger email purpose. This elevates it above baseline, though the description does not systematically walk through each parameter.

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 clear verb+resource: 'Book a flight from a search result.' The FLOW line positions it as the final step after search_flights, distinguishing it from related tools like book_hotel and unlock_flight_offer. The purpose is unambiguous and 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?

The FLOW explicitly states the sequence authenticate -> search_flights -> book_flight, giving clear when-to-use context. The RESULT section provides a critical 'when not to' instruction: if booked:false, do not retry but pass the booking_url to the user. This is explicit behavioral guidance beyond simple prerequisites.

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 no annotations, the description carries the full burden of behavioral disclosure and delivers thoroughly: the price is authorised but not taken, captured only after supplier confirmation, released on failure, and there is no fee/deposit/pay link. It also discloses async behavior, final statuses, validation-before-hold, and duplicate retry semantics.

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 long but appropriately so for a high-stakes booking tool with 20 parameters. It is front-loaded with the core purpose and each paragraph covers a distinct operational concern: payment handling, async return, price copying, guest validation, and idempotency.

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 tool with no output schema and no annotations, the description explains the return value, polling workflow, final statuses, failure behavior, payment hold mechanics, validation errors, and retry idempotency. It even names the sibling polling tool, leaving little for the agent to infer.

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 75%, but the description adds crucial meaning beyond the schema: currency omitted means PLN, fx_rate omitted for PLN offers, expected_price must be the offer's price verbatim, and guests must include every occupant with adults first then children in child_ages order. This materially improves parameter understanding.

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 'Book one hotel rate', a specific verb and resource that clearly distinguishes it from book_flight. It also states it returns a booking_job_id rather than the booking, separating it from get_hotel_booking.

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 explicit post-call guidance: poll get_hotel_booking every ~20s until a final status, and 'Do NOT call book_hotel again for a booking whose job is running.' It also tells the agent to copy offer fields exactly and warns about currency mismatch, making when-to-use and when-not-to-retry explicit.

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 no annotations, the description carries the full burden, and it discloses refund side effects, refusal behavior with a 409 status, long execution time, and timeout semantics. This is exemplary transparency for a mutating operation.

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

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

Three sentences, each earning its place: the action, the refund/refusal policy, and the timeout caveat. The most important operational warning is front-loaded near the end but clearly separated, and there is no redundant 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?

The description fully covers what the tool does, when it succeeds, when it fails, how long it takes, and what to do on timeout. Even without an output schema or annotations, an agent has enough to call it correctly and handle the response appropriately.

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 only parameter, 'confirmation,' is fully described in the schema as 'From the completed booking.' The description adds no further parameter-level detail, but the schema coverage is 100%, so the baseline of 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 uses a specific verb and resource: 'Cancel a hotel booking made by this account and refund the guest.' It clearly distinguishes this from booking, searching, or getting bookings, and even clarifies the account-scoped nature of the operation.

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 clear context for when cancellation is free versus when it will be refused with a 409, and directs attention to the hotel's booking terms for cost information. It does not explicitly name alternatives or say 'use get_hotel_booking first,' but the guidance is strong enough for an agent to decide and handle the outcome.

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 no annotations provided, the description carries the full burden and does so thoroughly: nothing is charged, card details never touch LetsFG, a person must open the returned connect_url, the tool refuses to run without LETSFG_API_KEY, and it replaced setup_payment. This discloses important side effects and failure conditions far beyond minimal expectations.

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 dense but every sentence earns its place: an upfront routing warning, a precise functional statement, a security/behavior note, explicit anti-automation guidance, an environment prerequisite with rationale, and a deprecation note. It is front-loaded with the most important guidance and contains no filler.

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

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

For a zero-parameter tool with no output schema and no annotations, this description is fully sufficient. An agent knows what the tool does, when to use it instead of authenticate, what environment variable is required, what the returned connect_url is for, and that a human must complete the flow. Nothing needed for correct invocation is missing.

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

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

There are zero parameters, so the schema is trivially complete. The description adds useful operational context by mentioning the environment variable LETSFG_API_KEY and the returned connect_url, which helps an agent understand what is required and what to expect. Baseline 4 is appropriate for a no-parameter tool.

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: it 'Mints a one-time link for connecting a payment method to a PAID prepaid Developer API account.' It also explicitly distinguishes itself from the sibling 'authenticate' by saying 'you almost certainly want authenticate instead' and notes it replaced 'setup_payment.' This is clear and well-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?

The description gives explicit when-to-use and when-not-to-use guidance: it is Developer API only, users should prefer 'authenticate' unless they truly need to connect payment to a paid account, and agents must not collect card numbers or automate the browser step. It even explains the LETSFG_API_KEY requirement and why it exists, which is strong contextual 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?

With no annotations, the description carries the burden of disclosing behavior. It states read-only, requires an API key, and explains the PFS token limitation—unexpected behavior that is valuable. It doesn't cover rate limits or error cases, but for a simple getter this is adequate.

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

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

Two sentences, front-loaded with the primary purpose, followed by crucial usage caveats. Every sentence adds value with no 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?

For a zero-parameter, read-only endpoint with no output schema, the description provides the essential context: what it returns (profile, balance, usage stats), auth requirements, and the PFS token edge case. It lacks explicit error behavior but otherwise is 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?

There are zero parameters, and the schema covers 100% of them trivially. The description adds meaningful auth context (LETSFG_API_KEY) that is not in the schema, which is helpful for correct invocation. Baseline 4 for zero-parameter tools 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 clearly states the tool fetches agent profile, balance, and usage stats with a specific verb and resource. It also distinguishes from sibling tools by explicitly noting PFS bearer tokens have no profile, making the tool's scope 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 explicit context: it is 'Developer API only', requires LETSFG_API_KEY, and clarifies when not to use it (PFS bearer token users). It doesn't name an alternative tool, but the context is sufficient for an agent to decide when 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?

With no annotations, the description carries the full burden. It discloses that the booking takes 4-11 minutes, that money is HELD not taken until airline confirmation, the exact terminal states and their consequences, and the one-hour ref expiry. This goes beyond a simple 'poll the status' and gives the agent critical operational behavior.

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

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

Though longer than typical descriptions, every sentence carries essential information. The purpose is front-loaded, the polling interval and terminal states are clearly structured, and warnings are explicit. No filler or repetition exists; the length is proportional to the tool's operational complexity.

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

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

There is no output schema, so the description must fully explain what the tool returns and how to interpret it. It does so by defining all terminal states and their implications (PNR issued, card charged; hold released; needs attention). Combined with polling cadence and ref expiry, an agent has everything needed to invoke and interpret the result without ambiguity.

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 schema has 100% coverage for the single parameter booking_ref, already defining it as 'The booking_ref book_flight returned'. The description adds meaningful context beyond that: the ref's one-hour lifetime and its role in repeated polling until terminal state. This extra usage-centric semantics justifies a score above the baseline 3.

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 and resource: 'Poll a flight booking started by book_flight.' It clearly distinguishes this from book_flight by explaining that book_flight returns a booking_ref and state 'booking_in_progress', not a PNR, and that this tool is required to learn the final outcome. Sibling differentiation is explicit.

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 provides precise when-to-use guidance: call every 20-30 seconds with the booking_ref until a terminal state. It enumerates terminal states and their meanings, and explicitly warns against rebooking while state is moving and against treating a slow poll as failure. It also states refs last one hour, covering lifecycle constraints.

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?

The description discloses key behavioral traits beyond annotations: polling interval, final vs non-final statuses, side effects (guest is e-mailed), and safety ('Read-only and safe to repeat'). It also explains consequences for each status (hold released, nothing charged, etc.). Since no annotations are provided, the description carries the full burden and does so well, though it could mention rate limits or error handling for network issues.

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 well-structured and front-loaded: it states the purpose first, then the polling instruction, then status breakdowns, and ends with side effects and safety. Every sentence earns its place, and the use of bullet-like formatting for statuses improves scannability without being verbose.

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 the tool's complexity (multiple statuses with distinct outcomes), the description is complete. It covers all possible statuses, their meanings, finality, side effects, and safety. The absence of an output schema is compensated by the detailed status breakdown. An agent has everything needed to call and interpret this 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% for the single parameter booking_job_id, and the description adds context by stating it comes 'From book_hotel'. This clarifies the parameter's origin and format, going slightly beyond the schema's bare description. A 4 is appropriate because the description adds meaningful context, though the schema already covers the basic 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 description clearly states the tool's purpose: 'Collect the result of a booking started with book_hotel.' It uses a specific verb ('collect') and resource ('result of a booking'), and explicitly references the sibling tool book_hotel, distinguishing it from other tools like get_flight_booking. The polling instruction adds clarity about its role as a status-retrieval 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?

The description provides explicit when-to-use guidance: poll every ~20s, stop on final statuses, and do NOT book again on attention. It also differentiates from alternatives by referencing book_hotel as the source of the booking_job_id. This is comprehensive and leaves no ambiguity about when to use this tool.

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?

No annotations are provided, so the description carries full burden. It states the tool loads a guide (read behavior) but does not disclose the return format (e.g., plain text, structured JSON) or any potential side effects. For a simple loader, this is adequate but lacks some detail.

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

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

The description is extremely concise with two sentences. The key action and context are front-loaded, and every sentence adds value without 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?

For a documentation-loading tool with no parameters, output schema, or complex behavior, the description is mostly complete. It could mention that the guide is returned in the response, but the purpose and usage are well covered.

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 has zero parameters, so per guidelines the baseline score is 4. The schema coverage is trivially 100%, and the description adds no parameter information as none are needed.

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 explicitly states it loads the LetsFG workflow guide, specifying the content areas (booking flow, pricing, rules, error handling). It clearly identifies the verb-resource pair and distinguishes from sibling tools like book_flight or search_flights.

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 provides explicit guidance: call once at conversation start, and clarifies that clients with MCP resource support get this automatically, so the tool is for those without. This offers clear when-to-use and when-not-to-use context.

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 no annotations provided, the description carries the burden and discloses that the operation is read-only and safe to repeat. It also implies multiple results by referencing 'the first result,' which adds useful behavioral context beyond 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 description is three sentences, front-loaded with the main purpose and includes actionable instructions on using the result, with no wasted words.

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 tool with no output schema, the description is thorough: it states what the tool does, when to call it, that it is safe, and how to interpret the response. This makes it complete for agent use.

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 schema already describes the 'text' parameter as a place name with 100% coverage, so the description adds little new information. It reiterates 'place name' and 'city name' without adding format or additional constraints.

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 converts a place name to the supplier city id needed by search_hotels, using a specific verb and resource. It also distinguishes from siblings by positioning it as a prerequisite for search_hotels.

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 says 'Always call this first if you only have a city name,' providing a clear when-to-use condition. However, it does not mention alternatives or when not to use it, such as when the city ID is already known.

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 no annotations provided, the description carries full burden and explicitly states 'Read-only, safe to call multiple times', clearly indicating no side effects and idempotency.

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 two sentences, no redundant words. The purpose is stated first, followed by usage guidance. It is concise and 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?

Given the tool's simplicity (one parameter, no output schema), the description fully covers its purpose and usage context. It also explains its relationship to sibling tools, making it 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% with a clear description for the query parameter. The description adds context by specifying the output (IATA codes) and reiterating the parameter's purpose, adding 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?

The description clearly states the tool converts a city/airport name to IATA codes, using a specific verb ('Convert') and resource. It also distinguishes itself from sibling tools by explicitly recommending it as a prerequisite for search_flights.

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 explicitly says 'Always call before search_flights if you only have a city name', providing clear when-to-use guidance. It also notes it is read-only and safe to call multiple times, further guiding usage.

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 no annotations, the description carries the full burden and does so thoroughly: it discloses that the call is read-only, async (polls on the caller's behalf, waits out the split-ticket merge), requires LETSFG_BEARER_TOKEN or LETSFG_API_KEY, and explains the starlink field semantics, split-ticket/unprotected-connection implications, and how absent fields should be interpreted.

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?

Long but dense and front-loaded: the core purpose and read-only nature come first, then return-value semantics, then the split-ticket warning. Almost every sentence carries operational guidance, though the starlink and split-ticket paragraphs are verbose enough that some tightening is possible.

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 an 11-parameter search tool with no output schema, the description compensates by explaining return fields and their interpretation. Combined with the auth and workflow pointers, an agent has enough to call and correctly report results.

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 11 parameters are already documented, making 3 the baseline. The description adds interpretive value around the return payload (starlink, split_ticket) but little per-parameter detail 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?

Opens with a specific verb+resource+scope: 'Search hundreds of airlines for live flight prices' and adds the read-only/free framing. An agent can immediately distinguish it from siblings like search_hotels and book_flight 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?

Gives clear context for when to use it (live price search, read-only) and implicitly routes name-based origins to resolve_location. It also notes the auth prerequisite and the authenticate->search->book workflow via the letsfg://guide resource, but doesn't explicitly contrast against other search/booking siblings.

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 no annotations, the description carries the full behavioral burden and does so excellently. It discloses the surprising session-opening behavior, the payment prerequisite, refundability fields, exact price composition and markup rates, the fact that nothing is added at booking, the fields book_hotel needs, and the expected latency.

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 dense but every sentence earns its place: search scope, prerequisite, rate-type behavior, pricing formula, downstream contract, and latency. It is front-loaded with the core purpose and keeps related details grouped logically, with no filler.

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

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

For a tool with 10 parameters, no output schema, and no annotations, this description is unusually complete. It covers prerequisites, side effects, price semantics, required downstream identifiers, rate-type distinctions, and timing. An agent can invoke it and pass the result to book_hotel with confidence.

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 meaning beyond the schema by explaining how price relates to currency and markup_rate, confirming child_ages are needed for supplier pricing, and noting that nationality genuinely changes rates and taxes. This is useful but supplementary rather than essential.

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 pair, 'Search real, bookable hotel inventory,' and clearly distinguishes itself from booking, cancellation, and city-resolution tools. It leaves no ambiguity that this tool returns bookable hotel offers rather than managing bookings.

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 clear contextual usage guidance: a payment method must be connected, search itself opens a supplier session, and the results feed directly into book_hotel. It does not explicitly enumerate when-not-to-use alternatives, but there is no competing hotel-search sibling, and the downstream/upstream relationship is strongly implied.

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