{"$schema_note":"Drop-in tool catalog for OpenAI-compatible function-calling APIs (Qwen-on-vLLM, OpenAI, DeepSeek, Anthropic via translation). Each entry is a complete `tools[]` element. The agent loop's job is: (1) load this list at startup; (2) include it in every chat-completion call to Qwen; (3) when Qwen emits a tool-call, dispatch to the matching IHI OpenAPI endpoint and feed the result back. $base_url below is the public replica's origin (serves the /v1/* data routes); a tailnet-internal caller should substitute its own reachable IHI OpenAPI host instead — never hardcode an internal hostname into a deployed loop.","$base_url":"https://history.cooperate.social","$openapi_spec":"/openapi.json — auto-generated OpenAPI 3.x spec, served publicly at $base_url/openapi.json (same origin as the /v1/* data routes). Swagger UI at /docs, ReDoc at /redoc, this kit at /agent-kit/ — all public. Re-fetch this catalog when the spec version changes. Response schemas are not declared in the spec (every 200 is schema {}); see the 'Response shapes' section of /agent-kit/readme.md for the three pagination shapes in use.","$versioning":"Tools target /v1/* routes. Re-fetch this catalog when the OpenAPI spec version changes.","$design_notes":["Tool granularity: chosen to be 'one tool per researcher action,' not 'one tool per HTTP route.' For example, search_catalog combines BM25 and semantic into one call with a backend choice — the agent shouldn't have to know which is faster for which kind of query.","Naming: verb_noun, snake_case. Names should hint at when to use, not how the implementation works.","Descriptions: written for the LLM. They explain what the tool RETURNS and when to USE IT, not HTTP details. The LLM doesn't care about the URL.","Required vs optional: prefer optional with sensible defaults. The agent should be able to call with minimal arguments and refine on the next turn.","Output shape: described in the description. The agent reads the result as JSON and reasons about it; we don't need a strict response schema in the tool definition.","Body-author caveat: relay-attribution discipline (see find_witnesses_in_corpora) — the model needs to be told that envelope From: addresses are relay authors for the IP list and friends, and the body author is who actually said the thing. Bake this into the prompt that introduces the tool catalog."],"tools":[{"type":"function","function":{"name":"consult_librarian","description":"(Recognised patrons only: an anonymous call answers 403 — see llms.txt.) Delegate a whole research question to the resident librarian — an agentic 235B harness with every tool in this kit plus verification gates (quotes/handles verified against actual retrievals; fabrications blocked). Returns a Collection Brief: a short lede plus verified artifact cards with pull-quotes and reading-room doors, plus the librarian's investigation trace. Costs 1-6 minutes; use for multi-step questions where you would otherwise chain many tool calls, or when you need citable, verified quotes. For quick lookups use retrieve instead. Pass session to continue a prior consultation.","parameters":{"type":"object","required":["question"],"properties":{"question":{"type":"string","description":"The whole research question to delegate to the librarian."},"session":{"type":"string","description":"A prior consultation's session id, to continue that thread."},"model":{"type":"string","default":"235b","description":"Librarian model key: 235b (default) or 35b."}}},"$endpoint":{"method":"POST","path":"/v1/consult","body_template":{"question":"{question}","session":"{session}","model":"{model}"}}}},{"type":"function","function":{"name":"retrieve","description":"START HERE for almost any question. One fused search across every index — lexical (ElasticSearch BM25, fuzzy/phrase/entity facets), semantic (message + catalog embeddings AND the Qwen3-8B thread engine), and exact (Message-ID / email / 16-hex talk-id lookup) — over 4.8M artifacts, reciprocal-rank-fused into one ranked list. USE FIRST, then drill into what it surfaces with the specialist tools. DON'T reach past it to recall_corpus/search_catalog first — those are scoped slices of what this already fuses. WHICH SEARCH TOOL? whole conversation → search_threads; exact literal string (Message-ID, RFC#, draft slug, version) → recall_keyword; 'did X ever present' / roster → search_talks; a community-PRODUCED artifact (draft, slide, paper, digest) → recall_extras; delegate the whole question for a verified brief → consult_librarian; everything else starts here. Params: query (free text, an entity, a Message-ID, an email, or a talk-id); top (default 20); optional kinds (e.g. [\"message\",\"thread\",\"talk\",\"rfc\",\"work\",\"authority\",\"inquiry\"]), year_from/year_to, and entity facets people/orgs (substring match — NOTE these currently boost, not hard-filter, so off-facet rows can still appear). Returns rows: {kind, title, who, date, score, legs (which legs fired), source_id, door}. Handle caveat: a message source_id is a bare <msg-id> WITHOUT its corpus/ym — feed it to walk_thread (accepts a bare msg-id) to recover its corpus; it will NOT round-trip directly into fetch_message_body/recall_sources, which need the corpus. DATA-QUALITY: rows from remediation-flagged corpora (conf-talks, conf-visual, thread-digests, ietf-drafts, and non-ih/ip message corpora) are machine-extracted — fetch the raw body before quoting. Example: retrieve(query=\"BGP route leak\", kinds=[\"thread\"], people=[\"Madory\"], year_from=2010). CITATION TRACING: to find every discussion citing a specific RFC, pass cited_rfc — e.g. retrieve(cited_rfc=[1105]) surfaces the BGP-era threads that cite RFC 1105, with or without a query. PHRASE PRECISION: wrap a span in double quotes to require it as an exact phrase — retrieve(query='\"paid peering\" depeering') matches only messages actually containing 'paid peering' (leftover words just re-rank), instead of the OR-soup of every message with 'paid' or 'peering'. kinds accepts a list or a comma-joined string (kinds=talk,thread); an unknown kind or year_from > year_to is a 422, not an empty 200. Response: {results:[...], legs_used, took_ms, reason?, hints?} — no pagination keys; raise top (max 100) instead.","parameters":{"type":"object","required":[],"properties":{"query":{"type":"string","description":"Free-text query, an entity, a Message-ID, an email address, or a 16-hex talk-id. May be omitted when a hard filter such as cited_rfc is supplied."},"kinds":{"type":"array","items":{"type":"string"},"description":"Restrict to these artifact kinds (e.g. message, thread, talk, document, rfc, work, authority, inquiry). 'document' = preserved documents: policy/procedure/institutional papers — the RIPE document series (incl. ripe-001 Terms of Reference), MoUs, NCC quarterly reports, AFNIC decisions, administrative records — distinct from 'talk' (conference decks/videos). 'rfc' = the standards texts, full-text searchable by CONTENT not just number (retrieve(kinds=['rfc'], query='exterior gateway protocol') surfaces the EGP-era RFCs); trace citation lineage with cited_rfc=[N] and the graph (graph_neighbors node_type=rfc)."},"top":{"type":"integer","default":20,"minimum":1,"maximum":100,"description":"Number of fused results to return."},"year_from":{"type":"integer","minimum":1969,"maximum":2030,"description":"Lower year bound."},"year_to":{"type":"integer","minimum":1969,"maximum":2030,"description":"Upper year bound."},"people":{"type":"array","items":{"type":"string"},"description":"Entity facet — filter/boost by person-name substrings."},"orgs":{"type":"array","items":{"type":"string"},"description":"Entity facet — filter/boost by organization-name substrings."},"cited_rfc":{"type":"array","items":{"type":"integer"},"description":"HARD filter (not a boost): return only messages that cite these RFC numbers, via the normalized cited_rfcs reverse-index (built from each message's referenced_resources + subject). e.g. cited_rfc=[1105] finds every discussion citing RFC 1105 — the reliable way to trace where a protocol was argued. Works with a query or with query omitted entirely (pure filter)."}}},"$endpoint":{"method":"GET","path":"/v1/retrieve","query_template":{"query":"{query}","kinds":"{kinds}","top":"{top}","year_from":"{year_from}","year_to":"{year_to}","people":"{people}","orgs":"{orgs}","cited_rfc":"{cited_rfc}"}}}},{"type":"function","function":{"name":"get_artifact","description":"Universal fetch: resolve ANY handle this kit hands you and get the artifact itself — metadata plus verbatim text where held. Accepts: a message-id (angle brackets optional), a 16-hex talk id (verbatim deck/transcript text plus a corrected year with year_source), a thread id (returns members), 'RFC 1519', a catalog slug like estrada-susan, or an ark:/26338 id. USE THIS to round-trip anything from retrieve/search results into readable primary text before quoting. Example: GET /v1/artifact?handle=RFC 1519. A 404 names every store it tried. For talks the response carries text_source (which layer `text` came from: talkpages/text = pdftotext, deck pages = vision transcription, transcript = captions) and text_quality (pdftotext garble/coverage scores); the vision layer is served automatically when the extracted text is garbled (font-shifted glyphs), thin, or missing on a third of the pages. kind must be one of the listed values (else 422).","parameters":{"type":"object","required":["handle"],"properties":{"handle":{"type":"string","description":"any id: <msg-id> (brackets optional), 16-hex talk id, thread id, RFC number, catalog slug, or ark"},"kind":{"type":"string","description":"auto (default) or message|talk|thread|rfc|work|authority|inquiry to force","enum":["auto","message","talk","thread","rfc","work","authority","inquiry"]},"max_chars":{"type":"integer","description":"verbatim-text cap, default 50000"}}},"$endpoint":{"method":"GET","path":"/v1/artifact","query_template":{"handle":"{handle}","kind":"{kind}","max_chars":"{max_chars}"}}}},{"type":"function","function":{"name":"aggregate","description":"Facet summary over the fused index: WHO/WHICH-ORGS/WHEN/WHERE for any query — the roster primitive. facet=people|orgs|year|corpus with optional query, kinds, year bounds, and people/orgs filters; returns ranked buckets with counts. USE for 'who presented for X', 'which organizations discussed Y', 'when did Z peak' — enumeration questions where a result LIST is the wrong shape. Example: GET /v1/aggregate?facet=people&orgs=Renesys&kinds=talk. Empty results carry reason and hints, never a bare []. SURFACING WORKING GROUPS: for protocol-related questions, facet=corpus with significant=true ranks mailing lists by how ABOUT the theme they are (overrepresentation, not size) — the standard move for finding the relevant IETF working-group lists (ietf-dtls-iot, ietf-ace, ietf-cose...) that raw counts bury under giant corpora; equally finds the right NOG for operational topics. Present the top lists themselves as findings. CORPUS SCOPING: pass corpus=[...] to term-filter the aggregation to named lists; umbrella names expand to their decade shards, so corpus=[\"nanog\"] scopes to the four NANOG decade shards (the messages, ~224,920) and never double-counts the umbrella-tagged thread artifacts. DISCLOSURE: matched_estimate/matched_total is the TRUE match count (track_total_hits, never the 10k cap); matched_total_is_exact=true. For facet=year the series is bounded to [1969, current_year+1] with the excluded tail reported as out_of_range_excluded, and undated_excluded counting query matches that carry no year — always disclose these when presenting a per-year series. PHRASE PRECISION: wrap a span in double quotes to require it as an exact phrase — aggregate(facet=orgs, query='\"paid peering\" depeering') returns the market actors actually in those discussions (Comcast/Level3/Cogent/Netflix), cutting ~176k token-soup matches (IETF boilerplate) to the ~200 real ones.","parameters":{"type":"object","required":["facet"],"properties":{"facet":{"type":"string","description":"people | orgs | year | corpus"},"query":{"type":"string","description":"optional free-text scope"},"kinds":{"type":"array","items":{"type":"string"},"description":"restrict to kinds, e.g. [\"talk\"], [\"document\"] (preserved policy/institutional papers: RIPE document series, MoUs, administrative records), or [\"rfc\"] (standards texts, content-searchable)"},"year_from":{"type":"integer"},"year_to":{"type":"integer"},"people":{"type":"array","items":{"type":"string"}},"orgs":{"type":"array","items":{"type":"string"}},"top":{"type":"integer","description":"bucket count, default 30"},"significant":{"type":"boolean","description":"rank by overrepresentation vs the index (venue discovery), default false"},"corpus":{"type":"array","items":{"type":"string"},"description":"scope to one or more corpora (term filter on `corpus`). Umbrella names (nanog) expand to decade shards; explicit shards (nanog-10s) and non-NANOG names pass through."},"cited_rfc":{"type":"array","items":{"type":"integer"},"description":"scope to messages that cite these RFC numbers (term filter on the cited_rfcs reverse-index). Combine with facet=year to chart a spec's discussion arc — e.g. facet=year cited_rfc=[2547] traces the BGP/MPLS-VPN discussion rising through the early 2000s and tailing off."}}},"$endpoint":{"method":"GET","path":"/v1/aggregate","query_template":{"facet":"{facet}","query":"{query}","kinds":"{kinds}","year_from":"{year_from}","year_to":"{year_to}","people":"{people}","orgs":"{orgs}","top":"{top}","significant":"{significant}","corpus":"{corpus}","cited_rfc":"{cited_rfc}"}}}},{"type":"function","function":{"name":"walk_thread","description":"USE when you hold ANY one message of a conversation and want the whole thread — every sibling message including renamed subjects that keyword search can't see ('who else was in that conversation'). Never declare a thread exhausted without walking it. WHEN NOT: if you only have a topic, not a message — search_threads/retrieve first, then walk a hit. Param: msg_id (RFC-2822 Message-ID, angle brackets accepted with or without). Returns {thread_id, corpus, n_messages, messages:[{date, from_addr, subject, msg_id}]} ordered by date — the per-message msg_ids round-trip into fetch_message_body(corpus, msg_id) using the corpus this call reports. Quirk: takes a message id; it does NOT accept the thread_id that search_threads returns. Example: walk_thread(msg_id=\"<199401.abc@isi.edu>\"). total_members ALWAYS reports the TRUE thread size from the message index (not just what was returned), and messages_truncated flags when the thread is bigger than the returned page — so 'largest thread' superlatives are verifiable. limit defaults to 200, accepts up to 2000. A thread_id (from thread geometry) is accepted in the msg_id slot and is walkable even when its root message is a dangling reference (resolved_by reports msg_id vs thread_id).","parameters":{"type":"object","required":["msg_id"],"properties":{"msg_id":{"type":"string","description":"RFC 2822 Message-ID (with or without angle brackets)."},"limit":{"type":"integer","description":"max messages returned, ordered by date (default 200, up to 2000); total_members still reports true size"}}},"$endpoint":{"method":"GET","path":"/v1/threads/walk","query_template":{"msg_id":"{msg_id}","limit":"{limit}"}}}},{"type":"function","function":{"name":"search_threads","description":"USE for 'find the thread where operators discussed X' — semantic search over 1M reconstructed THREADS on the strongest embedding model in the stack (Qwen3-8B). Returns whole conversations, not messages. Prefer this over retrieve when you specifically want thread-level hits ranked by the best model rather than diluted in fusion. WHEN NOT: single-message or entity lookups — use retrieve. Params: query; k (default 12 — NOTE this tool calls the count 'k', not top); by_corpus (array; accepts umbrella names like nanog — auto-expanded to decade shards — or exact shards like nanog-10s); after_date/before_date (YYYY-MM-DD, on thread first_date). Returns rows under BOTH items and results (dual-keyed for consumer compatibility): each a thread with thread_id, subject, corpora, dates, score. Round-trip: the thread_id has no direct expander — pull one member msg-id from the row and walk_thread it. Example: search_threads(query=\"NCP to TCP/IP cutover scramble\", by_corpus=[\"ih\"]).","parameters":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Free-text query — what conversation are you looking for?"},"k":{"type":"integer","default":12,"minimum":1,"maximum":100,"description":"Number of threads to return."},"by_corpus":{"type":"array","items":{"type":"string"},"description":"Restrict to threads whose corpora include at least one of these. Accepts umbrella names (e.g. 'nanog', auto-expanded to its decade shards) or exact decade shards (e.g. 'nanog-10s')."},"after_date":{"type":"string","description":"YYYY-MM-DD; keep only threads whose first_date is on/after this."},"before_date":{"type":"string","description":"YYYY-MM-DD; keep only threads whose first_date is on/before this."}}},"$endpoint":{"method":"POST","path":"/v1/search/threads","body_template":{"query":"{query}","k":"{k}","by_corpus":"{by_corpus}","after_date":"{after_date}","before_date":"{before_date}"}}}},{"type":"function","function":{"name":"search_talks","description":"THE roster tool: 'did X ever present', 'who presented for org Y'. Direct SQL probe of the 46k-deck conference-talk shelf. USE for exact presenter/title/event/affiliation lookups. WHEN NOT: conceptual talk-topic search — use recall_extras(corpus=\"conf-talks\", …). Params: term (substring, 2+ chars — NOTE this tool calls the query 'term', not query); field one of presenter|title|event|affiliation|any (default any); limit (default 40, max 200); event (one meeting key, e.g. sanog-12); year_from/year_to (inclusive band; reversed band is a 422); match (substring|word); offset (pagination, walk while has_more). Returns {n_results, has_more, offset, affiliation_available, results:[{talk_id, presenter, event, year, title, affiliation?}]} — n_results counts the rows returned; total is the size of the whole match set; copies of one deck are folded into the first row (copies_folded says how many). affiliation is present only where the org-axis backfill reached; affiliation_available tells you if the column exists at all. talk_id is a 16-hex handle → door /talk?id=<talk_id>. DATA-QUALITY: talk titles are often URL-derived sludge — judge relevance by presenter/event, and fetch the deck (recall_extras / get_artifact) before quoting a slide. Example: search_talks(term=\"Madory\", field=\"presenter\").","parameters":{"type":"object","required":[],"properties":{"term":{"type":"string","description":"Substring to match (2+ chars). May be empty when event is given: then the meeting's whole roster is listed."},"field":{"type":"string","default":"any","enum":["presenter","title","event","affiliation","any"],"description":"Which column to match against."},"limit":{"type":"integer","default":40,"minimum":1,"maximum":200,"description":"Max rows to return. Max 200 (a larger value is a 422)."},"year_from":{"type":"integer","minimum":1969,"maximum":2030,"description":"Lower year bound (inclusive). Rows with no resolvable year are dropped when any bound is set. year_from > year_to is a 422."},"year_to":{"type":"integer","minimum":1969,"maximum":2030,"description":"Upper year bound (inclusive)."},"event":{"type":"string","maxLength":80,"description":"Restrict to one meeting key exactly as the catalogue uses it (e.g. icann-86, ietf-40, nanog-39, sanog-12). Case-insensitive."},"match":{"type":"string","enum":["substring","word"],"default":"substring","description":"'word' requires each term token to match at a word boundary, so NAT does not match 'international'."},"offset":{"type":"integer","minimum":0,"maximum":50000,"default":0,"description":"Skip the first N matching rows. Walk offset += limit while has_more is true for exhaustive pulls; ordering is stable (event, then rowid)."},"order":{"type":"string","enum":["event","year_desc","year_asc"],"description":"event (default: by meeting key, then catalogue order) | year_desc | year_asc"}}},"$endpoint":{"method":"GET","path":"/v1/talks/search","query_template":{"term":"{term}","field":"{field}","limit":"{limit}","event":"{event}","year_from":"{year_from}","year_to":"{year_to}","match":"{match}","offset":"{offset}"}}}},{"type":"function","function":{"name":"recall_keyword","description":"USE for EXACT literal strings that fuzzy search misses — a raw Message-ID, an RFC number cited in body prose, a draft slug, a software version, a specific date string. This is the citation-precision drill; pair it with retrieve (sense) — they miss differently. WHEN NOT: conceptual queries (embeddings win there — use retrieve/recall_corpus). SEMANTICS: by DEFAULT the WHOLE query is ONE case-insensitive literal substring, punctuation included — '$/Mbps' finds the literal '$/Mbps' (NOT the token 'mbps'), '$150 per month' matches only that exact run, 'xyzzy per foobar' -> honest 0. Wrap a span in double quotes to require it as a phrase inside a longer query. Pass tokens=true for legacy AND behaviour (query split into stop-word-stripped tokens matchable token-apart, e.g. 'NCP transition' -> 'ncp' AND 'transition' anywhere) — use it when you want token-AND breadth, not an exact string. QUIRKS THAT DECIDE SUCCESS: a required substring under 3 chars (a bare '$') falls back to a slow linear scan; the corpus stores surnames/login-names, not full names (\"feinler\" not \"Elizabeth J. Feinler\"); if a long substring is empty, SHORTEN it or switch to tokens=true before you vary. Response echoes `semantics` (substring|phrase|tokens) and `keywords` (the literals actually searched). Params: query, top (default 20), corpus (single, optional). Returns {results:[{msg_id, corpus, ym, subject, …}]} — the msg_id+corpus+ym triple round-trips cleanly into recall_sources. DATA-QUALITY: rows are keyword hits into extraction records under remediation — fetch the raw body (recall_sources / fetch_message_body) before quoting. Example: recall_keyword(query=\"RPKI origin validation\", corpus=\"nanog\"). Returns total: the TRUE number of messages matching the literal(s) across the whole corpus (not just the returned top-N) — a cheap second derivation for 'how many mention X' counting questions; total_is_lower_bound flags the rare capped case.","parameters":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Exact substring to match (case-insensitive by default)."},"top":{"type":"integer","default":20,"minimum":1,"maximum":200,"description":"Max results to return."},"corpus":{"type":"string","description":"Restrict to a single corpus (e.g. 'nanog-90s', 'ietf-mboned')."}}},"$endpoint":{"method":"POST","path":"/v1/recall/keyword","body_template":{"query":"{query}","top":"{top}","corpus":"{corpus}"}}}},{"type":"function","function":{"name":"recall_corpus","description":"SOFT-DEPRECATED — prefer retrieve; this remains for pure-semantic ranking scoped in a way retrieve doesn't expose as first-class. This tool's semantic-over-messages-and-catalog IS one of retrieve's legs, un-fused; a stranger cannot tell why they'd pick it over retrieve. USE it directly only when you need a single corpus, a single catalog chunk-role (kind = summary|body|fact|question|action|witness|revision), or a year_from/year_to band. Params: query; top (default 8); source (catalog|corpus|both, default catalog — NOTE default is catalog-only, pass both or corpus for mail); corpus (single, when source includes corpus); kind; year_from/year_to. Returns {results:[…], _schema_notes} — every message row carries msg_id+corpus+ym (round-trips into recall_sources) and, for 35B-derived corpora, a _schema_note remediation flag you MUST propagate. DATA-QUALITY: recall rows are machine-derived summaries — fetch the raw body before quoting. Example: recall_corpus(query=\"who first proposed RPKI\", source=\"corpus\", corpus=\"nanog\", year_from=2008).","parameters":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Free-text query; embedded by BAAI/bge-small-en-v1.5."},"top":{"type":"integer","default":8,"minimum":1,"maximum":100,"description":"Number of dedup'd results to return."},"source":{"type":"string","enum":["catalog","corpus","both"],"default":"both","description":"Restrict to Catalog only, mailing-list corpus only, or both."},"corpus":{"type":"string","description":"When source includes 'corpus', restrict to this single corpus (e.g. 'nanog-10s', 'ietf-tls', 'cisco-nsp')."},"kind":{"type":"string","description":"When source includes 'catalog', restrict to a single chunk_role (summary, body, fact, question, action, witness, revision)."},"year_from":{"type":"integer","description":"Lower bound on year (inclusive)."},"year_to":{"type":"integer","description":"Upper bound on year (inclusive)."}}},"$endpoint":{"method":"GET","path":"/v1/recall","query_template":{"query":"{query}","top":"{top}","source":"{source}","corpus":"{corpus}","kind":"{kind}","year_from":"{year_from}","year_to":"{year_to}"}}}},{"type":"function","function":{"name":"search_catalog","description":"SOFT-DEPRECATED — prefer retrieve(kinds=[\"work\",\"authority\",\"inquiry\"]); this remains for a fast keyword/entity-name pass scoped to the curated Catalog. It searches the same curated Catalog records retrieve covers, un-fused. Params: query; k (default 10 — NOTE k, not top); backend (bm25 fast keyword, or rag semantic — start bm25, fall back to rag for conceptual queries); record_type (catalog_work|catalog_authority|inquiry). Returns {backend, n_results, items:[{slug, title, ark, url, chunk text, score}]}. Score caveat: bm25 and rag scores live in different spaces — don't compare across backends. The slug round-trips into fetch_work/fetch_authority/fetch_inquiry. Example: search_catalog(query=\"Cerf Kahn 1974\", backend=\"bm25\").","parameters":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"k":{"type":"integer","default":10,"minimum":1,"maximum":50},"backend":{"type":"string","enum":["bm25","rag"],"default":"bm25"},"record_type":{"type":"string","enum":["catalog_work","catalog_authority","inquiry"],"description":"Restrict results to one record type"}}},"$endpoint":{"method":"POST","path_when_bm25":"/v1/search/concordance","path_when_rag":"/v1/search/rag","body_template":{"query":"{query}","k":"{k}","record_type":"{record_type}"}}}},{"type":"function","function":{"name":"recall_extras","description":"USE when the answer is an artifact PRODUCED BY the community — a draft, a slide, a paper, a synthesized debate — not a message discussing one. The only door to six per-corpus shelves. Params: corpus (REQUIRED enum: rfcs 10,646 · ietf-drafts ~176K · treasures-text 20,145 BBN reports / oral histories / papers · conf-talks ~70K talk extractions · conf-visual ~264K slide alt-text · thread-digests synthesized debate summaries) — call recall_extras_inventory first if unsure which shelf; query; top (default 8). NOTE this six-name enum is its OWN namespace, separate from the message-corpus names in list_corpora. Returns {corpus, results:[…], _schema_notes} with a corpus-specific handle per row (rfc_number / draft_name / treasure_id / talk_id / pdf_path+page_n / thread_id). TWO HARD CAVEATS: (1) most of these corpora are UNDER REMEDIATION (35B-derived; audit defect rates 60-100% on synthesized fields — key_quotes, notable_claims, debate_summary etc.); every row carries a _schema_note you MUST surface and must NOT quote synthesized fields from — fetch the raw artifact and quote that. (2) several of these handles (rfc_number / treasure_id / draft_name) do NOT yet round-trip through a fetch tool. Example: recall_extras(corpus=\"treasures-text\", query=\"end-to-end argument\").","parameters":{"type":"object","required":["corpus","query"],"properties":{"corpus":{"type":"string","enum":["rfcs","ietf-drafts","treasures-text","conf-talks","conf-visual","thread-digests"],"description":"Which per-corpus index to query. See recall_extras_inventory for available row counts."},"query":{"type":"string","description":"Free-text query (semantic; embedded by BAAI/bge-small-en-v1.5)."},"top":{"type":"integer","default":8,"minimum":1,"maximum":50,"description":"Number of dedup'd results to return."}}},"$endpoint":{"method":"GET","path":"/v1/recall/extras","query_template":{"corpus":"{corpus}","query":"{query}","top":"{top}"}}}},{"type":"function","function":{"name":"recall_extras_inventory","description":"List the per-corpus FAISS indexes built 2026-06-11 (RFCs, IETF Drafts, treasures-text, conf-talks, conf-visual, thread-digests). Returns each corpus's row count and whether it's currently loaded in memory. Use this BEFORE recall_extras when the patron's question could plausibly route to any of multiple corpora — read the inventory descriptions to pick the right one.","parameters":{"type":"object","properties":{}},"$endpoint":{"method":"GET","path":"/v1/recall/extras/inventory","query_template":{}}}},{"type":"function","function":{"name":"find_witnesses_in_corpora","description":"USE to build a community-attestation arc for a named resource — every Phase-1 message whose structured referenced_resources field names a resource by URL/name, chronologically sorted. This searches a resource-name index, not free text (that's retrieve/recall_corpus). Params: key (resource name or URL fragment — NOTE this tool calls the query 'key'; keys ≤5 chars match on word-boundary to avoid ENUM/renum false hits); corpora (array, default [\"ih\",\"ip\"]; list_corpora enumerates the ~1600 message corpora); limit (default 50). Returns {n_hits, items:[{msg_id, date, from_addr, subject, ym, corpus, citation_quote}]}. RELAY-ATTRIBUTION CAVEAT: the IP list is Farber-curated — envelope from_addr on IP messages is the relay (Farber), NOT the body author; call fetch_message_body and read the body to resolve who actually spoke. The msg_id+corpus round-trips into fetch_message_body. DATA-QUALITY: these are Phase-1 extraction rows under remediation — fetch the body before quoting. Example: find_witnesses_in_corpora(key=\"mapstuff.html\", corpora=[\"ih\",\"ip\"]).","parameters":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Resource name or URL fragment, case-insensitive substring match"},"corpora":{"type":"array","items":{"type":"string"},"default":["ih","ip"],"description":"Corpora to search. Use list_corpora to discover available corpora."},"limit":{"type":"integer","default":50,"maximum":500}}},"$endpoint":{"method":"POST","path":"/v1/corpora/find-references"}}},{"type":"function","function":{"name":"search_witness_quotes","description":"Substring search across every Catalog Work's list_witnesses[].quote field. Use when you want to find which Works cite a particular phrase, URL fragment, or specific terminology — e.g. searching 'mapstuff.html' to find every Work that records a Padlipsky witness for the LAFN ARPANET maps.","parameters":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Substring to match (case-insensitive)"},"k":{"type":"integer","default":20}}},"$endpoint":{"method":"POST","path":"/v1/search/witnesses"}}},{"type":"function","function":{"name":"fetch_message_body","description":"USE to read the verbatim body of one message you already have a handle for — the primary text you MUST hold before quoting, naming a subject, or asserting authorship. Params: corpus (REQUIRED — the enclosing corpus; if you only have a bare msg-id from retrieve, get the corpus from walk_thread first), msg_id (angle brackets accepted with or without — stripped either way), max_chars (default 50000). Returns {corpus, msg_id, subject, from_addr, date, ym, body, truncated} — subject/from/date are first-class (parsed from the extraction record, not the body). Relay caveat as in find_witnesses_in_corpora: on the IP list, from_addr is the relay; the true author is in the body. This is the raw primary text — quote from here, not from recall/extraction summaries. Example: fetch_message_body(corpus=\"ih\", msg_id=\"<199401.abc@isi.edu>\"). (Overlaps recall_sources' corpus branch; recall_sources additionally needs ym.)","parameters":{"type":"object","required":["corpus","msg_id"],"properties":{"corpus":{"type":"string","description":"Corpus name from list_corpora, e.g. ip"},"msg_id":{"type":"string","description":"Bare Message-ID without angle brackets, or with — they're stripped"},"max_chars":{"type":"integer","default":50000,"maximum":200000}}},"$endpoint":{"method":"GET","path":"/v1/corpora/{corpus}/messages/{msg_id}"}}},{"type":"function","function":{"name":"recall_sources","description":"Verification path (not a discovery tool): take a handle from recall_corpus / recall_keyword / find_witnesses_in_corpora and fetch the raw source artifact behind it. For a mailing-list message you need the FULL triple msg_id + corpus + ym — a bare retrieve msg-id with no corpus/ym will 404 here; recover corpus/ym via walk_thread first. For a Catalog handle, supply doc_id + doc_kind. Some handles return an explicit path you can pass instead. Closes the citation loop: recall says 'this matches'; recall_sources returns 'this is the verbatim text you can quote'. Use it before quoting any recalled fact.","parameters":{"type":"object","properties":{"msg_id":{"type":"string","description":"Message-ID from a corpus recall handle (angle brackets accepted with or without)."},"corpus":{"type":"string","description":"Corpus name from the handle (e.g. 'nanog-10s')."},"ym":{"type":"string","description":"Year-month bucket from the handle (e.g. '2018-03')."},"path":{"type":"string","description":"Optional explicit file path returned by some handles."},"doc_id":{"type":"string","description":"Catalog doc slug for a Catalog handle."},"doc_kind":{"type":"string","enum":["Work","Authority","Inquiry"],"description":"Catalog record type for a Catalog handle."}}},"$endpoint":{"method":"GET","path":"/v1/recall/sources","query_template":{"msg_id":"{msg_id}","corpus":"{corpus}","ym":"{ym}","path":"{path}","doc_id":"{doc_id}","doc_kind":"{doc_kind}"}}}},{"type":"function","function":{"name":"fetch_work","description":"Fetch a single Catalog Work by slug. Returns the full frontmatter (title, ARK, holdings, list_witnesses with quotes and msg-ids, custody_events, etc.) plus the body markdown. Use after list_works/search_catalog has surfaced a Work you want to read in detail.","parameters":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"Work slug, e.g. cerf-kahn-1974"}}},"$endpoint":{"method":"GET","path":"/v1/works/{slug}"}}},{"type":"function","function":{"name":"fetch_authority","description":"Fetch a single Catalog Authority (person or organization) by slug. Returns the full frontmatter (title, ARK, entity_type, website, identifiers like Wikidata) plus the body markdown plus a reverse-index of Works that name this Authority as creator/custodian/custody-event-party. Use after a Work mentions an Authority you want to learn more about, or after a graph-walk surfaces a high-centrality Authority.","parameters":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"Authority slug — the doc_id/slug returned by search_catalog or the graph tools (e.g. estrada-susan). Do NOT guess a surname-only slug; resolve it from a search result first."}}},"$endpoint":{"method":"GET","path":"/v1/authorities/{slug}"}}},{"type":"function","function":{"name":"fetch_inquiry","description":"Fetch a single Research Inquiry by slug. Returns the full dossier — established facts, open questions, next actions, witnesses, revision log — plus the human-readable essay body. Use after list_inquiries surfaces a relevant investigation thread.","parameters":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"}}},"$endpoint":{"method":"GET","path":"/v1/inquiries/{slug}"}}},{"type":"function","function":{"name":"fetch_atlas_theme","description":"Fetch a single Atlas theme by slug. Returns the cluster metadata plus the body markdown — the theme-naming essay, year-by-year salience, top contributors, and sample messages with archive_url evidence links. Use after list_atlas_themes surfaces a thematic cluster you want to read in detail.","parameters":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"}}},"$endpoint":{"method":"GET","path":"/v1/atlas/themes/{slug}"}}},{"type":"function","function":{"name":"graph_neighbors","description":"Return the immediate neighborhood of a node in the IHI cross-reference graph. Use to discover what Works cite a given Authority, what other Works are related to a given Work, what Inquiries witness a given Work, or — for RFCs — the citation lineage. Pass node_type=work|authority|inquiry|rfc plus the slug; get back inbound and/or outbound edges with their kind (creator, custodian_current, related, body_link, witness_evidence, and for RFCs obsoletes/updates/cites/authored_by). For an RFC the slug is its number: node_type=rfc, slug=1105 → node id rfc:1105, whose outbound edges walk the citation DAG (e.g. rfc:1105 cites rfc:904, authored_by lougheed-kirk & rekhter-yakov).","parameters":{"type":"object","required":["node_type","slug"],"properties":{"node_type":{"type":"string","enum":["work","authority","inquiry","rfc"]},"slug":{"type":"string","description":"Node slug. For node_type=rfc this is the bare RFC number (e.g. 1105)."},"direction":{"type":"string","enum":["outbound","inbound","both"],"default":"both"}}},"$endpoint":{"method":"GET","path":"/v1/graph/neighbors/{node_type}/{slug}"}}},{"type":"function","function":{"name":"graph_path","description":"Find the shortest path between two nodes in the IHI cross-reference graph (BFS, undirected). Returns a sequence of nodes and the edge kinds connecting them. Use when an investigator asks 'how is X connected to Y?' — e.g. 'how is the Cerf & Kahn 1974 paper connected to the modern Lauren Weinstein operator-relay ecosystem?' Node ids are type-prefixed (work:slug, authority:slug, inquiry:slug, rfc:NNNN); RFCs join the same graph, so graph_path(src=rfc:4271, dst=rfc:904) walks the BGP-to-EGP citation spine.","parameters":{"type":"object","required":["src","dst"],"properties":{"src":{"type":"string","description":"Source node id, e.g. work:cerf-kahn-1974"},"dst":{"type":"string","description":"Destination node id, e.g. authority:lweinstein"},"max_depth":{"type":"integer","default":6,"minimum":1,"maximum":10}}},"$endpoint":{"method":"GET","path":"/v1/graph/path"}}},{"type":"function","function":{"name":"list_works","description":"List Catalog Works (held + sought primary-historical artifacts of Internet history). Returns a paginated summary list with slug, title, ARK, shelf (e.g. operator-history), priority (foundational/context), holdings status, weight, creators, and witness count. Use to scan the Catalog by topic family or to find candidates before fetching their full content with fetch_work. Filterable by shelf, priority, holdings, creator slug, min weight, and whether the Work has any list_witnesses citations.","parameters":{"type":"object","properties":{"shelf":{"type":"string","description":"e.g. operator-history, protocols-and-standards, oral-histories, mailing-lists"},"priority":{"type":"string","enum":["foundational","context"]},"holdings":{"type":"string","enum":["held","partial","unheld","external"]},"creator":{"type":"string","description":"Authority slug, e.g. cerf"},"min_weight":{"type":"integer","minimum":0,"maximum":100},"has_witnesses":{"type":"boolean","description":"Restrict to Works with at least one list_witnesses entry"},"limit":{"type":"integer","default":50,"maximum":500},"offset":{"type":"integer","default":0}}},"$endpoint":{"method":"GET","path":"/v1/works"}}},{"type":"function","function":{"name":"list_inquiries","description":"List the IHI Research Inquiries — living dossiers that synthesize what is known and what remains unknown about specific historical-research questions. Each entry includes the prompting question, prompting author, and counts of established facts, open questions, and witnesses. Use to discover existing investigation threads before opening a new one.","parameters":{"type":"object","properties":{"limit":{"type":"integer","default":50},"offset":{"type":"integer","default":0}}},"$endpoint":{"method":"GET","path":"/v1/inquiries"}}},{"type":"function","function":{"name":"list_corpora","description":"List the message-corpus namespace — ~1600 mailing-list / discussion corpora that have Phase-1 LLM extractions (GET /v1/corpora). Each entry: name, kind (phase1 | mbox-only), namespace, n_parts (shard count), n_records (+ n_mbox_files for mbox-only). No filesystem paths. Test/smoke fixture corpora are hidden (fixtures_hidden reports the count; include_fixtures=true lists them). Pass brief=true for name+kind only (about half the bytes). The listing is cached server-side and answers in well under a second once warm. This is one of THREE distinct corpus namespaces in the kit, and they do NOT interchange: (1) these message-corpus names — used by recall_corpus, recall_keyword, fetch_message_body, and find_witnesses_in_corpora; (2) the fixed six-shelf FAISS enum (rfcs, ietf-drafts, treasures-text, conf-talks, conf-visual, thread-digests) — used only by recall_extras; (3) the thread umbrella/decade-shard space (e.g. nanog auto-expands to nanog-90s / -00s / -10s / -20s) — used by search_threads(by_corpus) and retrieve. NOTE some corpora appear BOTH as an umbrella (nanog) and as decade shards (nanog-90s); pick the granularity the target tool wants. Call this before find_witnesses_in_corpora / recall_keyword to get an exact corpus string — don't guess. Returns {n_corpora, items:[…], results:[…] (same list under both keys), namespaces, fixtures_hidden?}.","parameters":{"type":"object","properties":{"brief":{"type":"boolean","default":false,"description":"name + kind only"},"include_fixtures":{"type":"boolean","default":false,"description":"also list test/smoke fixture corpora"}}},"$endpoint":{"method":"GET","path":"/v1/corpora","query_template":{"brief":"{brief}","include_fixtures":"{include_fixtures}"}}}},{"type":"function","function":{"name":"list_atlas_themes","description":"List Atlas Scale 1 themes — named clusters of mailing-list discussion derived from UMAP+HDBSCAN over Phase 1 message embeddings. Each theme has a register (historical/operational/policy/archival), temporal_shape (abiding/burst/recurring), first/last year, message count, and a candidate_inquiry_seed flag indicating whether it is a good candidate for a new Research Inquiry. Use to discover thematic threads in the corpus.","parameters":{"type":"object","properties":{"register":{"type":"string","description":"e.g. historical, operational, policy, archival"},"temporal_shape":{"type":"string","description":"e.g. abiding, burst, recurring"},"candidate_inquiry_seed":{"type":"boolean"},"min_messages":{"type":"integer","minimum":0},"limit":{"type":"integer","default":30}}},"$endpoint":{"method":"GET","path":"/v1/atlas/themes"}}},{"type":"function","function":{"name":"resolve_identifier","description":"Resolve any IHI slug or ARK identifier to its canonical URL, ARK, and n2t.net resolver URL. Use to mint a citation, or to discover the full URL when given a bare slug.","parameters":{"type":"object","properties":{"slug":{"type":"string","description":"Use slug OR ark, not both"},"ark":{"type":"string","description":"ARK string, e.g. ark:/26338/c/cowie-presentations-2001-2026"}}},"$endpoint":{"method":"GET","path_when_slug":"/v1/resolve/{slug}","path_when_ark":"/v1/ark/{ark}"}}},{"type":"function","function":{"name":"evidence_chain","description":"Walk the IHI evidence chain — every (witness message, embedded URL) pair surfaced by the evidence_expand pipeline. Filter by container msg-id (find what URLs a specific witness pointed at), host (find every message that pointed at a given site), or classification (e.g. high_priority_pdf, candidate). Use to follow URLs out of the witness layer into the actual content the community was pointing at.","parameters":{"type":"object","properties":{"witness_msg_id":{"type":"string"},"host":{"type":"string","description":"Embedded URL host, e.g. www.vortex.com"},"classification":{"type":"string","description":"e.g. high_priority_archive, high_priority_pdf, candidate, note"},"limit":{"type":"integer","default":100}}},"$endpoint":{"method":"GET","path":"/v1/evidence/chain"}}},{"type":"function","function":{"name":"catalog_gaps","description":"Return the broken-references list — every cross-reference in the Catalog that points to a node (Authority or Work) that doesn't yet exist. The Catalog's explicit gap list, suitable for picking the next missing Authority to draft. Each entry includes source node, missing target slug, relationship kind, and source field.","parameters":{"type":"object","properties":{}},"$endpoint":{"method":"GET","path":"/v1/graph/broken-references"}}},{"type":"function","function":{"name":"topical_gaps","description":"Return curated TOPICAL gaps — subjects IHI knows it should have but currently doesn't (e.g. Taiwan Internet history, China mainland history, AfNOG/AfriNIC, etc.). Distinct from catalog_gaps (which returns broken cross-references). Use this when an investigation surfaces a topic IHI has nothing on, to affirmatively say \"this is a known gap, not an oversight\" rather than guessing. Each entry includes slug, title, region, why_missing, what_exists (pointers to whatever IHI does have that touches the topic), candidate_sources, and priority.","parameters":{"type":"object","properties":{}},"$endpoint":{"method":"GET","path":"/v1/graph/topical-gaps"}}},{"type":"function","function":{"name":"evidence_candidates","description":"Return ranked recovery candidates from the evidence chain — distilled, deduplicated URLs that are referenced N times in the corpus by M authors but are NOT yet cataloged as IHI Works. The actionable digest for 'what should we accession next?' Filter by classification or minimum attestation count.","parameters":{"type":"object","properties":{"classification":{"type":"string"},"min_attestations":{"type":"integer","default":1},"limit":{"type":"integer","default":50}}},"$endpoint":{"method":"GET","path":"/v1/evidence/candidates"}}},{"type":"function","function":{"name":"open_questions","description":"Return every open question across every Inquiry, optionally filtered by priority (P1/P2/P3) or status (unresolved/partial/substantially-resolved/closed). Use to answer 'what is the IHI corpus currently trying to figure out?' or to pick a question to investigate.","parameters":{"type":"object","properties":{"priority":{"type":"string","enum":["P1","P2","P3"]},"status":{"type":"string","enum":["unresolved","partial","substantially-resolved","closed"]}}},"$endpoint":{"method":"GET","path":"/v1/inquiries/open-questions/all"}}},{"type":"function","function":{"name":"resolve_provider","description":"Resolve a provider/ISP/network name (or an AS number) into ASNs, peers, and IXes via live infrastructure data (local IYP graph + RIPEstat), returning search_seeds to reseed corpus searches - THE move when a company name returns nothing from the shelves. Give it a brand ('Elcat', 'Beeline') or an AS number ('AS8449'); it returns matched ASes with holder, country, alternate names, IXP memberships, and neighbours (transit upstreams ranked by AS-Hegemony, plus peers), and a deduped search_seeds list (AS-number forms, holder brand tokens, peer/upstream network names, IXP names). Reseed retrieve/recall_keyword with those seeds - the AS number alone often unlocks the operator-list record. Facts here are LIVE infrastructure data (present-day BGP/registry), not corpus holdings; label them so. Answers within a ~10 s budget: the response's `enrichment` object says whether every upstream step completed (complete, elapsed_s, missing[]); when IYP is slow you get a partial answer with the seeds that were reachable rather than a 503 after 40 s. A bare AS number is answered even when both backends are down (source 'none', unenriched: true).","parameters":{"type":"object","properties":{"name":{"type":"string","description":"A provider/ISP/network name ('Elcat', 'Beeline') or an AS number ('AS8449', '8449')."}},"required":["name"]}},"$endpoint":{"method":"GET","path":"/v1/resolve_provider"}},{"type":"function","function":{"name":"search_deck_text","description":"USE when you need a SPECIFIC SLIDE — page-level literal search across ~1.95M transcribed conference deck pages. Returns the talk, the PAGE NUMBER, the matching passage with context, and a citeable door. retrieve answers at DOCUMENT granularity ('this talk matched'); this answers at PAGE granularity ('slide 7 says X'). WHEN: citing a slide; finding a term that appears once inside a long deck whose title is unrelated; recovering names/figures that live only in slide furniture (org charts, network diagrams, agendas). Real example: query 'TAS-IX' returns a FARSI-language CAPIF agenda, page 5, naming the director of TAS-IX — a person no title-level search reaches. CAVEAT: slide text is a vision model's reading of a rendered page, i.e. a transcription of an image. Quote it as slide content and verify any figure you intend to print against the page itself via the returned door. A ZERO RESULT IS A SEARCH MISS, NEVER PROOF OF ABSENCE — the response carries a _search_note reminding you to try spelling variants (hyphen/space/glued: AMS-IX / AMS IX / AMSIX; transliterations: Qaz-/Kaz-; expanded and local-language forms). A real case from this collection: 'QazGovIX' finds nothing, 'KazGovIX' finds the deck that documents it.","parameters":{"type":"object","properties":{"query":{"type":"string","description":"Literal substring to find in slide text; case-insensitive, punctuation included."},"corpus":{"type":"string","description":"Optional: restrict to one corpus, e.g. 'conf-capif'."},"top":{"type":"integer","description":"Max rows (1-100, default 20)."}},"required":["query"]},"$endpoint":{"method":"POST","path":"/v1/recall/deck","body_template":{"query":"{query}","corpus":"{corpus}","top":"{top}"}}}},{"type":"function","function":{"name":"get_deck_pages","description":"FETCH every transcribed slide page of ONE talk, in page order — the deck as a readable document. Use after search located the talk (retrieve / search_deck_text) and you need the WHOLE deck: reading a presentation end-to-end, quoting a specific slide with its page number, or the written-register forms of terms (slides are the WRITTEN layer; the interpreter track is not). Slide text is vision transcription of a rendered page — verify figures you will print against /talk?id=… . Companion: get_floor_record for the same talk's spoken layers. Status codes: 400 if talk_id is not 16 hex chars, 404 if no talk record exists, 200 otherwise with deck_status one of transcribed | pending (deck held, vision not yet run) | transcript (no deck, captions transcript served at transcript_door) | text-document (minutes/paper, see note) | none. When the vision pass covered fewer pages than the deck has, truncated is true and n_pages_total gives the deck's page count; the pdftotext layer for the whole deck is at get_artifact(handle='talk:<id>', max_chars=400000).","parameters":{"type":"object","properties":{"talk_id":{"type":"string","description":"16-hex talk id"}},"required":["talk_id"]},"$endpoint":{"method":"GET","path":"/v1/talks/{talk_id}/deck-pages"}}},{"type":"function","function":{"name":"get_floor_record","description":"FETCH one talk's FLOOR RECORD: the speaker's own words (Russian Whisper ASR, timestamped cues) plus the live interpreter's English (VTT cues) — the two SPOKEN layers, unusual for any conference archive. BOTH are ASR: aggregate, never trust a single line. The MT of the floor track is deliberately not served (alignment aid, not evidence). Session/day-stream talks return the whole recording's cues — locate the talk via its &t= video offset. Companion: get_deck_pages for the written layer.","parameters":{"type":"object","properties":{"talk_id":{"type":"string","description":"16-hex talk id"}},"required":["talk_id"]},"$endpoint":{"method":"GET","path":"/v1/talks/{talk_id}/floor"}}}]}