# Tools And Web Search

Omnius has two related tool surfaces:

- the agent tool catalog offered to a model during an Omnius run; and
- the daemon's direct-call registry exposed by `/v1/tools`.

Discovering a tool does not imply that it is directly callable. Always inspect
the tool metadata and its invocation interfaces.

## Discover Before Calling

```bash
omnius discover "web search"
omnius show tool.web-search
omnius discover "tools API" --kind api
```

Daemon metadata:

```bash
curl -s http://127.0.0.1:11435/v1/tools
curl -s http://127.0.0.1:11435/v1/tools/web_search
```

`GET /v1/tools/{name}` describes the schema, scope, risk, network behavior,
and invocation mode. A tool is directly callable only when its returned
metadata says `direct_callable: true`.

## `web_search` Is Agent-Bound

`web_search` is intentionally documented as agent-bound. Inspect its schema
through discovery or `GET /v1/tools/web_search`, then execute it through an
agent loop:

```bash
curl -s -X POST http://127.0.0.1:11435/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <run-key>' \
  -H 'x-omnius-min-version: <required-version>' \
  -d '{
    "model": "<configured-model>",
    "messages": [{"role":"user","content":"Find current primary sources for this claim."}],
    "agent_loop": true,
    "include_daemon_tools": ["read"],
    "prompt_template": "factual-first"
  }'
```

Equivalent agentic entrypoints are `POST /v1/chat` and `POST /v1/run`.
`include_daemon_tools: ["read"]` offers read-scope tools such as
`web_search`, `web_fetch`, and safe file inspection to the model.
`prompt_template: "factual-first"` requests a search-first policy but does not
expand auth scope or bypass the tool policy.

Do not call `POST /v1/tools/web_search/call` unless the live metadata for the
installed service explicitly marks it direct-callable. Catalog presence,
read-scope classification, or a tool schema alone does not grant that
invocation mode.

## Complete Web Sources

`web_fetch` retains the complete native response and its byte hash. Its `text`
view includes all static body sections, articles, tables, code, captions and
exact link/image/form destinations;
`format: "raw_html"` returns complete markup, including script and API clues.
The legacy `max_length` argument is accepted but ignored, so it cannot discard
later source content. Context capacity is handled by the agent runtime: use the
complete view when it fits, otherwise extract from the immutable full source
and keep unresolved coverage explicit. A selected excerpt is not a full read.

Static text does not establish what a JavaScript application renders or that
missing information is absent. Inspect sparse or script-dependent pages with
an available authorized browser. Responses above the 5 MiB fetch limit fail
explicitly instead of returning a successful partial prefix. Supplemental
image/date metadata indexes are selective; the complete raw source remains
available for broader inspection.

Browser content, DOM, selected-element and evaluation reads also retain the
complete returned view, including valid complete evaluation JSON. Their source
receipts describe that actual scope; a selected element or evaluation result is
not a complete rendered-page observation. Crawler results retain each returned
page's content, links and metadata within the explicit page/depth scope.

Oversized views use isolated source workers that receive the full request and
every requested facet. They account for contiguous source ranges, validate
literal source quotes and retain all findings. An unfinished pass reports its
remaining cursor; it cannot establish absence in unread material. If the full
findings do not fit the parent context, they remain in an owned artifact for
explicit reading or reduction.

Completed passes also retain a compact artifact containing every finding,
separate from the verbose checkpoint. Read that artifact to reopen all findings
without repeating extraction. If the intact request and required output reserve
cannot fit the selected model's context, the runtime pauses explicitly; it does
not substitute a shortened page or repeated tiny-output requests.

For a current task's retained extraction, `artifact_read` accepts
`resume_source_extraction: true` with the exact source/findings `artifact_uri`.
This resumes remaining chunks without replaying a browser evaluation. It cannot
be combined with a query or line range. Restarted or foreign tasks cannot adopt
that live resumer; the artifact remains readable and the runtime reports the
missing current ownership instead of rerunning potentially mutating JavaScript.

## Direct Tools

For a tool marked `direct_callable: true`, use:

```bash
curl -s -X POST http://127.0.0.1:11435/v1/tools/<name>/call \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <key>' \
  -H 'x-omnius-min-version: <required-version>' \
  -d '{"args":{}}'
```

The body wrapper is always `args`; the nested shape comes from the tool
metadata. Direct calls are still gated by bearer scope, tool policy, profile,
origin, network/off-device policy, and risk.

## External And MCP Tools

- `POST /v1/tools/register` registers an HTTP- or MCP-backed application tool.
- `GET /v1/mcps` lists connected MCP servers.
- `POST /v1/mcps/{name}/call` invokes a connected MCP tool through the daemon.
- `tool_search` and `explore_tools` help an agent discover a large catalog
  without loading every schema into its context.

See [Tools, MCP, Hooks, Agents, And Code Graph](../rest/endpoints/tools.md) for
the complete REST contract.

## `adjudicate` Is A Top-Level Full-Agent Tool

`adjudicate` resolves a genuine decision impasse through an isolated,
evidence-scoped panel and final judge. It is agent-bound, but it is not a
daemon direct tool. The interactive TUI, one-shot CLI, `POST /v1/run`, and the
default full-agent `POST /v1/chat` path receive it. REST execution remains
subject to the active full-agent tool profile.

The parent freezes an admissible record before deliberation. Fresh constituent
contexts receive only assigned evidence and rules, and the judge receives the
record plus validated findings instead of the parent transcript. This reduces
anchoring from accumulated working context. It does not erase bias from record
selection or framing, which remain visible in the durable receipt.
Top-level runtimes run each constituent through a host-only `full_sub_agent`
process profile. The child accepts one bounded contract over stdin and makes
one `tools: []` request. It does not start the normal runner or load project
prompts, memory, skills, or writable tools. It also omits the project path and
ambient parent environment, and it runs from the system temporary directory.
`constituentExecution` can select
`auto`, `full_sub_agent`, or `direct`; `auto` prefers the isolated child when
the runtime wires it. An ordinary child transport failure is recorded before
bounded direct fallback. Cancellation and deadline expiry terminate the child
and do not fall through to another inference path.
Two schema-invalid planner responses activate a deterministic,
evidence-covering question plan. This fallback does not decide the case.
Backend failure or deadline expiry holds the case. Durable replay verifies
the case, finding, verdict, and receipt hashes without new inference.

The tool is intentionally excluded from sub-agents. This prevents nested
adjudication panels, recursive live blocks, and unbounded inference fan-out.
It is also absent from the daemon direct-tool registry, the bounded
`/v1/chat/completions` mini-loop, Telegram, and voice-call agents. Do not infer
`GET /v1/tools/adjudicate`, `POST /v1/tools/adjudicate/call`, or a Telegram
tool route from its catalog entry. Only the interactive TUI renders the
specialized streamed adjudication block. Headless and REST full-agent paths
use ordinary run/tool events and still persist the same receipt artifacts.

Use these offline discovery commands:

```bash
omnius discover "evidence-bound decision impasse"
omnius show tool.adjudicate
omnius show workflow.evidence-bound-adjudication
```

See [Evidence-Bound Adjudication](../ADJUDICATION.md) for admission rules,
panel isolation, quorum, verdict validation, durable receipts, CLI
observability, and the deterministic harness.

## Failure Rules

- Unknown tool: refresh discovery/metadata; do not retry the same name.
- Tool not direct-callable: move the request to an agent loop.
- `401` or `403`: fix bearer auth or scope; do not expose the key in output.
- Version `412`: update the Omnius daemon before resubmitting work.
- Provider/tool unavailable: report the prerequisite; do not silently
  substitute another network service.
