Fillin

Use this when your model is small / cheap / weaker at tool-result
synthesis (Llama, Gemini Flash, Mistral, Nemotron, Qwen). Fillin runs
a server-side LLM pass over the retrieved post-cutoff documents and
returns a 150-250 word answer with [title](url) citations already
embedded — you can quote it directly.

Premium models (Opus, Sonnet, GPT-4o) usually get better results from
`fillin_query` and synthesizing themselves, but this tool works for
any caller. Costs more than fillin_query because of the synthesis pass.

Returns:
    A dict with:
      - answer: the synthesized paragraph (str | None)
      - citations: list of {title, url} extracted from the answer
      - corpus_match: "strong" | "weak" | "none" — quality of retrieval
      - top_score: float — top reranked similarity score
      - model: the synthesizer model used (e.g. claude-haiku-4-5)
      - reason: set when answer is None (e.g. "no_relevant_docs")
      - results: raw post-cutoff documents (same shape as fillin_query)
      - cutoff, query, gap_days: echoes for context

Call this whenever the user asks about events, releases, papers, issues,
or news that might post-date your training data. Fillin only returns
documents published AFTER `cutoff`, so nothing returned is redundant
with what the model already knows.

Args:
    query: Natural-language search query (e.g. "rust async runtimes").
           Max 512 characters.
    cutoff: ISO-8601 date representing the agent's training cutoff
            (e.g. "2026-01-01"). Documents on or before this date are
            excluded from results.
    k: Number of documents to retrieve, 1-20. Defaults to 5.

Returns:
    A dict with:
      - cutoff: echoed cutoff (ISO timestamp)
      - query: echoed query
      - gap_days: days between cutoff and now
      - results: list of {id, source, url, published_at, title, text, score}

Each result row carries a structured `affected` list (one entry per
affected package: ecosystem, name, vulnerable_range, patched_range) and
a numeric `severity_score` (CVSS baseScore, nullable on OSV-only rows).
A buyer can act on the returned row — pin to `patched_range` — without
a second hop to NVD or GHSA.

Each result row carries the question, venue, close date, volume, and
a first-sight price snapshot embedded in `text`. Prices in the corpus
are point-in-time at first ingestion — for live pre-trade pricing,
follow the `url` to the venue and read the current quote there.