# Query guide

Worked examples and vocabulary for the Tandz archive MCP server. Read this when
a first search comes back empty, or before filtering by a name.

## Worked example: "find the episode about the Coldplay kiss cam, maybe a year ago"

The phrase "kiss cam" appears nowhere in the archive's text — it was said on air,
not written down. The band's name was written down.

```jsonc
// 1. Scope the vague time reference.
get_archive_overview({ "segmentLimit": 1 })
// → calendarYearCounts shows how many items exist per year

// 2. Search the one distinctive word, inside that range.
search_archive({ "query": "קולדפליי", "from": "2025-01-01", "limit": 5 })
// → total: 2, matching: { kind: "exact", label: "all terms matched" }
//   "קולדפליי: טוען שנתפס בקהל עם אישה נשואה ומציע מקומות מסתור" (2025-07-20)
```

The title confirms the story without ever containing "kiss cam". This is the
normal shape of a successful search here: find the one proper noun that a human
would have typed into a description, and let the title do the confirming.

Had you searched `קולדפליי קיס קאם` instead, the ladder would have widened the
query for you and returned `matching: { kind: "relaxed", droppedTerms: ["קיס",
"קאמ"] }` — the same episodes, correctly flagged as a weaker match. That is
useful, but landing on `exact` yourself is better evidence.

## Worked example: filtering by a character

```jsonc
// Wrong - an exact-match filter with a guessed spelling.
search_archive({ "character": "דני סביצה" })   // → total: 0, silently

// Right - ground it first.
list_entities({ "kind": "characters", "query": "סביצ" })
// → { value: "דני סביצ'ה", itemCount: 326 }
search_archive({ "character": "דני סביצ'ה", "sort": "newest" })
```

Note the geresh in `סביצ'ה`. Copy the value verbatim from `list_entities`; do not
retype it.

Some characters are large enough to browse rather than search. Among the
most-covered are `דורית`, `דני סביצ'ה`, `יורם קפיטולניק`, `אילנה`,
`פליקס וילנסקי`, `פאפא`, `בני ציצווה` and `עמי`, out of more than a thousand.
`list_entities` with `sort: "countDesc"` gives the current ranking.

## Worked example: nothing found

```jsonc
search_archive({ "query": "ראיון עם ראש הממשלה" })
// → total: 0, matching: { kind: "relaxed", ... }
```

Before concluding the archive lacks it:

1. Try the distinctive noun alone, dropping the framing (`ראיון`, `עם`, `על`).
2. Try a transliteration variant if a foreign name is involved.
3. Check whether the *character* exists via `list_entities` — the subject may be
   catalogued under a recurring segment rather than mentioned in a description.
4. Widen or remove the date range and check `get_archive_overview` for whether
   the archive covers that period at all.

Then say plainly that it was not found, and what you tried.

## Vocabulary

**Era groups** (`eraFilter` on the browse UI; era ids appear on items):
`tziporei` (ציפורי לילה מנקרות, גל״צ), `chotrim` (חותרים למגע, גל״צ), `haerev`
(תוכנית הערב, 102FM), `hasi`, `hayom`, `october-7`.

**Sources:** `102fm`, `youtube`, `omny`, `mixcloud`, `archive_org`, `icast`,
`samurai`, `reconstructed_archive`, `podcastgarden`.

**Types:** `full_episode`, `short`, `youtube_video`, `לקט` (compilation),
`song`, `other`.

**Availability:** `playable` or `metadata_only`. A few hundred items are
catalogued but have no media behind them. Pass `availability: "playable"` when
the user wants something to listen to.

## Dates are not all the same kind

An item's date may be a broadcast date, an approximate archival date, or a
publication date, distinguished by `calendar_date_basis` and
`calendar_date_precision`. Do not present an approximate archival date as a
broadcast fact — say "around" when the precision is coarser than a day.

Coverage is very uneven — at the time of writing 2017 held 2,324 items against
a few hundred in several other years. Call `get_archive_overview` for the live
distribution rather than trusting these figures; a search that finds nothing in
a thin year may simply be looking at a period the archive barely covers.

## Failure modes worth recognising

**Answering without searching.** The most damaging failure. If you have not
called a tool, you know nothing about this archive — describing what it
"probably contains" produces confident-sounding fiction the user cannot check.

**Presenting a relaxed match as an answer.** `matching.kind` of `relaxed` or
`merged` means the query as asked found nothing. Report the weakening.
`exhausted` means even the widened search found nothing — reach for different
words, not the same ones again.

**Searching a whole sentence.** Every term must substring-match. One extra
grammatical word is enough to take a good query to zero.

**Retyping a Hebrew name.** Exact-match filters fail silently on a near miss.
Copy values verbatim from `list_entities`.

**Assuming absence means absence.** No transcripts means plenty of real content
is unfindable by topic. "I could not find it" is honest; "the archive does not
contain it" usually is not.