tickets

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

The readOnlyHint annotation already declares the operation is safe, and the description adds useful behavioral context: results are live, prices are in euro cents, and there is a maximum quantity per line. This goes beyond the annotation without contradicting it.

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 dense sentence that front-loads the main purpose and then specifies the key output details. Every phrase earns its place; no filler or redundant repetition of schema 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 lookup tool with a simple two-parameter schema and an output schema available, the description provides all essential context: what it returns, in what units, and how the result connects to hold_tickets. Nothing critical is missing for invoking 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 100% for both parameters, so the schema already documents event_id and locale. The description does not add much parameter-level meaning, though 'per session' helps clarify the granularity of the returned data.

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 function: retrieving live ticket availability for a concert per session, and specifies the exact values returned (stock_id, category_id, price_id) that hold_tickets needs. It also adds important detail about prices being in euro cents and the maximum quantity per line. This distinguishes it from sibling getters like get_event or get_venue_info.

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 this tool by explaining that it provides the values hold_tickets needs, making the downstream use case clear. It does not explicitly state when not to use it or name alternatives, but the context is strong enough for an agent to infer the correct placement in a booking flow.

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, and the description adds meaningful behavior beyond that: it explains response shape per status, including that paid bookings carry ticket_url, ticket_pdf_url, and optional wallet URLs. This clarifies what the caller can expect without overpromising.

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 dense sentence that front-loads the core statuses before diving into URL details. Every clause adds value about possible response content, though the sentence is slightly long and could be split for easier 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?

For a read-only status tool with an output schema, the description covers the important response variations and special URL semantics. It does not mention the required booking_uuid or the locale default, but those are either visible in the schema or inferable from the tool name, making the definition reasonably complete.

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

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

Schema coverage is only 50%, with booking_uuid undocumented in the schema and the description providing no parameter-level meaning beyond the tool's purpose. The locale parameter is covered by the schema but the description does not compensate for the missing booking_uuid semantics, and the booking_uuid's role must be inferred from the tool name.

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 what the tool returns: the current status of a booking, with enumerated possible values. It distinguishes this as a status-read operation, separate from siblings like hold_tickets or set_contact, without 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 read-only 'current status' framing implies this is the tool to call for checking a booking's state, but it does not explicitly state when to prefer it over alternatives such as recover_tickets or wait_for_payment. No exclusions or alternative routing is provided, so the guidance is only implied.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful behavioral context by listing what the response contains, including the notable inclusion of other dates from the same run. No contradiction exists between the description and the annotation.

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, efficient sentence that front-loads the core purpose and then provides a compact, useful list of included details. There is no filler or redundant restatement of the tool name.

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-resource lookup with an existing output schema and fully documented parameters, this description provides sufficient context. The agent can infer the correct resource scope, the required event_id provenance, and the nature of the returned data without additional explanation.

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

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

Schema description coverage is 100%, including event_id's source from list_events and the locale enum with default value. The description itself adds little parameter-specific detail, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Full details of one concert') and enumerates concrete content: bio, line-up, other dates, prices, and availability. This clearly distinguishes it from list_events (many concerts) and from facet-specific tools like get_availability or get_venue_info.

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 by focusing on a single concert's full details, and the schema's event_id description ties it to list_events. However, it gives no explicit guidance on when to prefer get_availability or get_venue_info for narrower lookups, so usage context is clear but exclusions and alternatives are not stated.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful content context—what kind of venue information is returned (address, contact, house rules, practical questions)—but does not reveal additional behavior such as localization defaults or response shape, which is acceptable given the 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?

Two concise sentences with no fluff. The first sentence front-loads the core content, and the second adds a practical usage directive. Every word 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 a single optional parameter fully described in the schema, an output schema present, and readOnlyHint set, the description provides everything an agent needs to select and call it correctly. Nothing essential is missing.

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

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

The input schema fully documents the only parameter (locale), including its allowed values and default. The description adds no parameter-specific detail, but none is needed because schema coverage is 100%.

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 resource—address, contact details, and FAQ—and the name 'get_venue_info' supplies the retrieval verb. It distinguishes from sibling tools like get_availability or get_booking_status by focusing on venue facts, though it doesn't explicitly contrast itself with those siblings.

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

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

It explicitly instructs when to use this tool: 'Use this to answer buyer questions about the club instead of guessing.' This gives a clear use case, but it does not mention exclusions or name alternative tools for situations where venue info is not the answer.

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 not read-only nor idempotent. The description adds valuable behavioral context beyond those flags: the hold expires after 15 minutes without payment and the seats are automatically released. This meaningfully clarifies side effects.

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 tight sentences: the action, the critical time-bound behavior, and the usage boundary. Nothing is wasted, and the most important operational details are 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?

With an output schema present and well-described parameters, the description covers the essential operational semantics: what the call does, what it returns, when it should be used, and what happens on expiry. It could mention retry/idempotency behavior, but that is already in 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 high; every parameter has a description, including provenance hints like 'from get_availability'. The description itself adds little parameter-level detail, but the schema already carries that weight, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource — 'Reserves tickets' — and clearly identifies the output ('returns a booking_uuid'). It distinguishes itself from sibling tools like release_booking or get_booking_status by framing this as the reservation/holding action.

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

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

The description gives explicit when-to-use guidance ('Only call this once the buyer has chosen') and an explicit when-not-to-use rule ('do not hold speculatively'). This is strong operational guidance that an agent can act on directly.

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 readOnlyHint annotation already establishes a safe read operation, and the description adds useful context by enumerating exactly what is returned (date, line-up, genres, price/availability summary) and the currency unit (euro cents). It does not disclose ordering, pagination, or result limits, but that gap is minor for a simple read-only list tool with an output schema.

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

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

Two sentences with zero filler: the first front-loads the core purpose and returned fields, and the second isolates the critical currency detail (euro cents). Every sentence earns its place, and the description is appropriately sized for the tool's simplicity.

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-only listing tool, the combination is quite complete: annotations cover safety, the input schema fully documents the only parameter, the output schema covers return structure, and the description supplies the non-obvious detail (currency unit). The only minor gaps are ordering/pagination, which are not critical given the output schema exists.

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%: the locale parameter is fully documented with its enum values, purpose, and default in the schema itself. The description adds no parameter-level meaning, which is acceptable since the baseline for high coverage is 3 and the schema carries the burden.

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

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

The description clearly states the resource (upcoming concerts) and the returned fields (date, line-up, genres, price/availability summary), effectively conveying a list/browse operation. It implicitly distinguishes from siblings like get_event and get_availability, which target specific events or availability, though it never names an alternative or an explicit scope boundary.

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 context is implied: listing all upcoming concerts with summaries is the natural discovery/browse entry point, while siblings like get_event, get_availability, and hold_tickets serve detail and transaction purposes. However, there is no explicit when-to-use or when-not-to-use guidance, so the agent must infer the routing from the sibling names.

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

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

The description adds crucial behavior beyond the annotations: ticket links are only sent to the inbox, the response never contains them, and the inbox is the proof of ownership. It also instructs the agent to tell the buyer to check email and spam. These details are not present in the annotations and materially affect how the tool should be used.

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

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

The description is compact and front-loaded: the purpose appears in the first sentence, critical behavioral context in the second, and a direct agent instruction in the third. Every sentence earns its place with no redundancy 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 small two-parameter tool with a full output schema and annotations, the description covers the use case, the delivery behavior, the proof-of-ownership implication, and the follow-up instruction to the buyer. 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?

The input schema already provides 100% description coverage for both parameters, including the locale enum and its default. The tool description adds that the email is the address 'the buyer ordered with,' which slightly reinforces the email parameter's meaning, but it does not need to compensate for schema gaps. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: it sends ticket links from past paid orders to the buyer's email address. This clearly distinguishes it from sibling tools like hold_tickets, release_booking, and redeem_pass. The title reinforces the purpose with 'Re-send tickets by email'.

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 opens with 'For a buyer who lost their tickets,' which gives a clear situational trigger for when to use this tool. It does not explicitly name alternative tools or exclusions, but the context is specific enough to guide an agent away from unrelated 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?

The description discloses meaningful behavioral outcomes beyond the annotations: it consumes as much balance as needed, fully covered orders complete immediately with status paid, and partial coverage returns a payment_url. This gives the agent a clear model of the tool's side effects and conditional behavior.

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

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

Two sentences deliver the action, the prerequisite, the balance-consumption behavior, and the conditional outcome. Every clause earns its place, and the critical sequencing constraint 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 the output schema exists, the description adequately covers the operation's flow and outcome. It could optionally mention the relationship to wait_for_payment, but the response's payment_url and the immediate-paid outcome are sufficient for an agent to proceed 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 schema covers code and locale, while the description adds the essential context that booking_uuid refers to a held booking and that the code is a Toots gift card code provided by the buyer. This compensates for the undocumented booking_uuid parameter and reinforces the meaning of the other parameters.

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 ('Applies'), a specific resource ('a Toots gift card code' to 'a held booking'), and a clear sequencing constraint ('after set_contact'). This clearly distinguishes it from sibling tools like redeem_pass and wait_for_payment.

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 for when to use the tool: apply a buyer-supplied gift card code to a held booking after set_contact. It does not explicitly name alternatives or exclusion conditions, but the sequencing and purpose are unambiguous enough for an agent to route correctly.

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

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

The description adds value beyond the annotations by disclosing the conditional outcome: 'If the order is fully covered the booking completes immediately (status paid); otherwise the response carries the payment_url for the balance.' This explains the mutation behavior and edge case. It does not contradict the readOnlyHint=false, idempotentHint=false, or destructiveHint=false annotations, and supplements them with actionable 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?

The description is concise and front-loaded: it opens with the core action and prerequisite, then explains the behavior and outcome. Each sentence contributes new information—code format, coverage logic, and payment_url fallback—with no redundancy. It is slightly longer than minimal, but the extra sentences all serve clarity.

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 output schema exists, the description doesn't need to detail return values, but it still explains the conditional payment_url outcome, which helps the agent anticipate responses. It also covers the code format and the prerequisite, making it sufficiently complete for correct invocation. Minor gaps like error handling are likely covered by the output schema, so this is well-rounded.

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 compensates for the missing schema description of booking_uuid by referring to a 'held booking', implying the UUID's purpose. For the code, it adds format details (XXX-XXXXXX-XXX) and clarifies its origin and role, which are not in the schema. The locale parameter is well-described in the schema, so no additional context is needed. Overall, it bridges the 67% schema coverage gap effectively.

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

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

The description states a specific action ('Applies a Toots Pass code') on a specific resource ('held booking'), and differentiates this from sibling tools like redeem_gift_card by explicitly identifying the credential type and its role. It also mentions the prerequisite 'after set_contact', which adds clarity about the workflow step.

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

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

The description gives clear context for use: it must be used after set_contact, and it clarifies that the code is a venue credential, not a payment instrument, which helps the agent decide when to select this tool over alternatives. However, it does not explicitly list alternative tools or exclusion conditions beyond the prerequisite, so it stops short of full when/when-not 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 destructive and idempotent behavior. The description adds useful context on top: release happens immediately versus waiting for expiry, and paid bookings are protected. These details help the agent understand real-world consequences beyond the annotation flags.

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

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

Three short sentences, each adding a necessary detail: what happens, when to use it, and what cannot be released. There is no filler or redundant restating of the tool name or schema.

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

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

The description covers the essential precondition (unpaid hold), the alternative avoided (15-minute expiry), and the key constraint (paid bookings excluded). An output schema exists, so return values need not be described. For a small-footprint mutation tool, nothing needed for correct invocation is missing.

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

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

Schema coverage is only 50% because booking_uuid lacks a description, but the parameter is self-describing as the booking identifier. The description enriches it by specifying this must be an unpaid hold and that paid ones cannot be released, which compensates partially for the undocumented booking_uuid.

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

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

The description states a specific action (release seats on an unpaid hold), the resource (booking/hold), and distinguishes it from simply letting the hold expire. It also excludes paid bookings, making the tool's scope unambiguous even without opening the schema.

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

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

It explicitly says to call this when the buyer changes their mind, and clarifies that it should only be used for unpaid holds. This gives clear when-to-use guidance and a hard exclusion for paid bookings, leaving no ambiguity about the intended trigger.

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 already signal a non-read-only, non-destructive, idempotent operation. The description adds valuable behavioral context beyond that: the tool returns a payment_url, payment must be completed externally by the buyer, and tickets are emailed to the supplied address. This helps the agent avoid attempting payment through the API.

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

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

Three short, purposeful sentences. The core action and output are front-loaded, followed by the critical external-payment instruction and the ticket-delivery side effect. No filler or repetition.

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 covers the essential end-to-end flow: attach buyer to held booking, get payment_url, direct buyer to pay externally, expect tickets by email. With an output schema present and annotations covering safety, this is sufficiently complete for an agent to invoke the tool correctly, though it could have more explicitly noted the requirement to have a held booking first.

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 only 44%, so the description needed to compensate for undocumented parameters like booking_uuid, zip, country, firstname, lastname, and promo_code. It does not. The only parameter-related mention is email receiving the tickets, which duplicates the schema's own description rather than adding meaning.

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

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

The description states a specific verb and resource: 'Attaches the buyer to a held booking' and names the key output, the payment_url. This clearly distinguishes set_contact from siblings like hold_tickets, release_booking, or wait_for_payment.

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 is clear that the tool is used when a booking is held and the buyer needs to be attached. It also gives important operational guidance: give the payment_url to the human buyer because payment happens in their browser, never through this API. It does not explicitly name alternatives or sequence it after hold_tickets, but the context is strong.

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?

Even with readOnlyHint=true already in annotations, the description adds meaningful behavioral detail: it holds the request open, has a maximum hold time, returns as soon as the booking is paid, and implies a retry loop condition. This goes well beyond what the annotation conveys and sets accurate expectations for long-polling behavior.

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

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

The description is compact and front-loaded: the first sentence defines the behavior, and the second provides actionable usage. Every sentence contributes practical value with no filler.

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

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

Given the output schema exists and this is a read-only long-polling tool, the description covers the essential operational context: when to call, what triggers a return, and the retry condition. The 'after handing the buyer the payment_url' guidance anchors it in the booking flow.

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

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

Schema description coverage is only 33%, and the description does little to compensate. It indirectly references the timeout concept with 'up to 25 seconds' and 'the hold has time left', but it does not explain booking_uuid, locale, or timeout_seconds as parameters. An agent would have to infer most parameter meanings from context.

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

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

The description clearly states the tool's purpose: it waits for a booking to be paid, holding the request open up to 25 seconds and returning as soon as payment occurs. It also explicitly differentiates itself from the sibling get_booking_status by contrasting its long-polling behavior.

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

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

The description gives explicit, practical guidance: call it after handing the buyer the payment_url, use it instead of polling in a loop, and repeat while the status is still awaiting_payment and the hold has time left. This makes the intended usage unambiguous.

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