haggl.ai

haggl_get_bids

Have the merchants on haggl.ai in one shopping category (for example travel) bid for the user at once, from their haggl ID record, without new proof. Works once the record holds a verified purchase in that category (from an earlier offer with signed email proof); otherwise it says so and returns no bids. Each bid is a merchant's own offer, funded by the merchant, with an accept_url; show the user each one with its personalized_price_notice, and its algorithmic_price_disclosure when it has one (users in New York), word for word next to the price, and accept only with their approval.

Input Schema

Name	Required	Description
`query`	No	What the user is after, e.g. "hotel in Barcelona, 4 nights in December". Sets the category when category is omitted.
`category`	No	Optional: the brand index category, e.g. "travel".
`haggl_id`	Yes	The user's haggl ID.

Output Schema

Name	Required	Description
`bids`	No	Merchants' offers. Show each with its algorithmic_price_disclosure (users in New York) and personalized_price_notice word for word; accept only with the user's approval.
`code`	No	Present only when the call failed: a machine-readable error code, e.g. quote_uncertain or rate_limited.
`note`	No	Why there are no bids, when locked.
`error`	No	Present only when the call failed: what went wrong.
`label`	No	Category name.
`category`	No	The shopping category.
`recovery`	No	When the outcome is uncertain: the tool and session_id to read before retrying.
`unlocked`	No	Whether the record holds a verified purchase in this category; when false, bids is empty.
`retryable`	No	Whether the same call may be retried.
`how_it_works`	No	The flow, step by step.
`retry_after_seconds`	No	When rate limited: seconds to wait before retrying.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 29, 2026

changedOutput schema / properties / bids / description

Previous value: -"Merchants' offers. Show each with its algorithmic_price_disclosure and personalized_price_notice word for word; accept only with the user's approval."New value: +"Merchants' offers. Show each with its algorithmic_price_disclosure (users in New York) and personalized_price_notice word for word; accept only with the user's approval."

changedOutput schema / properties / bids / items / properties / algorithmic_price_disclosure / description

Previous value: -"Show word for word, next to the discount."New value: +"For a user in New York: show word for word, next to the discount."

Changed2 schema fields changedOct 19, 2026

changedOutput schema / properties / bids / description

Previous value: -"Merchants' offers. Show each with its personalized_price_notice; accept only with the user's approval."New value: +"Merchants' offers. Show each with its algorithmic_price_disclosure and personalized_price_notice word for word; accept only with the user's approval."

addedOutput schema / properties / bids / items / properties / algorithmic_price_disclosure

Added value: +{
+  "description": "Show word for word, next to the discount.",
+  "type": "string"
+}

First observedOct 16, 2026

TDQS

A4/5.0

Behavior5/5

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.

Conciseness3/5

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.

Completeness4/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 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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

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?