# Tools, MCP, Hooks, Agents, And Code Graph

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/tools` | List tool registry with security metadata |
| `GET` | `/v1/tools/{name}` | Get one tool definition |
| `POST` | `/v1/tools/{name}/call` | Invoke a tool |
| `GET` | `/v1/mcps` | List MCP servers |
| `GET` | `/v1/mcps/{name}` | Get MCP server details |
| `POST` | `/v1/mcps/{name}/call` | Invoke an MCP tool |
| `GET` | `/v1/hooks` | List hook types and counts |
| `GET` | `/v1/agents` | List agent types |
| `GET` | `/v1/web/search` | Inspect web-search availability, schema, and security policy |
| `POST` | `/v1/web/search` | Search the web through the shared tool runtime |
| `GET` | `/v1/web/fetch` | Inspect web-fetch availability, schema, and security policy |
| `POST` | `/v1/web/fetch` | Fetch one URL through the shared tool runtime |
| `GET` | `/v1/web/crawl` | Inspect web-crawl availability, schema, and security policy |
| `POST` | `/v1/web/crawl` | Crawl a website through the shared tool runtime |
| `GET` | `/v1/codegraph/snapshot` | Code graph stats and recent events |
| `GET` | `/v1/codegraph/events` | Code graph live event stream |

## Tool Metadata

`GET /v1/tools` and `POST /v1/tools/{name}/call` use the same direct-call registry, built from the `@omnius/execution` tool manifest plus virtual lifecycle tools such as `task_complete`. If a tool appears in `/v1/tools` with `direct_callable: true`, the same name is callable at `/v1/tools/{name}/call`.

`GET /v1/tools` returns each tool's:

- name
- class
- description
- JSON-schema parameters
- `direct_callable`
- security categories
- risk
- required scope
- off-device allowance
- rationale

Filters include:

```text
?category=read|write|exec|network|hardware|agent|sensitive
?scope=read|run|admin
?risk=low|medium|high|critical
?limit=200&offset=0
?profile=bookkeeping-tracking
```

Profiles can also be selected with `X-Tool-Profile`. Named profiles resolve in this order: built-in preset, `{working_dir}/.omnius/profiles/{name}.json`, then `~/.omnius/profiles/{name}.json`. Missing profiles fail closed.

## Tool Calls

`POST /v1/tools/{name}/call` body:

```json
{
  "session_id": "tracking-turn-123",
  "args": {},
  "working_dir": "/path/to/repo",
  "profile": "bookkeeping-tracking"
}
```

`args` is the canonical wrapper. The schema from `/v1/tools/{name}` describes the fields inside `args`.

Tool calls are gated by auth scope, tool policy, off-device policy, and profile restrictions.

## Stable Web Capability Aliases

The `/v1/web/search`, `/v1/web/fetch`, and `/v1/web/crawl` routes delegate to
`web_search`, `web_fetch`, and `web_crawl` in the shared tool registry. They do
not create a second execution path. Use `GET` to inspect live availability,
schema, and security policy. Use `POST` with the normal direct-tool envelope.
The same authentication, profile, origin, timeout, output-size, audit, and
network-egress policy applies.

Search accepts
`{"args":{"query":"...","num_results":5,"provider":"duckduckgo"}}`.
Fetch accepts `{"args":{"url":"https://example.com"}}`. Crawl arguments
must follow the schema returned by `GET /v1/web/crawl`; browser-backed crawling
also requires the reported runtime dependencies. Successful calls return the
standard `ToolResult` envelope. Policy denial returns `403`. Execution failure
returns `500`; search also returns `400` for an invalid request.

Inspect `direct_callable` in the live metadata before invoking a tool. Each
available built-in is directly callable through the shared policy gate.
`web_search` is available through `POST /v1/web/search` and
`POST /v1/tools/web_search/call` when its metadata reports availability. It can
also be offered through `/v1/run`, `/v1/chat`, or `/v1/chat/completions` with
`agent_loop: true` and `include_daemon_tools: ["read"]`.

See [Tools And Web Search](../../guides/tools-and-web-search.md).

Bookkeeping tools are direct-callable and do not require a model run:

```bash
curl -s -X POST "$OMNIUS/v1/tools/todo_write/call" \
  -H 'content-type: application/json' \
  -H 'x-omnius-session-id: tracking-turn-123' \
  -d '{"profile":"bookkeeping-tracking","args":{"todos":[{"content":"Create report","status":"in_progress"}]}}'
```

Use `todo_write`, `todo_read`, `working_notes`, and `task_complete` this way for deterministic tracking. `task_complete` on this endpoint is only a bookkeeping boundary; `/v1/runs/{id}` remains the canonical run terminal state.

## MCP

MCP endpoints list connected Model Context Protocol servers and invoke tools through the daemon with the same auth and audit envelope.

## Code Graph

Code graph endpoints expose repository indexing state and live graph events for GUI or dashboard clients.
