Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

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, queue, mcp. 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.
  • 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, 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.
  • 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:
    • sandboxed for high/critical risk
    • none for low/medium risk
  • 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

See also: Tool concepts.