# AI Tools

The `ai.tools` section controls which Atmos commands the AI assistant can execute and whether user
confirmation is required.

> ⚠️ Experimental

:::note Renamed in a recent release
`tools.allowed_tools`, `tools.restricted_tools`, and `tools.blocked_tools` were renamed to
`tools.allowed`, `tools.restricted`, and `tools.blocked` — the `tools:` block already establishes
what these are lists of. The old names are no longer read; update `atmos.yaml` to the new names.
`tools.allowed` also picked up a second responsibility: see [Tool Settings](#tool-settings) below.
:::

## How Tool Calling Works

When you ask a question that requires infrastructure data, the AI decides which tool to call, requests permission (if configured), executes the tool locally, and uses the result to answer your question.

```mermaid
sequenceDiagram
    participant User
    participant AtmosAI as Atmos AI Chat
    participant LLM as AI Provider (Claude)
    participant Tools as Local Tools
    participant Files as Local Files

    User->>AtmosAI: "What's the VPC CIDR in prod-use1?"
    AtmosAI->>LLM: Send message + tool definitions (metadata only)
    Note over LLM: AI analyzes question<br/>Determines it needs tool
    LLM->>AtmosAI: Response: "I need atmos_describe_component"
    AtmosAI->>User: Request permission (if required)
    User->>AtmosAI: Approve
    AtmosAI->>Tools: Execute: describe_component(vpc, prod-use1)
    Tools->>Files: Read local stack/component files
    Files-->>Tools: Component configuration
    Tools-->>AtmosAI: Tool result with CIDR info
    AtmosAI->>LLM: Send tool results
    LLM->>AtmosAI: Final answer with CIDR
    AtmosAI->>User: "The VPC CIDR is 10.0.0.0/16"
```

### What Gets Sent to the AI Provider

Only **metadata** is sent initially — tool definitions (names, parameters, descriptions) and your question. No actual infrastructure data leaves your machine until the AI specifically requests it by calling a tool.

When the AI calls a tool, it runs **locally** and only the tool's output is sent back. You control this through the [permission system](#permission-modes).

## Configuration

**File:** `atmos.yaml`

```yaml
ai:
  tools:
    enabled: true
    require_confirmation: true
    allowed:
      - atmos_describe_component
      - atmos_list_stacks
      - atmos_validate_stacks
      - atmos_describe_*            # Wildcard patterns supported
    restricted:
      - write_component_file
      - write_stack_file
      - edit_file
    blocked:
      - execute_bash_command
    yolo_mode: false                # Skip all confirmations (DANGEROUS!)
```

## Tool Settings

- **`tools.enabled`**
  Enable or disable the tool subsystem for 
  `atmos ai chat`
  /
  `ask`
  /
  `exec`
   (default: 
  `false`
  ). When disabled, the AI can only answer from its training data and conversation context. This does 
  **not**
   affect 
  `atmos mcp start`
   — see 
  [MCP note](#mcp-server-note)
   below.
- **`tools.require_confirmation`**
  Prompt the user before executing any tool (default: 
  `true`
  ). Set to 
  `false`
   to allow all tools except 
  `restricted`
   to execute automatically.
- **`tools.allowed`**
  When non-empty, restricts which tools exist at all — only tools matching one of these name patterns are registered; every other tool simply isn't available this session. Listed tools also skip the confirmation prompt. Supports wildcard patterns like 
  `atmos_describe_*`
  . Empty/unset (default: 
  `[]`
  ) means every tool is registered, subject to normal confirmation rules.
- **`tools.restricted`**
  List of tools (from whatever 
  `allowed`
   already let through) that always require user confirmation, even when 
  `require_confirmation: false`
   (default: 
  `[]`
  ). Use this to protect write and execute operations.
- **`tools.blocked`**
  List of tools completely blocked from execution (default: 
  `[]`
  ). The AI cannot invoke these tools under any circumstances.
- **`tools.yolo_mode`**
  Skip all permission checks and execute tools immediately (default: 
  `false`
  ). Only use in trusted, isolated CI/CD environments. 
  **Never use in production or shared environments.**

### MCP Server Note

`atmos mcp start` always registers tools (subject to `tools.allowed`/`restricted`/`blocked`)
regardless of `tools.enabled` — `mcp.enabled: true` is that command's own, sufficient opt-in.
`tools.enabled` only gates `atmos ai chat`/`ask`/`exec`'s own tool-use loop. See
[MCP Configuration](/cli/configuration/mcp).

## Available Tools

### Atmos Commands

- **`atmos_describe_component`**
  Describe a component's configuration in a stack. Read-only.
- **`atmos_list_stacks`**
  List all available stacks. Read-only.
- **`atmos_validate_stacks`**
  Validate stack configurations against schemas and policies. Read-only.
- **`atmos_validate_schema`**
  Validate atmos.yaml (plus atmos.d and profile fragments) and other configured YAML files against their JSON Schemas. Read-only.
- **`describe_affected`**
  Show components affected by git changes. Read-only.
- **`get_template_context`**
  Debug Go template variable context. Read-only.
- **`execute_atmos_command`**
  Execute any Atmos CLI command. Permissions vary by command.
- **`atmos_list_findings`**
  List security findings from AWS Security Hub for Atmos stacks. Read-only.
- **`atmos_describe_finding`**
  Get detailed information about a specific security finding by ID. Read-only.
- **`atmos_analyze_finding`**
  Analyze a security finding using AI to determine root cause and remediation steps. Read-only.
- **`atmos_compliance_report`**
  Generate a compliance posture report for a framework (CIS AWS, PCI DSS, SOC2, HIPAA, NIST). Read-only.
- **`atmos_config_get`**
  Read a value from the active atmos.yaml using a dot-notation path. Read-only.
- **`atmos_config_list`**
  List the dot-notation setting paths defined in the active atmos.yaml. Read-only.
- **`atmos_config_set`**
  Set a value in the active atmos.yaml using a dot-notation path, preserving comments and anchors. Requires confirmation by default.
- **`atmos_config_delete`**
  Delete a value from the active atmos.yaml using a dot-notation path. Requires confirmation by default.
- **`atmos_config_format`**
  Format the active atmos.yaml file in place, preserving comments and anchors. Requires confirmation by default.
- **`atmos_stack_config_get`**
  Read the effective value of a component-relative dot-path for a component in a stack. Read-only.
- **`atmos_stack_config_list`**
  List editable component-relative config paths for a component in a stack. Read-only.
- **`atmos_stack_config_set`**
  Set a component-relative value for a component in a stack, using provenance to find the defining manifest. Requires confirmation by default.
- **`atmos_stack_config_delete`**
  Delete a component-relative value from the manifest that defines it for a component in a stack. Requires confirmation by default.
- **`atmos_stack_config_format`**
  Format the manifest files that define a stack component in place. Requires confirmation by default.
- **`atmos_vendor_config_get`**
  Read a raw value from a vendor manifest (vendor.yaml) by dot-notation path. Read-only.
- **`atmos_vendor_config_list`**
  List raw setting paths from a vendor manifest and its imports. Read-only.
- **`atmos_vendor_config_set`**
  Set a raw value in a vendor manifest by dot-notation path. Requires confirmation by default.
- **`atmos_vendor_config_delete`**
  Delete a raw value from a vendor manifest by dot-notation path. Requires confirmation by default.
- **`atmos_vendor_config_format`**
  Format a vendor manifest file in place, preserving comments and anchors. Requires confirmation by default.
- **`atmos_vendor_check_updates`**
  Check whether vendored Git-sourced components have a newer version available than the one currently pinned. Read-only.
- **`atmos_vendor_diff`**
  Show a unified diff between a vendored component's pinned version and another ref. Read-only.
- **`atmos_vendor_update`**
  Update vendored Git-sourced components' pinned version to the latest available tag. Requires confirmation by default.
- **`atmos_list_commands`**
  List Atmos CLI commands and subcommands. Read-only.
- **`atmos_command_help`**
  Get detailed help for a specific Atmos CLI command. Read-only.
- **`atmos_describe_dependents`**
  List the Atmos components that depend on a given component/stack pair. Read-only.
- **`atmos_describe_workflows`**
  List all Atmos workflows discovered under the configured workflows base path. Read-only.
- **`atmos_list_workflows`**
  List all Atmos workflows with their defining file, description, and step count. Read-only.
- **`atmos_list_components`**
  List unique Atmos components defined across all stacks. Read-only.
- **`atmos_list_values`**
  List a component's values across every stack where it's used. Read-only.
- **`atmos_auth_whoami`**
  Show the currently active Atmos authentication identity and credential status. Read-only.
- **`atmos_auth_list`**
  List configured Atmos authentication providers and identities. Read-only.
- **`atmos_toolchain_list`**
  List tools declared in the project's .tool-versions file. Read-only.
- **`atmos_toolchain_add`**
  Add a tool dependency to the project's .tool-versions file. Requires confirmation by default.
- **`atmos_toolchain_remove`**
  Remove a tool dependency from the project's .tool-versions file. Requires confirmation by default.
- **`atmos_toolchain_set`**
  Set a tool's default pinned version in the project's .tool-versions file. Requires confirmation by default.
- **`atmos_version_track_status`**
  Check every dependency in an Atmos version track against its datasource for available updates. Read-only.
- **`atmos_version_track_add`**
  Add a dependency entry to an Atmos version track. Requires confirmation by default.
- **`atmos_version_track_set`**
  Update fields of an existing Atmos version track dependency entry. Requires confirmation by default.
- **`atmos_version_track_remove`**
  Remove a dependency entry from an Atmos version track. Requires confirmation by default.
- **`atmos_version_track_update`**
  Advance an Atmos version track's locked versions within each entry's update policy. Requires confirmation by default.
- **`atmos_secret_list`**
  List declared secrets and their initialization status. Read-only.
- **`atmos_validate_component`**
  Validate an Atmos component's configuration in a stack using JSON Schema or OPA policies. Read-only.

### File Operations

- **`read_file`**
  Read any file from the repository. Read-only.
- **`read_component_file`**
  Read a file from the components directory. Read-only.
- **`read_stack_file`**
  Read a file from the stacks directory. Read-only.
- **`list_component_files`**
  List files in a component directory. Read-only.
- **`search_files`**
  Search for patterns across files. Read-only.
- **`edit_file`**
  Edit an existing file with targeted changes. Requires confirmation by default.
- **`write_component_file`**
  Write or modify a component file. Requires confirmation by default.
- **`atmos_terraform_component_hcl_get`**
  Read an attribute value or block from a Terraform component file using an hcledit-style HCL address. Read-only.
- **`atmos_terraform_component_hcl_edit`**
  Structurally edit a Terraform component file using hcledit, preserving comments and formatting. Requires confirmation by default.
- **`write_stack_file`**
  Write or modify a stack file. Requires confirmation by default.

### Execution

- **`execute_bash_command`**
  Execute shell commands. Requires confirmation by default.

### Validation and Web

- **`validate_file_lsp`**
  Validate files using LSP diagnostics (
  [requires LSP](/lsp/lsp-client)
  ). Read-only.
- **`atmos_validate_file`**
  Validate a YAML file against a JSON Schema with line numbers, no LSP required. Read-only.
- **`web_search`**
  Search the web via DuckDuckGo or Google. Requires confirmation by default.

All file operations include **path traversal protection** -- files can only be accessed within configured directories.

### Web Search Configuration

**File:** `atmos.yaml`

```yaml
ai:
  web_search:
    enabled: true
    max_results: 10
    # Google Custom Search (optional)
    # google_api_key: !env "GOOGLE_API_KEY"
    # google_cse_id: !env "GOOGLE_CSE_ID"
```

See [Web Search](/cli/configuration/ai#web-search) in the AI configuration reference for all settings.

## Permission Modes

- ****Prompt** (default)**
  Set 
  `require_confirmation: true`
  . Ask before each tool execution. The most secure mode.
- ****Allow****
  Set 
  `require_confirmation: false`
  . Auto-execute all tools except those in 
  `restricted`
  .
- ****YOLO****
  Set 
  `yolo_mode: true`
  . Skip all permission checks. Only use in isolated CI/CD environments.

### Permission Flow

A tool must first be _registered_ to be callable at all: if `tools.allowed` is non-empty, only
matching tools are registered in the first place. Everything below only applies to a tool that
made it that far:

```
1. YOLO Mode?     → Yes → Execute immediately
2. Blocked?       → Yes → Deny
3. Allowed list?  → Yes → Execute without prompt
4. Restricted?    → Yes → Always prompt
5. Default        → Prompt if require_confirmation is true
```

### Permission Prompts

When a tool requires confirmation:

```
Tool Execution Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tool: atmos_describe_component
Description: Describe an Atmos component configuration in a specific stack

Parameters:
  component: vpc
  stack: prod-use1

Options:
  [a] Always allow (save to .atmos/ai.settings.local.json)
  [y] Allow once
  [n] Deny once
  [d] Always deny (save to .atmos/ai.settings.local.json)

Choice (a/y/n/d):
```

## Wildcard Patterns

Tool lists support glob-style wildcard patterns:

```yaml
allowed:
  - atmos_describe_*      # Match all describe commands
  - atmos_list_*          # Match all list commands
  - *_validate            # Match anything ending in _validate
```

## Persistent Permission Cache

"Always allow" and "always deny" choices from interactive prompts are saved to `.atmos/ai.settings.local.json`. This file is user-specific and gitignored by default.

**Priority order:** `tools.allowed` (registration filter) > Blocked tools (config) > Cached denials > Allowed tools (config) > Cached allowances > Restricted tools > Default behavior.

## Skill-Specific Tool Access

Each [AI skill](/cli/configuration/ai/skills) defines which tools it can use, creating a safety layer where specialized skills only perform actions relevant to their purpose.

- ****General****
  Can read all, write all, execute all. Full access (respects global config).
- ****atmos-stacks****
  Can read stacks, components, files. No write or execute. Analysis only.
- ****atmos-components****
  Can read components, files. Can write and execute (with confirmation). Code-focused.
- ****atmos-terraform****
  Can read stacks, components, files. No write. Can execute (with confirmation). Plan/review only.
- ****atmos-validation****
  Can read stacks, files, LSP. No write or execute. Validation only.

**Workflow tip:** Use different skills for different phases — analyze with `atmos-stacks`, refactor with `atmos-components`, validate with `atmos-validation`. Switch skills with **Ctrl+A** in the chat TUI.

## Security Best Practices

**Start conservative.** The default (prompt for everything) is the most secure. Relax permissions over time as you build trust:

**File:** `atmos.yaml`

```yaml
# Production: very restrictive
ai:
  tools:
    enabled: true
    allowed: []                    # All tools registered; prompt for everything
    blocked:
      - execute_*                  # Block all execution tools
      - write_*                    # Block all write operations

# Development: more permissive
ai:
  tools:
    enabled: true
    allowed:
      - atmos_*                    # ONLY atmos_* tools are registered, and auto-approved
    blocked:
      - atmos_validate_stacks      # Still registered (it matches atmos_*) but every call is denied
```

Note: `allowed` only controls _registration_ (whether a tool exists this session at all).
`blocked`/`restricted` are checked at _execution_ time, against whatever `allowed` already let
through — a blocked tool can still appear in `tools/list` (MCP) or the AI's tool set, but every
call to it is denied. A tool listed in both `allowed` and `restricted` is auto-approved, not
prompted — `allowed` is checked first, before `restricted`.

:::warning YOLO Mode
Never use `yolo_mode` in production, shared environments, or workstations with production access. Reserve it for isolated CI/CD runners and sandboxed testing.
:::

## Troubleshooting

**Tools not executing:** Check `tools.enabled: true` in your config, verify the tool isn't in `blocked`, and — if you've set `tools.allowed` — verify the tool is actually in that list (otherwise it was never registered in the first place).

**No permission prompts:** The tool may be in `allowed` or you may have previously chosen "always allow" in `.atmos/ai.settings.local.json`. Delete the cache file to reset.

**Timeouts:** Tools have a 30-second timeout. Long-running operations are automatically cancelled. Run them manually if needed.

## Related Documentation

- [AI Configuration](/cli/configuration/ai) - Configure AI providers and settings
- [AI Skills](/cli/configuration/ai/skills) - Skill system and custom skill creation
- [AI Sessions](/cli/configuration/ai/sessions) - Persistent conversation sessions