Fine-Grained Tool Control with toolsSettings

In Day 4, you controlled tool access with tools and allowedTools. The toolsSettings field provides granular control over how each tool operates.

Shell Tool Control

{
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["npm test", "npm run build", "git diff", "git log"],
      "deniedCommands": ["rm -rf", "sudo", "chmod 777"],
      "denyByDefault": true,
      "autoAllowReadonly": true
    }
  }
}

Setting	Description
allowedCommands	Commands permitted without confirmation (regex supported)
deniedCommands	Commands that are blocked
denyByDefault	Block all commands by default
autoAllowReadonly	Auto-allow read-only commands

AWS Tool Control

{
  "toolsSettings": {
    "aws": {
      "allowedServices": ["s3", "lambda", "cloudformation", "logs"],
      "deniedServices": ["iam", "organizations"],
      "autoAllowReadonly": true
    }
  }
}

Read / Write Tool Control

{
  "toolsSettings": {
    "read": {
      "allowedPaths": ["src/**", "tests/**", "docs/**", "*.md"],
      "deniedPaths": [".env", "*.key", "secrets/**"]
    },
    "write": {
      "allowedPaths": ["src/**", "tests/**"],
      "deniedPaths": ["package-lock.json", "node_modules/**"]
    }
  }
}

Web Fetch Tool Control

{
  "toolsSettings": {
    "web_fetch": {
      "trusted": ["https://docs\\..*", "https://api\\.github\\.com/.*"],
      "blocked": ["https://internal\\.company\\.com/.*"]
    }
  }
}

Tool Aliases

When multiple MCP servers provide tools with the same name, use toolAliases to rename them:

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@jira-mcp/get_issues": "jira_issues"
  }
}

This lets you clearly distinguish between github_issues and jira_issues in prompts.

Resources — Automatic Context Loading

The resources field specifies files to load automatically when the agent starts.

file:// Resources

File contents are loaded directly into context at startup:

{
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "file://CONTRIBUTING.md"
  ]
}

Glob patterns work for matching multiple files.

skill:// Resources

Only metadata is loaded at startup; full content loads on demand. Best for large documents:

{
  "resources": [
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

Knowledge Bases

For large document collections, register them as knowledge bases. Context is consumed only when searched:

{
  "resources": [
    {
      "type": "knowledgeBase",
      "source": "./docs",
      "name": "project-docs",
      "description": "Project documentation and API references",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

Index Type	Characteristics	Best For
fast	BM25 lexical search, high speed	Logs, configs, large codebases
best	Semantic search, high accuracy	Documentation, research

Practical Agent Examples

AWS Specialist

{
  "name": "aws-specialist",
  "description": "AWS infrastructure and development tasks",
  "prompt": "You are an AWS infrastructure expert. Follow AWS Well-Architected Framework best practices.",
  "tools": ["read", "write", "shell", "aws"],
  "allowedTools": ["read", "aws"],
  "toolsSettings": {
    "aws": {
      "allowedServices": ["s3", "lambda", "cloudformation", "ec2", "iam", "logs"],
      "autoAllowReadonly": true
    },
    "write": {
      "allowedPaths": ["infrastructure/**", "scripts/**", "*.yaml", "*.yml", "*.json"]
    }
  },
  "model": "claude-sonnet-4"
}

Use cases: CloudFormation stack deployment, S3/Lambda management, infrastructure troubleshooting.

Development Workflow (Git MCP)

{
  "name": "dev-workflow",
  "description": "Development workflow with Git integration",
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": []
    }
  },
  "tools": ["read", "write", "shell", "@git"],
  "allowedTools": [
    "read",
    "@git/git_status",
    "@git/git_log",
    "@git/git_diff"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**", "docs/**", "*.md", "*.json"]
    }
  }
}

Use cases: Code review, test creation, Git workflow management, documentation updates.

Code Review (Read-Only)

{
  "name": "code-reviewer",
  "description": "Code review and quality analysis (read-only)",
  "prompt": "You are a senior code reviewer. Focus on code quality, security vulnerabilities, adherence to coding standards, and potential improvements.",
  "tools": ["read", "shell"],
  "allowedTools": ["read"],
  "toolsSettings": {
    "shell": {
      "allowedCommands": [
        "grep", "find", "wc", "head", "tail", "cat", "diff",
        "git diff", "git log", "eslint", "pylint"
      ]
    }
  },
  "resources": [
    "file://CONTRIBUTING.md",
    "file://.kiro/steering/**/*.md"
  ]
}

Use cases: PR review, security vulnerability detection, coding standard checks. No write tool means zero risk of code modification.

Project-Specific (Docker + DB)

{
  "name": "backend-dev",
  "description": "Backend development with Docker and PostgreSQL",
  "mcpServers": {
    "docker": {
      "command": "docker-mcp-server",
      "args": []
    },
    "database": {
      "command": "postgres-mcp-server",
      "args": [],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  },
  "tools": ["read", "write", "shell", "@docker", "@database"],
  "allowedTools": [
    "read",
    "@docker/docker_ps",
    "@docker/docker_logs",
    "@database/query_read_only"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": [
        "src/**", "tests/**", "migrations/**",
        "docker-compose.yml", "Dockerfile", "requirements.txt"
      ]
    },
    "shell": {
      "allowedCommands": [
        "npm test", "npm run build",
        "docker-compose up", "docker-compose down", "docker-compose logs"
      ]
    }
  }
}

Use cases: Docker container management, database queries, migrations, API testing.

flowchart TB
    subgraph AWS["AWS Specialist"]
        A1["read, write, shell, aws"]
        A2["S3, Lambda, CF, EC2"]
    end
    subgraph Dev["Dev Workflow"]
        D1["read, write, shell, @git"]
        D2["status, log, diff"]
    end
    subgraph Review["Code Reviewer"]
        R1["read, shell only"]
        R2["grep, diff, lint"]
    end
    subgraph Backend["Backend Dev"]
        B1["read, write, shell, @docker, @db"]
        B2["docker_ps, query_read_only"]
    end
    style AWS fill:#f59e0b,color:#fff
    style Dev fill:#3b82f6,color:#fff
    style Review fill:#22c55e,color:#fff
    style Backend fill:#8b5cf6,color:#fff

MCP Server Configuration in Agents

Define MCP servers directly in agent configurations:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      },
      "timeout": 120000
    }
  },
  "includeMcpJson": true
}

Field	Description
command	Executable command (required)
args	Command arguments
env	Environment variables
timeout	Timeout in milliseconds (default: 120000)

Setting includeMcpJson to true also loads MCP configs from .kiro/settings/mcp.json and ~/.kiro/settings/mcp.json.

HTTP MCP Servers

Connect to remote servers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "redirectUri": "http://localhost:38951",
        "oauthScopes": ["repo", "user", "read:org"]
      }
    }
  }
}

Troubleshooting

JSON Syntax Errors

> /agent schema

Verify your configuration against the schema. Common mistakes: trailing commas, missing quotes, unmatched brackets.

Agent Not Found

> /agent list

• Check file location (.kiro/agents/ or ~/.kiro/agents/)
• Ensure .json extension
• Verify filename matches the agent name

Tool Not Available

• Verify the tool is in the tools array
• Ensure MCP servers are properly configured
• Use @server_name/tool_name format for MCP tools

Persistent Permission Prompts

• Ensure tools are in both tools and allowedTools
• Check for spelling inconsistencies
• Use full prefixed names for MCP tools in allowedTools

Summary

Topic	Details
toolsSettings	Fine-grained control over tool behavior
toolAliases	Resolve tool name conflicts
resources	file://, skill://, knowledgeBase for automatic context
MCP config	Define directly in agents, HTTP/OAuth support
Examples	AWS, Git integration, code review, Docker+DB

In Day 6, you'll learn about Code Intelligence for advanced code understanding.