haggl.ai

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

Goes well beyond annotations: warns effects may be unknown, explains that a phone deal books no job and takes no payment, clarifies that haggl.ai never takes payment and any payment happens at the merchant's checkout, and that a returned checkout link does not establish payment. This is rich consequential 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?

Front-loads the action and its consequence, then layers caveats. Dense with multiple sentences, but nearly every sentence carries behavioral value; only minor trimming would help.

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?

Output schema exists, so return values needn't be explained. The description covers effects, idempotency, payment non-handling, and approval requirements, leaving nothing an agent needs to call correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning to expected_offer_version ('the offer version the buyer reviewed and approved; a changed offer needs a new approval') and ties it to state.offer_version, beyond the schema's own text.

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 (accept) and resource (the vendor's offer) plus the outcome (lock in the deal). An agent can distinguish it from submit_offer or start_negotiation without opening any schema.

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

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

Explicit preconditions: 'only call after the buyer has approved this exact offer, every time' and 'a changed offer needs a new approval.' It also directs the agent to read state.acceptance_effects and state.commits_purchase first. Clear when-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?

Goes far beyond the annotations: states the ID expires 12 months after last use, that only a fingerprint is stored, what the record does and does not contain, that merchants never see the ID itself, that anyone holding the ID can delete it, and how consent is withdrawn. The mutating, non-idempotent, non-reversible nature is fully disclosed and consistent with readOnlyHint=false and idempotentHint=false.

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 purpose and the call gating are front-loaded correctly, but the bulk is a lengthy verbatim consent disclosure that dominates the definition. That text is functionally required rather than wasteful, but from a definition-quality standpoint it buries the operational instructions and makes the tool harder to scan.

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 consent-gated creation tool with high-stakes privacy implications, nothing an agent needs is missing: the trigger condition, the decline fallback, the delegation fallback, the required field values, and the instruction to store and never share the returned ID. An output schema exists, so return-format details are not needed in prose.

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 real conditional logic the schema cannot express: when to use channel=standing_instruction vs the default, that consent_version must be '2026-10-16.4', and that the statement must be quoted words of agreement with no names or contact details. It does not explicitly clarify that confirmation substitutes for the other two fields, though the schema hints at it.

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 opening sentence gives a specific verb and resource ('Create a haggl ID for the user') plus the rationale ('offers and codes from different merchants stay together and can be read back later'). It is clearly distinguishable from siblings like haggl_request_haggl_id_confirmation and haggl_delete_haggl_id, which are named or implied later.

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

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

Explicitly states the precondition ('Show the user this text first, and call this only if they agree'), the decline path ('If they decline, go on without a haggl ID'), and the exact alternative when the user is absent ('otherwise use haggl_request_haggl_id_confirmation instead, then call this with its confirmation'). It even specifies the standing_instruction branch condition.

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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the cascade behavior (linked offers are unlinked) and a non-obvious residual effect (already-issued codes remain valid at the merchant until expiry). That residual-state detail is exactly the kind of behavioral context annotations cannot express.

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

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

Three short sentences, front-loading the action and its side effect before the guardrail and the residual-state caveat. Every sentence carries distinct information; nothing is redundant filler.

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

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

With an output schema present, return values need no explanation, and the description covers the destructive scope and post-deletion state. It could still say whether the deletion is permanent or recoverable and whether any prerequisite confirmation step (cf. haggl_request_haggl_id_confirmation) is expected, so it is not quite exhaustive.

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

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

Schema description coverage is 100% and the single parameter is already documented as "The user's haggl ID," so the description adds no new meaning, syntax, or format guidance. Baseline 3 applies when the schema carries the parameter 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?

States a specific verb (delete) and resource (the user's haggl ID) and names the consequential side effect (unlinking linked offers). This clearly distinguishes it from the sibling haggl_create_haggl_id and the offer-oriented tools without requiring the schema to be opened.

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?

"Only when the user asks" is an explicit gating condition for invocation, which is the key usage constraint for a destructive tool. It does not, however, name alternatives or explain what to do instead if the user merely wants to pause or disconnect offers, so it stops short of a full when/when-not routing rule.

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?

Goes well beyond annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): discloses that no new proof is needed, that bidding is one-shot across all merchants in the category, the merchant-funded nature of bids, and the presence of accept_url, personalized_price_notice, and algorithmic_price_disclosure for NY users. Those presentation obligations are non-obvious and materially affect correct invocation.

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 action is front-loaded, which is good, but the opening sentence is a dense pile of clauses ('at once, from their haggl ID record, without new proof'), and the final sentence stacks several display requirements that are harder to parse than necessary. Content mostly earns its place but could be tighter.

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

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

An output schema exists, so return values needn't be detailed, and the description still covers the precondition, the failure mode, and how to surface bids. Missing only a note on timing/pagination or whether repeated calls produce duplicate bids despite idempotentHint=false.

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 each parameter is already documented, including how query sets the category when category is omitted. The description reinforces that only one category is targeted and gives a travel example, but adds little beyond the schema and never mentions the query parameter directly. 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: solicit simultaneous bids from merchants in one category on behalf of a user, sourced from their haggl ID record. It is clearly distinguishable from retrieval tools like haggl_get_my_offers or haggl_get_negotiation, though it never names a sibling 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?

Gives the key precondition (the record must already hold a verified purchase in that category from an earlier offer with signed email proof) and the fallback behavior when unmet (no bids, it says so). It also instructs on downstream handling ('show the user each one... accept only with their approval') but does not explicitly contrast with alternative tools for getting offers.

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 the safe read-only, idempotent, non-destructive profile, so the description does not need to repeat those. It adds useful context by listing what is returned and the 'newest first' ordering, but it omits auth requirements, error behavior, or result limits.

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 definition is a single well-formed sentence with no wasted words. It front-loads the action and scope, then lists the returned data and ordering.

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 low-complexity read tool with full schema coverage, rich annotations, and an output schema, the description is sufficiently complete. It explains the data domain and ordering, though it does not cover edge cases such as invalid or missing haggl IDs.

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

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

Schema coverage is 100% and the single parameter has its own description ('The user's haggl ID'). The tool description restates the haggl ID scope but adds no format, syntax, or validation detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a clear verb ('Read') and specifies the resource: data held for the user's haggl ID, including creation time, negotiations, offers, and codes. It is understandable without opening the schema, but it does not explicitly distinguish this tool from siblings like haggl_get_negotiation or haggl_get_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?

Usage is implied by the scope ('for the user's haggl ID'), but there is no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent can infer this is for retrieving stored account data, but must reason about sibling tools on its own.

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 closed-world, so the safety profile is covered. The description adds value on top: it frames this as the canonical re-read point after uncertain results or transport switches, telling the agent it is safe to call for reconciliation, and confirms no new session is created. It says nothing about behavior for an invalid/stale session id.

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

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

Two sentences, no filler. The payload description is front-loaded and the usage trigger plus the 'does not open another session' caveat follow in the second clause.

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-param tool with an output schema and strong annotations, the description supplies what structured fields cannot: when to re-read and the fact that it is not a session initiator. Minor gap: no statement of the failure/staleness behavior an agent would hit with an obsolete 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?

Single parameter with 100% schema description coverage, so the schema already defines session_id fully. The description adds no syntax, format, or provenance detail about the id, leaving the schema to carry it – correct baseline for a one-param tool.

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

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

Specific verb ('Read') plus resource ('an existing negotiation') and an enumeration of the payload it returns: canonical state, offer version, guidance, permitted actions. It also distances itself from the session-opening sibling ('does not open another session'). It stops short of naming the other read siblings (get_bids, get_my_offers) so an agent must infer which read surface it wants.

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 concrete trigger conditions – after human changes, reloads, transport switches, or uncertain results – which is exactly the re-sync situation an agent needs. It also draws a clear negative boundary by stating it does not open a session, implicitly routing to haggl_start_negotiation, though that sibling is never named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description need not restate safety. It adds useful context that no haggl ID is required and scopes the tool to San Francisco hotels, but it does not add much beyond that regarding 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 a single dense sentence that front-loads the resource and enumerates the key returned information. It is appropriately sized for the amount of context, though the parenthetical list makes it slightly heavy rather than crisp.

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, the description does not need to explain return values and instead focuses on scope and usage trigger. It is largely complete for a zero-parameter informational tool, though it could better distinguish this offer-overview tool from the related cashback claim/stay/get 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?

The tool has zero parameters, so there are no parameter semantics to document. The description reinforces this by saying 'No haggl ID needed,' which is consistent with the empty input schema and helps prevent an agent from inventing required inputs.

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: the haggl.ai hotel cashback offer, including whether it is open, tiers/rates, participating hotels, vendor IDs, and steps. It is specific about contents, though it does not explicitly distinguish itself from similar cashback siblings such as haggl_hotel_cashback_get.

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

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

It gives a clear triggering condition: 'Call it when the user is choosing a hotel in San Francisco.' It also states 'No haggl ID needed,' which helps an agent decide this tool is callable without prerequisite IDs. It does not explicitly name alternatives or when not to use it.

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

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

Adds real behavior beyond the annotations: one email per call, the email is discarded ('not kept'), an explicit user-consent requirement, the 12-month recency window, and the tier thresholds (1+ returning, 3+ frequent). This is the kind of side-effect and privacy disclosure annotations cannot carry.

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 optional/ordering cue and every clause adds facts (evidence types, window, tier math, consent, retention). It is dense but no sentence is wasted.

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

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

With an output schema present and annotations covering safety, the description supplies the consent, privacy and evidence constraints an agent needs. Minor gap: no mention of failure/rejection outcomes or duplicate-email handling, which matters somewhat given idempotentHint=true.

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, and the description earns more by constraining raw_mime_b64 to a signed, original, in-window trip email and by stating one email per call. It still doesn't clarify format details already handled by 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?

Specific verb and object: 'prove one past trip to San Francisco ... with its signed flight booking, hotel booking or hotel post-stay email' to 'raise the user's cashback tier'. Scope (last 12 months, one email per call) is stated. Sibling tools are not named, so differentiation from haggl_hotel_cashback_stay/claim relies on inference.

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?

Clear timing context: 'Optional, before asking a hotel's agent for a rate', plus the consent gate 'Only with the user's go-ahead to send that email'. No explicit exclusions or named alternatives, 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?

Goes well beyond the annotations (which only declare non-read-only, non-destructive, closed-world, non-idempotent): discloses that the raw email is parsed by an AI model, that fingerprints and extracted fields are retained rather than the email, that payout happens within 2 business days post-stay via Stripe/PayPal, that the email address is deleted after 6 months, and that fraudulent claims or exhausted budgets can be refused.

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 operative instruction is correctly front-loaded, but roughly two-thirds of the text is verbatim legal/terms copy plus a privacy URL. That block is functionally motivated (the agent must show it to the user) yet makes the description long and hard to scan for the actual call contract.

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 6 parameters (5 required), full schema coverage, an output schema, and rich annotations, the description supplies everything else an agent needs: eligibility, timing, consent gating, what to pass verbatim, what happens after submission, and how payment is delivered.

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, but the description adds real meaning: it prescribes the literal terms_version string, defines statement as the user's own quoted words without names or contact details, and explains payout_email as the destination for a Stripe bank-transfer link or PayPal payment after the stay.

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?

Starts with a specific verb and resource: claim the cashback, with the triggering object (the hotel's booking confirmation email, exactly as received). Preconditions (booked the accepted-offer hotel, before reference code expiry) make it clearly distinct from the sibling reads (haggl_hotel_cashback_get) and writes (haggl_hotel_cashback_add_trip, _stay), though no sibling is named 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?

States the exact window in which to call (after booking, before the reference code expires), the prerequisite (the user accepted the agent's offer), and an explicit gate: show the user these conditions first and call only if they agree. It also front-loads the sequence constraint, so the agent knows not to fire this pre-booking.

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 fully covered structurally. The description adds that the call yields a status plus next-step information, which is modest extra value; it says nothing about authorization requirements or what happens for an unknown claim_id.

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

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

A single front-loaded sentence with no filler; the resource and outcome are stated immediately. It is arguably slightly too terse for a tool with two required identifiers, but nothing is redundant.

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 rich annotation set and an output schema, the description needn't explain return fields, and it correctly signals the response concept (status, next steps). However, for a tool sitting among many cashback siblings, it leaves the agent without enough to know when this is the right call versus claim/quote/stay.

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 baseline of 3 applies. The description only echoes that the claim is made 'with the user's haggl ID' and adds no format, sourcing or relationship detail for claim_id beyond what the schema states.

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

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

Specific verb ('Read') plus a specific resource ('a hotel cashback claim') scoped by the user's haggl ID. It doesn't name or contrast any of the nearby siblings (haggl_hotel_cashback_claim, _quote, _stay), so the differentiation comes only from the noun phrase, not explicit routing.

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

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

The phrase 'its status and what comes next' implies this is a follow-up lookup on an existing claim, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the alternative siblings that create or advance a claim.

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 declare this is a non-readonly, idempotent, non-destructive write; the description goes beyond that by explaining the downstream consequence ('haggl.ai sends the cashback within 2 business days') and the fidelity requirement. It doesn't cover failure modes or what happens if the email doesn't prove the stay, so it's not 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?

Two sentences, no waste, with the trigger condition front-loaded and the payoff (cashback timing) second. Every clause adds information an agent needs.

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

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

An output schema exists, so return values needn't be explained, and the description supplies the key context an agent needs: when to call it and what it unlocks. Minor gaps remain around error/edge cases (e.g., email that doesn't prove the stay).

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 each parameter already carries a description, including the byte-for-byte requirement on raw_mime_b64 and the pointer to haggl_hotel_cashback_claim for claim_id. The description's 'exactly as received' largely restates the schema, 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 — send the hotel's post-stay email (receipt/folio, thank-you, or review request) — plus the timing ('after the user checked out'). This distinguishes it from the adjacent cashback tools (claim, get, quote) that also appear among the 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?

The 'After the user checked out' clause gives a clear triggering condition, and referencing the email 'exactly as received' implies the input source. It stops short of explicitly naming a sibling alternative or stating when not to use this tool, which keeps it at a 4.

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), so credit is for extra context: the list is not exhaustive because vendors can opt out, and it is not a ranking or recommendation despite paid plans. This is genuinely useful framing not present in structured fields.

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

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

Front-loaded with the core purpose, then caveats, then the usage rule. The middle clause about haggl.ai running sales agents and paid plans is slightly verbose but earns its place by motivating the 'not a ranking' caveat.

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 annotations covering safety, the description need not explain return values or pagination. It covers inclusion criteria, completeness limits, and usage, leaving only minor gaps such as pagination over a potentially large vendor list.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond the schema; baseline 4 applies. No parameter-related claims are made or 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?

States a specific verb+resource (list vendors) and sharply scopes it: vendors that accept AI-agent price negotiations through haggl.ai, with the concrete inclusion condition (Shopify app installed or snippet detected). It does not explicitly distinguish itself from close siblings like haggl_search_catalog or haggl_search_discounts, 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?

Provides a clear trigger and an explicit exclusion: use it when the user asks for a discount or wants to negotiate, not for a purchase at the listed price. It does not name the alternative sibling to use in the purchase case, leaving that 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 declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description need not repeat safety. It adds useful behavioral context: the confirmation link is valid for 30 minutes, the operation returns a pending state until confirmed, and the next call depends on the returned confirmation. It does not cover edge cases like expiration or retries.

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 front-load the action, its condition, and the follow-up procedure. Every sentence adds necessary information 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 zero-parameter schema, rich annotations, and the presence of an output schema, the description supplies all the agent needs to use the tool correctly: purpose, usage condition, link validity, pending state, and the required next step. No key detail 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 tool takes no parameters, so the baseline of 4 applies. The description does not need to explain parameter semantics, and the empty schema is fully self-contained.

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: getting a link for the user to read and confirm haggl ID consent. It distinguishes itself from siblings by saying it is used when the user is not in the conversation, and it names the follow-up tool haggl_create_haggl_id.

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 when to use the tool ('when they are not in this conversation to agree to it'), what to do with the output ('Send them confirm_url'), and what to call next after confirmation ('call haggl_create_haggl_id with the returned confirmation'). This leaves little ambiguity for an agent.

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 safety is covered; the description adds real behavioral context beyond that by disclosing that results branch into three catalog types (store/campaign/quote) with different shapes and a how_to_ask field that dictates the follow-up call. It does not mention pagination or auth needs, keeping it below a top score.

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

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

Front-loads the core action and purpose in the first clause, then uses one tight sentence per catalog type. Every sentence carries distinct information about how to build the next call; nothing is restated from the schema or annotations.

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, the description need not explain return fields, and it correctly focuses on the interpretation an agent still needs: which catalog flavor was found and what payload shape to use downstream. It is nearly complete, missing only error/empty-result behavior.

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

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

Schema description coverage is 100%, so all four parameters (vendor_id, query, limit, collection) are already documented; the description's detail about handles, variant_ids and recipes describes results rather than input parameters. It neither compensates for nor extends the schema, 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+resource ('Search a vendor's catalog') and adds the downstream reason ('so the offer can name exact products'), which separates it from haggl_list_vendors and haggl_search_discounts by making clear it reaches a single vendor's product inventory. It stops short of naming an alternative sibling explicitly, so it is clear but not sibling-differentiated by name.

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 the triggering context (needed when an offer must name exact products) and a concrete next step ('follow the how_to_ask field of the result'). It never states when NOT to use it or which sibling to prefer for a different need, so it is clear context without 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?

Goes well beyond the readOnly/idempotent annotations: it explains that offers are merchant-funded and capped, that a merchant may return no offer, and that an empty list means 'not on haggl.ai' rather than 'no discount exists anywhere'. It also discloses the brand-fallback behavior and warns that alternatives must never be presented as that brand, plus the vendor_id handoff to haggl_start_negotiation and where the code goes on approval.

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

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

Front-loads the core purpose and trigger, then layers caveats. It is on the long side at eight sentences, and the final checkout/discount-field instruction is more workflow guidance than tool semantics, but nearly every sentence carries decision-relevant information and nothing is redundant.

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

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

An output schema exists, yet the description still surfaces the parts of the result an agent must act on (vendor_id, the brand field, empty-list meaning). Given a single-parameter read tool, there is nothing material an agent would need that 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?

Only one parameter, and schema description coverage is 100% — the schema already says 'A business name, website (e.g. "degrenne.fr") or kind of product.' The description restates those accepted input forms without adding syntax, normalization or format rules beyond the schema, so it lands at the baseline.

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

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

States a specific verb and resource — 'Find merchants that run a sales agent on haggl.ai' — with the searchable keys (business name, website, kind of product) spelled out. It does not name the closest siblings (haggl_list_vendors, haggl_search_catalog) to differentiate itself, so the agent must infer that this is the offer-oriented merchant search rather than a catalog search.

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 an explicit trigger ('Only when the user asks for a discount, a coupon, a promo code or a lower price') and an explicit exclusion ('a purchase at the listed price is not a request for one'). It also routes the agent away from this tool for product discovery and checkout, pointing at the shopping/checkout tools 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?

The description adds useful operational context beyond the annotations: it creates a new session, returns contextual guidance and permitted actions, and requires no customer-profile selection. The non-destructive but non-idempotent behavior is covered by annotations, so the remaining gap is minor.

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 four tight sentences with no wasted text. The purpose is front-loaded, followed by return behavior and the key routing condition.

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 that an output schema exists and annotations cover safety hints, the description provides everything an agent needs: what the tool starts, what it returns, when not to call it, and where to go instead.

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 each parameter is already documented in the input schema. The description does not add parameter-level meaning beyond implying that session.id should be reused by haggl_submit_offer, so it sits at the baseline for fully documented schemas.

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: 'Start a price negotiation with a vendor.' It also clarifies the return shape and explicitly routes agents away from this tool when a session already exists, distinguishing it from haggl_submit_offer.

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 an explicit exclusion condition: skip this tool if REST initialization already returned a session, and pass that session.id to haggl_submit_offer. It also states that no customer-profile selection is required, removing a likely prerequisite question.

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 it is non-read-only, non-idempotent, and non-destructive, so the agent knows this is a mutating submission. The description adds useful behavioral context beyond that: omission of data is allowed, context can be supplied in later rounds, and the result may be authorized terms or no offer with contextual guidance and permitted next actions. It doesn't explain non-idempotency risks or the state-changing effect in detail, but it covers the key negotiation semantics.

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

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

Three sentences, front-loaded with the core action, followed by practical omission guidance and return outcomes. There is no redundant or wasted text.

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 full schema coverage, an output schema, and annotations, the description supplies the needed behavioral essentials: data can be omitted, later rounds matter, and outcomes may be terms, no offer, or next actions. It is nearly complete, though it could briefly clarify the non-idempotent nature of repeated submissions.

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 all six parameters thoroughly. The description only indirectly touches on the optionality of 'data' and evidence; it adds no syntax, format, or conditional guidance beyond what the schema provides, matching the baseline for high-coverage schemas.

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 ('Request a quote'), making the tool's function immediately clear. However, it does not name or differentiate itself from siblings like haggl_accept_offer, haggl_get_bids, or haggl_get_negotiation, leaving the agent to infer its exact role in the negotiation flow.

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 implies usage by noting that buyer data and evidence can be omitted and supplied later in remaining rounds, which gives some practical guidance. But it never explicitly states when to use this tool instead of alternatives, nor does it mention prerequisites or conditions for not using it.

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