Skip to content
ollama-intern-mcp

Tool Reference

Tools are grouped into four tiers. At-a-glance: 31 atoms (15 original + 13 added in v2.1.0 + code_review + the v2.9 pair verify_claims / log_stats) + 3 briefs + 3 packs + 7 artifact tools = 44 total. Pack and artifact tiers remain frozen at 3 and 7; the atom freeze was lifted at v2.1.0 and new atoms require an audit-justified gap, tests, handbook page, and CHANGELOG entry.

Per-tool reference pages

Section titled “Per-tool reference pages”

Every tool has a dedicated page. Six are hand-curated deep-dives (examples, pitfalls, related-tool guidance); the rest are generated from each tool’s zod schema and registration — the same source of truth the server validates against at the wire, kept byte-in-sync by CI (npm run gen:tool-docs).

Atoms (31 total)

Section titled “Atoms (31 total)”

Original atoms (15)

Section titled “Original atoms (15)”

Job-shaped primitives. Pick the tool that names the job; the tier follows.

Tool Tier Purpose
ollama_research Deep Takes file paths, not raw text. Chunks locally, answers with citations validated against source_paths. v2.2.0+ surfaces structured weak / abstained / sources_address_question fields — see README §Abstention contract.
ollama_corpus_search Embed Persistent corpus concept search (BM25 + RRF fusion).
ollama_corpus_answer Deep Chunk-grounded synthesis over a corpus. Every claim cites a chunk id. v2.2.0+ accepts optional min_top_score topicality threshold and surfaces per-citation retrieval scores — see README §Abstention contract.
ollama_corpus_index Embed Build or update a corpus from a root directory.
ollama_corpus_refresh Embed Incremental refresh using the corpus manifest.
ollama_corpus_list — List known corpora.
ollama_embed_search Embed Ad-hoc vector search.
ollama_embed Embed Batch-aware embeddings.
ollama_classify Instant Single-label classification with confidence. Batch-capable. v2.2.0+ accepts optional frame and surfaces frame_alignment topicality output — see README §Frame-bound extraction.
ollama_triage_logs Instant Stable-shape log digest: errors, warnings, suspected root cause. Batch-capable.
ollama_summarize_fast Instant Gist of short input (~4k tokens). v2.2.0+ accepts optional frame and surfaces frame_alignment topicality output — see README §Frame-bound extraction.
ollama_summarize_deep Deep Digest of long input (~32k tokens) with optional focus. v2.2.0+ accepts optional frame and surfaces frame_alignment topicality output — see README §Frame-bound extraction.
ollama_draft Workhorse DRAFT code/prose stubs. Runs compile check when language is known. Never autonomous.
ollama_extract Workhorse Schema-constrained JSON extraction. Batch-capable. v2.2.0+ accepts optional frame and surfaces frame_alignment topicality output — see README §Frame-bound extraction.
ollama_chat Workhorse Ad-hoc chat. Last resort. If you reach for this often, a specialty tool is missing.

Batch-capable atoms (classify, extract, triage_logs) accept items: [{ id, text }] and return one envelope per batch. Duplicate ids refused.

Briefs (3 flagship primitives)

Section titled “Briefs (3 flagship primitives)”

Evidence-backed structured operator briefs. Every claim cites an evidence id. Unknowns are stripped server-side before the result returns. Weak evidence flags weak: true with coverage notes instead of smoothing fake narrative.

Tool Purpose
ollama_incident_brief “What just happened” — symptoms, timeline, suspected cause, investigative next checks. v2.2.0+ propagates corpus retrieval scores into evidence items when sourced from a corpus — see README §Abstention contract.
ollama_repo_brief Operator map of a repo — what it is, how it’s laid out, where to start reading. v2.2.0+ propagates corpus retrieval scores into evidence items when sourced from a corpus — see README §Abstention contract.
ollama_change_brief Change impact brief with DRAFT release note. v2.2.0+ propagates corpus retrieval scores into evidence items when sourced from a corpus — see README §Abstention contract.

Packs (3, frozen)

Section titled “Packs (3, frozen)”

Fixed pipelines end-to-end. Each runs deterministic steps and writes markdown + JSON to disk.

Tool Default root Writes
ollama_incident_pack ~/.ollama-intern/artifacts/incident/ <slug>.md + <slug>.json
ollama_repo_pack ~/.ollama-intern/artifacts/repo/ <slug>.md + <slug>.json
ollama_change_pack ~/.ollama-intern/artifacts/change/ <slug>.md + <slug>.json

Pack artifacts are rendered by code, not by a prompt — the markdown shape is deterministic.

Artifact tier (7)

Section titled “Artifact tier (7)”

Continuity surface over what packs wrote. No model calls in this tier.

Tool Purpose
ollama_artifact_list Metadata-only index, filterable by pack / date / slug glob.
ollama_artifact_read Typed read by {pack, slug} or {json_path}.
ollama_artifact_diff Structured same-pack comparison; weak-flip surfaced. Cross-pack diff is refused loudly.
ollama_artifact_export_to_path Write an existing artifact (with provenance header) to a caller-declared allowed_roots. Refuses existing files unless overwrite: true.
ollama_artifact_incident_note_snippet Deterministic operator-note fragment.
ollama_artifact_onboarding_section_snippet Deterministic handbook fragment.
ollama_artifact_release_note_snippet Deterministic DRAFT release-note fragment.

Batch workflow examples

Section titled “Batch workflow examples”

Batch-capable atoms (classify, extract, triage_logs) accept items: [{ id, text }] in a single call and return one envelope for the whole batch. Duplicate ids are refused before the model runs — id collisions fail loud with SCHEMA_INVALID.

Why batch: one prewarm, one residency probe, one envelope to parse. Ten single-item calls cost ten prewarms and ten round-trips.

Batch classify — 10 support tickets

Section titled “Batch classify — 10 support tickets”
// → Claude → ollama-intern-mcp
{
  "tool": "ollama_classify",
  "arguments": {
    "labels": ["bug", "feature-request", "question", "spam"],
    "items": [
      { "id": "t-001", "text": "login button does nothing on mobile Safari" },
      { "id": "t-002", "text": "can you add dark mode?" },
      { "id": "t-003", "text": "how do I reset my password?" },
      { "id": "t-004", "text": "BUY NOW AMAZING CRYPTO DEAL" },
      { "id": "t-005", "text": "cursor jumps to end of input on save" },
      { "id": "t-006", "text": "keyboard shortcut for save would be nice" },
      { "id": "t-007", "text": "where is the export menu?" },
      { "id": "t-008", "text": "click here for free iphone!!!" },
      { "id": "t-009", "text": "crash on empty project open" },
      { "id": "t-010", "text": "allow toggling sidebar" }
    ]
  }
}
// → envelope.result
{
  "items": [
    { "id": "t-001", "label": "bug",             "confidence": 0.94 },
    { "id": "t-002", "label": "feature-request", "confidence": 0.91 },
    { "id": "t-003", "label": "question",        "confidence": 0.88 },
    { "id": "t-004", "label": "spam",            "confidence": 0.97 },
    { "id": "t-005", "label": "bug",             "confidence": 0.86 },
    { "id": "t-006", "label": "feature-request", "confidence": 0.83 },
    { "id": "t-007", "label": "question",        "confidence": 0.79 },
    { "id": "t-008", "label": "spam",            "confidence": 0.98 },
    { "id": "t-009", "label": "bug",             "confidence": 0.92 },
    { "id": "t-010", "label": "feature-request", "confidence": 0.81 }
  ]
}

Same tier, same model, same envelope — tier_used: "instant", model: "hermes3:8b", tokens_* summed across the batch.

Batch extract — 5 commits into structured release-note fragments

Section titled “Batch extract — 5 commits into structured release-note fragments”
{
  "tool": "ollama_extract",
  "arguments": {
    "schema": {
      "type": "object",
      "properties": {
        "kind":  { "enum": ["feat", "fix", "chore", "docs", "refactor"] },
        "scope": { "type": "string" },
        "summary": { "type": "string" }
      },
      "required": ["kind", "summary"]
    },
    "items": [
      { "id": "c1", "text": "feat(corpus): surface :latest drift on refresh" },
      { "id": "c2", "text": "fix(index): TOCTOU between stat and read" },
      { "id": "c3", "text": "chore(deps): bump zod to 4.3.6" },
      { "id": "c4", "text": "docs(handbook): new troubleshooting page" },
      { "id": "c5", "text": "refactor(envelope): hoist residency into shared builder" }
    ]
  }
}

Returns { items: [{ id, extracted: { kind, scope, summary } }, ...] }.

Batch triage_logs — 3 incident windows

Section titled “Batch triage_logs — 3 incident windows”
{
  "tool": "ollama_triage_logs",
  "arguments": {
    "items": [
      { "id": "window-a", "text": "[05:07] worker-3 OOM killed\n[05:07] evicted=true" },
      { "id": "window-b", "text": "[05:14] connection reset by peer x5\n[05:14] retry-after=60" },
      { "id": "window-c", "text": "[05:21] typescript compilation succeeded\n[05:22] nothing interesting" }
    ]
  }
}

Returns a stable-shape per-item digest: errors, warnings, suspected_root_cause, next_checks. Window C will likely come back with suspected_root_cause: null and an empty errors — weak signal is weak signal, not manufactured narrative.

Concurrency contention

Section titled “Concurrency contention”

On the default dev-rtx5080 profile the tier semaphore is sized for 2 concurrent calls. A third caller blocks; a fourth caller blocks harder. Every block emits a semaphore:wait event to the NDJSON log with queue_depth, in_flight, and expected_wait_ms. See Observability for how to read those events.

If you’re dispatching 3+ parallel batches and seeing retries, that’s the semaphore — not a bug. Drop parallelism or move to a profile with more VRAM headroom.

id collision behavior

Section titled “id collision behavior”

Duplicate ids inside one batch refuse at schema validation (SCHEMA_INVALID), before any model work. Pick stable, unique ids per call — there is no implicit de-duplication.

v2.1.0 atoms (13)

Section titled “v2.1.0 atoms (13)”

Tier freeze stays at 4 — everything here extends existing tiers, no new tier class. Combined with the 15 originals above, the atom tier total is 28.

Ops tools

Section titled “Ops tools”
Tool Purpose
ollama_doctor First-run prereqs + status snapshot: Ollama reachability, loaded vs pulled vs required models, profile/tiers, allowed_roots, recent errors. Returns healthy: boolean for a quick gate.
ollama_log_tail Tail the NDJSON call log from inside an MCP session, with filters. See Observability → ollama_log_tail.
ollama_log_stats Aggregate the NDJSON receipts into measured economics (no model call): totals + per-tool/per-tier tokens, cloud/local/degraded split, cloud→local fallback_rate, tier timeout/fallback counts, p50/p95 elapsed_ms overall and per tool, bounded by since. The rollup behind “cloud vs local split” and “tokens this week” — log_tail shows the raw events behind any number here. Added v2.9.
ollama_batch_proof_check Run tsc / eslint / pytest / ruff / cargo-check over a set of paths; single envelope with per-check pass/fail. Executes under cwd validation + per-check timeouts — new security surface, see SECURITY.md.

Refactor & verification tools

Section titled “Refactor & verification tools”
Tool Purpose
ollama_code_map Structural map of a code tree (languages, frameworks, entrypoints, build commands). Reads the caller-declared source_paths (.. refused); scope is caller-declared, not operator-confined — see SECURITY.md.
ollama_code_citation Given a question over source_paths, returns a synthesized answer with every claim grounded at {file, start_line, end_line}. Citations outside scope stripped.
ollama_code_review Structured PR-review findings (bugs, risks, nits) over a diff / source_paths. Workhorse tier; review-only — never edits. Added post-v2.1.0.
ollama_verify_claims The counterpart to code_review: review GENERATES findings, this ADJUDICATES claims — a cross-family Ollama Cloud flagship panel (default deepseek / kimi / glm) votes CONFIRMED / REFUTED / UNCERTAIN per claim, lone-dissent-never-decides. Cloud-required (CLOUD_NOT_CONFIGURED without a key); served-model-checked jurors; weak flag when the panel thins. See verify-claims. Added v2.9.
ollama_multi_file_refactor_propose Reads N files, returns a coordinated per-file change plan with risk levels, cross-file impact, affected imports, and verification steps. No writes — a plan for you (or Claude) to execute.
ollama_refactor_plan Phased sequencing for a proposed refactor: which files change in which phase, parallelism, tests to write, rollback strategy. Pairs with multi_file_refactor_propose.

Artifact tools

Section titled “Artifact tools”
Tool Purpose
ollama_artifact_prune Age-based artifact deletion (older_than_days, optional pack filter). Dry-run default — dry_run: false must be explicit. See Artifacts → artifact_prune.
ollama_hypothesis_drill Takes {artifact_slug, hypothesis_index} from an existing incident_pack, produces a focused sub-brief for that single hypothesis without re-running the pack.

Corpus tools

Section titled “Corpus tools”
Tool Purpose
ollama_corpus_health Per-corpus health summary: chunks, staleness_days, embed_model, drift detection, failed_paths count, write_complete flag, amend status. Superset of corpus_list.
ollama_corpus_amend Additive in-place edit to an existing corpus. Breaks the “corpus is a pure disk snapshot” invariant; subsequent answers over the corpus surface has_amended_content: true. See Observability → corpus_amend.
ollama_corpus_amend_history Read-only companion to corpus_amend: lists which paths have been amended, when, and the current vs original chunk hashes. Use before deciding whether to re-index.
ollama_corpus_rerank Post-retrieval re-sort of corpus_search hits by recency (file mtime), path_specificity (deeper paths), or lexical_boost (term matches in preview).
ollama_corpus_search with filter Existing tool gained {filter: {path_glob?, since?}} to narrow to matching paths or freshness window.
ollama_corpus_search with explain: true Existing tool gained per-hit “why matched” reasoning (top-5 cap, graceful degrade if the explain model is unavailable).
ollama_summarize_deep with source_path Existing tool gained a single-file source_path shape so callers stop having to prepack text.

End-to-end refactor workflow (new tools composed)

Section titled “End-to-end refactor workflow (new tools composed)”

Say you want to rename foo to bar across five files. The v2.1.0 flow:

  1. ollama_code_map({source_paths: [...]}) — confirm the repo’s languages, frameworks, entrypoints. Feeds context.
  2. ollama_multi_file_refactor_propose({files, change_description: "rename foo to bar"}) — get the coordinated per-file change plan with risk levels and affected imports.
  3. ollama_refactor_plan({files, change_description}) — get the phased sequencing (which file first, parallelism, rollback).
  4. Execute the changes (via Claude / editor / ollama_draft per file).
  5. ollama_batch_proof_check({checks: ["typescript", "eslint"], files}) — verify nothing broke.
  6. If something surprises you: ollama_code_citation({question: "where is bar now called?", source_paths}) to audit.

None of the 13 new v2.1.0 atom tools write to disk; all writes are yours to authorize.

Envelope

Section titled “Envelope”

Every tool returns the same envelope — see Envelope & tiers.

Deeper dives

Section titled “Deeper dives”
  • Corpora — full lifecycle for corpus_index / refresh / search / answer
  • Error codes — every structured error a tool can return and what to do
  • Observability — NDJSON log, event kinds, jq recipes, ollama_log_tail
  • Comparison — honest matrix vs other local-LLM MCPs