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

Catalog presence does not imply direct invocation. Inspect
`direct_callable` in the live metadata. In particular, `web_search` is
agent-bound: discover its schema with `GET /v1/tools/web_search`, then offer it
through `/v1/run`, `/v1/chat`, or `/v1/chat/completions` using
`agent_loop: true` and `include_daemon_tools: ["read"]`. Do not assume
`POST /v1/tools/web_search/call` is available.

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.