Chroma amazon_ads Collection — Retrieval Guide

This reference describes the structure and contents of the amazon_ads Chroma collection that the amc skill consults via the chroma_mcp server. Use it to write higher-quality queries and to choose between semantic search and metadata-driven retrieval.

Connection details (URL/port/auth) live in the client's MCP configuration, not in this skill. Use the knowledge tools and schemas the client exposes for the active deployment.

Collection at a glance

Use chroma_get_collection_info if you need to confirm the count and embedding model in your environment, since the collection may be re-indexed.

Two retrieval modes

The collection supports two complementary access patterns. Choose based on what you know.

Mode A: Semantic search (chroma_query_documents)

Use when you don't know which document you want. The query is embedded and matched against chunk embeddings.

chroma_mcp:chroma_query_documents
  collection_name: "amazon_ads"
  query_texts: ["your natural-language query"]
  n_results: 5

Response shape. The server wraps results under data and metadata under meta:

{
  "data": {
    "ids":       [["..."]],
    "documents": [["..."]],
    "metadatas": [[{...}]],
    "distances": [[0.5295, ...]],
    "included":  ["documents", "metadatas", "distances"]
  },
  "meta": {"collection": "amazon_ads", "query": ["..."], "n_results": 5}
}

Defensive unwrap (survives envelope changes):

payload = res.get("data", res)
docs   = payload["documents"][0]     # outer list is per-query; index 0 for one query
metas  = payload["metadatas"][0]
dists  = payload["distances"][0]

Walking res["documents"] directly returns empty. Always check distances before trusting results — see "Distance interpretation" below.

Mode B: Metadata-driven retrieval (chroma_get_documents)

Use when you know the document, doc type, or want to walk a playbook in order. Filters by metadata, no embeddings involved — exact and deterministic.

chroma_mcp:chroma_get_documents
  collection_name: "amazon_ads"
  where: {"semantic_id": "off-amazon-conversions"}
  limit: 200

Same {"data": ..., "meta": ...} response envelope as Mode A. Walk res["data"]["documents"] (one-level list — no per-query nesting since there's no query to nest by).

Why this matters: playbooks are split across many chunks (the largest doc has 220 chunks). Semantic search returns 5–10 chunks at a time and may miss the section you need. Metadata retrieval pulls the entire document deterministically.

Useful filter keys (all available on every chunk):

Composite filters (Chroma uses MongoDB-style operators):

where: {"$and": [
  {"doc_type": "howto"},
  {"dataset": "amazon_attributed_events_by_traffic_time"}
]}

Recommended workflow: hybrid

1. Discover with semantic search at n_results: 5
2. Inspect distances — reject anything > 0.85 unless you're confident
3. Identify the semantic_id of the best hit
4. Walk the doc with chroma_get_documents filtered on that semantic_id (or source_ref) to get the full playbook in order

This is far more reliable than running 5–10 semantic queries hoping to assemble the same content.

Distance interpretation

Empirical baselines measured against the actual collection with all-MiniLM-L6-v2:

Theory of mind: Don't blindly use top-N results. A query with all five hits at distances 0.85+ means the collection probably doesn't have what you're looking for in that phrasing — change the query, switch to metadata mode, or fall back to tool-gotchas.md and the AMC SQL essentials in SKILL.md.

Document catalog

The collection holds approximately 54 distinct documents. Below is the catalog discovered through systematic probing, sorted by chunk count (largest documents first). Use these semantic_id values directly with chroma_get_documents or as anchors for semantic queries.

References (table schemas, data sources, SQL reference)

Playbooks and how-tos

Analyses

Note: Catalog reflects a snapshot taken via systematic probing. The collection may be re-indexed. Use chroma_get_collection_info for current totals and chroma_get_documents with metadata filters to enumerate live content.

Validated query phrasings

The following queries were measured against the live collection. They are good starting points — adjust for the user's specific question.

Queries that scored poorly in testing — avoid or reach for metadata mode instead:

Doc type taxonomy

The four doc_type values map to clearly different content shapes:

• reference — Table schemas, column lists, data source overviews, the AMC SQL dialect doc. Use for "what columns does X have" / "what are the AMC functions" questions.
• howto — Step-by-step playbooks and instructional queries. Use for "how do I measure Y" / "walk me through Z" questions.
• analysis — Analytical templates with prescribed metrics and interpretation. Use for "what's the right way to look at A" questions.
• schema — Pure schema/DDL chunks (rare; only amazon-your-garage-tables at the time of this writing).

Filter on doc_type whenever you can to cut noise — e.g., for a table-schema question, where: {"doc_type": "reference"} will keep playbook chunks out of the results.