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 declare readOnlyHint=false, openWorldHint=true and non-idempotent, so the safety profile is partly covered. The description adds genuinely useful value by naming the response contents (eligibility status, upgrade options, bid ranges, session id), which discloses the stateful session creation implicitly; but calling it a 'lookup' slightly undersells the non-read-only nature the annotations flag.

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

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

A single front-loaded sentence with the inputs first and the return payload second, with essentially no wasted words. It could have used a second short sentence for sibling routing without hurting brevity.

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

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

For a 7-parameter, nested-object tool with no output schema, the description does well to enumerate the return shape. But in a sibling cluster of four-plus eligibility/session tools it leaves the agent without enough to disambiguate entry points, and it never states prerequisites or the booking-reference+last-name match requirement beyond restating inputs.

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 every parameter including the nested intentContext and conversationId is already documented in the schema. The description only gestures at 'booking reference and last name, and airline' and adds no format, privacy or session-binding detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (looks up), resource (a booking's upgrade eligibility) and the keying inputs (booking reference, last name, airline), plus what it returns. It does not, however, differentiate itself from near-name siblings such as start_eligibility_check, get_eligibility_result or mint_eligibility_session, so an agent could still pick the wrong entry point.

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

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

There is no explicit when-to-use guidance and no mention of the alternative eligibility tools that crowd the sibling list. The only routing hint is the trailing 'session id for follow-up bid tools', which is about the next step rather than when this tool beats its 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?

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value beyond them: settlement timing (24–72h), the meaning of an empty result ('no change observed yet'), and the incremental-polling model via the since cursor. It stops short of auth or rate-limit details.

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

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

Dense but front-loaded: purpose first, then invocation, then poll cadence and the empty-result caveat. Every sentence carries information, though the single paragraph is longer than strictly necessary.

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

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

No output schema exists, yet the description compensates by describing the event record shape (offer reference, new/previous status, amount, cabin) and the empty-result semantics. An agent has everything needed to call and interpret 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 coverage is 100%, so baseline is 3. The description goes further by explaining the workflow relationship between sessionId/conversationId ('or') and how `since` is used across successive calls, adding meaning beyond the field-level descriptions.

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

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

States a specific verb and resource: an ordered log of bid-outcome events on a checked booking, and explicitly frames it against a sibling by saying it works 'without re-running a status check' (i.e., vs get_bid_status). It even enumerates the event types, so an agent knows exactly what comes back.

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

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

Gives explicit when-to-use ('poll periodically', 'bids settle 24–72h before departure'), when-not ('instead of asking the traveler to check back'), and a named alternative ('subscribe via REST POST /api/v1/webhooks'). The sessionId/conversationId and since-cursor invocation path is spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return contents (products with official URL, loyalty program, cabin paths, access, summary) in the absence of any output schema, though it says nothing about rate limits, auth, or freshness of the data.

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 efficient sentences with the core purpose front-loaded; the parenthetical field list is dense but earns its place by defining the otherwise vague term 'upgrade profile.' No filler or restated title.

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 single-carrier lookup with a fully documented two-param schema, the description covers the essentials, and its return-field enumeration compensates for the missing output schema. Minor gaps remain around data freshness and any error behavior when a carrier is unknown.

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 both parameters are already documented in the schema. The description's example ('AC' or 'Air Canada') duplicates the schema's own example ('LH' or 'Lufthansa') and adds no new semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Get the full upgrade profile for one operator') and then enumerates exactly what that profile contains — products plus official page URL, loyalty program, cabin paths, access, summary. It explicitly distinguishes itself from the sibling ask_upgrade_agent, so an agent can route without opening either schema.

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

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

It gives clear relative positioning via 'More detailed than ask_upgrade_agent,' which tells the agent when this tool is the richer choice. It does not state an explicit when-not condition or other alternatives (e.g. list_partners, partner_question_insights), so it stops short of full routing guidance.

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

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

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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context: data is aggregated from anonymized eligibility checks, results may fall back to operator-wide scope, and the tool signals when observed data is insufficient. It doesn't cover latency, pagination, or sample-size thresholds, keeping it from a 5.

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

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

Four sentences, front-loaded with the return format first, then input acceptance, then scoping/fallback behavior. Each sentence carries distinct information with no filler. Slightly long but 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?

With no output schema, the description carries the burden of describing returns, and it does so (low/typical/high, per cabin) plus fallback labelling. The 6 optional parameters and ambiguous combination rules (e.g., conversationId vs carrier precedence) are not fully addressed, leaving a minor gap.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that route scoping applies in either direction and that operator-wide ranges are the labelled fallback when route data is absent. This route-fallback semantics is not captured in the parameter descriptions.

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

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

The description states a specific verb+resource: returns typical upgrade bid ranges (low/typical/high, per cabin) for an operator, aggregated from anonymized eligibility checks. It is clear what is produced and from what source. It does not explicitly name sibling tools like get_price_breakdown or predict_bid_success to differentiate, so it stops short of a 5.

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

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

It explains accepted inputs (IATA code or name) and the route-scoping condition, which implies when this tool is useful. However, it never says when to prefer this over get_price_breakdown, predict_bid_success, or check_upgrade_eligibility, so usage versus alternatives is left to inference.

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

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

Annotations already 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 readOnly, idempotent, non-destructive and non-openWorld, so safety is covered. The description adds genuinely useful behavior: output is a text summary plus a full report object in structuredContent, the default 30d window, and the important caveat that a partner argument is ignored for partner-scoped tokens. It does not mention cost, latency or pagination, but the added detail is substantive.

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

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

The core content is front-loaded, but the middle is a long parenthetical enumeration of report sections that reads as a feature dump rather than routed information. It is informative yet denser than it needs to be for an agent choosing a tool.

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

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

With no output schema, the description carries the return-value burden and does so by stating the report arrives as a text summary plus a structuredContent object, and it names the scope of the analysis. The main remaining gap is the absence of any relationship to the overlapping sibling tools.

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

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

Schema description coverage is 100%, so both parameters (window enum, partner) are already documented, including the partner-scoped-token caveat. The description's example names ('Air Canada', 'MSC Cruises') restate rather than extend 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?

States a specific resource (per-partner analytics report) and enumerates its sections: question intents, conversion funnel, AI visibility, content gaps and bid ranges. An agent can tell it is an analytics read, not a booking action. It does not explicitly differentiate itself from the sibling partner_visibility_report, which appears to overlap on the AI-visibility portion.

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

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

Usage is implied by the report contents and the instruction to pass a partner name, but there is no explicit when-to-use or when-not-to-use guidance, and no reference to the close sibling partner_visibility_report or usage_totals. Adequate but leaves the routing decision to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the bar is lower, yet the description still adds value: it discloses that partner-scoped tokens are locked to their own brand (an authorization boundary) and that answers are flagged for human review. It does not describe pagination or the response format.

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

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

It is a single dense sentence but front-loads the object of the report before listing the breakdowns, and the closing scoping clause is placed last where it belongs. Every clause carries content; 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?

There is no output schema, so the description must convey what comes back, and it does so concretely (share of answer, cited domains, agent statements, wrong/contradicted claims). It is essentially complete for a read-only report tool, missing only structural detail like sections or pagination.

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

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

Schema coverage is 100%, so both parameters (window, partner) are already documented, including the enum values and the note that partner is ignored for scoped tokens. The description's 'partner-scoped tokens are locked to their own brand' largely restates the schema rather than adding new parameter detail, so baseline 3 applies.

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

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

The description states a specific resource and a rich set of outputs: share of answer across ChatGPT/Claude/Perplexity/Gemini, cited domains, agent statements, and incorrect/contradicted claims. It never names a sibling (e.g. partner_question_insights) to differentiate itself, so it falls just short of the top mark.

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

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

Usage is implied by the enumerated content ('AI visibility for one partner's upgrade program'), so an agent can infer this is the reporting tool rather than the Q&A or bidding tools. There is no explicit when-to-use, when-not, or named alternative, which the sibling list (partner_question_insights, get_partner_info) would have rewarded.

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 establish this is a safe, idempotent, non-destructive read, so the burden is lower. The description adds genuine behavioral context beyond them: it discloses the data sources (resolved bid outcomes, operator read), the sessionId dependency, and that null is returned when data is insufficient — a useful failure-mode disclosure.

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

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

Two dense sentences that front-load the core purpose and then layer the data-grounding and null behavior. Every clause carries information, though the second sentence is packed tightly enough to require a second read.

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

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

With no output schema, the description should describe the return shape, but it only says it returns null when data is short — not what a successful result looks like (probability, score, label, or confidence). It covers the input prerequisites well but leaves the output contract underspecified for a 7-parameter analytic tool.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, including the sessionId provenance and the travelerQuestion privacy guidance. The description mostly reinforces this ('sessionId ... unlocks the operator's LIVE bid-strength read'), adding the causal link between live data and the sessionId but little syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: estimating the acceptance likelihood of a given bid amount, grounded in resolved bid outcomes and the operator's bid-strength read. This clearly separates it from siblings like get_bid_status (status of an existing bid) or get_upgrade_pricing (price discovery), though it never names an alternative explicitly.

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

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

Implies usage through the sessionId condition ('unlocks the LIVE bid-strength read for this exact booking and amount') and the null fallback, which hints at a data-availability prerequisite. But it never says when to prefer this over get_upgrade_pricing, get_bid_status, or check_upgrade_eligibility, leaving the routing decision to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on substantive behavioral detail: the third carrier group is flagged as an unconfirmed hub match carrying no pricing, and pricing comes from anonymized checks in either direction. This provenance/labeling context is info an agent needs to interpret results correctly.

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

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

Front-loaded with the core purpose, then two parallel mode branches. It is dense and clause-heavy with multiple em-dashes, but nearly every clause carries information about the result composition rather than 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?

With 8 optional parameters, no output schema, and closed-world annotations, the description does the heavy lifting by explaining what each of the three carrier groups in the route result means. It stops short of clarifying pagination/limits or how region/vertical/product interact without a route.

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 63%, and the schema already documents date, cabin, origin, destination, and travelerQuestion. The description's only incremental parameter insight is that route results are computed 'either direction' and that date drives live inventory confirmation, which the schema largely already states. 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 opens with a specific verb and resource ('Finds operators that offer upgrades') and then clearly delineates two operating modes (route-level vs. operator list). It distinguishes itself from siblings by scope, though it never names an alternative tool like get_upgrade_pricing or list_partners.

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 two branches ('With an origin and destination airport...' and 'Without a route...') give explicit conditions for the two modes, which is real when-to-use guidance. However, it never names an alternative tool or states when a sibling such as get_upgrade_pricing should be preferred instead.

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

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

Annotations mark this as non-read-only and non-idempotent, so the agent knows it initiates stateful work. The description adds genuinely useful context beyond that: the tool does not itself collect PII but hands off to a secure page where the traveler enters booking reference and last name, and the inline form is only available 'where supported'.

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: purpose first, returned artifact second. Every clause earns its place.

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

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

With no output schema, the description correctly takes on the burden of describing the return value (a secure page plus optional inline form), which is the key thing an agent needs. It stops short of explaining the session/lifecycle relationship to get_eligibility_result or mint_eligibility_session, but for a session-initiating tool this is largely adequate.

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

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

Schema description coverage is 100%, so the schema already documents carrier, language, intentContext, and travelerQuestion thoroughly, including privacy caveats. The description adds no parameter-level meaning and notably does not clarify that booking reference/last name are entered on the returned page rather than passed as arguments, which is a missed opportunity.

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

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

States a specific verb and resource ('starts an upgrade eligibility check') and names the supported domains (flight, cruise, rail). It also discloses the artifact returned (a secure page/inline form). However, it does not distinguish itself from nearby siblings such as check_upgrade_eligibility or mint_eligibility_session, leaving the agent to infer the difference.

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 when-not-to-use guidance, and no alternative is named despite at least three closely related eligibility tools in the sibling list. Usage is only implied by the 'start' verb.

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.