> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolsets Reference

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

<Info>
  **Official Schema**: See the [JSON Schema definition](https://github.com/IBM/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/schemas/json/sql-tools-config.json) for the authoritative toolset configuration specification.
</Info>

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

<Note>
  **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.
</Note>

***

## Toolset Structure

Define toolsets in the `toolsets` section of your YAML configuration:

```yaml theme={null}
toolsets:
  toolset_name:
    title: "Human-Readable Title"
    description: "What this toolset provides"
    tools:
      - tool_name_1
      - tool_name_2
      - tool_name_3
```

### Basic Example

```yaml theme={null}
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                    |

<Warning>
  **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.
</Warning>

***

### Field Details

<Tabs>
  <Tab title="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`

    ```yaml theme={null}
    # ✅ Good names
    toolsets:
      performance_monitoring:
      employee_information:
      security_audit:
      business_reporting:

    # ❌ Avoid
    toolsets:
      tools1:
      misc:
      temp:
    ```
  </Tab>

  <Tab title="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.

    ```yaml theme={null}
    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
    ```

    <Note>
      **Cross-toolset tools**: A tool can appear in multiple toolsets. This is useful for shared utilities or tools that serve multiple purposes.
    </Note>
  </Tab>

  <Tab title="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.

    ```yaml theme={null}
    toolsets:
      performance_monitoring:
        title: "Performance Monitoring"  # Displayed to users
        description: "Tools for monitoring system performance"
        tools:
          - system_status
          - active_jobs
    ```
  </Tab>

  <Tab title="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

    ```yaml theme={null}
    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
    ```
  </Tab>
</Tabs>

***

## Organization Strategies

### By Functional Domain

Organize tools by what they do:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

```bash theme={null}
# No --toolsets parameter loads everything
npx -y @ibm/ibmi-mcp-server@latest --tools tools/my-tools.yaml
```

### Load Specific Toolsets

```bash theme={null}
# 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

```bash theme={null}
# 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:**

```yaml theme={null}
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:**

```yaml theme={null}
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:**

```bash theme={null}
# 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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="Toolset Size" icon="layer-group">
    **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:**

    ```yaml theme={null}
    # ✅ 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]
    ```
  </Accordion>

  <Accordion title="Naming Consistency" icon="text">
    **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:**

    ```yaml theme={null}
    # ✅ Consistent pattern
    toolsets:
      performance_monitoring:
      security_monitoring:
      application_monitoring:

    # ❌ Inconsistent
    toolsets:
      performance:      # Missing "_monitoring"
      sec_audit:        # Abbreviated
      app_mon_tools:    # Different pattern
    ```
  </Accordion>

  <Accordion title="Cross-Toolset Tools" icon="arrows-split">
    **Tools can belong to multiple toolsets:**

    ```yaml theme={null}
    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
  </Accordion>

  <Accordion title="Documentation Standards" icon="book">
    **Always include:**

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

    ```yaml theme={null}
    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
    ```
  </Accordion>
</AccordionGroup>

***

## Environment-Specific Toolset Loading

Use environment variables to control toolset loading across environments:

**Development:**

```bash theme={null}
# .env.development
SELECTED_TOOLSETS=development_full,testing_validation
```

**Production:**

```bash theme={null}
# .env.production
SELECTED_TOOLSETS=production_readonly,system_monitoring
```

**Start server:**

```bash theme={null}
npx -y @ibm/ibmi-mcp-server@latest --tools tools/ --toolsets $SELECTED_TOOLSETS
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Sources Reference" icon="database" href="/sql-tools/sources">
    Configure database connection sources
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/sql-tools/tools">
    Define individual SQL tool operations
  </Card>

  <Card title="Building SQL Tools" icon="hammer" href="/sql-tools/building-tools">
    Step-by-step guide to creating tools and toolsets
  </Card>

  <Card title="Tools Overview" icon="book-open" href="/sql-tools/overview">
    High-level overview of the SQL tools system
  </Card>
</CardGroup>

<Note>
  **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.
</Note>