upgrade-agent

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating the tool is safe and open-ended. The description adds context that it is for general questions and is not booking-specific, which aligns with annotations. No contradictions; additional context about informational-only scope is helpful but not extensive beyond annotations.

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

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

The description is two sentences with zero wasted words. It front-loads the core purpose and immediately follows with usage guidance. Efficient and well-structured.

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 adequately covers what the tool does, when to use it, and how it relates to siblings. Given the small parameter count and high schema coverage, the description is sufficient for the agent to understand and invoke the tool correctly. Could mention limitations like no real-time data, but not necessary for completeness.

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 parameters (askedBy, question, conversationId) are fully documented in the schema. The tool description does not add new parameter-level meaning beyond what the schema already provides; it only reiterates the tool's purpose. 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 clearly states the tool answers general travel-upgrade questions, lists specific topics (how bid/instant/points upgrades work, eligibility, strategy, etc.), and explicitly distinguishes from booking-specific tools like start_eligibility_check. The purpose is specific and leaves no ambiguity.

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 to use this for informational questions only and identifies start_eligibility_check as the preferred tool for checking a specific booking, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate this is a mutating, non-idempotent operation. The description adds 'releases the bid' and a warning to confirm first, which offers some behavioral context. However, it does not disclose failure modes, consequences of omitting orderChangeId with multiple bids, or any side effects beyond the obvious cancellation.

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

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

Three sentences, front-loaded with the core action, then parameter guidance, then a traveler-confirmation warning. No fluff; every sentence contributes to correct invocation.

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

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

The description plus fully-documented schema covers all key aspects for a 5-parameter tool with no output schema. It explains which parameters are needed in which scenarios and includes a prerequisite. Minor gaps: it doesn't describe the response or explain the presentationReport parameter in the main description, but the schema covers that.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the relationship between sessionId/conversationId and mentions orderChangeId comes from get_bid_status, but the schema already documents each parameter. No significant new parameter semantics 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 uses the specific verb 'Withdraw' and clearly identifies the resource: 'a bid already placed on a booking the traveler checked with start_eligibility_check.' It also names the sibling relationship by referencing get_bid_status for listing bids, so an agent can immediately distinguish this from place_bid or modify_bid.

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

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

It gives concrete instructions: pass sessionId or conversationId, use orderChangeId when multiple bids exist and get_bid_status lists them, and confirm with the traveler before calling. While it doesn't explicitly contrast with modify_bid or state when not to use it, the context is clear.

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

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

Annotations already signal open-world, non-read-only, non-idempotent behavior. The description adds that the tool returns a session id for follow-up bid tools, which implies a stateful side effect beyond a pure lookup. It does not detail side effects or external calls, but the annotations carry the safety profile, so 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 with no filler. The action, inputs, outputs, and downstream purpose are front-loaded, making the definition easy to scan and act on.

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 rich schema with 100% parameter coverage and an absent output schema, the description sufficiently explains what the tool returns and why it matters. It leaves out how optional context fields should be used, but that burden is already carried by the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates three inputs (booking reference, last name, airline) but adds no new meaning beyond the schema, and it says nothing about language, intentContext, conversationId, or travelerQuestion.

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 ('Looks up a booking's upgrade eligibility') and names the key inputs and outputs. It stops short of a 5 because it does not explicitly differentiate this from siblings like start_eligibility_check or get_eligibility_result, which appear to overlap in purpose.

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 implies the tool should be used to check eligibility before follow-up bid tools, since it returns a session id for them. However, it gives no explicit when-to-use or when-not-to-use guidance and does not name alternative sibling tools, so the usage signal is only implicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description correctly aligns with a read-only operation. The extra note about showing a manage screen inline in certain hosts adds behavioral context beyond the annotations, and the requirement to pass sessionId is a clear usage prerequisite. No contradictions found.

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 concise sentences with no filler. The primary purpose is front-loaded, followed by a key parameter instruction and then a pointer to alternatives. Every sentence contributes useful information, making it easy to scan and parse.

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 provides enough context for an agent to invoke the tool correctly: what it returns (bids, cabins, cart), how to obtain the required sessionId, and what to do for modifications. It does not specify the output format or error handling, but the lack of an output schema and the simplicity of the read-only operation make this acceptable. Minor gaps like handling missing sessionId are not critical.

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 description explicitly tells the agent that sessionId comes from start_eligibility_check, which is crucial for proper invocation and goes beyond the schema's generic description. It does not elaborate on presentationReport or conversationId, but the schema descriptions for these are detailed and cover 100% of parameters, so the description adds modest value without redundancy.

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 exactly what the tool does: checks bids on a booking (with statuses), eligible cabins and ranges, and the current cart. It also names sibling tools (modify_bid, cancel_bid) to distinguish its role as a read-only check. The verb 'check' and resource 'bids' are specific and unambiguous, setting it apart from related tools.

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 clear guidance: pass the sessionId from start_eligibility_check, and explicitly points to modify_bid / cancel_bid for changing or withdrawing a bid, which establishes a when-to-use vs when-not-to-use boundary. It does not mention other alternatives like get_eligibility_result, but for its primary purpose it is adequately scoped.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: it returns a 'still waiting' status until passenger submits, and describes the output schema elements (eligible options, bid ranges, offer URL). No contradiction.

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, efficient and front-loaded with the main action. No extraneous information.

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

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

For a read-only tool with 2 parameters and no output schema, the description covers the key behavior, prerequisites, and result types. It could mention that the output might be incomplete if waiting, but it does address that.

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

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

Schema coverage is 100% and describes both parameters well. The description echoes the sessionId source but does not add significant new meaning beyond the schema. 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 clearly states the tool reads the result of a secure eligibility check, specifying it returns the live eligibility outcome or a waiting status. It distinguishes itself from siblings like start_eligibility_check and place_bid.

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 to use after start_eligibility_check and pass the sessionId. It implies usage context but does not explicitly list when not to use or alternative tools, though sibling differentiation is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as rate limits, authentication needs, or error behavior. It is consistent with annotations but does not enhance transparency beyond them, so a 3 is appropriate.

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 with no redundancy. It front-loads the purpose and contents, then adds the comparison and input format. Every sentence earns its place, making it highly concise and well-structured.

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

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

For a read-only tool with two parameters and no output schema, the description is fairly complete. It specifies the input format (IATA code or name) and outlines the response content (products, loyalty, cabin paths, access, summary). It does not mention error cases or pagination, but these are not critical for this simple info-retrieval tool. It adequately covers what an agent needs to call 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?

The input schema provides full descriptions for both parameters (carrier and travelerQuestion), so schema coverage is 100%. The description repeats the carrier format example ('AC' or 'Air Canada') which is essentially the same as the schema's example, adding no new meaning. It does not elaborate on travelerQuestion beyond the schema's privacy note. Baseline 3 is correct since the schema already covers semantics.

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 verb 'Get' and the resource 'full upgrade profile for one operator,' enumerating the specific contents (products with URL, loyalty program, cabin paths, access, summary). It also explicitly distinguishes itself from the sibling tool ask_upgrade_agent by noting it is 'More detailed.' This provides unambiguous purpose and differentiation.

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

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

The description gives a clear comparison to ask_upgrade_agent ('More detailed than ask_upgrade_agent'), implying it should be used when a fuller profile is needed. However, it does not explicitly mention when not to use it or how it compares to other siblings like list_partners or check_upgrade_eligibility. The context is clear but lacks explicit exclusions, so it earns a 4 rather than a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: it returns an itemized all-in cost including taxes/fees, and for BID it returns the operator's bid-strength read. It doesn't describe the output structure or edge cases, but it supplements the annotations without contradicting them.

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-loads the core purpose, and packs in usage conditions, parameter relationships, and a use-case trigger without redundancy. Every sentence earns its place.

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

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

For a 0-required, 6-parameter tool with no output schema, the description covers the purpose, workflow timing, key parameter guidance, and BID-specific behavior. Gaps remain: there is no output-shape description despite the lack of an output schema, and 'cabin/segment' is slightly ambiguous because the schema only defines a segment parameter, not a cabin parameter.

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 83%, so the baseline is 3. The description adds real value by explaining the sessionId/conversationId interchangeability, the rule to omit amount for INSTANT, and when segment is needed. It doesn't cover every parameter, but it goes beyond simply restating 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 identifies the tool's job with a specific verb and object: 'Show the itemized all-in cost of an upgrade' and explains it covers amount plus taxes/fees. It also adds useful specificity about BID behavior and the 'what will this actually cost me?' use case. However, it does not explicitly differentiate itself from the similarly named sibling get_upgrade_pricing; its only workflow contrast is 'before place_bid,' so it falls short of full sibling differentiation.

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

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

The description gives concrete when-to-use guidance: call it before place_bid to answer cost questions, and it provides conditional parameter guidance such as omitting amount for INSTANT and passing a segment when multiple options exist. It lacks explicit when-not-to-use instructions or named alternatives beyond place_bid, so it stops short of a 5.

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

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

Annotations already mark readOnlyHint, idempotentHint, and destructiveHint, so the description's extra context counts: it discloses that values are aggregated from anonymized eligibility checks and that insufficient data is reported rather than hidden. This adds meaningful behavioral detail beyond the structured annotations.

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

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

Two sentences, no filler: the first sentence carries the core return and source, and the second covers input flexibility and the insufficient-data behavior. Each sentence adds distinct information and is 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 no output schema, the description does describe the output shape (low/typical/high per cabin) and low-data behavior, and the schema covers all four optional parameters. It could more explicitly state that carrier or conversationId is needed, but the description's input hints plus schema make for a mostly complete picture.

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

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

Schema description coverage is 100%, so the baseline applies; the description's only param-relevant note is 'Accepts an IATA code or a name,' which mostly restates the carrier schema description. No new parameter semantics beyond the schema are provided.

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 exactly what the tool returns ('typical upgrade bid ranges (low / typical / high, per cabin) for an operator') and the source of aggregation, making it clearly distinct from sibling tools like place_bid or get_price_breakdown. The verb 'Returns' plus specific resource and output shape gives clear purpose.

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

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

There is no explicit when-to-use or alternative routing like 'use get_price_breakdown for...' present; however, the purpose itself implies using it when typical bid ranges are needed. It does give some practical input guidance ('Accepts an IATA code or a name') and a low-data behavior note, so there is a weak usage context rather than none.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms it's non-destructive and adds that it returns status/improvements, but does not disclose behavioral details beyond what annotations cover.

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, no fluff. Front-loaded with the primary action and output, then provides the parameter hint. Every sentence contributes meaning.

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

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

For a simple read tool with one param and no output schema, the description adequately covers purpose, parameter source, and return content. No gaps given the complexity.

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 has one required param with description. Description adds value by specifying that the token comes from start_watch, which simplifies parameter understanding. Schema coverage is 100%, so baseline is 3; extra context pushes to 4.

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?

Description clearly states the action (check status), the resource (watch from start_watch), and what it returns (status, watched condition, improvements). Distinguishes from siblings by referencing start_watch.

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 instructs to pass the token from start_watch, which is the correct usage. Does not mention when not to use or alternatives, but context makes it clear it's the complementary read operation.

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

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

Annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) already indicate a safe read operation. Description adds return field details but does not disclose additional behavioral traits such as pagination or rate limits. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose and return details, followed by usage advice. No waste; every phrase adds value.

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 0 required params, 100% schema coverage, good annotations, and description that outlines output structure, the definition is complete. No further context needed.

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 enum constraints and descriptions for all 3 parameters. Description adds context about return fields but does not elaborate on parameter semantics beyond what schema provides, 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?

Description specifies 'List the travel operators that offer upgrade programs' with optional filters and enumerates returned fields (name, IATA/code, vertical, region, products). This distinguishes it from sibling tools like get_partner_info (specific partner details) and ask_upgrade_agent (conversational).

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

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

States 'Use this to build travel workflows or answer which airlines/cruise lines offer upgrades,' providing clear usage context. However, it does not explicitly exclude use cases or mention when to prefer alternatives like get_partner_info.

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

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

Annotations already indicate a mutating, non-idempotent operation. The description goes beyond that by clarifying that it creates a secure session, returns its id, and has no UI. It does not detail session lifetime or side effects, but for an internal helper this is meaningful added 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?

One concise sentence front-loads the purpose, then immediately adds the usage caveat and redirects to the correct sibling. Every clause contributes information without repetition or 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 simple internal helper with two optional, well-documented parameters dollar, the description states what it creates, what it returns, and that agents should use a different tool. The lack of an output schema is mitigated because the return value is specified as the session 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?

The schema fully describes both optional parameters (carrier and language) with 100% coverage. The description adds no additional parameter-level detail, 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?

The description states a specific verb and resource: it creates a secure session and returns its id. It also explicitly marks itself as an internal helper and distinguishes itself from start_eligibility_check, so an agent can tell it apart from sibling tools.

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 an explicit exclusion: 'No UI; agents should use start_eligibility_check instead.' This clearly tells agents not to use this tool and names the correct alternative, leaving no ambiguity about when it should be invoked.

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

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

Annotations already signal it is a write operation (readOnlyHint=false, destructiveHint=false). The description adds valuable context: the new amount is validated against the airline's range and payment/confirmation completes on the operator's secure page, which informs the agent about side effects and external dependencies. It does not detail idempotency or failure behavior, but the bar is lower given annotation coverage.

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 with no fluff. It front-loads the core purpose and then adds the most critical usage detail and a behavioral note. Every word earns its place, and it is well-structured for quick scanning.

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 (8 parameters, 1 required) and lack of an output schema, the description covers the essential purpose, differentiation from siblings, and key behavioral aspects. It does not explain all parameters, but the schema handles that. It could mention return values or confirmation steps, but the secure page note partially covers that. Overall, it is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 75%, so the schema documents most parameters. The description adds meaning by emphasizing 'NEW amount' and highlighting sessionId and segment as key inputs for this update use case, which is not evident from the schema alone. It does not explain quantity or upgradeType, but those are either optional or covered by enum values.

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 action ('Change the amount of a bid') and the resource (bid on a booking). It explicitly differentiates from sibling place_bid by saying 'Same as place_bid but for updating an existing bid,' which removes ambiguity about when to invoke this tool.

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

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

It provides clear context: use for updating an existing bid, and names the sibling place_bid as the alternative for new bids. It also instructs to pass sessionId, the NEW amount, and cabin/segment if ambiguous, but does not explicitly state when NOT to use it (e.g., for cancellations). The 'if ambiguous' phrase implies conditional usage but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description is not required to repeat safety traits. It adds valuable context about the report content (volume, frequent questions, which agents, answer quality), which enhances transparency beyond the structured fields.

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

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

The description is two sentences, front-loaded with the main verb 'Report' and the resource. Every word earns its place, with no unnecessary information. Examples are included efficiently.

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 tool is simple (1 parameter, no required fields) with no output schema. The description fully explains what the report covers: total volume, most frequent questions, which agents ask, and answer strengths. This is sufficient for a user to understand the tool's output without needing additional context.

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%, providing a baseline of 3. The description adds extra meaning by specifying that the partner parameter is ignored for partner-scoped tokens, which is not in the schema description. It also gives concrete examples, slightly exceeding the baseline.

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

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

The description uses the specific verb 'Report' and clearly identifies the resource as 'what travelers and AI agents are asking about a specific partner's upgrade programs'. It distinguishes this tool from siblings like ask_upgrade_agent (which asks questions) and get_partner_info (general info) by focusing on aggregated insights.

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 states to 'Pass the partner name' and provides examples, making it clear how to use the tool. However, it does not explicitly mention when not to use it or alternative tools for different needs, such as getting raw question data.

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

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

Annotations are sparse: readOnlyHint=false, destroyHint=false, so the description carries the burden. It discloses that the call returns a secure operator link for payment, implies a multi-step flow, and clarifies the confirm parameter's role for real submissions. This goes beyond the schema, although it could mention test vs. production behavior more explicitly. Not a contradiction.

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 a single concise paragraph that front-loads the core action, then covers exclusions and payment flow. It is efficient and readable, though it packs many details; the key exclusions (INSTANT) are well placed, so it earns a 4 rather than a 5.

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

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

Given the tool's high complexity (9 parameters, 3 purchase types, multiple workflows), the description covers the main paths and redirects to eligibility checks. However, it doesn't explain the confirm parameter's default behavior (staged vs live) in detail or the return structure of the operator link. With an output schema absent, a bit more detail would make it fully complete, but it is competent for an expert agent.

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 crucial context: it explains the interplay between purchaseType and amount (omitted for INSTANT), the role of sessionId vs conversationId, and the strict business rule for presentationReport. This adds real semantic value beyond the schema properties.

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 dual purpose: placing an upgrade bid or buying an INSTANT upgrade. It names the resource (checked booking), the key modalities (BID, INSTANT, POINTS), and gives enough detail to distinguish it from related tools like modify_bid or cancel_bid.

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 tells when to place a bid or use INSTANT, references the required sessionId from start_eligibility_check, and clarifies that amount is omitted for INSTANT. It also mentions the operator payment link, signaling a follow-up action, so an agent understands when to call this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and non-mutating. The description adds context by explaining the data sources (historical outcomes, optional live read) and the null return when data is insufficient. It doesn't contradict annotations and provides value beyond them, but it doesn't detail all behavioral edge cases (e.g., error conditions beyond null).

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, front-loaded with the core purpose. The first sentence states the main function and data grounding; the second notes the null return. There is no redundant wording or unnecessary detail. It is compact and immediately scannable.

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 7 parameters and no output schema, the description should clarify the return format. It says 'how likely' and 'returns null when there isn't enough data,' implying a numeric value but not specifying the scale (e.g., 0-1 probability, percentage, or score). It also doesn't state what 'enough data' means or any prerequisites for using sessionId. Given the complexity, this is a notable gap, though the description does cover the core 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 all seven parameters already have detailed descriptions in the schema. The tool description does not add significant parameter-specific meaning beyond what the schema provides. It mentions the sessionId's role ('unlocks the operator's LIVE bid-strength read') which aligns with the schema description, but the schema already covers this. Baseline 3 is appropriate since the schema carries the semantic load.

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 a specific verb and resource: 'estimates how likely a specific bid amount is to be accepted.' It also specifies the data sources (Plusgrade's resolved bid outcomes, operator's bid-strength read) and distinguishes itself from siblings like place_bid, get_bid_status, and modify_bid by focusing on prediction rather than execution or status. The purpose is unambiguous.

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

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

The description implies when to use it: before placing a bid, to evaluate the likelihood of acceptance. It notes that a sessionId unlocks a live read, and it returns null when data is insufficient. However, it does not explicitly compare against alternatives like 'use this instead of place_bid when you want to assess success likelihood' or state when not to use it. It's clear but lacks explicit exclusion guidance.

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

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

Annotations already mark the call read-only and non-destructive; the description adds a key behavioral limitation: coverage is by region, not flight route networks, and origin/destination do not route-filter. This prevents an agent from drawing a false inference that the tool can verify city pairs.

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, no filler: the core action and filters come first, and the crucial caveat is set off as a NOTE. Every sentence contributes.

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

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

For a read-only search tool with no required parameters and no output schema, the description covers what the tool returns conceptually, how filters behave, and the key route-network limitation. 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?

With only 50% schema coverage, the description compensates by clarifying that vertical/region/product act as filters and that origin/destination are informational placeholders rather than route constraints. The travelerQuestion parameter is already well described in the schema, so the overall parameter meaning is clear.

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 precise verb and object: 'Find operators that offer upgrades', and immediately enumerates the filter dimensions (vertical, region, product). It clearly positions this as a search tool, distinct from the eligibility/pricing/bid siblings, even without naming 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?

It gives clear context on how filters should be applied and explicitly warns that origin/destination are informational only, so agents know not to expect route-filtered results. It does not name alternative sibling tools or state explicit when-not-to-use conditions beyond the route-network limitation, so it stops short of a 5.

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

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

The annotations are all false booleans and provide no real safety profile, so the description carries most of the burden. It adds useful behavior by saying the tool returns a secure page/form and delegates booking-reference entry to the traveler, but it does not disclose side effects, session creation, idempotency, or what happens after the page is returned.

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 front-loaded sentences with no filler: the first names the action and scope, the second explains the return experience. The parenthetical about inline forms is a useful qualifier, not waste.

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

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

With no output schema, the description should more fully specify the return value (e.g., URL vs. HTML vs. session reference) and how the result relates to later tools like check_upgrade_eligibility or get_eligibility_result. It covers the high-level flow but not enough for an agent to integrate the response reliably.

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

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

Schema coverage is 100%, so the baseline is 3 and the input schema already explains carrier, language, intentContext, and travelerQuestion with examples. The description adds no parameter-level information; it only describes the overall flow.

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 ('Starts') and resource ('upgrade eligibility check'), scopes it to flight/cruise/rail bookings, and distinguishes the tool from siblings by noting it returns a traveler-facing secure page rather than an eligibility verdict. This makes its role clear without opening sibling schemas.

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

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

It gives a domain window (flight, cruise, or rail) but no explicit when-to-use or when-not-to-use guidance, and it never names the sibling tools like check_upgrade_eligibility or get_eligibility_result that an agent must choose between. The intended use is only implied by the verb 'Starts'.

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

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

Annotations are all false, so the description carries the full burden. It states the tool sets up a watcher (a creation action) and returns a secure card/link, which gives some behavioral insight. However, it does not disclose idempotency, destructive side effects, authentication requirements, or what happens on repeated calls. It is not contradictory but incomplete.

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 concise, consisting of two sentences. It front-loads the main purpose and then provides examples and the output. There is no wasted wording.

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 tool has 9 parameters, nested objects, and no output schema. The description gives a high-level overview but does not explain parameter semantics or the return value in detail (only mentions a card/link). The schema handles most details, but the description could offer more on what happens after starting the watch, such as how to interact with it.

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

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

Schema description coverage is 78%, which is above 50%, so baseline is 3. The description adds no additional parameter meaning beyond the schema. It does not explain any parameters or their interplay, relying entirely on 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 action: 'Sets up a Watcher that monitors a traveler's booking between now and departure for upgrade opportunities' with specific examples. It distinguishes from siblings like start_eligibility_check and get_watch_status by focusing on monitoring for upgrades. The verb 'sets up' and resource 'Watcher' are specific.

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 clear context on what the tool does but does not explicitly mention when to use it versus alternatives or any exclusions. There is no mention of 'use start_eligibility_check for eligibility' or when not to use this tool. It gives context but no routing guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds system-wide scope and specifics of what totals are tracked, providing useful context beyond annotations.

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

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

Single sentence, front-loaded with purpose, 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 parameterless tool with no output schema, the description fully explains what it returns. Annotations confirm safety. Complete for its simplicity.

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?

No parameters, so schema coverage is 100%. Baseline for 0 params is 4; description adds no param info but none 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?

Description clearly states it provides running totals of questions asked and answered successfully across the whole system. Distinct from sibling tools which focus on specific features like upgrades or bids.

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

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

No explicit guidance on when to use vs siblings. Context implies it's for system-wide usage, but no when-not or alternatives mentioned.

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