# 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.

## 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.

## 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.