Skip to main content
Glama

iDevice Buyer's Guide

Pick between two or three products

pick_between
Read-onlyIdempotent

For two or three products, which one the written buy-or-wait rules put ahead, or that neither is ahead, optionally for a shopper who owns a device or uses iPhone or Android, with a budget. Each product comes with its verdict (buy_now, wait, skip, check_fit or not_enough_data), its fit with the phone given, today's retailer price and the reasons, each with its source and how sure iDevice is. A product that does not work with the phone given goes last; then the verdict decides, then the fit answer. Price alone does not put one ahead. When the rules leave two products level, review_tiebreak says whether outlets' published review scores separate them (at least two independent outlets that reviewed each, all one way, a clear margin) and lists the themes reviewers agree on, each with the outlets that reported it. purchase_today and product_for_you split the answer in two: the better purchase today on the rules, and the better product, named only on the phone or fit answer or on outlets' review scores, else No clear winner; where the companies' own figures lean one way, product_for_you says which product leads on which criteria, conditionally, and names no winner (lead null). A lead on the verdict alone (lead_basis timing) is about when to buy, not which product is better; a product that only reads BUY NOW or FINE TO BUY against NO RUSH is not a lead, and a product whose answer is not_enough_data (NEWER MODEL OUT, NOT ENOUGH DATA) is not out-bought unless the other product is its own newer model already out. The same comparison as the decision card on idevice.com. A line slug (for example 'samsung-galaxy-ring') names the line's newest model; when that model is not on sale the answer is for the newest model of the line that is, and resolved_to says which and why. With buyer_context, the answer also carries buyer_decision: the personal answer the idevice.com decision page for the same question gives for that context (a recommendation class, its rule_id, the decisive factors, the trade-offs, what would change it and what is unknown, each with its evidence), and buyer_decision_info with the same answer in plain words and the page it belongs to. buyer_decision.base_answers are that page's own answers, which can differ from this tool's answer for a phone platform or a budget given as arguments.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "product_slugs": "<product_slugs>"
    },
    "name": "pick_between"
  }
}

Input Schema

NameRequiredDescriptionDefault
budget_usdNoA price ceiling in US dollars
buyer_contextNoOptional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: "buyer-context-v1", context, provenance }. context: currency "USD", risk_tolerance "normal", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: "phone_platform", value: "iphone" or "android" }, { id: "no_subscription", value: true }, { id: "max_budget", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency "USD", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, "hard_constraints:<id>": "selected" when the shopper stated it; a hard constraint without "selected" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log.
product_slugsYesTwo or three product_slugs, e.g. ['oura-ring-4','samsung-galaxy-ring-1']
owned_platformNoThe phone platform the shopper uses
owned_device_slugNoA product_slug of a device the shopper already owns, e.g. 'iphone-17'

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / buyer_context
      Added value: +{
      +  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      +}
  2. Changed1 schema field changed
    • removedInput schema / properties / buyer_context
      Removed value: -{
      -  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      -}
  3. Changed1 schema field changed
    • addedInput schema / properties / buyer_context
      Added value: +{
      +  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      +}
  4. Changed1 schema field changed
    • removedInput schema / properties / buyer_context
      Removed value: -{
      -  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      -}
  5. Changed1 schema field changed
    • addedInput schema / properties / buyer_context
      Added value: +{
      +  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      +}
  6. Changed1 schema field changed
    • removedInput schema / properties / buyer_context
      Removed value: -{
      -  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      -}
  7. Changed1 schema field changed
    • addedInput schema / properties / buyer_context
      Added value: +{
      +  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      +}
  8. Changed1 schema field changed
    • removedInput schema / properties / buyer_context
      Removed value: -{
      -  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      -}
  9. Changed1 schema field changed
    • addedInput schema / properties / buyer_context
      Added value: +{
      +  "description": "Optional. The shopper's own situation, in the closed grammar of the form on the idevice.com decision pages: { context_version: \"buyer-context-v1\", context, provenance }. context: currency \"USD\", risk_tolerance \"normal\", urgency (today, within_30_days, within_90_days or can_wait), priorities (up to three { id, importance }, importance must_have, high or medium; an id is a use or buying criterion the page can weigh, such as sleep, fitness or battery_life), hard_constraints (up to three: { id: \"phone_platform\", value: \"iphone\" or \"android\" }, { id: \"no_subscription\", value: true }, { id: \"max_budget\", value: a dollar amount }), cost_inputs (up to three { kind: offered_price, trade_in or required_accessories, amount, currency \"USD\", explicit_zero }), and optionally platform, expected_ownership_months (12, 24, 36 or 48), owned_condition and ecosystem_switch_willingness. Amounts are numbers from 0 to 100000 with at most two decimals. provenance: for each hard constraint, \"hard_constraints:<id>\": \"selected\" when the shopper stated it; a hard constraint without \"selected\" is not applied. The products come from this call's own arguments. A context outside the grammar is answered with buyer_decision_info naming the fields to fix, and the rest of the answer is unchanged. The context is used for this one answer and then dropped: it goes into no log."
      +}
  10. Changed1 schema field changed
    • changedInput schema / properties / product_slugs / description
      Previous value: -"Two or three product_slugs, e.g. ['oura-ring-4','samsung-galaxy-ring']"New value: +"Two or three product_slugs, e.g. ['oura-ring-4','samsung-galaxy-ring-1']"
  11. Added

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered; the description goes further with genuinely useful behavior: tie handling via review_tiebreak, the purchase_today vs product_for_you split, the rule that a lead_basis timing lead 'is about when to buy, not which product is better', the line-slug resolution via resolved_to, and the explicit privacy promise that buyer_context 'goes into no log'. It even documents error behavior for a context outside the grammar. It stops short of describing result size or performance, but the disclosure is well beyond the annotation baseline.

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

Conciseness2/5

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

One roughly 350-word run-on block with no line breaks, headings or bullet structure; clauses like 'a product that only reads BUY NOW or FINE TO BUY against NO RUSH is not a lead' are buried mid-paragraph. The opening does front-load the core purpose, and most sentences carry non-redundant information, but the density makes it hard to scan and several qualification clauses could be condensed.

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?

With no output schema, the description carries the full burden of describing return values, and it does: verdict classes, fit, retailer price, reasons with sources, review_tiebreak contents, the purchase_today/product_for_you split and buyer_decision structure. Combined with 100% schema coverage on inputs, only the failure/edge behavior for missing products is left implicit.

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 the baseline is 3, and the description does not restate the parameters. It does add real meaning in places – how a line slug resolves to a model, what buyer_context unlocks (buyer_decision, buyer_decision_info, base_answers that 'can differ from this tool's answer') – but it never explains budget_usd vs the max_budget hard constraint or how owned_device_slug relates to owned_platform, which are the ambiguities an agent actually faces.

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?

The opening clause states a specific operation: for two or three products, which one 'the written buy-or-wait rules put ahead, or that neither is ahead'. It also anchors the result to 'the decision card on idevice.com', giving an agent a concrete mental model. It never names a sibling such as compare_products or should_i_buy, so the agent must infer differentiation from behavior rather than a routing statement.

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

Usage Guidelines3/5

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

Usage is implied by the input shape (2-3 slugs, optional owned phone/budget) and by statements about what happens under buyer_context, but there is no explicit 'use this when X, use compare_products/should_i_buy when Y'. The ordering rules (compatibility last, then verdict, then fit; 'Price alone does not put one ahead') read as output semantics rather than when-to-call guidance. The reader must reconstruct the use case.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.