Toolsets Reference

Complete reference for organizing SQL tools into logical groups using toolsets.

Official Schema: See the JSON Schema definition for the authoritative toolset configuration specification.

Toolsets organize related tools into logical groups that can be discovered, filtered, and deployed together. They provide a way to structure large collections of tools by functional area, business domain, or use case.

What Are Toolsets?

Toolsets are named collections of tools that share a common purpose or domain. They enable:

• Selective loading - Load only the tools you need
• Logical organization - Group related capabilities together
• Discoverability - Help AI agents find relevant tools
• Access control - Manage permissions by toolset
• Deployment flexibility - Deploy different toolsets to different environments

Design Principle: Toolsets are purely organizational - they don’t change tool behavior. A tool works the same whether loaded individually or as part of a toolset.

---

Toolset Structure

Define toolsets in the toolsets section of your YAML configuration:

toolsets:
  toolset_name:
    title: "Human-Readable Title"
    description: "What this toolset provides"
    tools:
      - tool_name_1
      - tool_name_2
      - tool_name_3

Basic Example

tools:
  system_status:
    source: ibmi-system
    description: "Get system performance metrics"
    # ... tool configuration

  active_job_info:
    source: ibmi-system
    description: "List active jobs"
    # ... tool configuration

  memory_pools:
    source: ibmi-system
    description: "Show memory pool statistics"
    # ... tool configuration

toolsets:
  performance_monitoring:
    title: "Performance Monitoring"
    description: "Tools for monitoring IBM i system performance and resource utilization"
    tools:
      - system_status
      - active_job_info
      - memory_pools

---

Toolset Fields Reference

Required Fields

All toolsets must include these fields:

Field	Type	Description
toolset_name	string (YAML key)	Unique identifier for the toolset, used to reference and load it
tools	array of strings	List of tool names to include in this toolset

Tool References: Each tool name in the tools array must match a key in the tools section. The server will error if a referenced tool doesn’t exist.

---

Field Details

toolset_name

Unique identifier for the toolset

The toolset name is the YAML key and must be unique across all toolsets in the configuration.

Naming conventions:

• Use lowercase with underscores: performance_monitoring
• Be descriptive of the domain: employee_information, security_audit
• Group logically: system_administration, business_reporting

# ✅ Good names
toolsets:
  performance_monitoring:
  employee_information:
  security_audit:
  business_reporting:

# ❌ Avoid
toolsets:
  tools1:
  misc:
  temp:

tools

Array of tool names to include

Type: array of strings (tool names)

Required: Yes

Lists the tools that belong to this toolset. Each name must match a tool defined in the tools section.

toolsets:
  employee_information:
    title: "Employee Information"
    description: "Tools for retrieving and analyzing employee data"
    tools:
      - get_employee_details
      - find_employees_by_department
      - find_employees_by_job
      - search_employees

Cross-toolset tools: A tool can appear in multiple toolsets. This is useful for shared utilities or tools that serve multiple purposes.

title

Human-readable display name

Type: string

Required: No (but recommended)

Provides a clear, user-friendly name for the toolset displayed in documentation and tooling.

toolsets:
  performance_monitoring:
    title: "Performance Monitoring"  # Displayed to users
    description: "Tools for monitoring system performance"
    tools:
      - system_status
      - active_jobs

description

Explanation of toolset purpose

Type: string

Required: No (but recommended)

Describes what capabilities this toolset provides and who should use it.

Best practices:

• Describe the business purpose, not just the tools
• Mention target users or use cases
• Note any special requirements

toolsets:
  security_audit:
    title: "Security Audit Tools"
    description: "Comprehensive security analysis and audit trail tools for compliance reporting. Requires *AUDIT special authority."
    tools:
      - user_audit
      - authority_check

---

Organization Strategies

By Functional Domain

Organize tools by what they do:

toolsets:
  performance_monitoring:
    title: "Performance Monitoring"
    description: "System performance and resource utilization"
    tools:
      - system_status
      - active_job_info
      - memory_pools
      - http_server_stats

  system_administration:
    title: "System Administration"
    description: "Administrative tools for system management"
    tools:
      - describe_object
      - list_services_by_category
      - search_services_by_name
      - library_list_info

  security_audit:
    title: "Security Audit"
    description: "Security analysis and compliance reporting"
    tools:
      - user_profile_audit
      - object_authority_check
      - audit_trail_analysis

By Business Process

Organize tools by business workflow:

toolsets:
  employee_onboarding:
    title: "Employee Onboarding"
    description: "Tools for new employee setup and validation"
    tools:
      - create_employee_record
      - assign_department
      - initialize_benefits
      - setup_security_access

  payroll_processing:
    title: "Payroll Processing"
    description: "Payroll calculation and reporting tools"
    tools:
      - calculate_gross_pay
      - compute_deductions
      - generate_pay_stub
      - tax_withholding_report

  performance_review:
    title: "Performance Review"
    description: "Employee performance evaluation workflow"
    tools:
      - get_employee_metrics
      - calculate_bonus
      - generate_review_report
      - update_salary_grade

By User Role

Organize tools by who uses them:

toolsets:
  developer_tools:
    title: "Developer Tools"
    description: "Development and debugging utilities"
    tools:
      - object_dependencies
      - recently_used_objects
      - stale_object_detection
      - source_code_search

  dba_tools:
    title: "Database Administrator Tools"
    description: "Database management and optimization"
    tools:
      - table_analysis
      - index_statistics
      - foreign_key_relationships
      - database_health_check

  auditor_tools:
    title: "Auditor Tools"
    description: "Compliance and security auditing"
    tools:
      - user_access_audit
      - privilege_escalation_check
      - data_modification_log
      - security_configuration_review

By Environment

Organize tools by deployment environment:

toolsets:
  production_monitoring:
    title: "Production Monitoring"
    description: "Production system monitoring (read-only)"
    tools:
      - prod_system_health
      - prod_performance_metrics
      - prod_job_status
      - prod_error_logs

  development_utilities:
    title: "Development Utilities"
    description: "Development and testing tools (write-enabled)"
    tools:
      - dev_create_test_data
      - dev_reset_environment
      - dev_debug_trace
      - dev_schema_compare

---

Selective Loading

Control which toolsets are loaded at server startup:

Load All Toolsets

# No --toolsets parameter loads everything
npx -y @ibm/ibmi-mcp-server@latest --tools tools/my-tools.yaml

Load Specific Toolsets

# Load single toolset
npx -y @ibm/ibmi-mcp-server@latest --tools tools/my-tools.yaml --toolsets performance_monitoring

# Load multiple toolsets (comma-separated)
npx -y @ibm/ibmi-mcp-server@latest --tools tools/my-tools.yaml --toolsets performance_monitoring,security_audit

# Load from environment variable
SELECTED_TOOLSETS=employee_information,payroll_processing
npx -y @ibm/ibmi-mcp-server@latest --tools tools/my-tools.yaml --toolsets $SELECTED_TOOLSETS

List Available Toolsets

# Show all toolsets without starting the server
npx -y @ibm/ibmi-mcp-server@latest --list-toolsets --tools tools/my-tools.yaml

Output:

Available toolsets in tools/my-tools.yaml:

performance_monitoring:
  Title: Performance Monitoring
  Description: Tools for monitoring IBM i system performance
  Tools: system_status, active_job_info, memory_pools (3 tools)

security_audit:
  Title: Security Audit
  Description: Security analysis and compliance reporting
  Tools: user_profile_audit, object_authority_check (2 tools)

employee_information:
  Title: Employee Information
  Description: Employee data retrieval and analysis
  Tools: get_employee_details, find_employees_by_department, search_employees (3 tools)

---

Multiple File Organization

Structure large tool collections across multiple files with consistent toolsets:

File Structure

tools/
├── performance.yaml       # Performance monitoring tools
├── security.yaml          # Security and audit tools
├── employee.yaml          # Employee management tools
└── business.yaml          # Business logic tools

Consistent Toolsets Across Files

tools/performance.yaml:

sources:
  ibmi-system:
    # ... connection config

tools:
  system_status:
    # ... tool config
  active_job_info:
    # ... tool config

toolsets:
  performance_monitoring:
    title: "Performance Monitoring"
    tools:
      - system_status
      - active_job_info

tools/security.yaml:

sources:
  ibmi-system:
    # ... connection config

tools:
  user_audit:
    # ... tool config
  authority_check:
    # ... tool config

toolsets:
  security_audit:
    title: "Security Audit"
    tools:
      - user_audit
      - authority_check

Load all files:

# Load entire directory
npx -y @ibm/ibmi-mcp-server@latest --tools tools/

# Load directory with specific toolsets
npx -y @ibm/ibmi-mcp-server@latest --tools tools/ --toolsets performance_monitoring,security_audit

---

Complete Examples

Example 1: Sample Database Toolsets

tools:
  get_employee_details:
    # ... tool config
  find_employees_by_department:
    # ... tool config
  get_employee_projects:
    # ... tool config
  find_project_team_members:
    # ... tool config
  get_department_salary_stats:
    # ... tool config
  calculate_employee_bonus:
    # ... tool config

toolsets:
  employee_information:
    title: "Employee Information"
    description: "Tools for retrieving and analyzing employee data"
    tools:
      - get_employee_details
      - find_employees_by_department
      - find_employees_by_job
      - search_employees

  project_management:
    title: "Project Management"
    description: "Tools for managing project assignments and team members"
    tools:
      - get_employee_projects
      - find_project_team_members

  salary_analysis:
    title: "Salary Analysis"
    description: "Tools for analyzing salary data across departments"
    tools:
      - get_department_salary_stats
      - calculate_employee_bonus

Example 2: System Administration Toolsets

toolsets:
  system_monitoring:
    title: "System Monitoring"
    description: "Real-time system health and performance monitoring"
    tools:
      - system_status
      - subsystem_status
      - active_job_info
      - memory_pools
      - http_server_stats

  object_management:
    title: "Object Management"
    description: "Database object inspection and analysis"
    tools:
      - describe_object
      - list_services_by_category
      - search_services_by_name
      - object_statistics
      - object_dependencies

  security_management:
    title: "Security Management"
    description: "User and authority management tools"
    tools:
      - user_profile_info
      - object_authority_check
      - library_list_security
      - audit_trail_analysis

Example 3: Multi-Environment Toolsets

toolsets:
  production_readonly:
    title: "Production Read-Only Tools"
    description: "Safe monitoring tools for production environment"
    tools:
      - prod_system_health
      - prod_job_status
      - prod_performance_metrics
      - prod_error_logs

  development_full:
    title: "Development Full Access"
    description: "All development tools including write operations"
    tools:
      - dev_system_health
      - dev_job_status
      - dev_create_test_data
      - dev_reset_environment
      - dev_debug_trace

  testing_validation:
    title: "Testing Validation Tools"
    description: "Tools for test execution and validation"
    tools:
      - test_data_validation
      - test_result_comparison
      - test_coverage_analysis

---

Best Practices

Toolset Size

Optimal size: 3-10 tools per toolset

• Too small (1-2 tools): Defeats the purpose of grouping
• Too large (20+ tools): Reduces discoverability and increases load time
• Just right (3-10 tools): Easy to understand and manage

Example:

# ✅ Good size
toolsets:
  performance_monitoring:
    tools: [system_status, active_jobs, memory_pools, cpu_usage]

# ❌ Too small
toolsets:
  single_tool_set:
    tools: [system_status]

# ❌ Too large
toolsets:
  everything:
    tools: [tool1, tool2, ... tool25]

Naming Consistency

Use consistent naming patterns:

• Domain-based: {domain}_{purpose} → security_audit, performance_monitoring
• Role-based: {role}_tools → developer_tools, dba_tools
• Environment-based: {env}_{category} → prod_monitoring, dev_utilities

Be consistent within a project:

# ✅ Consistent pattern
toolsets:
  performance_monitoring:
  security_monitoring:
  application_monitoring:

# ❌ Inconsistent
toolsets:
  performance:      # Missing "_monitoring"
  sec_audit:        # Abbreviated
  app_mon_tools:    # Different pattern

Cross-Toolset Tools

Tools can belong to multiple toolsets:

tools:
  system_health:
    # ... config

toolsets:
  production_monitoring:
    tools:
      - system_health
      - prod_metrics

  development_monitoring:
    tools:
      - system_health  # Same tool in different toolset
      - dev_metrics

Use cases:

• Shared utility tools (logging, health checks)
• Cross-domain tools (system information)
• Different access levels to same tool

Documentation Standards

Always include:

• title: Clear, human-readable name
• description: Purpose and target users
• Mention any special requirements (authorities, environments)

toolsets:
  security_audit:
    title: "Security Audit Tools"
    description: "Comprehensive security analysis and audit trail tools for compliance reporting. Requires *AUDIT special authority. Production use only."
    tools:
      - user_audit
      - authority_check
      - compliance_report

---

Environment-Specific Toolset Loading

Use environment variables to control toolset loading across environments:

Development:

# .env.development
SELECTED_TOOLSETS=development_full,testing_validation

Production:

# .env.production
SELECTED_TOOLSETS=production_readonly,system_monitoring

Start server:

npx -y @ibm/ibmi-mcp-server@latest --tools tools/ --toolsets $SELECTED_TOOLSETS

---

Next Steps

Sources Reference

Configure database connection sources

Tools Reference

Define individual SQL tool operations

Building SQL Tools

Step-by-step guide to creating tools and toolsets

Tools Overview

High-level overview of the SQL tools system

Toolset Design Philosophy: Toolsets are organizational constructs that improve discoverability and deployment flexibility. Design toolsets around how tools are used (functional domains, business processes, user roles) rather than how they’re built (database schemas, file structure). Good toolsets help AI agents and humans quickly find the right tool for their task.