# Tool

> **Stability: beta** -- This resource kind ships with `orloj.dev/v1` and is suitable for production use, but its schema may evolve with migration guidance in future minor releases.

## spec

- `type` (string): tool type. Allowed values: `http`, `external`, `grpc`, `webhook-callback`, `mcp`, `wasm`, `cli`. Unknown values are rejected at apply time.
- `endpoint` (string): tool endpoint URL (or `host:port` for gRPC).
- `description` (string): human-readable description of the tool. Passed to model gateways for richer tool definitions. Auto-populated for MCP-generated tools.
- `input_schema` (object): JSON Schema for tool parameters. Passed to model gateways for structured parameter definitions. Auto-populated for MCP-generated tools.
- `mcp_server_ref` (string): name of the McpServer that provides this tool. Required when `type=mcp`.
- `mcp_tool_name` (string): the tool name as reported by the MCP server's `tools/list`. Required when `type=mcp`.
- `cli` (object): CLI tool configuration. Required when `type=cli`.
  - `command` (string): binary path or name to execute. Required.
  - `args` ([]string): argument templates. Each entry is evaluated as a Go `text/template` with the parsed JSON input as data context. Each template produces one argv entry.
  - `image` (string): container image containing the binary. Required when `isolation_mode` is not `none`.
  - `image_pull_secret` (string): name of a Secret containing registry credentials for pulling `cli.image`. The Secret must contain either a `.dockerconfigjson` key with a complete Docker config JSON, or `registry`, `username`, and `password` keys. Requires `image` to be set.
  - `network` (string): Docker network mode for the container. Defaults to `bridge` (unlike HTTP tools which default to `none`). Set to `none` for tools that do not need network access.
  - `stdin_from_input` (bool): if `true`, pipe the raw model input to the process's stdin.
  - `output` (string): which streams to return. Allowed values: `stdout` (default), `stderr`, `both`.
  - `working_dir` (string): working directory inside the container or on the host.
  - `env` (map[string]string): literal environment variables.
  - `env_from` ([]object): environment variables resolved from secrets.
    - `name` (string): env var name. Required.
    - `secretRef` (string): Orloj secret reference. Required.
    - `key` (string): key within the secret (default: `value`).
- `capabilities` ([]string): declared operations.
- `operation_classes` ([]string): operation class annotations. Allowed values: `read`, `write`, `delete`, `admin`. Used by `ToolPermission.operation_rules` for per-class policy verdicts.
- `risk_level` (string): `low`, `medium`, `high`, `critical`.
- `runtime` (object):
  - `timeout` (duration string)
  - `isolation_mode`: `none`, `sandboxed`, `container`, `kubernetes`, `wasm`
  - `retry.max_attempts` (int)
  - `retry.backoff` (duration string)
  - `retry.max_backoff` (duration string)
  - `retry.jitter`: `none`, `full`, `equal`
- `auth` (object):
  - `profile` (string): auth profile. Allowed values: `bearer`, `api_key_header`, `basic`, `oauth2_client_credentials`. Defaults to `bearer` when `secretRef` is set.
  - `secretRef` (string): namespaced secret reference. Required when `profile` is set.
  - `headerName` (string): custom header name. Required when `profile=api_key_header`.
  - `tokenURL` (string): OAuth2 token endpoint. Required when `profile=oauth2_client_credentials`.
  - `scopes` ([]string): OAuth2 scopes.

## Defaults and Validation

- `type` defaults to `http`. Unknown types are rejected with a validation error. `mcp` type tools are typically auto-generated by the McpServer controller; see [Connect an MCP Server](../../guides/connect-mcp-server.md). `cli` type tools invoke local binaries via execve; see [CLI Tool Guide](../../concepts/tools/cli-tool.md).
- `cli.command` is required when `type=cli`. `cli.image` is required when `isolation_mode` is not `none`. `cli.image_pull_secret` requires `cli.image`.
- `cli.output` defaults to `stdout`. `cli.network` defaults to `bridge`.
- `auth` is not supported for `type=cli` tools. Use `cli.env_from` for credential injection.
- `auth.profile` defaults to `bearer` when `secretRef` is set. Unknown profiles are rejected.
- `auth.headerName` is required when `profile=api_key_header`.
- `auth.tokenURL` is required when `profile=oauth2_client_credentials`.
- `capabilities` are trimmed and deduplicated (case-insensitive).
- `operation_classes` are trimmed, lowercased, and deduplicated. Invalid values are rejected. Defaults to `["read"]` for `low`/`medium` risk, `["write"]` for `high`/`critical` risk.
- `risk_level` defaults to `low`.
- `runtime.timeout` defaults to `30s` and must parse as duration.
- `runtime.isolation_mode` defaults to:
  - `container` for `type=cli` (regardless of risk level)
  - `sandboxed` for `high`/`critical` risk (non-CLI)
  - `none` for `low`/`medium` risk (non-CLI)
  - `kubernetes` must be set explicitly; requires `--tool-k8s-enabled=true`
- `runtime.retry` defaults:
  - `max_attempts` -> `1`
  - `backoff` -> `0s`
  - `max_backoff` -> `30s`
  - `jitter` -> `none`

## status

- `phase`, `lastError`, `observedGeneration`

Examples:

- `examples/resources/tools/*.yaml`
- `examples/resources/tools/wasm-reference/wasm_echo_tool.yaml`
- `examples/resources/tools/cli_kubectl_tool.yaml`
- `examples/resources/tools/cli_gh_tool.yaml`

See also: [Tool concepts](../../concepts/tools/tool.md).
