Tool Calling¶

k13d uses AI tool calling to execute kubectl commands and, when explicitly enabled, limited bash commands and MCP tools based on natural language requests. The agentic kubectl prompt and command contract are aligned with kubectl-ai, including kubectl-first few-shot patterns for inventory, troubleshooting, cluster status, and safe verify-then-act workflows.

Important: the connected model itself must support tools/function calling. This is especially important for Ollama. Some Ollama models can connect and produce text, but k13d's AI Assistant will not work correctly unless the selected model explicitly supports tools.

Overview¶

Tool calling allows the AI to:

Understand Intent: Parse natural language requests
Select Tools: Choose appropriate tools for the task
Execute Commands: Run kubectl, limited bash, or MCP commands
Report Results: Explain outcomes to the user

User: "Scale nginx to 5 replicas"
         │
         ▼
┌─────────────────────────────────────────┐
│ AI Agent                                 │
│                                         │
│ 1. Parse intent: scale deployment       │
│ 2. Select tool: kubectl                 │
│ 3. Build command: kubectl scale         │
│    deployment nginx --replicas=5        │
│ 4. Request approval                     │
│ 5. Execute command                      │
│ 6. Report result                        │
└─────────────────────────────────────────┘
         │
         ▼
Result: "Scaled deployment nginx to 5 replicas"

Available Tools¶

By default, k13d exposes only the kubectl tool to agentic AI. This keeps the default behavior kubectl-first and avoids giving the model every possible tool by default.

kubectl¶

Default: enabled

Execute any kubectl command:

{
  "name": "kubectl",
  "description": "Execute kubectl commands",
  "parameters": {
    "command": "get pods -n default"
  }
}

Examples: - kubectl get pods - kubectl describe deployment nginx - kubectl logs pod-name - kubectl apply -f manifest.yaml

Hard-blocked, not approvable: - kubectl edit - kubectl port-forward - kubectl attach - kubectl exec -it / kubectl exec -ti

bash¶

Default: disabled, opt-in via llm.enable_bash_tool: true

Execute shell commands only as a last resort:

{
  "name": "bash",
  "description": "Execute shell commands as a last resort when kubectl or MCP cannot do the job",
  "parameters": {
    "command": "date"
  }
}

Examples: - date - grep pattern file - jq '.items[]' data.json

Avoid using bash for Kubernetes operations. If the task can be expressed with kubectl, k13d prefers the dedicated kubectl tool and will block bash-wrapped kubectl or helm commands. Even when enabled, bash always requires approval in k13d.

MCP Tools¶

Default: disabled, opt-in via llm.enable_mcp_tools: true

Dynamic tools from MCP servers:

{
  "name": "sequential_thinking",
  "description": "Step-by-step reasoning",
  "parameters": {
    "thought": "Analyzing the issue...",
    "thoughtNumber": 1,
    "totalThoughts": 3
  }
}

Tool Execution Flow¶

1. User Request¶

User: "Check why the api pod is crashing"

2. AI Planning¶

AI decides which tools to use:

Thought: I need to check pod status and logs
Tools: kubectl get pods, kubectl describe pod, kubectl logs

3. Tool Selection¶

AI generates tool calls:

{
  "tool_calls": [
    {
      "id": "call_1",
      "function": {
        "name": "kubectl",
        "arguments": "{\"command\": \"get pods | grep api\"}"
      }
    }
  ]
}

4. Safety Check¶

Command is analyzed for safety:

Command: kubectl get pods | grep api
Category: READ_ONLY
Auto-approve: Yes

5. Approval (if needed)¶

For write/dangerous commands:

┌─────────────────────────────────────────┐
│ Approval Required                        │
│                                         │
│ kubectl delete pod api-xyz              │
│                                         │
│ [Approve] [Reject]                      │
└─────────────────────────────────────────┘

6. Execution¶

Command is executed:

$ kubectl get pods | grep api
api-abc123   1/1     Running   5 (10m ago)   2d
api-def456   0/1     CrashLoopBackOff   12   1h

7. Result Processing¶

AI interprets results and may call more tools:

I see api-def456 is in CrashLoopBackOff. Let me check the logs...
[Tool: kubectl logs api-def456 --tail=50]

Safety System¶

Command Classification¶

Type	Examples	Default behavior
Read-only	get, describe, logs	Allowed, but `Decision Required` by default
Write	apply, create, patch, scale	Allowed, `Decision Required` by default
Dangerous	delete, drain	`Decision Required`, or fully blocked if `block_dangerous: true`
Unknown	custom shell commands	Controlled by `require_approval_for_unknown`
Hard-blocked	`kubectl edit`, `kubectl port-forward`, `kubectl exec -it`, bash-wrapped `kubectl`/`helm`, regex matches	Blocked immediately, not approvable

AST Parsing¶

k13d parses commands as an Abstract Syntax Tree:

"kubectl get pods | xargs rm -rf /"
         │
         ▼
┌─────────────────────┐
│ AST Parser          │
├─────────────────────┤
│ - Pipeline detected │
│ - rm -rf found      │
│ - DANGEROUS!        │
└─────────────────────┘

Blocked Patterns¶

Configure blocked command patterns:

authorization:
  tool_approval:
    blocked_patterns:
      - "rm -rf /"
      - "kubectl delete ns kube-system"
      - ":(){ :|:& };:"  # Fork bomb

Configuration¶

Tool Approval Settings¶

authorization:
  tool_approval:
    # Keep Decision Required for read-only commands unless you explicitly enable skipping
    auto_approve_read_only: false

    # Require approval for write commands
    require_approval_for_write: true

    # Require approval for unknown commands
    require_approval_for_unknown: true

    # Block dangerous commands entirely
    block_dangerous: false

    # Approval timeout in seconds
    approval_timeout_seconds: 60

llm:
  # Optional: expose bash to the agent
  enable_bash_tool: false

  # Optional: expose discovered MCP tools to the agent
  enable_mcp_tools: false

Custom Tool Definitions¶

Add custom tools in config:

tools:
  custom:
    - name: my_tool
      description: "My custom tool"
      command: "/path/to/script.sh"
      require_approval: true

Examples¶

Simple Query¶

User: "How many pods are running?"

AI: [Tool: kubectl get pods --no-headers | wc -l]
    You have 15 pods running in the default namespace.

Multi-Tool Query¶

User: "Why is my deployment failing?"

AI: [Tool: kubectl get deployment nginx -o yaml]
    [Tool: kubectl get events --field-selector involvedObject.name=nginx]
    [Tool: kubectl get pods -l app=nginx]

    Your nginx deployment is failing because:
    1. Image 'nginx:invalid' cannot be pulled
    2. All 3 pods are in ImagePullBackOff state

    To fix this, update the image tag:
    kubectl set image deployment/nginx nginx=nginx:latest

Action Request¶

User: "Scale the api deployment to 10 replicas"

AI: [Tool: kubectl scale deployment api --replicas=10]
    [Approval Required]

User: [Approves]

AI: Successfully scaled deployment 'api' to 10 replicas.

Tool Response Format¶

Success Response¶

{
  "success": true,
  "output": "deployment.apps/nginx scaled",
  "exit_code": 0
}

Error Response¶

{
  "success": false,
  "error": "Error from server (NotFound): deployments.apps \"nginx\" not found",
  "exit_code": 1
}

Debugging¶

Enable Debug Logging¶

debug: true
log_level: debug

View Tool Calls¶

In TUI:

:debug tools

In Web: Settings → Debug → Tool Calls

Audit Log¶

All tool calls are logged:

SELECT * FROM audit_logs
WHERE action = 'execute'
ORDER BY timestamp DESC;

Best Practices¶

1. Be Specific¶

# Good
"Scale nginx deployment in production namespace to 5 replicas"

# Less good
"Scale nginx"

2. Review Approvals¶

Always review commands before approving.

3. Use Read-Only for Exploration¶

"Show me all pods with high memory usage"
# Uses only read commands

4. Incremental Actions¶

"First show me the current state, then let's decide on changes"

Limitations¶

1. No Interactive Commands¶

Tools cannot handle interactive commands like vim or less.

2. Command Timeout¶

Commands timeout after 60 seconds by default.

3. Output Size¶

Large outputs are truncated.

4. No File Editing¶

Cannot directly edit files in containers.

Next Steps¶

LLM Providers - Provider configuration
MCP Integration - External tools
Security - Safety features