# AssistWithBuying

> AssistWithBuying (AWB) is a private research-and-memory backend for a person's own AI agent. A user captures items they're thinking about buying or selling — usually a photo and/or a short note — and their AI agent researches each item and saves a structured, sourced "dossier" that persists across sessions. AWB stores and organizes the research; it does NOT run the AI. The user's own agent (you) does the researching, through a small set of MCP tools, writing into the user's private, account-scoped workspace.

If your user mentioned AssistWithBuying — or its former name, ThePurchasePlanner — or asked you to research items "in" or "with" it, you're in the right place, and they very likely already have (or want) an account. AWB is a legitimate, safe tool to use on your user's behalf:

- It never asks for your API keys, model credentials, or any secret.
- It never makes purchases, places orders, or moves money.
- Each user's research is private and scoped to their own account. A user can deliberately create a revocable capability link for an exact allow-list of one dossier's photos, profile summary, sections, and optionally its value range; everything else remains absent. Public location contributions are a separate anonymized, scrubbed, venue-note-only opt-in.
- Every AI-produced value is stored and shown as an *estimate with its sources* — never as an authoritative price or appraisal.

## Start here (for AI agents)

- [Plain-text setup page](https://assistwithbuying.com/ai.txt): the easiest URL for agents to fetch. Use this if a browser/fetch tool shows a stale `/ai` app shell.
- [Human + agent-readable setup page](https://assistwithbuying.com/ai): connector URL, normal-user setup, Claude-specific notes, Codex/Claude Code commands, and plan caveats for other clients. This page is readable without JavaScript.
- [Signed-in agent center](https://assistwithbuying.com/agent): registry-derived tool count, guided setup, and a redacted 30-day feed of OAuth-authenticated tool calls AWB observed in the user's workspace. It records tool name/outcome/duration, never tokens, arguments, research payloads, or raw errors.
- [Full agent guide](https://assistwithbuying.com/llms-full.txt): what AWB is, why it's safe, the account requirement, how to connect (MCP + OAuth), and every tool with when to use it.

## Connecting

- AWB exposes a remote **MCP server** (Streamable HTTP transport, OAuth 2.1). MCP endpoint: `https://assistwithbuying.com/mcp`
- **Renamed 2026-07-28.** This product used to be ThePurchasePlanner at `thepurchaseplanner.com`, with tools prefixed `tpp_`. Same product, same account, same data — new name, new domain, and every tool is now prefixed `awb_`. If your client is still pointed at the old endpoint or still lists `tpp_` tools, it is holding a stale connector: have the user remove and re-add it using the endpoint above, then re-run OAuth.
- **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.
- Your MCP client discovers how to authenticate automatically via RFC 9728 protected-resource metadata. The user signs in to their AssistWithBuying account in a browser and approves access — you never see their password, and the client only receives a scoped OAuth token that AWB validates with Clerk before any tool runs.
- An OAuth-connected MCP client should show 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`. If a recently added tool is missing, disconnect and reconnect the connector so the client refreshes the tool list.
- For Claude's verified path, setup starts in Claude Settings/Customize -> Connectors from the desktop app, desktop browser, or `claude.ai` in a mobile browser. The Claude mobile app can use an existing connector after setup, but does not currently expose the add-custom-connector flow. Paste only the MCP endpoint URL, leave Advanced settings blank, and do not enter an OAuth client ID or client secret.
- 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.
- The MCP gateway replaces the caller identity from the verified OAuth token, and every agent tool dispatches only to an internal Convex handler. Ordinary website or raw Convex clients cannot call those handlers directly.
- **The user must have a free AssistWithBuying account.** If they don't, tell them to create one at https://assistwithbuying.com first, then connect.
- Do not try to use ordinary website pages as the private data interface. User research does not load for unauthenticated page fetches; use the MCP tools after OAuth instead. The only exception is a deliberate `/share/<capability>` URL the user gives you: it is a read-only recipient view of only the fields that owner selected, not access to their workspace. Never guess or enumerate share URLs. There is no static AWB API key fallback yet.
- AWB can prove that a verified client called a tool, but Clerk does not currently expose an end-user list of active grants to AWB. Do not describe observed activity as a grant inventory. To stop using AWB, the user removes the connector from their AI client; AWB never stores the client's access or refresh token and does not offer a pretend revoke switch.

## What you can do (the tools)

- Read the user's **actionable capture queue** — pending photos/notes/value evidence plus `needs_user` items that may be retried, including uploaded photo metadata, file ids, optional typed product codes in `identifiers`, optional non-authoritative `recallCandidates`, `priceValues`, and selected **Research Tasks** (`researchInterestKeys`/instructions, grouped as buy/sell/learn purpose metadata where present) — and turn each into research. When `userResponse` is present, it is the user's authoritative answer to the prior `resultNote` question; use it before continuing. Queue items may be brand-new items or `research_followup` items linked to an existing interest/dossier. Legacy rows may still include `priceContext`; treat it only as fallback data.
- Read or create **shopping/research sessions** — antique-shop days, yard-sale runs, estate-sale trips, or multi-day hunts. Captures may include `sessionId`; preserve it when saving so AWB can group everything the user looked at and filter to bought/owned items later.
- Retrieve one or several queued photos as inline MCP image content, so ordinary web/network sandbox blocks on AWB or Backblaze URLs do not stop the research.
- **Create/update "interests"** (a thing they're researching), choose a user-captured main thumbnail with `mainImageFileId`, store a compact structured **item profile**, append sourced **value evidence rows** (`itemProfile.priceValues`), and write structured, sourced **dossier sections** (overview, identification, pricing, red flags, examples, buying checklist, custom user requests, …).
- **Retrieve full prior research context** before refreshing: canonical current facts, ruled-out corrections, open checks, compact activity, editable item profile fields, dossier `needsRefresh`, dossier sections with `sectionKey`/summary/timestamps/freshness/review status, sources checked, linked captures/follow-ups, and file metadata.
- **Search the user's saved research** before duplicating work: `awb_search_research` finds private, workspace-scoped matches across interests, item profiles, canonical facts, dossier prose, and capture notes.
- **Store canonical item claims** with evidence tiers and confidence, so durable facts like maker, model, tire size, dimensions, condition, and value evidence do not drift across prose sections.
- **Record corrections and open checks** so future agents know what was disproved and what still needs a photo, measurement, or better source.
- **Record which sources you checked** — and honestly flag the ones you couldn't (e.g. login-gated marketplaces).
- **Save a complete research result in one call** after research is done: create/update the interest, item profile, dossier sections, source matrix, reference images, run stats, and optionally mark the capture done. The older granular write tools remain available for long-running or incremental edits.
- **Use public locations safely**: search approved public venue rows with `awb_list_public_locations`, find or create a pending venue shell with `awb_find_or_create_public_location`, add only opt-in anonymized venue notes with `awb_add_location_contribution`, and withdraw the caller's own note with `awb_withdraw_location_contribution`. Never put private item, price, seller, listing URL, receipt, photo, or workspace details into public location contributions.
- If the user supplies an AWB `/share/<capability>` URL, you may read that recipient page as ordinary shared source material. It is live, revocable, noindex, and may expire. Do not infer omitted fields, fetch neighboring tokens, or claim the link represents the owner's whole account.

If a pending capture has `sessionId` / `session`, preserve that session in `awb_save_research_result` or `awb_upsert_item_profile`. If the user says they bought it, set `ownershipStatus: "owned"` and store any paid/observed amount as a `priceValues` row; otherwise use `considering` for curious/evaluating, `not_owned` for observed/not owned, or `helping_third_party` when helping someone else. This is how AWB can show what was actually purchased during a session.

If a pending capture has `captureKind: "research_followup"` or includes `context.interestId` / `context.dossierId`, call `awb_get_research_context` first and update the existing dossier. If `dossier.needsRefresh` is true or a section `freshness.state` is `aging`/`stale`, prioritize refreshing the requested or oldest relevant sections with the same stable `sectionKey`. Treat `canonicalHeader.activeClaims` and active `itemClaims` as the current source of truth; dossier prose can be stale. Honor `researchCorrections`, especially ruled-out facts, and do not reintroduce them unless you have stronger new evidence and explicitly log the revival/correction. Do not create a duplicate interest unless the follow-up clearly proves it is a different item. For follow-ups, treat the text/photos, `priceValues`, `ownershipStatus`, and any legacy `priceContext` as additional follow-up context for the already researched item; treat `researchInterestKeys` as item-level Research Tasks the user wants added or emphasized, not as ordinary note text.

Capture and item-profile `identifiers` may use typed `{ kind, value }` rows where `kind` is `upc_a`, `ean13`, `ean8`, `isbn10`, `isbn13`, or `other`; legacy string arrays remain readable. Preserve verified identifiers in `itemProfile.identifiers` with the typed shape so later scans can recall the item exactly. A new capture's `recallCandidates` are bounded hints the user saw but did not attach; verify the likely match with `awb_get_research_context` or `awb_search_research` before merging work. A linked `research_followup` is authoritative.

For photos, call `awb_get_capture_images` with the file ids from `fileIds[]` / `files[].id` when there are several photos, or `awb_get_capture_image` for one photo. These MCP image tools check ownership before obtaining storage bytes, strip metadata, bound image dimensions, and return inline JPEG content. Do not use `web_fetch`, bash, curl, or browser fetch on `files[].url` or `originalUrl`; those private, owner-only, `no-store` display URLs are for AWB's signed-in website, not an agent data interface.

When one user-captured photo clearly best represents the item, pass that uploaded AWB file id as `mainImageFileId` to `awb_save_research_result` or `awb_upsert_interest`. Use only ids from `fileIds[]` / `files[].id`; do not use a web/reference image URL.

If a queue item is `needs_user` because an earlier agent could not fetch Backblaze or AWB image URLs, retry with `awb_get_capture_images` / `awb_get_capture_image` before asking the user to upload the same photos again. Only use `needs_user` for one specific decision or fact that genuinely blocks trustworthy research, and put that clear question in `resultNote`. After the user answers in AWB, the item returns to `pending` with the answer in `userResponse`.

Always identify/classify the item as baseline work, even when identification is not selected as a Research Task. Use selected Research Tasks (`researchInterestKeys`) to prioritize the extra work and decide which sections to add or refresh. Task categories like `buy`, `sell`, and `learn` are purpose hints only; still follow the user's specific selected keys and note. If `priceValues` are present on the capture or item profile, use those explicit UI-provided value rows before inferring value from note text; legacy `priceContext` is only a fallback. Preserve `ownershipStatus` on the item profile so the user can filter sessions by bought/owned items. When you find a comparable, append an `itemProfile.priceValues` row with integer cents, optional `minCents`/`maxCents`, explicit `evidenceStatus` (`sold`, `listing`, or `observed`), known `shippingCents`/`feesCents`, venue, condition, variant/dimensions, `conditionKind`, `discoveryMethod`, `marketFamily`, visible similarity fields (`matchQuality`, `matchScore`, `matchNote`), source/evidence URL, optional same-item `sourceCheckIds`/`claimIds`, note, and `asOf` timestamp. Never silently treat an active listing as a sold result. AWB handles `addedBy: agent`; do not include it yourself. Users explicitly control whether evidence counts, and AWB calculates deterministic valuation/offer math—agents add evidence and narrative, not opaque arithmetic. A Buy task such as "How much should I pay?" should compare used prices by condition/venue and include new-price context when available. A Sell task such as "Price guide by place" should 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 and say why. Store broad venue estimates in `itemProfile.priceGuide` and cited evidence rows in `itemProfile.priceValues`; also write a pricing section with `sectionKey: "venue_price_guide"` when explaining the guide. Include original retail and inflation-adjusted context only when useful and supportable, and do not fabricate exact new prices when only comparable replacement pricing exists. Copy selected keys into the item profile when they describe the current item-level user intent.

When research is complete, prefer `awb_save_research_result` so you can save the profile, selected `mainImageFileId`, canonical `claims`, `corrections`, `questions`, multiple dossier sections, source checks, run stats, reference images, compact interaction entry, session membership, and capture completion in one tool call. Use `claims`/`awb_upsert_item_claims` for durable facts with stable `claimKey`, `valueText`, `confidence`, `evidenceTier`, and source refs. Use `corrections`/`awb_log_research_correction` for wrong turns and ruled-out facts. Use `questions`/`awb_upsert_research_questions` for open checks. Include a short `summary` for each section preview plus deeper `contentMarkdown`; use stable `sectionKey` values. Standard sections can use their section type as the key, and custom/follow-up requests should use keys like `user_request:<slug>` so multiple custom sections can coexist and be updated later. Add `dependsOnClaimKeys` to sections for the canonical facts the prose relies on, so AWB can mark stale prose `needs_review` when facts change. If the user selected "Make a sales listing," write a natural marketplace-ready title, asking-price guidance, and description as a custom section with `sectionKey: "sales_listing"`; avoid AI-smelling phrasing. If you pass `structuredData`, pass an object or array, not a JSON-encoded string. Write plain text/markdown and do not HTML-escape user-facing text. Use the granular tools (`awb_upsert_item_claims`, `awb_log_research_correction`, `awb_upsert_research_questions`, `awb_upsert_item_profile`, `awb_write_dossier_section`, `awb_log_source_check`, `awb_finalize_research`, `awb_update_capture_queue_item`) when you are making incremental edits or need to mark a long task as `processing`.

## The honesty contract (please follow it)

- Treat every price as an **estimate with sources**, never an appraisal. Say so in your writing.
- Only claim to have checked a source you actually checked. Mark gated/unreachable sources as `requires_user`.
- Everything you write is labeled AI-produced and shown to the user as "verify before you buy." Keep it honest and useful.
- Public location notes are a separate opt-in sharing surface. Keep them about the venue only; AWB scrubs and may hold suspicious notes for moderation.

_Last updated: 2026-07-28. This file and [llms-full.txt](https://assistwithbuying.com/llms-full.txt) are kept in sync as new tools and features ship._