haggl.ai

haggl_accept_offer

Idempotent

Accept the vendor's offer and lock in the deal. Consequential: only call after the buyer has approved this exact offer, every time. Provide the offer version the buyer reviewed and approved; a changed offer needs a new approval. Read state.acceptance_effects and state.commits_purchase first: merchant handoff effects may be unknown. haggl.ai never takes payment: any payment happens at the merchant's checkout, under the merchant's terms and refund policy. A returned checkout link alone does not establish payment or enrollment completion. Accepting the same offer version again returns the same result.

Input Schema

TableJSON Schema

Name	Required	Description
`round`	No	Legacy offer round. If supplied it must match the current or already reserved offer.
`session_id`	Yes	Session id of the negotiation to accept.
`expected_offer_version`	Yes	state.offer_version from the quote reviewed and approved by the buyer.

Output Schema

TableJSON Schema

Name	Required	Description
`code`	No	Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited.
`error`	No	Present only when the call failed: what went wrong.
`state`	No	Canonical negotiation state. Follow allowed_actions.
`rounds`	No	Each round: the offer and when it was made.
`status`	No	Session status.
`support`	No	Who the buyer deals with after acceptance.
`guidance`	No	What this merchant values, as contextual guidance. Evidence is optional.
`recovery`	No	When the outcome is uncertain: the tool and session_id to read before retrying.
`retryable`	No	Whether the same call may be retried.
`vendor_id`	No	Vendor id.
`created_at`	No	ISO 8601 time the session started.
`expires_at`	No	ISO 8601 time the session expires.
`max_rounds`	No	Most quote rounds in this session.
`next_steps`	No	After acceptance: how the buyer redeems the offer (checkout_url, coupon_code, reference, expires_at, …).
`session_id`	No	Negotiation session id.
`current_offer`	No	The merchant's offer for the requested items. Merchant engines may add fields.
`current_round`	No	Rounds used.
`accepted_offer`	No	The merchant's offer for the requested items. Merchant engines may add fields.
`context_received`	No	The buyer context fields received so far and their provenance.
`rounds_remaining`	No	Rounds left.
`retry_after_seconds`	No	When rate limited: seconds to wait before retrying.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All haggl.ai tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?