Choosing a tool¶

What you'll do: pick the right occam_* tool from your goal — without memorizing all fifteen names.

Decision guide¶

I want to…	Call	Notes
Connect Occam to my AI	`occam connect` (CLI)	Detect hosts; auto-connect live-validated ones — onboarding · MCP hosts
See a recorded first job	Workflow gallery	Named host builds; not a global quality score
Save one task as a cited folder	`occam pack` (CLI)	Orchestrates existing tools; not a new MCP tool — context packs
Research one site under budgets	`occam research` (CLI)	Map then transcode; resume/cancel; not a new MCP tool — site research
Re-read docs for command/default changes	`occam brief` (CLI)	`if_none_match`; not `occam_watch` — docs change brief
Inspect whether a page backs a sentence	`occam cite` (CLI)	Wraps `occam_claim_check`; you judge support — citation inspector
Read one page as Markdown	`occam_transcode`	Only `url` is required; add `focus_query` + `fit_markdown` to save tokens
Check if a URL is worth fetching	`occam_probe`	Cheap; returns extractability score and recommended backend
Research several pages	`occam_digest`	Up to 8 URLs; use `focus_query` for synthesis
Find URLs on a site I don't know yet	`occam_map` → `occam_digest`	Map discovers links; digest reads them
Search the web for URLs	`occam_search` → probe/transcode	Default DuckDuckGo; pass `handle` or `url` (`S1` is latest-search only)
Get structured fields (price, author, …)	`occam_playbook_resolve` → `occam_extract_knowledge`	Needs a playbook with `knowledge_schema`
Use a site's tuned extract recipe	`occam_playbook_resolve` → `occam_transcode`	`playbook_policy=auto` (default)
Fix a hard site (draft a playbook)	`occam_transcode` fails → `occam_playbook_heal` → edit JSON → `occam_playbook_lint` → `occam_playbook_save`	Local only
Look up evidence blocks for one sentence	`occam_claim_check`	Evidence/support lookup + Merkle membership; you judge support vs refute — does not prove the claim
Heuristic citation-support assessment	`occam_attest`	Status classifier over retrieved blocks — not cryptographic attestation
Verify a signed extraction	`occam_verify`	Integrity check against a key; optional live drift
Build an auditable URL set for RAG	`occam_dataset_export`	1–20 URLs, manifest signature (integrity, not factual correctness)
Watch a page for changes	`occam_watch`	EXPERIMENTAL — `OCCAM_WATCH_MCP=1`
Compare multi-source / multi-vantage agreement	`occam_crosscheck`	EXPERIMENTAL — `OCCAM_CONSENSUS_MCP=1`; agreement ≠ correctness (not “consensus proof”)
Session failure telemetry	`occam_failure_atlas`	EXPERIMENTAL — `OCCAM_ATLAS_MCP=1`
Queue many URLs asynchronously	`occam_batch_submit` → status → results	EXPERIMENTAL — `OCCAM_BATCH_MCP=1`

Common flows¶

Read one article¶

occam_probe(url)          # optional — skip if you trust the URL
occam_transcode(url)

Add fit_markdown: true and focus_query: "your question" when context is tight. For technical references, the focus ranker preserves numeric identifiers and exact anchors. A URL such as https://example.org/spec#section-15.5.2 uses the fragment as local section intent while fetching the fragment-free page.

On success, optional quality.verdict may be short_quality or rich — both are usable. Do not treat a short body as failure.

For a direct npm /package/<name> permalink blocked by the presentation site, the bundled playbook may return public latest-version registry metadata instead. Check backend=npm_registry_package and url.finalUrl for the actual source; this is not a browser bypass and does not guarantee README text.

For an exact crates.io /crates/<name> permalink, the bundled playbook may resolve the latest non-yanked version through the sparse index and return its official rendered README. Check backend=crates_io_readme and the static.crates.io url.finalUrl. Other crates.io paths stay on the normal acquisition ladder rather than being guessed or rewritten.

Multi-source research¶

occam_search(query)       # optional — keyless DuckDuckGo by default
occam_digest(urls, focus_query="…")

Or discover then digest:

occam_map(url, source="sitemap")
occam_digest(urls from map)

Structured facts¶

occam_playbook_resolve(url)
occam_extract_knowledge(url)   # only if schema exists

If resolve shows no schema, use occam_transcode for prose instead.

Verifiable report¶

occam_transcode(url, json_blocks=true)
occam_claim_check(claim, url)   # per critical sentence
occam_verify(receipt, markdown) # offline check

Before shipping a multi-source answer:

occam_attest(claims=[{claim, sourceUrl}, …])

When not to call a tool¶

Situation	Do this instead
`ok: false` on transcode	Read `failure.code`; do not invent content
`captcha_or_challenge`	Try `session_profile` + local `backend_policy=browser`; then stop — no CAPTCHA solver
`http_404`	Fix or drop the URL
No `knowledge_schema`	Use `occam_transcode`, not `occam_extract_knowledge`
Several known URLs	One `occam_digest`, not N× `occam_transcode`
Short but complete page (`quality.verdict=short_quality`)	Treat as success — do not heal / escalate
`thin_extract` after browser already tried	Stop; page is genuinely chrome/shell/near-empty

Thin ≠ short: thin_extract means bad extraction (promo chrome, consent shell, headings-only interstitial). A glossary leaf or status page can be small and still ok: true with quality.verdict=short_quality.

Full failure actions: Failure codes.

Anti-patterns (measured friction)¶

Anti-pattern	Prefer
Generic host `web_extract` / memory of the page	`occam_transcode(url)` — default page reader
Rename mental model to `occam_read`	Keep `occam_transcode` (A/B: rename hurt first-tool pick)
8× `occam_transcode` for research	One `occam_digest`
`occam_playbook_heal` on every thin or short page	Heal only for real BE after reading `failure` / `agentMeta`
Full tool surface on a small local model	`OCCAM_PROFILE=researcher` (or `reader`)

Exposing tools to an agent (keep the set narrow)¶

If you drive occam from a small local model — or any agent that drifts into playbook authoring on a simple read — narrow the surface with OCCAM_PROFILE instead of manually filtering tools in the host config. A large tool set both dilutes tool-selection and invites heal/save loops on thin_extract.

`OCCAM_PROFILE`	Exposes	Hides (unless `full`)
`reader`	`occam_client_capabilities`, `occam_transcode`, `occam_probe`, `occam_map`, `occam_digest`, `occam_extract_knowledge`, `occam_search`, `occam_verify`	playbook authoring, attest/dataset
`researcher` (recommended for coding agents)	reader + `occam_claim_check`	heal/save/resolve/lint/attest/dataset
`auditor`	researcher + `occam_attest`, `occam_dataset_export`, `occam_playbook_lint`	heal/save/resolve
`full`	all fifteen	—

Set in the MCP host env block, e.g. "OCCAM_PROFILE": "researcher". Details: configuration.md.

Client budget: at session start call occam_client_capabilities with your context window (or set OCCAM_CLIENT_CONTEXT_TOKENS) so later reads without max_tokens stay within what you can hold — see configuration.md.

Smaller models also emit cleaner tool calls with a narrow set: on the full fifteen, an 8B model sometimes wrote the call as prose instead of a structured tool call; on a single tool it was reliable. Larger tool-calling models stay structured across the full set but still benefit from a role-scoped surface.

Parameter defaults worth knowing¶

Tool	Default that matters
`occam_transcode`	`backend_policy=http_then_browser`; only `url` required
`occam_digest`	`fit_markdown=true`; max 8 URLs; pass `urls` as a native string array (legacy strings are deprecated)
`occam_map`	`source=homepage`; HTTP-only, up to 64 links
`occam_playbook_save`	`verify=true` dry-runs before write

Full tables: Tools reference.

Worked recipes¶

Copy-paste flows: Recipes.