SchemaSmith Documentation

Trust Levels

Three trust levels control which of the 46 schema tools are available — from read-only exploration to full external tool execution.

Overview Trust Levels Tool Tiers Configuration Recommendations
Ask Forge Trust Levels

Overview

Ask Forge uses a tiered permission model built on two distinct concepts:

  • 3 Trust Levels (Observer, Assistant, Operator) — the user-facing permission setting that controls which tools are accessible.
  • 4 Tool Tiers (ReadOnly, Generate, Modify, External) — the classification system that groups tools by capability and risk.

Each trust level grants access to one or more tool tiers. This design follows the principle of least privilege — users start with read-only access and explicitly opt in to higher capabilities.

Default: Assistant. Out of the box, Ask Forge runs at the Assistant trust level, giving access to Tier 1 (ReadOnly) and Tier 2 (Generate) tools. Escalate to Operator only when you need to modify schemas or run external tools.

Trust Levels

Observer Read-Only

The safest trust level. Observer grants access to Tier 1 (ReadOnly) tools only — 24 tools that inspect and analyze schemas without making any changes. Safe for any user or environment.

Available Tools (Tier 1)

  • Schema navigation and browsing
  • Table and column inspection
  • Data validation checks (nulls, orphans, duplicates)
  • Index analysis and recommendations
  • Dependency graphing
  • Schema search and filtering
  • Diff and compare operations
  • Knowledge base access

What You Cannot Do

  • Generate migration scripts
  • Create or modify schema definitions
  • Execute external tools against databases
  • Save files to disk
Assistant Default + Generation

The default trust level. Assistant grants access to Tiers 1-2 (ReadOnly + Generate) — 33 tools total. Can create new content (scripts, schemas, suggestions) but cannot modify existing schema files or execute external tools.

Additional Tools (Tier 2) + all Observer tools

  • Migration script generation
  • Change suggestion generation
  • Schema generation from natural language
  • Script saving to disk
  • Configuration management

What You Cannot Do

  • Modify existing schema JSON files
  • Rename tables or columns in-place
  • Execute external tools against databases
Operator + Modify & External

The highest trust level. Operator grants access to all 4 tiers — all 46 tools. This includes modifying schema definitions and executing external SchemaSmith tools against live databases. Tier 3 and Tier 4 tools require confirmation by default.

Additional Tools (Tiers 3-4) + all Assistant tools

  • Apply changes to schema JSON
  • Rename tables and columns
  • Create new tables and packages
  • Manage tokens and variables
  • SchemaTongs — Extract schema from a live database
  • SchemaQuench — Deploy schema changes to a database
  • DataTongs — Compare data between databases

Safety Mechanism

Tier 3 (Modify) and Tier 4 (External) tools require explicit confirmation before executing. Ask Forge shows you exactly what will change and waits for your approval. See Confirmation Workflow.

Tool Tiers

Tools are organized into 4 tiers based on capability and risk. Higher tiers require higher trust levels and may require confirmation before execution.

Tier Name Count What It Does Confirmation
1 ReadOnly 24 Navigate, query, analyze, validate schemas Never
2 Generate 9 Generate scripts, schemas, manage config Never
3 Modify 9 Modify schema JSON files on disk Required by default
4 External 4 Run SchemaSmith tools against live databases Required by default

Trust Level Comparison

Capability Observer Assistant Operator
Browse schemas, tables, columns
Validation checks (nulls, orphans, duplicates)
Index analysis and dependency graphs
Schema search, diff, compare
Knowledge base access
Generate migration scripts
Generate schemas from natural language
Save scripts to disk
Modify schema JSON files (confirmation)
Rename tables and columns (confirmation)
Create tables and packages (confirmation)
Execute SchemaTongs, SchemaQuench, DataTongs (confirmation)

Configuration

Set the trust level using one of three methods. When multiple are set, the highest-precedence method wins.

1. Command-Line Flag Highest Precedence

ask-forge --trust-level operator list-tables

2. Environment Variable

set FORGE_TRUST_LEVEL=operator
ask-forge
export FORGE_TRUST_LEVEL=operator
ask-forge

3. Config File Lowest Precedence

{
  "agent": {
    "trustLevel": "assistant"
  }
}
Precedence: CLI flag > environment variable > config file. The default trust level is Assistant. Valid values: observer, assistant, operator.

Confirmation Workflow

When operating at the Operator trust level, Tier 3 (Modify) and Tier 4 (External) tools require confirmation before executing:

  1. Ask Forge displays a preview of what the tool will do
  2. You are prompted to confirm or cancel
  3. The tool only executes after explicit confirmation
  4. Results are displayed after execution

Even when autoExecute is true, confirmation is still required for Tier 3 and Tier 4 tools unless the corresponding confirm setting is disabled.

Confirmation Settings
Setting Type Default Description
confirmTier3 bool true Require confirmation for Modify tools
confirmTier4 bool true Require confirmation for External tools
autoExecute bool true Allow Tier 1-2 tools to execute without manual trigger
maxToolIterations int 10 Maximum tool calls per conversation turn (prevents runaway loops)
Bypassing Confirmation

CLI: --yes Flag

Skip all confirmation prompts in a single command:

ask-forge apply-change --table Users --definition @change.json --yes

Config File: Disable Per Tier

{
  "agent": {
    "confirmTier3": false,
    "confirmTier4": false
  }
}

MCP Server

When running as an MCP server, the AI assistant can pass confirm: true in tool parameters to indicate pre-approval from the user.

Warning: Disabling confirmation for Tier 4 tools means external tools can modify live databases without prompting. Use with caution.

Security

Credential Security
  • Use ${ENV_VAR} substitution for passwords and API keys rather than storing raw secrets in config.json:
{
  "apiKey": "${ANTHROPIC_API_KEY}",
  "connections": [{
    "password": "${DB_PASSWORD}"
  }]
}
  • Never commit your config file to version control
  • The list-connections command never displays passwords
  • The show-config command displays the full config (including connection details) — use with care
  • For development, use dotnet user-secrets to manage sensitive values outside of config files
MCP Server Security
  • Set FORGE_TRUST_LEVEL to control what the AI assistant can do
  • Recommended: Use observer or assistant for MCP to prevent AI-initiated database modifications
  • The MCP server inherits the trust level from its environment — do not run with operator unless you want the AI to be able to modify schemas and run external tools
Running the MCP server at the Operator trust level means the connected AI assistant can modify schema files and execute tools against live databases. Only use this configuration in environments where that level of access is intentional.

Recommendations by Use Case

Team Explorer

For team members who need to browse and understand the schema without making changes.

Observer 
{
  "agent": {
    "trustLevel": "observer"
  }
}
Developer

For developers who need to generate migration scripts and design new schema components.

Assistant

This is the default trust level — no configuration needed.

Database Admin

For DBAs who need to extract schemas from live databases and deploy changes.

Operator 
{
  "agent": {
    "trustLevel": "operator",
    "confirmTier3": true,
    "confirmTier4": true
  }
}
Automated Workflows

For scripted or unattended workflows that need non-interactive schema operations.

Operator 
{
  "agent": {
    "trustLevel": "operator",
    "confirmTier3": false,
    "confirmTier4": false,
    "autoExecute": true
  }
}

Use --yes on the command line to skip all prompts in scripts.