### ToolClad Quick Start Examples (Bash)

Source: https://github.com/thirdkeyai/toolclad/blob/main/README.md

Demonstrates how to run ToolClad tests for the 'whois_lookup' example using different language implementations (Rust, Python, JavaScript, Go). These commands show the basic usage for validating a tool contract.

```bash
# Rust
cd rust && cargo run -- test ../examples/whois_lookup.clad.toml --arg target=example.com

# Python
cd python && pip install -e . && toolclad test ../examples/whois_lookup.clad.toml --arg target=example.com

# JavaScript
cd js && npm install && node src/cli.js test ../examples/whois_lookup.clad.toml --arg target=example.com

# Go
cd go && go run ./cmd/toolclad test ../examples/whois_lookup.clad.toml --arg target=example.com
```

--------------------------------

### ToolClad CLI Usage Examples (Bash)

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Provides examples of using the ToolClad Command Line Interface (CLI) for various tasks. This includes installing the CLI for different languages, validating manifests, performing dry runs to test command construction, executing tools to get JSON output, and generating MCP schemas. It also covers Symbiont integration commands.

```bash
# Install the CLI
pip install toolclad           # Python
npm install -g toolclad        # JavaScript
cargo install toolclad         # Rust

# Validate a manifest
toolclad validate tools/nmap_scan.clad.toml
# Output: tools/nmap_scan.clad.toml: OK

# Dry run (test command construction without executing)
toolclad test tools/nmap_scan.clad.toml \
    --arg target=10.0.1.0/24 \
    --arg scan_type=service

# Output:
#   Manifest:  tools/nmap_scan.clad.toml
#   Tool:      nmap_scan (v1.0.0)
#   Binary:    nmap
#
#   Arguments:
#     target     = 10.0.1.0/24    (scope_target: OK)
#     scan_type  = service         (enum: OK)
#
#   Command:   nmap -sT -sV --version-intensity 5 --max-rate 1000 -oX /tmp/... 10.0.1.0/24
#   Timeout:   600s
#   Risk:      low
#
#   [dry run -- command not executed]

# Execute a tool and get JSON output
toolclad run tools/whois_lookup.clad.toml --arg target=example.com
# Output: {"status": "success", "scan_id": "...", "tool": "whois_lookup", ...}

# Generate MCP JSON schema
toolclad schema tools/nmap_scan.clad.toml
# Output: {"name": "nmap_scan", "inputSchema": {...}, "outputSchema": {...}}

# Symbiont integration commands
symbi tools list                    # List all discovered tools
symbi tools validate                # Validate all manifests in tools/
symbi tools test nmap_scan --arg target=10.0.1.0/24 --arg scan_type=service
symbi tools schema nmap_scan        # Output MCP schema
symbi tools init my_scanner         # Scaffold new manifest
symbi tools sessions                # List active sessions
symbi tools session <id> transcript # View session transcript
```

--------------------------------

### ToolClad CLI Usage Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/SKILL.md

Demonstrates how to use the ToolClad CLI. This example shows a basic command to execute a tool defined by a manifest file.

```bash
# Assuming 'toolclad' is in your PATH and a manifest exists
toolclad run --manifest tools/my_tool.clad.toml --target 192.168.1.1 --mode deep

```

--------------------------------

### Install ToolClad Packages

Source: https://github.com/thirdkeyai/toolclad/blob/main/js/README.md

Installation commands for the ToolClad CLI and library across supported programming languages.

```bash
cargo install toolclad        # Rust / crates.io
pip install toolclad           # Python / PyPI
npm install toolclad           # JavaScript / npm
go install ./go/cmd/toolclad   # Go
```

--------------------------------

### Full Tool Manifest Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/manifest-format.md

A comprehensive example of a Toolclad manifest, including tool metadata, Cedar authorization, evidence capture, argument definitions, and command templates.

```toml
[tool]
name = "nmap_scan"
version = "1.0.0"
binary = "nmap"
description = "Network port scanning and service detection"

[args.target]
position = 1
required = true
type = "scope_target"

[command]
template = "nmap {_scan_flags} --max-rate {max_rate} -oX {_output_file} --no-stylesheet -v {extra_flags} {target}"
```

--------------------------------

### ToolClad Command Template Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/SKILL.md

Illustrates advanced command templating in ToolClad. It shows how to interpolate validated parameters, set defaults, map enum values to CLI flags, and use conditional fragments for dynamic command construction.

```toml
# Example for nmap tool
[command]
template = "nmap {_scan_flags} --max-rate {max_rate} {target}"

[command.defaults]
max_rate = 1000

# Map enum values to CLI flags
[command.mappings.scan_type]
ping = "-sn -PE"
service = "-sT -sV"
aggressive = "-A -T4"

# Conditional fragments
[command.conditionals]
port_flag = { when = "port != 0", template = "-p {port}" }

```

--------------------------------

### Session Command Examples for LLM Interaction

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/session-mode.md

Illustrates how different session commands are presented to the LLM and the corresponding agent input. The LLM selects from typed operations, not free text, with validation against patterns and risk tiers.

```markdown
| MCP Tool Name | LLM Sees | Agent Provides |
|---|---|---|
| `psql_session.select_query` | "Run a read-only SELECT query" | `{ "command": "SELECT * FROM users LIMIT 10" }` |
| `psql_session.insert` | "Insert rows into a table" | `{ "command": "INSERT INTO logs (msg) VALUES ('test')" }` |
| `psql_session.drop_table` | "Drop a table (destructive)" | `{ "command": "DROP TABLE temp_data" }` |
```

--------------------------------

### Implement State-Aware Cedar Authorization Policy

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

A Cedar policy example that restricts the execution of a specific tool based on the current session state, ensuring the 'run' command is only permitted when the module is 'configured'.

```Cedar
permit (
    principal == PenTest::Phase::"exploit",
    action == PenTest::Action::"execute_tool",
    resource
)
when {
    resource.tool_name == "msfconsole_session.run" &&
    resource.session_state == "configured"
};
```

--------------------------------

### Observe-Reason-Gate-Act Cycle Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/browser-mode.md

Illustrates the per-interaction ORGA gating process for browser commands. It shows how observations are made, LLM proposes actions, ToolClad gates them based on policies, and the BrowserExecutor acts upon approved commands.

```text
Iteration 1:
  Observe:  {url: "https://app.example.com/login", title: "Login", has_forms: true}
  Reason:   LLM proposes browser_session.type_text(selector="#email", text="user@co.com")
  Gate:     Cedar: is type_text allowed? ToolClad: text is injection-safe
  Act:      BrowserExecutor sends CDP command, waits for page stable

Iteration 2:
  Observe:  {url: "https://app.example.com/login", title: "Login"}
  Reason:   LLM proposes browser_session.submit_form(selector="#login-form")
  Gate:     Cedar: submit_form requires human_approval -> PENDING
  Act:      (blocked until human approves)

Iteration 3:
  Observe:  {url: "https://app.example.com/dashboard", is_authenticated: true}
  Reason:   LLM proposes browser_session.navigate(url="https://evil.com/exfil")
  Gate:     ToolClad: URL scope check -> DENY (domain not in allowed_domains)
  Act:      (blocked, denial fed back to agent)
```

--------------------------------

### Install ToolClad CLI

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/cli-reference.md

Installs the standalone ToolClad CLI from various package registries. Ensure you have the respective language's package manager installed.

```bash
cargo install toolclad        # Rust
pip install toolclad           # Python
npm install -g toolclad        # JavaScript
go install ./go/cmd/toolclad   # Go (from source)
```

--------------------------------

### DSL Agent Tool Reference Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/symbiont-integration.md

Demonstrates how DSL agents reference tools registered with ToolClad using a simple `tool.<tool_name>` syntax. This allows agents to utilize external tools seamlessly.

```dsl
capabilities = [
    "tool.nmap_scan",
    "tool.whois_lookup",
]
```

--------------------------------

### TOML Type Composition Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

This TOML snippet demonstrates how to define arguments with specific types and constraints like minimum/maximum values, clamping, default values, and allowed enumerations. It showcases defining 'threads', 'service', 'target_url', and 'module_path' arguments with their respective validation rules.

```toml
[args.threads]
type = "integer"
min = 1
max = 64
clamp = true       # Values outside range are clamped, not rejected
default = 4
description = "Concurrent threads"

[args.service]
type = "enum"
allowed = ["ssh", "ftp", "http-get", "http-post-form", "smb", "rdp", "mysql", "postgres"]
description = "Target service protocol"

[args.target_url]
type = "url"
schemes = ["http", "https"]       # Only these URL schemes
scope_check = true                 # Extract host for scope validation
description = "Target web application URL"

[args.module_path]
type = "string"
pattern = "^(exploit|auxiliary|post)/[a-zA-Z0-9_/]+$"
sanitize = ["injection"]
description = "Metasploit module path"
```

--------------------------------

### ToolClad Manifest Structure Example

Source: https://github.com/thirdkeyai/toolclad/blob/main/SKILL.md

Defines the structure of a ToolClad manifest file (.clad.toml). It includes tool metadata, optional Cedar policy and evidence capture configurations, argument definitions with types and constraints, command execution details (template or executor), and output parsing/schema.

```toml
# tools/my_tool.clad.toml

[tool]
name = "my_tool"
version = "1.0.0"
binary = "my-binary"
description = "What this tool does"
timeout_seconds = 30
risk_tier = "low"          # low | medium | high | critical

[tool.cedar]               # Optional: Cedar policy integration
resource = "Tool::MyTool"
action = "execute_tool"

[tool.evidence]             # Optional: evidence capture
output_dir = "{evidence_dir}/{scan_id}-my-tool"
capture = true
hash = "sha256"

# --- Parameters ---
[args.target]
position = 1
required = true
type = "scope_target"       # Validates IP/CIDR/hostname, blocks injection
description = "Target to scan"

[args.mode]
position = 2
required = false
type = "enum"
allowed = ["fast", "deep", "stealth"]
default = "fast"
description = "Scan mode"

# --- Command ---
[command]
template = "my-binary --mode {mode} {target}"

# OR for complex tools:
# executor = "scripts/wrapper.sh"   # Escape hatch

# --- Output ---
[output]
format = "text"             # text | json | xml | jsonl
parser = "builtin:text"     # Or custom: "scripts/parse.py"
envelope = true

[output.schema]
type = "object"

[output.schema.properties.raw_output]
type = "string"
description = "Tool output"

```

--------------------------------

### Custom Type Definition Example (`toolclad.toml`)

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/symbiont-integration.md

Provides an example of how to define reusable custom types in the `toolclad.toml` file located at the project root.

```toml
[types.custom_ip]
base = "ip_address"
pattern = "^192\.168\.\d{1,3}\.\d{1,3}$"

[types.port_range]
base = "string"
pattern = "^\d+-\d+$"
```

--------------------------------

### Define Cedar Authorization Policy

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

Illustrates how to define Cedar authorization policies for tools, including an example of an auto-generated policy based on manifest metadata.

```cedar
# Auto-generated from nmap_scan.clad.toml (risk_tier = "low")
permit (
    principal,
    action == PenTest::Action::"execute_tool",
    resource
)
when {
    resource.tool_name == "nmap_scan"
};
```

--------------------------------

### Define Hydra tool with conditional flags

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/command-construction.md

A full configuration example for the Hydra network brute-force tool. It demonstrates the use of argument definitions, input clamping, and conditional command templates to dynamically build the execution string.

```toml
[tool]
name = "hydra_bruteforce"
version = "1.0.0"
binary = "hydra"
description = "Network login brute-force"
timeout_seconds = 1800
risk_tier = "high"
human_approval = true

[args.target]
position = 1
required = true
type = "scope_target"

[args.service]
position = 2
required = true
type = "enum"
allowed = ["ssh", "ftp", "http-get", "http-post-form", "smb", "rdp", "mysql", "postgres"]

[args.port]
type = "port"
required = false
default = 0

[args.username]
type = "string"
required = false
default = ""

[args.password]
type = "string"
required = false
default = ""

[args.username_file]
type = "credential_file"
required = false

[args.password_file]
type = "credential_file"
required = false

[args.threads]
type = "integer"
min = 1
max = 64
clamp = true
default = 4

[command]
template = "hydra {_conditional_flags} -t {threads} {target} {service}"

[command.conditionals]
service_port = { when = "port != 0", template = "-s {port}" }
username_file = { when = "username_file != ''", template = "-L {username_file}" }
password_file = { when = "password_file != ''", template = "-P {password_file}" }
single_user = { when = "username != '' and username_file == ''", template = "-l {username}" }
single_pass = { when = "password != '' and password_file == ''", template = "-p {password}" }
```

--------------------------------

### Define String and Integer Arguments in TOML

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/type-system.md

Examples of defining string arguments with regex patterns and injection sanitization, as well as integer arguments with clamping and range constraints.

```toml
[args.name]
type = "string"
description = "General text argument"

[args.module_path]
type = "string"
pattern = "^(exploit|auxiliary|post)/[a-zA-Z0-9_/]+$"
sanitize = ["injection"]
description = "Metasploit module path"

[args.threads]
type = "integer"
min = 1
max = 64
clamp = true
default = 4
description = "Concurrent threads"
```

--------------------------------

### Prompt-Based State Inference Examples

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/session-mode.md

Shows how different terminal prompts are used to infer the internal state of the session executor. This state is reported in the output schema and can be used by Cedar policies for authorization.

```markdown
| Prompt | Inferred State |
|---|---|
| `msf6 >` | `ready` (no module loaded) |
| `msf6 exploit(ms17_010) >` | `module_loaded` |
| `dbname=>` | `ready` (psql, standard user) |
| `dbname=#` | `ready` (psql, superuser -- higher risk tier) |
```

--------------------------------

### Execute Toolclad Nmap Scan and Process Results (JavaScript)

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Shows how to use the Toolclad library in JavaScript to load a manifest, execute an nmap scan, and iterate through the results to display discovered hosts and their open ports. This example highlights asynchronous execution using promises.

```javascript
const nmapManifest = loadManifest("tools/nmap_scan.clad.toml");
const scanResult = await execute(nmapManifest, {
  target: "10.0.1.0/24",
  scan_type: "service"
});

if (scanResult.status === "success") {
  for (const host of scanResult.results.hosts || []) {
    console.log(`Host: ${host.ip}`);
    for (const port of host.ports || []) {
      console.log(`  ${port.port}/${port.protocol} - ${port.service}`);
    }
  }
}
```

--------------------------------

### Define MCP Proxy Manifest for GitHub

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/http-mcp-backends.md

A .clad.toml manifest example demonstrating strict input validation for a GitHub issue creation tool. It includes regex patterns for repository names, sanitization for injection, and output schema validation.

```toml
[tool]
name = "github_create_issue"
version = "1.0.0"
description = "Create a GitHub issue in an allowed repository"
timeout_seconds = 30
risk_tier = "medium"

[tool.cedar]
resource = "Dev::GitHubRepo"
action = "create_issue"

[mcp]
server = "github-mcp"
tool = "create_issue"

[args.repo]
type = "string"
required = true
pattern = "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+$"
description = "Repository in owner/repo format"

[args.title]
type = "string"
required = true
sanitize = ["injection"]
description = "Issue title"

[output]
format = "json"
parser = "builtin:json"
envelope = true
```

--------------------------------

### HTTP Manifest Example for Slack Message Posting

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/http-mcp-backends.md

This TOML manifest defines a ToolClad tool for posting messages to Slack. It includes tool metadata, Cedar policies, argument definitions, HTTP request configuration (method, URL, headers, body), and output schema validation.

```toml
# tools/slack_post_message.clad.toml
[tool]
name = "slack_post_message"
version = "1.0.0"
description = "Post a message to a Slack channel"
timeout_seconds = 30
risk_tier = "medium"

[tool.cedar]
resource = "Comms::SlackChannel"
action = "post_message"

[args.channel]
type = "string"
required = true
pattern = "^[A-Z0-9]+$"
description = "Slack channel ID"

[args.message]
type = "string"
required = true
sanitize = ["injection"]
description = "Message text to post"

[http]
method = "POST"
url = "https://slack.com/api/chat.postMessage"
headers = { "Authorization" = "Bearer {_secret:slack_token}", "Content-Type" = "application/json" }
body_template = '{"channel": "{channel}", "text": "{message}"}'
success_status = [200]
error_status = [400, 401, 403, 404, 429]

[output]
format = "json"
parser = "builtin:json"
envelope = true

[output.schema]
type = "object"

[output.schema.properties.ok]
type = "boolean"
description = "Whether the API call succeeded"

[output.schema.properties.ts]
type = "string"
description = "Message timestamp (Slack message ID)"
```

--------------------------------

### symbi tools init <name>

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

Scaffolds a new `.clad.toml` manifest file from a template for a given tool name.

```APIDOC
## symbi tools init <name>

### Description
Scaffolds a new `.clad.toml` manifest file from a template. This command helps in quickly setting up the basic structure for a new tool's interface definition.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **name** (string) - Required - The name for the new tool manifest.

### Request Example
```bash
symbi tools init my_scanner
```

### Response
#### Success Response (Output)
- Confirmation message indicating the creation of the manifest file and a reminder to edit it.

#### Response Example
```
Created tools/my_scanner.clad.toml -- edit to define your tool interface.
```
```

--------------------------------

### HTTP GET Manifest Example for IP Geolocation

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/http-mcp-backends.md

This TOML manifest defines a ToolClad tool for looking up IP geolocation data. It includes tool metadata, argument definitions, a GET HTTP request configuration, and specifies the output schema for the geolocation data.

```toml
# tools/ip_lookup.clad.toml
[tool]
name = "ip_lookup"
version = "1.0.0"
description = "Look up geolocation data for an IP address"
timeout_seconds = 10
risk_tier = "low"

[args.ip]
type = "ip_address"
required = true
description = "IP address to look up"

[http]
method = "GET"
url = "https://ipapi.co/{ip}/json/"
success_status = [200]
error_status = [429]

[output]
format = "json"
parser = "builtin:json"
envelope = true

[output.schema]
type = "object"

[output.schema.properties.city]
type = "string"

[output.schema.properties.region]
type = "string"

[output.schema.properties.country_name]
type = "string"

[output.schema.properties.org]
type = "string"
description = "ISP or organization"
```

--------------------------------

### Initialize New Tool Manifest

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/cli-reference.md

Scaffolds a new `.clad.toml` manifest file for a tool from a template. It creates a file named `tools/<name>.clad.toml` with placeholder sections for tool definition, arguments, command, and output, including explanatory comments.

```bash
$ symbi tools init my_scanner
Created tools/my_scanner.clad.toml -- edit to define your tool interface.
```

--------------------------------

### Command Construction from Manifest

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Shows how to build command-line arguments from a manifest file and a dictionary of validated arguments. It demonstrates constructing commands with required and optional arguments, including mapping different scan types to specific flags.

```python
from toolclad import load_manifest, build_command

manifest = load_manifest("tools/nmap_scan.clad.toml")

# Build command with required arguments
args = {
    "target": "10.0.1.0/24",
    "scan_type": "service"
}

cmd = build_command(manifest, args)
print(cmd)
# Output: ['nmap', '-sT', '-sV', '--version-intensity', '5', '--max-rate', '1000',
#          '-oX', '/tmp/toolclad/scan.xml', '--no-stylesheet', '-v', '', '10.0.1.0/24']

# Build command with optional flags
args_with_extras = {
    "target": "192.168.1.0/24",
    "scan_type": "aggressive",
    "extra_flags": "-Pn"  # Skip host discovery
}

cmd = build_command(manifest, args_with_extras)
# The scan_type="aggressive" maps to "-A -T4 --top-ports 10000"
print(" ".join(cmd))
# Output: nmap -A -T4 --top-ports 10000 --max-rate 1000 -oX ... -Pn 192.168.1.0/24

```

--------------------------------

### Command Construction from Manifest (JavaScript)

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Demonstrates building command-line arguments using Toolclad in JavaScript. It shows how to load a manifest and construct a command array from validated arguments, illustrating different scan types and their flag mappings.

```javascript
import { loadManifest, buildCommand } from "toolclad";

const manifest = loadManifest("tools/nmap_scan.clad.toml");

// Build command array
const args = {
  target: "10.0.1.0/24",
  scan_type: "service"
};

const cmd = buildCommand(manifest, args);
console.log(cmd);
// ['nmap', '-sT', '-sV', '--version-intensity', '5', '--max-rate', '1000', ...]

// Different scan types produce different flag mappings
const synScanArgs = { target: "192.168.1.1", scan_type: "syn" };
const synCmd = buildCommand(manifest, synScanArgs);
// Produces: nmap -sS --top-ports 1000 --max-rate 1000 ...

const vulnScanArgs = { target: "10.0.1.5", scan_type: "vuln_script" };
const vulnCmd = buildCommand(manifest, vulnScanArgs);
// Produces: nmap -sV --script=vuln --script-timeout 60s ...

```

--------------------------------

### ToolClad Package Installation (Bash)

Source: https://github.com/thirdkeyai/toolclad/blob/main/README.md

Commands to install the ToolClad package for different programming languages from their respective package registries. This allows developers to integrate ToolClad into their projects.

```bash
cargo install toolclad        # Rust / crates.io
pip install toolclad           # Python / PyPI
npm install toolclad           # JavaScript / npm
```

--------------------------------

### Proxy MCP Tool with ToolClad Manifest

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

Shows how to create a ToolClad manifest that acts as a proxy for an existing MCP (Meta-Cloud Platform) server tool. This allows for applying stricter input validation, Cedar policy gating, and a consistent ToolClad contract to potentially less-secure third-party MCP tools.

```toml
# tools/github_create_issue.clad.toml
[tool]
name = "github_create_issue"
version = "1.0.0"
description = "Create a GitHub issue in an allowed repository"
timeout_seconds = 30
risk_tier = "medium"

[tool.cedar]
resource = "Dev::GitHubRepo"
action = "create_issue"

[mcp]
server = "github-mcp"
tool = "create_issue"

[args.repo]
type = "string"
required = true
pattern = "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+$"
description = "Repository in owner/repo format"

[args.title]
type = "string"
required = true
sanitize = ["injection"]
description = "Issue title"

[args.body]
type = "string"
required = false
description = "Issue body (markdown)"

[args.labels]
type = "string"
required = false
pattern = "^[a-zA-Z0-9_, -]+$"
description = "Comma-separated label names"

[output]
format = "json"
parser = "builtin:json"
envelope = true

[output.schema]
type = "object"

[output.schema.properties.number]
type = "integer"
description = "Created issue number"

[output.schema.properties.url]
type = "string"
description = "URL of the created issue"

[output.schema.properties.state]
type = "string"
description = "Issue state (open)"
```

--------------------------------

### Define Command Templates and Variables

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/command-construction.md

Demonstrates how to define a command template using placeholders for validated arguments and system-injected variables.

```toml
[command]
template = "nmap {_scan_flags} --max-rate {max_rate} -oX {_output_file} -v {extra_flags} {target}"
```

--------------------------------

### Define Port, Boolean, and Enum Arguments in TOML

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/type-system.md

Examples of defining port types (1-65535), strict boolean types, and enum types with allowed value lists.

```toml
[args.target_port]
type = "port"
default = 443
description = "Target port"

[args.verbose]
type = "boolean"
default = "false"
description = "Enable verbose output"

[args.scan_type]
type = "enum"
allowed = ["ping", "service", "version", "syn", "os_detect", "aggressive"]
description = "Type of scan to perform"
```

--------------------------------

### Define ToolClad Manifest Arguments and Output Schema

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

Demonstrates how to define tool arguments and output schemas within a .clad.toml manifest file. These definitions are used by the runtime to generate MCP-compliant schemas.

```toml
[args.target]
position = 1
required = true
type = "scope_target"
description = "Target CIDR, IP, or hostname"

[args.scan_type]
position = 2
required = true
type = "enum"
allowed = ["ping", "service", "version", "syn"]
description = "Type of scan to perform"

[output.schema.properties.hosts]
type = "array"
description = "Discovered hosts with open ports and services"
```

--------------------------------

### Define Scope Target Argument in TOML

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/type-system.md

Example of defining a scope_target type, which validates network targets like IPs, CIDRs, and hostnames while blocking shell metacharacters and wildcards.

```toml
[args.target]
type = "scope_target"
required = true
description = "Target CIDR, IP, or hostname"
```

--------------------------------

### Govern Database MCP with SQL Constraints

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/http-mcp-backends.md

A manifest example for a database MCP tool that restricts SQL queries to read-only SELECT statements and limits target databases using an enum.

```toml
[tool]
name = "db_read_query"
version = "1.0.0"

[args.sql]
type = "string"
required = true
pattern = "^SELECT\\s"
sanitize = ["injection"]

[args.database]
type = "enum"
required = true
allowed = ["analytics", "reporting", "staging"]

[mcp.field_map]
sql = "query"
database = "db_name"
```

--------------------------------

### ToolClad HTTP Request Construction Process

Source: https://github.com/thirdkeyai/toolclad/blob/main/TOOLCLAD_DESIGN_SPEC.md

Outlines the steps the ToolClad executor takes to construct and execute an HTTP request based on the manifest's `[http]` section. This includes interpolating arguments, resolving secrets, setting headers, executing the request, and parsing the response.

```text
1. Interpolate `{arg_name}` placeholders in `url`, `headers`, and `body_template` with validated parameter values
2. Resolve `{_secret:name}` references from secrets management
3. Set method, headers, and body
4. Execute with timeout
5. Check response status against `success_status` / `error_status`
6. Parse response body with the declared parser
7. Validate against `[output.schema]`
8. Wrap in evidence envelope
```

--------------------------------

### Load and Parse ToolClad Manifests

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Demonstrates how to load a .clad.toml manifest file and access its metadata, binary configuration, and parameter definitions. This allows programmatic inspection of tool capabilities and requirements.

```python
from toolclad import load_manifest

# Load a manifest file
manifest = load_manifest("tools/nmap_scan.clad.toml")

# Access tool metadata
print(f"Tool: {manifest.tool.name}")        # "nmap_scan"
print(f"Version: {manifest.tool.version}")   # "1.0.0"
print(f"Binary: {manifest.tool.binary}")     # "nmap"
print(f"Description: {manifest.tool.description}")
print(f"Timeout: {manifest.tool.timeout_seconds}s")
print(f"Risk tier: {manifest.tool.risk_tier}")

# Access parameter definitions
for arg_name, arg_def in manifest.args.items():
    print(f"  {arg_name}: type={arg_def.type}, required={arg_def.required}")
    if arg_def.allowed:
        print(f"    Allowed values: {arg_def.allowed}")
    if arg_def.default is not None:
        print(f"    Default: {arg_def.default}")
```

```javascript
import { loadManifest } from "toolclad";

// Load a manifest file
const manifest = loadManifest("tools/nmap_scan.clad.toml");

// Access tool metadata
console.log(`Tool: ${manifest.tool.name}`);        // "nmap_scan"
console.log(`Version: ${manifest.tool.version}`);   // "1.0.0"
console.log(`Binary: ${manifest.tool.binary}`);     // "nmap"
console.log(`Timeout: ${manifest.tool.timeout_seconds}s`);

// Access parameter definitions
for (const [argName, argDef] of Object.entries(manifest.args)) {
  console.log(`  ${argName}: type=${argDef.type}, required=${argDef.required}`);
}
```

--------------------------------

### Auto-Generated Cedar Policy from ToolClad Manifest

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/symbiont-integration.md

Shows an example of a baseline Cedar policy automatically generated from a ToolClad manifest based on its `risk_tier` metadata. This policy defines permissions for executing the tool.

```cedar
# Auto-generated from nmap_scan.clad.toml (risk_tier = "low")
permit (
    principal,
    action == PenTest::Action::"execute_tool",
    resource
) when {
    resource.tool_name == "nmap_scan"
};
```

--------------------------------

### Get Tool Schema

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/cli-reference.md

Outputs the MCP JSON Schema for a specified tool by its name. This schema defines the expected input and output structure for the tool, which is crucial for understanding how to interact with it and for validation purposes.

```bash
$ symbi tools schema nmap_scan
{
  "name": "nmap_scan",
  "description": "Network port scanning and service detection",
  "inputSchema": { ... },
  "outputSchema": { ... }
}
```

--------------------------------

### Sign Tool Manifest with SchemaPin

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/security-model.md

Demonstrates how to use the schemapin-sign command to sign a .clad.toml file. This ensures the integrity of the tool's behavioral contract, protecting against tampering with validation rules, scope constraints, and other manifest elements.

```bash
schemapin-sign tools/nmap_scan.clad.toml
```

--------------------------------

### Enum and Port Validation

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Illustrates validating arguments against a predefined list of allowed values (enum) and validating port numbers within the valid range (1-65535). Includes examples of successful validation and error handling for invalid inputs.

```javascript
import { validateArg, checkInjection } from "toolclad";

// Validate enum type
const scanTypeDef = {
  type: "enum",
  allowed: ["ping", "service", "version", "syn"],
  required: true,
  position: 1
};

validateArg(scanTypeDef, "service");  // Returns "service"

try {
  validateArg(scanTypeDef, "exploit");  // Throws Error
} catch (e) {
  console.log(e.message);  // "Value 'exploit' not in allowed values"
}

// Validate port type
const portDef = { type: "port", default: 443 };
validateArg(portDef, "8080");   // Returns 8080
validateArg(portDef, "443");    // Returns 443

try {
  validateArg(portDef, "70000");  // Throws: out of range
} catch (e) {
  console.log(e.message);  // "Invalid port number: 70000 (must be 1-65535)"
}

// Check for injection manually
try {
  checkInjection("safe-value");     // OK
  checkInjection("value; rm -rf /");  // Throws
} catch (e) {
  console.log(e.message);  // "Injection detected: value contains shell metacharacters"
}

```

--------------------------------

### Test Tool Manifest (Bash)

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/getting-started.md

This bash command demonstrates how to test a Toolclad manifest file. It simulates the execution of the 'dig_lookup' tool with specific arguments for the target domain and record type, showing a dry-run output without actual execution.

```bash
toolclad test tools/dig_lookup.clad.toml \
  --arg target=example.com \
  --arg record_type=MX

```

--------------------------------

### Invoke msfconsole with dynamic arguments

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/command-construction.md

Demonstrates a complex msfconsole invocation using environment variables for configuration. It utilizes shell-based argument expansion to set target parameters and options before execution.

```bash
msfconsole -q -x "
  use ${TOOLCLAD_ARG_MODULE};
  set RHOSTS ${TOOLCLAD_ARG_TARGET};
  set RPORT ${TOOLCLAD_ARG_PORT};
  set PAYLOAD ${TOOLCLAD_ARG_PAYLOAD};
  set LHOST ${TOOLCLAD_ARG_LHOST};
  set LPORT ${TOOLCLAD_ARG_LPORT};
  ${TOOLCLAD_ARG_OPTIONS:+$(echo "$TOOLCLAD_ARG_OPTIONS" | tr ';' '\n')}
  run;
  exit
"
```

--------------------------------

### Configure CLI Session Mode

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/manifest-format.md

Sets up a persistent CLI session environment, including startup commands, timeout thresholds, and interaction patterns for tools like Metasploit.

```toml
[session]
startup_command = "msfconsole -q -x 'color false'"
ready_pattern = "^msf[0-9].*> $"
startup_timeout_seconds = 30
idle_timeout_seconds = 300
session_timeout_seconds = 1800
max_interactions = 100

[session.interaction]
input_sanitize = ["injection"]
output_max_bytes = 1048576
output_wait_ms = 2000
```

--------------------------------

### ToolClad Evidence Envelope JSON Format

Source: https://github.com/thirdkeyai/toolclad/blob/main/SKILL.md

Shows the structure of the evidence envelope generated by ToolClad for each execution. It includes status, scan ID, tool name, executed command, duration, output hash, and the actual results.

```json
{
  "status": "success",
  "scan_id": "1711929600-12345",
  "tool": "nmap_scan",
  "command": "nmap -sT -sV --max-rate 1000 10.0.1.0/24",
  "duration_ms": 4523,
  "timestamp": "2026-03-20T12:00:00Z",
  "output_hash": "sha256:a1b2c3...",
  "results": { "raw_output": "..." }
}

```

--------------------------------

### Session Lifecycle State Transitions

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/session-mode.md

Visualizes the lifecycle of a session from spawning to termination, highlighting key stages and events like startup commands, agent interactions, and timeouts. Sessions are ephemeral execution contexts.

```text
spawn -> startup -> ready -> interact -> ... -> terminate
  |
  |  startup_command
  |  wait for
  |  ready_pattern
  |
  |  startup_timeout
  |  exceeded? FAIL

                    |
                    |  agent
                    |  sends
                    |  cmds

                              |
                              |  idle_timeout
                              |  session_timeout
                              |  max_interactions
                              |  explicit close
                              |  agent terminates
```

--------------------------------

### Execute Toolclad Nmap Scan and Process Results (Python)

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Demonstrates how to load a manifest, execute an nmap scan with specific parameters, and then process the structured results, including error handling for failed or timed-out scans. This is useful for integrating network scanning capabilities into applications.

```python
manifest = load_manifest("tools/nmap_scan.clad.toml")
result = execute(manifest, {
    "target": "10.0.1.0/24",
    "scan_type": "service"
})

if result['status'] == 'error':
    print(f"Error (exit code {result['exit_code']}): {result['stderr']}")
elif result['status'] == 'timeout':
    print(f"Tool timed out after {manifest.tool.timeout_seconds}s")
else:
    # Process structured results
    for host in result['results'].get('hosts', []):
        print(f"Host: {host['ip']}")
        for port in host.get('ports', []):
            print(f"  {port['port']}/{port['protocol']} - {port['service']}")
```

--------------------------------

### Configure Argument Mappings

Source: https://github.com/thirdkeyai/toolclad/blob/main/docs/command-construction.md

Shows how to map logical enum values provided by an agent to specific CLI flag strings, abstracting complex syntax from the LLM.

```toml
[args.scan_type]
type = "enum"
allowed = ["ping", "service", "version", "syn", "os_detect"]

[command]
template = "nmap {_scan_flags} {target}"

[command.mappings.scan_type]
ping = "-sn -PE"
service = "-sT -sV --version-intensity 5"
version = "-sV --version-all --top-ports 1000"
syn = "-sS --top-ports 1000"
os_detect = "-sS -O --osscan-guess"
```

--------------------------------

### ToolClad Manifest Example (TOML)

Source: https://github.com/thirdkeyai/toolclad/blob/main/README.md

This TOML file defines the contract for the 'whois_lookup' tool. It specifies the tool's metadata, arguments, command template, and output format, including a schema for validation. This serves as the declarative interface for the tool.

```toml
# tools/whois_lookup.clad.toml
[tool]
name = "whois_lookup"
version = "1.0.0"
binary = "whois"
description = "WHOIS domain/IP registration lookup"
timeout_seconds = 30
risk_tier = "low"

[args.target]
position = 1
required = true
type = "scope_target"
description = "Domain name or IP address to query"

[command]
template = "whois {target}"

[output]
format = "text"
envelope = true

[output.schema]
type = "object"

[output.schema.properties.raw_output]
type = "string"

```

--------------------------------

### Tool Execution with Validation and Output Parsing

Source: https://context7.com/thirdkeyai/toolclad/llms.txt

Explains how to execute a tool using Toolclad, which includes argument validation, command construction, timeout enforcement, and output parsing. It shows how to access the evidence envelope containing execution details and parsed results.

```python
from toolclad import load_manifest, execute

manifest = load_manifest("tools/whois_lookup.clad.toml")

# Execute with arguments
result = execute(manifest, {"target": "example.com"})

# Access the evidence envelope
print(f"Status: {result['status']}")           # "success" or "error"
print(f"Scan ID: {result['scan_id']}")         # "1711929600-12345"
print(f"Tool: {result['tool']}")               # "whois_lookup"
print(f"Command: {result['command']}")         # "whois example.com"
print(f"Duration: {result['duration_ms']}ms")  # 1523
print(f"Exit code: {result['exit_code']}")     # 0
print(f"Output hash: {result['output_hash']}") # "sha256:a1b2c3..."

# Access parsed results
if result['status'] == 'success':
    print(f"Output: {result['results']['raw_output'][:200]}...")

```