Tool

The Tool primitive defines an executable function the agent can invoke. CKP Tools are a strict superset of MCP Tools — every MCP tool definition is a valid CKP tool, with additional fields for sandbox binding, policy binding, and lifecycle metadata.

URI pattern: claw://local/tool/{name}

---

Schema

claw: "0.3.0"
kind: Tool
metadata:
  name: "web-fetch"
  version: "1.2.0"
  labels:
    category: "network"
spec:
  description: "Fetch content from a URL and return the response body"

  input_schema:
    type: "object"
    properties:
      url:
        type: "string"
        format: "uri"
        description: "The URL to fetch"
      headers:
        type: "object"
        additionalProperties:
          type: "string"
        description: "Optional HTTP headers"
    required: ["url"]

  output_schema:
    type: "object"
    properties:
      status_code:
        type: "integer"
      body:
        type: "string"
      content_type:
        type: "string"

  sandbox_ref: "network-sandbox"
  policy_ref: "network-policy"

  mcp_source:
    uri: "stdio:///usr/local/bin/web-fetch-server"

  annotations:
    readOnlyHint: false
    destructiveHint: false
    idempotentHint: true
    openWorldHint: true

  timeout_ms: 30000

  retry:
    max_attempts: 2
    backoff: "exponential"

---

Key Fields

Field	Required	Description
description	Conditional	Human-readable description. Required when mcp_source is absent.
input_schema	Conditional	JSON Schema for input parameters. Required when mcp_source is absent.
output_schema	No	JSON Schema describing the tool’s output structure.
sandbox_ref	No	Which sandbox this tool executes in.
policy_ref	No	Which policy governs this tool’s execution.
mcp_source	No	MCP server source, enabling seamless bridging to MCP tools.
annotations	No	Same as MCP tool annotations (untrusted hints about tool behavior).
timeout_ms	No	Maximum execution time before the runtime terminates the tool.
retry	No	Retry configuration for transient failures.

---

MCP Compatibility

Any MCP tool can be referenced directly from a CKP manifest:

claw: "0.3.0"
kind: Tool
metadata:
  name: "filesystem-read"
spec:
  mcp_source:
    uri: "stdio:///path/to/mcp-filesystem-server"
    tool_name: "read_file"
  sandbox_ref: "fs-sandbox"
  policy_ref: "readonly-policy"

When an MCP source is specified, the runtime MUST:

1. Connect to the MCP server using standard MCP handshake
2. Map the CKP sandbox_ref and policy_ref as execution constraints
3. Proxy tools/call through the declared sandbox and policy

The mcp:// URI scheme is RESERVED and MUST NOT be used. MCP server references MUST use the mcp_source field with native MCP transport URIs (stdio:///, https://).

---

Validation Rules

• When mcp_source is absent, both description and input_schema are REQUIRED.
• When mcp_source is present, description and input_schema are OPTIONAL (the runtime MUST obtain them from the MCP server via tools/list).
• The input_schema field, when present, MUST be a valid JSON Schema object. The runtime MUST validate tool call arguments against it before execution; invalid arguments MUST be rejected with error code -32602.
• If timeout_ms is specified and tool execution exceeds it, the runtime MUST terminate the execution and return error code -32014.

---

Design Rationale

The Tool primitive is a strict superset of MCP’s tool definition. input_schema maps to MCP’s inputSchema, mcp_source enables seamless bridging, and sandbox_ref/policy_ref bind security directly to tool definitions. This means any existing MCP tool ecosystem is immediately usable within CKP without modification.