haggl.ai

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

Adds substantial context beyond the annotations: haggl.ai never takes payment (payment occurs at the merchant's checkout under merchant terms), a returned checkout link does not prove payment or enrollment, and repeating the same offer version returns the same result (consistent with idempotentHint=true). This is exactly the kind of effect/edge-case disclosure a consequential, open-world action needs.

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 imperative purpose is front-loaded and every sentence carries operational weight. It is on the long side and slightly repetitive (payment caveat restated across two sentences), but the density is justified for a purchase-committing action.

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 need no explanation; the description instead covers the things that schema cannot: approval preconditions, side effects to read first, payment semantics, and idempotency scope. Nothing an agent needs before calling 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 100%, so the baseline is 3, but the description adds genuine meaning for expected_offer_version — it must be the version the buyer reviewed and approved, and a changed offer invalidates it. It says nothing about the optional legacy 'round' parameter, which is the only gap.

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 — accept the vendor's offer and lock in the deal — with the consequential nature called out immediately. It is clearly distinguishable from sibling actions like haggl_submit_offer or haggl_get_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 approved this exact offer, supply the reviewed/approved offer version, and a changed offer requires a new approval. It also directs the agent to read state.acceptance_effects and state.commits_purchase first when merchant handoff effects may be unknown.

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, idempotentHint=false and destructiveHint=false, but the description adds substantial non-obvious behavior: the ID is returned only once, anyone holding it can read or delete it, it expires 12 months after last use, only a fingerprint is stored, consent can be withdrawn via deletion, and record-sharing with merchant sales agents is authorized. This goes far beyond the annotation surface.

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 verbatim consent disclosure earns its place because it must be shown to the user, but it is a large block that buries the remaining routing instructions ('If they decline...' and the standing-instruction rule) after dozens of sentences. Key procedural guidance for the agent appears in the final third rather than being 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?

For a consent-gated creation tool with an output schema, the definition covers everything the agent needs: the prerequisite disclosure, the accepted consent-proof paths, the fallback tool, post-call handling of the ID, expiry, and deletion semantics. Return values are covered by the output schema and need not be repeated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates schema content (channel semantics, quoting the user's words without contact details, consent_version value, confirmation as an alternative to consent_version/statement), adding little parameter-level meaning beyond what the schema already documents.

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 states a specific verb and resource ('Create a haggl ID for the user') and immediately explains the purpose ('so offers and codes from different merchants stay together and can be read back later'). Combined with the named alternative haggl_request_haggl_id_confirmation, an agent can distinguish it from siblings 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?

Explicit when-to-use and when-not-to-use: show the consent text first, call only on agreement, 'If they decline, go on without a haggl ID', and route to haggl_request_haggl_id_confirmation when the user cannot read the text in-conversation. The standing-instruction path is also specified. Nothing 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?

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?

Annotations declare this is not read-only and not idempotent, and the description adds substantial non-structured context: the verified-purchase prerequisite, the empty-bid fallback, that each bid is merchant-funded with an accept_url, and the user-approval requirement before acceptance. It does not disclose side effects of repeated calls (non-idempotency) or rate/limit characteristics, but the additions go well beyond the 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 main action is front-loaded in the opening clause, and the following sentences carry real information (precondition, fallback, bid structure, approval rule) rather than filler. It is dense but each clause earns its place, with only mild redundancy around the category example.

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 shape need not be re-explained, yet the description usefully summarizes the bid contents (accept_url, personalized_price_notice). Preconditions, fallback behavior, and the approval gate are all covered, leaving only the multi-call/non-idempotent behavior unaddressed.

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 query, category, and haggl_id, including that query sets the category when omitted. The description echoes the category concept with a 'travel' example but adds no format or constraint detail the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

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 action (have merchants in one category bid at once) tied to a specific resource (bids from the user's haggl ID record), and the word 'at once' conveys the broadcast nature that separates it from retrieval tools like haggl_get_my_offers. It stops short of naming any sibling explicitly, so cross-tool disambiguation 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?

Gives a clear precondition ('works once the record holds a verified purchase in that category') and the failure behavior ('otherwise it says so and returns no bids'), plus a post-condition rule to accept only with user approval. It never names an alternative tool (e.g. haggl_start_negotiation) for the precondition-not-met case, so routing guidance is incomplete.

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, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the ordering behavior ('newest first') and the breadth of linked objects, which is genuinely useful, but with an output schema present it leaves return details to be discovered there.

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 sentence, tightly front-loaded on the verb and scope, with the returned contents and sort order packed in without filler. Every clause carries 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?

With a rich annotation set, a fully documented single parameter, and an output schema to describe returns, the description supplies enough to call the tool correctly. The only real gap is the absence of explicit sibling routing, which is minor at this 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 coverage is 100% with a single required haggl_id already documented as 'The user's haggl ID.' The description only repeats that framing and adds no format, sourcing, or validation 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 (Read) and resource (what haggl.ai holds for the user's haggl ID), and enumerates the payload: creation time, negotiations, offers, codes. It is distinguishable from haggl_get_negotiation and haggl_get_bids by being the aggregate for the whole ID, though it never names those siblings 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?

The phrase 'for the user's haggl ID' implies a broad, account-level read, but there is no explicit when-to-use guidance or routing against nearby siblings like haggl_get_negotiation (single negotiation) or haggl_get_bids (bids only). Usage must be inferred from the scope wording.

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 safety profile is covered. The description adds meaningful behavior beyond that: it returns canonical state plus permitted actions (routing-relevant), and explicitly states it does not open another session, clarifying that no side effects occur.

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, zero waste. The return contents are front-loaded and the usage triggers and non-side-effect note follow immediately; nothing needs trimming or reordering.

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-value structure need not be spelled out, and the description still summarizes what comes back (state, offer version, guidance, permitted actions). Combined with the when-to-use triggers and no-side-effect note, the definition is complete enough for the agent to call it correctly.

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

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

Only one parameter (session_id) with 100% schema description coverage, so the schema fully documents the input. The description says 'existing negotiation' which confirms it must reference a prior session, but adds no format or syntax 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?

Specific verb ('Read') plus resource ('negotiation'), and it enumerates what is returned: canonical state, current offer version, guidance and permitted actions. It also distinguishes itself from siblings by stating 'this does not open another session,' clearly separating it from haggl_start_negotiation.

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 when-to-use triggers ('after human changes, reloads, transport switches or uncertain results') that tell the agent this is a refresh/re-sync call. It does not name specific alternative sibling tools for those scenarios, but the context is unambiguous.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, yet the description adds substantial context: offers are merchant-funded and limit-bound, a merchant may have no offer, an empty list means nothing matched on haggl.ai (not that no discount exists), and unmatched brands return a brand field with category alternatives.

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 purpose then usage, then behavior and next steps with no filler sentences; it is dense and somewhat long, but each clause carries actionable information about result semantics or workflow.

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 an output schema exists, the description still covers empty-result interpretation, brand-fallback behavior, merchant funding limits, and the negotiation handoff, leaving nothing an agent needs to select or correctly invoke the 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?

With a single parameter at 100% schema description coverage, the schema already documents the query field fully. The description largely restates that query accepts a business name, website, or product kind, adding no syntax or format detail beyond the schema 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') and the query axes (business name, website, product kind), which clearly distinguishes it from siblings like haggl_list_vendors and haggl_search_catalog.

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 scopes when to use it ('Only when the user asks for a discount, a coupon, a promo code or a lower price; a purchase at the listed price is not a request for one') and names the downstream tool (haggl_start_negotiation) plus other tools to keep using for shopping/checkout.

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=false, idempotent=false, destructive=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns contextual guidance, current permitted actions, and a new session id, and states no customer-profile selection is needed. It does not mention auth requirements or rate limits, keeping it just short of 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 core purpose, then the return shape, then the routing rule. Efficient overall, though describing the return payload is somewhat redundant given an output schema exists, so it slightly exceeds the minimum needed.

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 4-param, nested-object tool with full schema coverage, complete annotations, and an output schema, the description supplies purpose, return summary, a precondition, and the alternative flow. It is essentially complete; only deeper operational details (auth/limits) are absent, which is acceptable here.

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% with 4 well-documented parameters, so the schema already carries the parameter meaning. The description only adds the 'no customer-profile selection' constraint, which is marginal beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('Start a price negotiation with a vendor') and explicitly separates itself from a named sibling by instructing the agent to skip it and pass session.id to haggl_submit_offer when REST init already returned a session. An agent can distinguish this from the other negotiation siblings without opening schemas.

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

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

Gives an explicit when-not condition ('Skip this tool if REST initialization already returned a session') and the concrete alternative action (pass session.id directly to haggl_submit_offer). It also clarifies a precondition ('No customer-profile selection is required'), leaving little 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 safety profile (mutation, non-destructive, non-idempotent, closed-world), so the description's burden is lower. It still adds real value by describing outcomes ('Returns authorized terms or no offer, contextual guidance and permitted next actions') and the round-based context model, going beyond the structured fields.

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

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

Front-loaded with the core action in the first sentence, followed by two tight sentences covering optional inputs and returns. No filler, though the name/description mismatch ('submit_offer' vs 'request a quote') is a minor structural wrinkle.

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-value detail is already covered, and the description nonetheless summarizes the outcome shape and the negotiation-round model. Combined with 100% schema coverage and annotations, an agent has everything needed to invoke this 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%, so the schema already documents all four parameters in depth, including the nested ask/data shapes. The description touches on omitting `data` but adds no syntax or format beyond the schema, making the baseline 3 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 action ('Request a quote') and ties it to the negotiation flow with existing context. It is clear on its own but does not differentiate itself from siblings like haggl_accept_offer or haggl_get_offers, so an agent still needs the negotiation context to place it precisely.

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 implied usage guidance ('Buyer data and evidence can be omitted; relevant additional context can be supplied later within the remaining rounds'), which helps an agent decide how to call it early in a session. However, it never states when to use this versus alternatives such as accept_offer or get_bids, leaving the choice to inference.

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