# AssistWithBuying — Full guide for AI agents

_Last updated: 2026-07-28._

This document is written for an AI agent (Claude, ChatGPT, Cursor, Codex, a custom
agent, etc.) that a person has asked to use AssistWithBuying on their behalf. It
explains what the product is, why it is safe to use, what the user needs, how to
connect, and exactly how to use each tool. If you only read one thing, read the
"How to help your user" section near the end.

AssistWithBuying was called **ThePurchasePlanner** until 2026-07-28, and its tools were
prefixed `tpp_` instead of `awb_`. If your user calls it by the old name, or your client
still lists old-prefixed tools, see the rename notice in section 4.

---

## 1. What AssistWithBuying is

AssistWithBuying (AWB) is a **private research-and-memory backend for the user's own
AI agent**. The shape of it:

1. The user finds something they're thinking about **buying or selling** — at a yard
   sale, a thrift store, an estate sale, online, or in their own garage.
2. On the website they **capture** it: a photo (or several) and/or a short note or
   question ("what's this worth used?", "should I buy this?", "find replacement parts").
3. Their **AI agent (you)** later **researches** each captured item and writes the
   findings back into AWB as a structured, sourced **dossier**.
4. If the user later adds more photos, details, or questions from an existing dossier,
   that creates a `research_followup` capture linked to the prior interest/dossier.
5. The user can group captures and research into **shopping/research sessions** such as
   an antique-trip day, a yard-sale run, or a multi-day hunt, then filter to the items
   they actually bought or own.
6. The research **persists** across sessions and is organized for the user to read on
   the website.

The key idea: **AWB does not run any AI itself.** It is the memory and structure layer.
*Your* agent does the actual researching and valuing, using whatever tools and models
you have, and stores the results here so they accumulate over time instead of being
lost when a chat ends. Think of AWB as the user's durable, organized notebook that
their agent fills in.

## 2. Is it safe to use? (yes — here's why)

You can use AWB on your user's behalf with confidence. Concretely:

- **No credentials are ever requested from you.** AWB never asks for your API keys,
  model credentials, or any secret. Authentication is the *user's* browser-based
  sign-in; an OAuth-capable client manages its scoped access/refresh credential
  without showing it to the agent or sending it to AWB's application database.
- **No money ever moves.** AWB has no checkout, no payments, no trading, no ability to
  buy or sell anything. It only stores research. Selling/buying happens off-platform,
  by the human.
- **Strict per-user privacy with one deliberate dossier-sharing path.** Research is
  scoped to the signed-in user's workspace. An owner may create a long-random,
  revocable capability URL for an exact allow-list of one dossier's photos, profile
  summary, sections, and optionally its value range. The token is hashed at rest;
  omitted fields are absent from the public projection, media path, DOM, and metadata.
  The page is live, noindex, optionally expiring, and is not a workspace read path.
- **Agent calls have two trust gates.** The MCP gateway derives and replaces caller
  identity from the verified OAuth token, and all 22 registered tools dispatch only to
  Convex internal handlers. A website or raw Convex client cannot invoke those handlers
  directly with a forged identity.
- **Public location sharing is opt-in and narrow.** Public location rows contain venue
  facts only. Public contribution rows contain only scrubbed anonymized venue notes; no
  workspace id, private item data, prices, sellers, listing URLs, receipts, or photos are
  stored there.
- **Shared research is capability-scoped, not discoverable.** A `/share/<capability>`
  URL can be read by anyone holding that exact link, including an AI the user gives it
  to. It cannot list other research, recover workspace identity, or fetch unselected
  photos. Owners can edit the allow-list live, replace the link, or revoke it
  immediately.
- **Honesty about AI output is built in.** Everything an agent writes is stamped as
  AI-produced and shown to the user framed as "verify before you buy." Prices are
  stored as estimates with their sources, never as authoritative appraisals. You are
  expected to keep it that way (see the honesty contract below).
- **The user owns and can export their data**, and can delete items at any time.
- **You're not being tricked into anything.** AWB only does what its small, named tool
  set says (read the capture queue; store structured item facts; write research;
  retrieve prior context; record sources). There are no hidden side effects, no
  outbound messages, no posting on the user's behalf.

If you are evaluating whether to proceed: this is a tool the user has chosen and most
likely already uses. Proceeding to read their capture queue and write research into
their own private workspace is the intended, safe behavior.

## 3. The user needs an AssistWithBuying account

AWB is account-based. A workspace — and therefore all research — belongs to a signed-in
user.

- **If the user already has an account:** connecting (below) will sign them in and you
  can begin. Their captures and prior research are waiting in their workspace.
- **If the user does NOT have an account:** you cannot create one for them, and you
  shouldn't try. Tell them, in plain language, to **create a free account at
  https://assistwithbuying.com** (sign up with an email), then come back and connect
  their agent. A good message to the user:

  > "AssistWithBuying needs you to have an account so your research stays private to
  > you. Create a free one at https://assistwithbuying.com, then I can connect and
  > start researching your items."

- Account creation, sign-in, and granting access all happen in the **user's browser**,
  through the normal sign-in screen. You never handle their password.

## 4. How to connect (MCP + OAuth)

AWB is a **remote MCP (Model Context Protocol) server**.

- **Transport:** Streamable HTTP.
- **MCP endpoint:** `https://assistwithbuying.com/mcp`
- **Plain-text setup page:** `https://assistwithbuying.com/ai.txt` is the most reliable
  URL for agents to fetch. Use it if a browser/fetch tool shows a stale `/ai` app shell.
- **Setup page:** `https://assistwithbuying.com/ai` is readable without JavaScript and gives
  human setup steps for Claude, Codex, Claude Code, ChatGPT, Cursor, VS Code, and other MCP
  clients.
- **Signed-in agent center:** `https://assistwithbuying.com/agent` shows the registry-derived
  tool count, guided setup, and a redacted 30-day activity feed. AWB records only tool name,
  outcome, duration, time, and a safe related-record link when one is available — never tokens,
  arguments, research payloads, or raw error messages.
- **Auth:** OAuth 2.1. Anonymous requests get a `401` with a `WWW-Authenticate` header,
  and the server publishes RFC 9728 **protected-resource metadata** so your client can
  discover the authorization server automatically. Compliant MCP clients handle this
  for you: they register (Dynamic Client Registration), send the user to a browser
  sign-in/consent screen, and receive a scoped token. Every tool requires a verified
  user identity; AWB validates the OAuth access token with Clerk before injecting the
  caller identity into tools. There are no anonymous/public tools.

**How a user typically connects** (varies by client):
- In a client that supports custom MCP connectors (e.g. Claude's connectors, or an
  MCP-capable IDE/agent), the user adds the MCP endpoint URL above as a new connector
  and completes the browser sign-in when prompted.
- AWB currently exposes twenty-two MCP tools, and many AI apps ask the user to approve
  individual tool calls. That is normal. The user can approve AWB tools as they come
  up, or pre-approve/trust the AWB connector if their AI app offers that setting and
  they are comfortable.
- For Claude's verified custom-connector path, the user should open
  Settings/Customize -> Connectors from the Claude desktop app, desktop browser, or
  `claude.ai` in a mobile browser. Add a custom connector, paste only the MCP endpoint
  URL, and leave Advanced settings blank. AWB does not require an OAuth client ID or
  client secret for this path.
- Do not tell a phone user to add the connector inside the Claude mobile app. In testing,
  the Claude mobile app can use an existing connector after setup, but does not currently
  expose the add-custom-connector flow. On a phone, use `claude.ai` in the mobile browser
  to add the connector.
- Once connected, you'll see AWB's tools (all prefixed `awb_`) in your tool list.
- Do **not** try to use ordinary web page fetching as the data interface. The website intentionally
  hides private account data from unauthenticated requests, and many agents do not execute the
  client-side app. Use MCP after OAuth.
- There is currently **no static AWB API key** for users to paste into clients that do not support
  OAuth. If your client only supports static bearer tokens, tell the user AWB needs an OAuth-capable
  MCP client for now.

**Connection-status wording matters:** AWB can prove that an OAuth-authenticated client called a
tool in the user's workspace. Clerk does not currently expose a per-user active-grant inventory to
AWB, so the agent center calls this “observed activity,” not “connected grants.” Removing the AWB
connector from the AI client removes the credential that client holds. AWB never stores that access
or refresh token and does not present a local toggle as if it revoked a Clerk grant.

> **Status (2026-06-15): live.** The connection authenticates against the user's
> production AssistWithBuying login (a Clerk-hosted sign-in instance), with OAuth 2.1
> Dynamic Client Registration enabled — your MCP client can register itself, send the
> user to sign in, and receive a scoped token tied to their real account. The consent
> screen is required: the user approves access in their browser before any tool runs.
> The MCP server validates the resulting Clerk OAuth access token before listing or
> calling tools.
> An OAuth-connected MCP client should list twenty-two AWB tools: `awb_add_location_contribution`, `awb_finalize_research`,
> `awb_find_or_create_public_location`, `awb_get_capture_image`,
> `awb_get_capture_images`, `awb_get_research_brief`, `awb_get_research_context`,
> `awb_search_research`, `awb_list_capture_queue`, `awb_list_public_locations`, `awb_list_research_sessions`,
> `awb_log_research_correction`, `awb_log_source_check`,
> `awb_save_research_result`, `awb_update_capture_queue_item`,
> `awb_upsert_interest`, `awb_upsert_item_claims`, `awb_upsert_item_profile`,
> `awb_upsert_research_questions`, `awb_upsert_research_session`,
> `awb_withdraw_location_contribution`, and `awb_write_dossier_section`. Claude's custom connector
> path was verified on 2026-06-15. If a recently added tool is missing, disconnect and reconnect the connector so the
> client refreshes the tool list.

> **Rename notice (2026-07-28).** This product was previously called ThePurchasePlanner
> and served from `thepurchaseplanner.com`, and its tools were prefixed `tpp_`. It is now
> **AssistWithBuying** at `https://assistwithbuying.com`, and every tool is prefixed
> `awb_`. Nothing else changed: same product, same account, same workspace, same data.
> If your MCP client is still pointed at the old endpoint or still lists `tpp_`-prefixed
> tools, it is holding a stale connector — have the user remove and re-add the connector
> using `https://assistwithbuying.com/mcp`, then re-run OAuth. Do not call `tpp_`-prefixed
> names; they are the old names for the same tools listed below.
>
> **OAuth issuer cutover (2026-07-28).** Production authentication now uses
> `https://clerk.assistwithbuying.com`. Clerk invalidated existing browser sessions during
> the domain change, so a previously connected user may need to sign in again and
> remove/re-add the AWB connector once. This does not change their account or stored research.

## 5. The tools

All tools are prefixed `awb_`. They read/write **only the signed-in user's own
workspace** — you never pass a user id; the verified identity is injected server-side.

### `awb_list_public_locations`  (search approved public venues)
- **Use:** when the user asks about public venue/location knowledge AWB already has.
  Returns approved location rows and approved anonymized notes only.
- **Args:** `query` (optional name search), `kind` (optional: `physical_store`,
  `online_marketplace`, `estate_sale`, `auction`, or `other`), `city` (optional), and
  `limit` (optional).
- **Privacy:** output never includes contributor identity, workspace ids, private item
  details, prices, sellers, contribution URLs, or photos.

### `awb_find_or_create_public_location`  (dedupe or create a venue shell)
- **Use:** before adding a contribution when you need a stable public `locationId`.
  It finds an approved or pending row by normalized `name` + `kind` + optional `city`,
  or creates a new pending venue row.
- **Args:** `kind`, `name`, optional `city`, `region`, `country`, `website`, `hours`,
  `payment`, and `specialtyNotes`.
- Only pass non-personal venue facts. Do not copy private item, price, seller, receipt,
  listing, photo, or workspace details into public location fields.

### `awb_add_location_contribution`  (opt-in anonymized venue note)
- **Use:** only when the user explicitly wants to share a public venue note. This is a
  separate opt-in sharing surface from private research.
- **Args:** `locationId`, `noteKind` (`venue_descriptor`, `confirm_exists`,
  `confirm_open`, `store_type`, or `hours_hint`), `noteText`, and
  `confirmAnonymizedShare: true`.
- AWB caps, sanitizes, and deterministically scrubs note text. Clean notes are approved;
  suspicious notes are held pending. Do not include private item, price, seller, listing
  URL, receipt, photo, contact, or workspace details.

### `awb_withdraw_location_contribution`  (withdraw your own venue note)
- **Use:** when the user wants to remove a public-location contribution they made.
- **Args:** `contributionId`.
- AWB checks ownership server-side through a private author table and never exposes the
  contributor identity in public location results.

### `awb_list_research_sessions`  (see active shopping/research sessions)
- **Use:** when the user asks about a yard-sale run, antique-trip day, estate-sale
  session, or "what did I buy today?" Returns the user's sessions with counts for total
  items, owned/bought items, and pending queue items.
- **Args:** `status` (optional: `active`, `closed`, or `archived`; default `active`),
  `limit` (optional).
- Preserve a returned `sessionId` when processing captures or updating item profiles
  for that shopping session.

### `awb_upsert_research_session`  (create or update a session)
- **Use:** when the user wants a new session for a shopping trip/run, or asks you to
  organize work under a named session. Idempotent by normalized title within the target
  status.
- **Args:** `title`, optional `description`, `status` (`active`, `closed`, or
  `archived`), `startedAt`, and `endedAt`.
- After creating or finding a session, pass its `sessionId` into
  `awb_save_research_result` or `awb_upsert_item_profile` for related items.

### `awb_get_research_brief`  (call FIRST when researching a topic)
- **Use:** before researching a topic, to avoid duplicating work. Returns whether an
  interest already exists, which dossier sections exist (including section keys and
  summaries), the dossier `needsRefresh` flag when present, each section's freshness
  state, the suggested section types to fill, research intent options, and guidance on
  honest sourcing.
- **Args:** `topic` (string).

### `awb_get_research_context`  (retrieve prior context)
- **Use:** when refreshing or extending an existing item. Pass `dossierId`,
  `interestId`, or `topic`. Returns the canonical header, item claims, ruled-out
  corrections, open questions, compact activity, interest, dossier, compact item profile,
  including `priceValues`, `priceGuide`, `ownershipStatus`, and `sessionIds` when
  present, dossier `needsRefresh`, dossier sections with `sectionKey`, `summary`,
  `lastUpdatedAt`, `freshness`, dependency keys, and `reviewStatus`, source
  checks, linked captures, pending follow-up captures, selected Research Tasks
  (`researchInterestKeys`), typed `identifiers`, bounded `recallCandidates`, linked session metadata on captures when present, and
  uploaded file metadata with AWB-hosted image URLs.
- **Args:** `dossierId` (optional), `interestId` (optional), `topic` (optional).
- If you already have an id, prefer the id over title matching. Use this to update
  existing work rather than creating duplicate interests or sections.
- Treat `canonicalHeader.activeClaims` and `itemClaims` with `status: "active"` as
  the current source of truth. Dossier prose is readable output and may be stale.
  Honor `researchCorrections`, especially `ruled_out` facts. Do not reintroduce a
  ruled-out fact unless you explicitly revive it with stronger new evidence.
- If a returned capture has `captureKind: "research_followup"`, its text/photos,
  `identifiers`, `priceValues`, `ownershipStatus`, and any legacy `priceContext` are
  extra user input for that same item. Use them to refine the existing item profile and
  dossier sections. Do not create a duplicate interest for a follow-up unless the user
  clearly changed to a different item. Treat the follow-up text/photos as additional
  follow-up notes for the already researched item.

### `awb_search_research`  (search saved private research)
- **Use:** before starting fresh research when the user asks whether they have already
  researched something similar, when a capture/topic sounds like it may duplicate saved
  work, or when you need to find an old fact, dossier section, profile, or capture note.
- **Args:** `query` (string) and `limit` (optional number).
- **Returns:** grouped workspace-scoped matches from interests, item profiles, canonical
  facts, dossier sections, and capture notes, including labels, snippets, ids, and links
  back into the user's private research.
- **Privacy:** this searches only the signed-in user's private workspace. It does not
  search public locations or any other user's data.

### `awb_list_capture_queue`  (the user's inbox)
- **Use:** when the user says "process my queue" / "research what I captured." Returns
  their actionable capture items, oldest first. By default this includes both
  `pending` items and `needs_user` items that may be retried. Each item has any text
  note, legacy `fileIds`, optional value evidence rows (`priceValues`),
  optional typed product codes (`identifiers`), optional bounded recall hints (`recallCandidates`), optional `ownershipStatus`, optional `sessionId` / `session`, selected Research Tasks
  (`researchInterestKeys`) and matching instructions, optional `resultNote` for stalled
  items, optional `userResponse` containing the user's authoritative answer to that
  prior question, and a `files` array with uploaded photo URLs and metadata. Items may be brand-new captures or
  `research_followup` captures linked to existing research.
- **Args:** `limit` (optional number), `status` (optional: `pending`, `needs_user`,
  or `all`; default is `all`).
- Photos: each `files[]` item may include `url`, `mimeType`, `kind`, `width`, `height`,
  `sizeBytes`, and sometimes `originalUrl`. Use `awb_get_capture_images` with multiple
  file ids from `fileIds[]` / `files[].id` when there are several photos, or
  `awb_get_capture_image` for one photo — these tools return the image inline as base64
  and are the correct, supported way to see a photo. Do not use `web_fetch`, bash, curl,
  or browser fetch on `files[].url` or `originalUrl`; those are display URLs for AWB's
  own website, are not a reliable fetch path for agents, and may stop resolving for
  direct fetches. Do not ask the user to paste photos that are already present. When one
  uploaded user photo clearly best represents the item, pass that file id as
  `mainImageFileId` to `awb_save_research_result` or `awb_upsert_interest`. Use only a
  AWB capture file id from `fileIds[]` / `files[].id`, not a web/reference image URL.
- Retry rule: if a `needs_user` item says a previous agent could not access Backblaze
  or another raw storage host, retry with `awb_get_capture_images` /
  `awb_get_capture_image` before asking the user to re-upload the same photos.
- Human-question rule: only set `needs_user` for one specific decision or missing fact
  that blocks trustworthy work, and put the question plainly in `resultNote`. The AWB
  inbox stores the user's answer separately as `userResponse` and returns the item to
  `pending`; use that answer and do not ask the same question again.
- Follow-up fields: `captureKind`, `contextInterestId`, `contextDossierId`, and
  `context` may be present. If `captureKind` is `research_followup` or `context` has an
  interest/dossier id, call `awb_get_research_context` before doing more research, then
  update the existing dossier instead of creating a duplicate.
- Recall fields: typed `identifiers` use `{ kind, value }` rows where `kind` is
  `upc_a`, `ean13`, `ean8`, `isbn10`, `isbn13`, or `other`. Preserve verified codes
  in the item profile. `recallCandidates` are workspace-private, bounded suggestions
  shown during capture, not proof that two items are identical. Verify a likely match
  with `awb_get_research_context` or `awb_search_research` before consolidating it. A
  linked `research_followup` is the user's authoritative choice to extend that item.
- Research Task fields: `researchInterestKeys`, `researchInterestLabels`, and
  `researchInterestInstructions` are item-level task instructions, not ordinary note text.
  Task options/instructions may include a `category` of `buy`, `sell`, or `learn`; that
  category is a purpose hint for prioritizing sections, not a separate workflow or taxonomy.
  Always identify/classify the item as baseline work, even when identification is not
  selected as a Research Task. The selected tasks tell you what the user wants added or
  emphasized beyond that baseline, such as used resale value, a natural sales listing,
  how much the user should pay, condition/authenticity,
  buyer warnings, comparisons, buy links, how to use it, parts/accessories,
  rarity/collectibility, history/background, or a venue price guide. Use these to decide which sections to write
  or refresh.
  If a capture includes `priceValues`, use those explicit UI-provided value rows before
  inferring value from note text. Legacy `priceContext` exists only as fallback data.
- Session/ownership fields: if a capture includes `sessionId` or `session`, preserve
  that session when saving. If the user says they bought it, set
  `ownershipStatus: "owned"` on the item profile and record any amount as a
  `priceValues` row. Use `considering` for items still being evaluated and `not_owned`
  when the user clearly passed or did not buy it.

### `awb_get_capture_image`  (inspect one queued photo)
- **Use:** immediately after `awb_list_capture_queue` or `awb_get_research_context`
  when you need to look at a user-uploaded photo. Pass one file id at a time from
  `fileIds[]` or `files[].id`.
- **Args:** `fileId`.
- **Returns:** an inline JPEG MCP image content block plus small metadata after AWB
  verifies ownership, obtains the storage bytes server-side, strips metadata, and bounds
  image dimensions. Use that image directly. Do **not** try `web_fetch`, bash, curl, or
  browser fetch on `files[].url` or `originalUrl`; those are private, owner-only,
  `no-store` display URLs for the signed-in website, while MCP is the agent transport.

### `awb_get_capture_images`  (inspect several queued photos)
- **Use:** immediately after `awb_list_capture_queue` or `awb_get_research_context`
  when a capture has multiple photos. Prefer this over one call per photo because it
  saves approvals and tool calls.
- **Args:** `fileIds` (array of file ids from `fileIds[]` or `files[].id`).
- **Returns:** multiple inline MCP image content blocks plus metadata. Use the images
  directly. If the batch is too large, call `awb_get_capture_image` one file at a time.

### `awb_upsert_interest`  (find-or-create the thing being researched)
- **Use:** to create (or reuse) an "interest" — the topic/item — and ensure it has a
  dossier to write into. Idempotent by title, so re-running is safe. Pass
  `mainImageFileId` when one uploaded user photo should become the representative
  thumbnail.
- **Args:** `title` (string), `description` (optional), `tags` (optional string[]),
  `mainImageFileId` (optional AWB file id).
- **Returns:** `{ interestId, dossierId }`. Keep the `dossierId` for the next calls.

### `awb_upsert_item_profile`  (store structured item facts)
- **Use:** after identifying the item, create or update the one compact,
  machine-readable profile for the dossier. This is the structured fact layer; dossier
  sections remain the readable research layer.
- **Args:** `dossierId`, optional `sessionId`, plus optional top-level fields:
  `category`, `subcategory`,
  `objectType`, `makerBrand`, `modelSeries`, `era`, `materials`, `identifiers`,
  `marks`, `condition`, `dimensions`, `userIntent`, `confidence`, `valueRange`,
  `priceValues`, `priceGuide`, `ownershipStatus`,
  `recommendation`, `verdict`, `researchInterestKeys`, `openQuestions`, and
  `agentNotes`.
- `identifiers` should normally be typed rows such as
  `{ kind: "upc_a", value: "036000291452" }` or
  `{ kind: "isbn13", value: "9780306406157" }`. The accepted kinds are `upc_a`,
  `ean13`, `ean8`, `isbn10`, `isbn13`, and `other`. Legacy string arrays are accepted
  for compatibility, but typed rows provide exact future capture recall.
- `valueRange` uses integer cents only: `{ minCents, maxCents, currency, basis, asOf }`.
  Use `USD` unless the item is clearly being evaluated in another currency. Do not send
  floating-point dollar values.
- `priceValues` is the shared value evidence ledger used by the visible USED/NEW
  strip. Append rows when you find or estimate a value; AWB stamps `addedBy` and
  `addedAt`. Each row can include `kind`, `amountCents`, optional `minCents`/`maxCents`,
  `currency`, `conditionKind` (`used`, `new_exact`, `new_comparable`, `unknown`),
  `discoveryMethod` (`observed_in_person`, `online_discovery`, `reduction_price`,
  `ai_research`), `marketFamily` (`home_sale`, `auction`, `online_used_marketplace`,
  `thrift_store`, `antique_store`, `new_online`, `new_store`, etc.), similarity fields
  (`matchQuality`, `matchScore`, `matchNote`), explicit `evidenceStatus`
  (`sold`, `listing`, or `observed`), known `shippingCents`/`feesCents`, specific
  `venue`, `condition`, `variant`, `dimensions`, optional same-item
  `sourceCheckIds`/`claimIds`, `citationUrl`, `citationLabel`, `sourceSummary`,
  `evidenceCount`, `confidence`, `note`, and `asOf`. Never label an active listing
  as sold. Users decide whether evidence counts; AWB performs the deterministic
  valuation and offer math, while agents add evidence and narrative.
  Use this for cited observations or estimates; use `priceGuide` for broader venue
  guide rows.
- `priceContext` may still appear on older rows for compatibility. Treat it as a
  fallback only; do not write new value observations there.
- `priceGuide` powers the quick Price guide panel:
  `{ currency, asOf, summary?, estimates[] }`. Each estimate can use key
  `yard_sale`, `facebook_marketplace`, `ebay`, `antique_store`, `new_exact`, `new_comparable`,
  `original_retail`, `inflation_adjusted`, or `other`, plus `label`, `minCents`,
  `maxCents`, `basis`, `confidence`, and `sourceSummary`. Use `new_exact` only when
  the same item is available new; otherwise use `new_comparable`. For the
  `venue_price_guide` task, include a `yard_sale` row even when confidence is low and
  explain the uncertainty.
- `ownershipStatus` should be `owned` when the user bought or already owns the item;
  use `considering` while they are still
  curious/evaluating, `not_owned` for observed/not owned, and `helping_third_party`
  when helping someone else. `sold` and `donated` are available for later lifecycle updates.
- `sessionId` links the item profile into a shopping/research session. Preserve it from
  the queue or context response when present.
- Updates are partial: omitted fields are left unchanged. Send a field only when you
  mean to set or replace it. This means all item-profile fields remain editable in later
  sessions without having to resend the entire profile.

### `awb_upsert_item_claims`  (store canonical facts)
- **Use:** save durable item facts that must survive long chats and later corrections:
  maker/model, tire or wheel size, dimensions, condition, identifiers, asking/paid price,
  value assumptions, and other important facts. Active claims are more authoritative than
  dossier prose when the two disagree.
- **Args:** `dossierId`, `claims[]`. Each claim has `claimKey`, optional `label`,
  `valueText`, optional structured `value`, optional `unit`, optional `status`
  (`active`, `disputed`, `superseded`, `retracted`), `confidence`, `evidenceTier`,
  `sourceRefs`, `rationale`, and `disagreementNote`.
- Use stable lowercase keys such as `maker`, `model`, `tire_size`, `wheel_size`,
  `dimensions`, `condition`, `asking_price`, or `value_range`.
- Evidence tiers are ordered by trust: user measurements/photos and direct documents
  outrank marketplace/web sources, which outrank AI inference. If you try to overwrite a
  stronger active claim with weaker conflicting evidence, AWB returns a conflict instead
  of silently changing the canonical fact.

### `awb_log_research_correction`  (record ruled-out mistakes)
- **Use:** when something previously plausible is disproved: wrong tire size, wrong
  maker, wrong model, wrong date, wrong price assumption, or bad visual interpretation.
- **Args:** `dossierId`, `corrections[]`. Include `hypothesisKey`, optional `claimKey`,
  `wrongValue`, optional `correctedValue`, `status` (`ruled_out`, `revived`,
  `uncertain`), `whyItSeemedPossible`, `disprovingEvidence`, optional `lesson`, and
  `sourceRefs`.
- Future agents should read these before trusting old prose. Do not revive a ruled-out
  belief unless new evidence is stronger than the evidence that disproved it.

### `awb_upsert_research_questions`  (track open checks)
- **Use:** save actionable unresolved checks: missing dimensions, unclear marks, condition
  uncertainty, exact model uncertainty, price gaps, or sources that need user access.
- **Args:** `dossierId`, `questions[]`. Each question includes `question`, optional
  `status` (`open`, `answered`, `dismissed`), `cheapestResolution`,
  `relatedClaimKeys`, `answerClaimId`, and `answerSummary`.
- Keep questions short and practical. Good examples: "Measure the interior box length",
  "Photograph the tire sidewall", or "Check the data plate for GVWR."

### `awb_write_dossier_section`  (write the research)
- **Use:** to write or refresh ONE structured section of the dossier. Idempotent per
  stable `sectionKey` — re-running with the same key overwrites that section in place,
  so you can refresh stale sections without duplicating. Different custom keys let
  multiple custom or user-request sections coexist.
- **Args:** `dossierId`, `sectionType` (one of: `overview`, `history`,
  `identification`, `what_to_look_for`, `red_flags`, `pricing`, `search_terms`,
  `examples`, `buying_checklist`, `open_questions`, `custom`), `sectionKey` (optional),
  `title`, `summary` (optional short preview), `contentMarkdown` (markdown is rendered),
  `sources` (optional array of
  `{ url, label, kind }` — attach the sources you actually used), `structuredData`
  (optional small machine-readable payload for that section), and
  `dependsOnClaimKeys` (optional canonical fact keys this prose relies on).
- Pass `structuredData` as an actual object or array, not as a JSON-encoded string.
  Write plain text/markdown in titles, summaries, and content; do not HTML-escape
  user-facing text such as `&` into `&amp;`.
- Standard sections can use the section type as their key (`pricing`, `identification`,
  etc.). For follow-ups and custom user requests, use a key like
  `user_request:<slug>` or `followup:<slug>` so later edits target the right section.
- Add `dependsOnClaimKeys` for claims the prose relies on. If a canonical claim later
  changes, AWB can mark dependent sections `needs_review` so users and agents know that
  prose may be stale.
- Write a handful of sections per item. Lead with an `overview` that gives a clear
  verdict + a value range. Tailor to the user's selected Research Tasks and note.
  If the user selected "Make a sales listing," write a custom section with
  `sectionKey: "sales_listing"` that includes a natural marketplace-ready title,
  asking-price guidance, honest condition notes, and a description without AI-smelling phrasing.
  If the user selected "Price guide by place," write a `pricing` section with
  `sectionKey: "venue_price_guide"` explaining the structured `itemProfile.priceGuide`
  estimates and append cited observations or AI estimates to `itemProfile.priceValues`
  with used/new classification and similarity notes. Do not fabricate exact new prices
  when only comparable replacement pricing exists.
  Format each section so the `summary` is useful by itself, with the deeper answer in
  `contentMarkdown`.

### `awb_log_source_check`  (the source-check matrix)
- **Use:** record one row per source you consulted — where you looked, the query, and
  the outcome — so the user sees what was and wasn't checked.
- **Args:** `dossierId`, `sourceName`, `sourceType` (`marketplace`, `search_engine`,
  `retail`, `auction`, `reference`, `local`), `status` (`checked`, `partial`,
  `blocked`, `requires_user`, `failed`), plus optional `url`, `queryUsed`,
  `resultCount`, `usefulResultCount`, `summary`, `limitations`.
- **Important:** use `requires_user` (not a fake "checked") for sources you could NOT
  actually search yourself — e.g. Facebook Marketplace, eBay *sold* listings behind a
  login. Use `blocked` for sources blocked by access controls, captcha, robots, or
  geography. Use `failed` when your own search/tool failed. This honestly shows the
  user what's still missing.

### `awb_save_research_result`  (preferred one-call save after research)
- **Use:** after you have finished the actual research and are ready to write the
  result back to AWB. Prefer this for normal queue items because it saves approval
  prompts and tool calls compared with calling every granular write tool separately.
- **What it can save in one call:** create/reuse an interest, select a
  `mainImageFileId`, create/update the compact
  item profile (including primary `priceValues`, `priceGuide`, `ownershipStatus`, and session
  membership), write canonical `claims`, `corrections`, `questions`, and compact
  `interactions`, write multiple dossier sections, replace the source-check matrix,
  attach comparable reference images, record run stats, and optionally mark the capture
  `done` or `needs_user`.
- **Args:** optional `captureItemId`, `captureStatus` (`done` or `needs_user`),
  `resultNote`, `mainImageFileId`, `sessionId`, `interestId`, `dossierId`, or
  `interest: { title, description, tags }`, plus optional `itemProfile`, `claims`,
  `corrections`, `questions`, `interactions`, `sections`, `sourceChecks`,
  `referenceImages`, and `stats`.
- **Follow-up rule:** if the capture is linked to an existing item, pass the
  `captureItemId`. AWB will enforce that the result updates the linked interest/dossier
  instead of accidentally creating a duplicate.
- **Session rule:** if the capture or prior context includes a `sessionId`, pass it.
  AWB will link the resulting interest/dossier/profile into that session so the user can
  later filter to bought/owned items from that trip.
- **Idempotency:** interest lookup is by title when no id is supplied; active claims are
  upserted by `claimKey` with evidence-tier conflict protection; corrections are
  deduped by hypothesis/wrong value; open questions are deduped by text; dossier sections
  are upserted by stable `sectionKey`; item-profile updates are partial, so omitted
  fields stay unchanged.
- Use the granular tools below when you need to work incrementally, mark a long task as
  `processing` before researching, or edit one existing field/section after the fact.

### `awb_finalize_research`  (wrap up — stats + comparison images)
- **Use:** call ONCE at the end of a research pass to (a) record compact run stats and
  (b) attach **reference images of comparable items** for visual comparison with the
  user's own photo.
- **Args:** `dossierId`; `referenceImages` (array of
  `{ url, caption, sourceUrl, sourceLabel }` — images of *comparable* items, NOT the
  user's photo; verify each URL actually loads as an image first); `stats` (optional
  `{ task, agentModel, clientName, sourcesChecked, searchQueries, sectionsWritten,
  sitesVisited, tokensUsed }`); `sourceChecks` (optional — passing this REPLACES the
  source-check matrix in one go, so omit it if you already used
  `awb_log_source_check` incrementally).
- **Note:** you only pass the `url`. AWB automatically re-hosts each reference image
  onto its own storage in the background so it persists even if the original link rots;
  the original `url` stays as the attribution/fallback. No extra work on your part.

### `awb_update_capture_queue_item`  (close the loop)
- **Use:** after turning a captured note into research, mark the capture item `done`
  (or `needs_user`) and link what it produced. First claim the item by setting it to
  `processing`; pending and needs_user items can both be claimed. Result links are
  accepted only when completing an item that is already processing.
- **Args:** `itemId`, `newStatus` (`processing` | `done` | `needs_user`),
  `resultInterestId` (optional), `resultDossierSectionIds` (optional), `note`
  (optional — a one-line verdict the user sees).

## 6. How to help your user (recommended workflows)

**"Process my queue" / "research what I captured":**
1. `awb_list_capture_queue` → get actionable items (`pending` plus retryable
   `needs_user` items by default), including selected Research Tasks, value evidence,
   ownership status, and session metadata when present.
2. If an item is going to take a long time or you need to stop midway,
   `awb_update_capture_queue_item` → set `newStatus: "processing"`. For a normal short
   research pass, you can skip the claim step and complete the capture with
   `awb_save_research_result` after research is done.
3. If the item looks like it may duplicate prior saved work, or the user asks whether
   they have researched something similar, call `awb_search_research` before doing new
   web research.
4. If the item is `captureKind: "research_followup"` or includes `context.interestId` /
   `context.dossierId`, call `awb_get_research_context` first. Use the canonical
   header, active item claims, ruled-out corrections, open questions, prior item profile,
   dossier sections, sources, and linked captures so you extend the existing research
   rather than duplicating it. If old prose conflicts with active claims, update the
   prose or mark it stale; do not follow stale prose.
5. Look at the photo(s) + note to identify/classify it as baseline work. For each photo, call
   `awb_get_capture_images` with all file ids when there are several photos, or
   `awb_get_capture_image` for a single photo, and inspect the returned inline image(s).
   Do not prefer `files[].url` or the raw storage host. If an older `needs_user` note says
   Backblaze or AWB URLs were blocked, retry through these MCP image tools before asking
   the user for the same image. Treat the capture text/photos and typed `identifiers` as the user's immediate
   note or follow-up context; use capture `priceValues` as explicit value evidence and
   legacy `priceContext` only as fallback old-row data; preserve `sessionId` if present; use capture `ownershipStatus`
   to decide whether the resulting item profile should be `owned`, `considering`,
   `not_owned`, or `helping_third_party`;
   treat `researchInterestKeys` as the item-level Research
   Tasks to add or emphasize beyond identification.
6. Do your real research outside AWB (search the web, find new/used prices and
   comparisons, answer the user's actual question). For "How much should I pay?", compare
   used prices by condition/venue and include new-price context when available. For
   "Price guide by place", estimate Yard Sale, Facebook Marketplace, eBay, Antique store,
   and New exact or New comparable expectations; include a `yard_sale` row even when
   confidence is low; include original retail and inflation-adjusted context only when useful
   and supportable.
7. `awb_save_research_result` once. Include:
   - `captureItemId` when processing a queued item, so AWB can link/complete the capture.
   - `sessionId` when the capture/context belongs to a shopping or research session.
   - `mainImageFileId` when one uploaded user photo is the best representative thumbnail.
   - `interest` or an existing `interestId`/`dossierId`.
   - `itemProfile` with compact structured facts: category/object type, maker/model, era,
     materials, typed identifiers/marks, condition, dimensions, user intent, selected item-level
     Research Tasks (`researchInterestKeys`), confidence, integer-cent value range,
     append-only `priceValues`, optional `priceGuide`, `ownershipStatus`,
     verdict/recommendation, open questions, and short agent notes.
   - `claims` for every important durable fact. Claims should include stable
     `claimKey`, `valueText`, `confidence`, `evidenceTier`, source refs, and rationale
     when useful. This is what future agents should trust before old prose.
   - `corrections` for facts you ruled out or corrected during research.
   - `questions` for unresolved checks the user or a later agent can answer.
   - `sections`: an `overview` with a clear verdict + value range, then relevant
     sections such as `identification`, `pricing`, `red_flags`, `buying_checklist`,
     `open_questions`, and any `custom` section the selected Research Tasks or question
     calls for. Include `summary` and stable `sectionKey`. For "Make a sales listing,"
     write a custom section with `sectionKey: "sales_listing"`. For "Price guide by
     place," write a pricing section with `sectionKey: "venue_price_guide"` in addition
     to `itemProfile.priceGuide`. Use `structuredData` when a section has useful
     machine-readable payloads; pass an object/array, not a JSON string. Include
     `dependsOnClaimKeys` for any canonical facts the section relies on.
   - `sourceChecks`, marking gated sources `requires_user`.
   - optional `referenceImages` of comparable items (verify they load) and `stats`.
   This one call can mark the capture `done`. If you could not finish, pass
   `captureStatus: "needs_user"` with a short `resultNote` explaining exactly what is needed.

**"Research X" (no capture):** use `awb_get_research_brief` first for exact/near title
matching. If the user asks whether this overlaps older work or the wording is broad, also
call `awb_search_research` before doing new web research. Then save with
`awb_save_research_result` using `interest.title`.

**"Start a yard-sale / antique-trip session":** call `awb_upsert_research_session`
with a human-readable title, then tell the user to capture items under that active
session. If the user asks "what did I buy?" or "show the session," call
`awb_list_research_sessions` first and then use the website session view for human
inspection. When saving research into the session, preserve `sessionId`, set
`ownershipStatus: "owned"` for items the user bought, and include a `priceValues`
row for the paid/observed amount when the paid price is known.

**Refreshing / working on an item later:** call `awb_get_research_context` first. Then
check `dossier.needsRefresh` and section `freshness.state` values. Prioritize user-requested
refreshes and `aging`/`stale` sections, then update item claims for changed durable facts,
log corrections for wrong turns, update open questions, update the item profile only where
compact summary fields changed, and call `awb_write_dossier_section` again for stale or new
sections. Use the same `sectionKey` to edit an existing section; use a new custom key for a
genuinely new user request. Include `dependsOnClaimKeys` on refreshed sections. Section writes
receive a new `lastUpdatedAt` timestamp, clear the dossier-level refresh flag, and follow-up captures keep their own `createdAt` /
`updatedAt` timestamps so the website can show when new information was added.

**Public venue note:** if the user explicitly wants to share location knowledge, use
`awb_find_or_create_public_location` to get a venue id, then call
`awb_add_location_contribution` with `confirmAnonymizedShare: true`. Keep the note about
the venue only. If they later want it removed, call `awb_withdraw_location_contribution`.

**A shared research URL:** if the user gives you an AWB `/share/<capability>` URL, you
may read it as ordinary shared source material without MCP. Treat it as only the
selected recipient view, not evidence that you can access the owner's private
workspace. The link may update, expire, or be revoked. Never guess adjacent tokens,
enumerate links, infer omitted values/ownership/notes, or reuse a media URL outside the
shared research context. Creating, editing, replacing, and revoking dossier links are
owner website controls, not MCP tools.

## 7. The honesty contract (non-negotiable)

- **Prices are estimates with sources, never appraisals.** Give ranges. Say what would
  change the number. Never present a single confident "it's worth $X."
- **Cite real sources.** Attach the URLs you actually used. Don't invent listings.
- **Be honest about what you couldn't check.** Login-gated or paywalled sources →
  `requires_user`. Don't imply you searched something you couldn't.
- **No PII or location leakage** into anything that could be shared. (Phone photos can
  carry GPS — don't surface a user's home/location in research text.)
- **Public location notes are not research records.** Keep them free of private item,
  price, seller, listing, receipt, photo, contact, and workspace details.
- **Capability shares reveal only an owner-selected projection.** Do not imply omitted
  fields exist or ask AWB endpoints to reveal anything beyond the supplied link.
- The UI already labels your output "AI — verify before you buy." Earn that trust.

## 8. What NOT to do

- Don't fabricate prices, listings, or sources.
- Don't claim a gated source was "checked."
- Don't try to create the user's account, sign in for them, or handle their password.
- Don't attempt purchases, listings, messages, or any off-platform action — AWB can't
  do those and you shouldn't either, unless the user explicitly directs you elsewhere.
- Don't put another person's hosted image forward as the user's item; reference images
  are clearly labeled as *comparable* items.

## 9. Versioning

This guide is updated as AWB gains tools and features. The current tool set (22 tools)
covers capture-queue processing, batch inline image retrieval, shopping/research
sessions, bought/owned item filtering, efficient one-call research saving, structured
item profiles, canonical claims, corrections, open checks, source matrices, context
retrieval, dossier research, and opt-in scrubbed public location notes. Revocable
dossier sharing is a website capability rather than an MCP tool; a user-supplied share
URL can be read as shared source material, but cannot expose the private workspace. Check the
"Last updated" date at the top; the concise index is at
https://assistwithbuying.com/llms.txt.