Tools Reference

The IBM i AI Platform provides a comprehensive suite of tools for observing, diagnosing, and managing IBM i systems. These tools follow the Observe → Recommend → Act capability model and are consolidated into Facade Tools to ensure consistent usage, strict execution safety, and auditable operations.

The Unified Tool Lifecycle (Observe → Recommend → Act)

To maximize safety and maintain a clear audit trail, all actions are split into read-only observation and a standardized, two-phase mutation lifecycle.

1. Observe (Read-Only)

Read-only queries are grouped into inspect_* tools. Each tool accepts a required view parameter to query different facets of system state. These are completely safe to execute at any time and do not require administrative approval.

2. Recommend & Act (Mutating Lifecycle)

All state-changing operations are handled by manage_* tools using a uniform two-step interaction model:

sequenceDiagram
    participant Operator as Operator / AI
    participant Hub as Hub Platform
    participant IBMi as IBM i Target

    Note over Operator,IBMi: Step 1: Recommend (Preview)
    Operator->>Hub: Call manage_* (mode="preview", action, reason)
    Hub-->>Operator: Returns previewId, previewToken & required approvals

    Note over Operator,IBMi: Step 2: Approval Gate
    Operator->>Hub: Request approvals in Hub UI
    Hub-->>Operator: Yields approvalTicket

    Note over Operator,IBMi: Step 3: Act (Execute)
    Operator->>Hub: Call manage_* (mode="execute", previewId, previewToken, approvalTicket)
    Hub->>IBMi: Executes approved CL / SQL changes
    IBMi-->>Hub: Returns execution results
    Hub-->>Operator: Complete

Each mutation requires:

  • operation: The action to perform (e.g. "create", "end").
  • mode: Either "preview" or "execute".
  • reason: Operator rationale for auditing.
  • action: Operation-specific parameters (e.g., target user name, job details).

1. Observe (Read-Only Facades)

These 15 tools let you query system metrics, logs, databases, and IFS files.

System & Health

inspect_system

Inspects IBM i hardware health, operating system identity, and PTF status.

  • Supported Views:
    • health: Returns a general system health status summary.
    • identity: Retrieves the system name, serial number, OS release, and partition information.
    • activity: Returns real-time CPU utilization and active system metrics.
    • ptf: Reviews individual PTF status by identifier.
    • ptf_groups: Lists active and pending PTF groups.
    • current_ptf_group_levels: Compares system PTF group levels against the official IBM PSP XML database.
    • disk: Returns disk-unit capacity and ASP utilization details.
    • memory_pools: Inspects memory pool configurations, thread counts, and fault rates.
    • asps: Lists Auxiliary Storage Pool status and structures.
    • system_values: Returns values for requested IBM i system configurations.
    • hardware_problems: Reviews open hardware problem logs.
    • licensed_programs: Inventories installed software licenses.
    • prerequisites: Checks host prerequisites and required SQL services.

inspect_storage

Inspects system storage pools, temporary storage allocations, and space utilization.

  • Supported Views:
    • summary: High-level overview of system and ASP storage limits.
    • consumers: Identifies the largest libraries, objects, or IFS directories consuming storage.
    • temp_by_job: Ranks active jobs by temporary storage consumption.
    • temp_buckets: Displays temporary storage consumption broken down by system bucket categories.
    • asps: Returns individual ASP configuration and disk utilization.
    • system_limits: Evaluates current storage states against configured alert thresholds.

Work Management

inspect_jobs

Analyzes active, queued, and scheduled workloads running on the system.

  • Supported Views:
    • active: Ranks active jobs by CPU, status, or job name.
    • scheduled: Lists native job schedule entries (WRKJOBSCDE).
    • job_queues: Lists active job queues and their current status.
    • queue_entries: Inspects jobs waiting inside a job queue.
    • pressure: Flags CPU or queue bottlenecks causing performance issues.

inspect_subsystems

Inspects subsystems controlling the IBM i runtime environments.

  • Supported Views:
    • active: Lists currently running subsystems and active job counts.
    • descriptions: Inventories subsystem descriptions (*SBSD) stored on the system.

inspect_spool

Views printer writers, output queues, and spooled file lists or contents.

  • Supported Views:
    • output_queues: Lists output queues on the system.
    • output_queue_entries: Retrieves lists of spooled files within a target queue.
    • writers: Displays state and library of active printer writers.
    • spooled_file_content: Reads the raw text content of a targeted spooled file.

Logs & Messages

inspect_messages

Triages system logs, operator message queues, and job execution logs.

  • Supported Views:
    • history_log: Fetches history log (QHST) entries with optional timestamp or severity filters.
    • qsysopr: Lists unanswered inquiry messages or warnings in QSYSOPR.
    • message_queue: Inspects entries inside any user or system message queue.
    • job_log: Returns the message log for a specific qualified job name.

File System & Objects

inspect_ifs

Examines files, paths, and search targets in the Integrated File System.

  • Supported Views:
    • directory: Lists directory items, sizes, and metadata.
    • path_status: Validates the existence and details of an absolute IFS path.
    • file_content: Reads raw text from an IFS file with windowing support.
    • file_summary: Synthesizes statistic summaries and samples of large IFS files.
    • file_query: Performs substring or regular expression text matches within a file.

inspect_objects

Analyzes libraries, objects, object locks, and save histories.

  • Supported Views:
    • library_objects: Inventories objects within a specific library.
    • object_authority: Inspects current privileges and owners for a specific object.
    • save_files: Lists save files (*SAVF) and their contents.
    • object_save_status: Checks last-saved metadata for an individual object.
    • recent_save_history: Lists save history logs.
    • object_locks: Reviews active locks on system objects.
    • record_locks: Reviews database record-level locks.

Network

inspect_network

Diagnoses network services, TCP connections, and server configurations.

  • Supported Views:
    • servers: Inventories active TCP servers (e.g., FTP, SMTP, Telnet).
    • tcp_listeners: Lists endpoints currently listening for connections.
    • tcp_connections: Returns active connection states and remote addresses.
    • http_servers: Lists Apache HTTP or WebSphere instances.
    • netserver: Returns NetServer file and print sharing status.
    • netserver_shares: Lists active NetServer shares.
    • rdb_directory: Reviews the Relational Database Directory entries.
    • drda_connections: Monitors active DRDA client/server connections.
    • configuration: Retrieves general TCP/IP configuration attributes.
    • time: Inspects SNTP configuration and current system clock alignment.
    • service_attributes: Retrieves attributes for specific services (like NTP).

Security & Database

inspect_users

Reviews profiles, special authorities, and credential health.

  • Supported Views:
    • profiles: Lists user profiles matching name or status filters.
    • authorities: Reviews special authorities granted to a specific user.
    • stale_profiles: Flags inactive profiles that haven't signed on in a specified timeframe.
    • password_expiration: Checks profile password expiration and status details.
    • special_authorities: Filters profiles containing administrative credentials (*ALLOBJ, *SECADM, etc.).

inspect_security

Provides deep-dive auditing of login history, certificates, and system-wide configurations.

  • Supported Views:
    • audit_configuration: Reviews system values controlling security audit journals.
    • certificate_expiry: Scans DCM keystores for expiring SSL certificates.
    • system_value_baseline: Compares security-sensitive values against recommended baselines.
    • authority_collection: Evaluates collected object authority usage.
    • required_authority: Detects required authority for specified execution paths.
    • function_usage: Inspects application function usage registrations.
    • authorization_lists: Lists system authorization lists (*AUTL).
    • authorization_list_authority: Reviews authority entries inside an authorization list.
    • login_activity: Triages authentication successes, failures, and sign-ons.

inspect_database

Explores Db2 for i database schemas, tables, and indexes.

  • Supported Views:
    • tables: Lists physical and logical tables inside a schema.
    • table_details: Explores columns, data types, and default definitions.
    • indexes: Displays table indexes, keyed fields, and optimization stats.
    • foreign_keys: Maps schema-level referential constraints.
    • sql_services: Inventories system-provided SQL views and procedures.
    • sql_service_details: Retrieves the parameter definitions and signatures of SQL services.
    • sql_recipes: Reviews system diagnostic SQL recipes.

Advanced Subsystems & HA

inspect_powerha

Monitors high-availability clustering and disk replication states.

  • Supported Views:
    • status: Aggregated health summary of the PowerHA environment.
    • cluster: Inspects cluster node topology and status.
    • crgs: Monitors Cluster Resource Groups and switchover readiness.
    • asp_sessions: Reviews replication sessions and synchronization status.
    • hyperswap: Monitors HyperSwap storage status.
    • admin_domain: Inspects the PowerHA administrative domain resource synchronization.

inspect_brms

Inspects Backup Recovery and Media Services (BRMS) catalog and operations.

  • Supported Views:
    • history: Reviews recent BRMS backup and recovery history logs.
    • control_groups: Lists BRMS backup control groups.
    • group_items: Lists items assigned inside a specific control group.
    • last_successful_saves: Identifies the latest healthy saves for system data.
    • media: Inventories tapes, virtual volumes, and media classes.
    • job_activity: Reviews BRMS batch and scheduled job history.

run_sql_recipe

Executes a read-only, audited IBM i SQL recipe from a curated list of system diagnostics.

2. Recommend & Act (Mutating Facades)

These 10 facade tools perform safe state updates using the two-phase preview and execution lifecycle.

Work & Queue Management

manage_job

Performs lifecycle and configuration updates on system jobs.

  • Supported Operations:
    • end: Safely terminates a job immediately or with a controlled timeout.
    • hold: Temporarily pauses job execution.
    • release: Resumes execution of a held job.
    • change: Modifies job properties (e.g. priority, run priority, time slice).

manage_job_queue

Controls job queues to manage system workload pressure.

  • Supported Operations:
    • hold: Prevents jobs in the queue from being dispatched to subsystems.
    • release: Resumes normal job dispatching from the queue.

manage_subsystem

Starts or ends isolated execution environments.

  • Supported Operations:
    • start: Launches a subsystem description.
    • end: Ends a running subsystem cleanly or immediately.

manage_spool_file

Manages print queue items.

  • Supported Operations:
    • delete: Deletes a targeted spooled file.
    • hold: Holds a spooled file.
    • move: Relocates a spooled file to a different output queue.

Storage, IFS, & Backups

manage_ifs_path

Handles operations on files and folders within the IFS.

  • Supported Operations:
    • delete: Deletes a file or symbolic link (RMVLNK).
    • rename: Renames an IFS object (RNM).
    • move: Relocates an IFS object (MOV).
    • create_directory: Creates a new IFS directory (MKDIR).
    • remove_directory: Deletes an empty IFS directory (RMVDIR).
    • change_authority: Modifies read/write permissions on a path (CHGAUT).

manage_ifs_backup

Performs save and restore procedures on IFS files.

  • Supported Operations:
    • save: Backs up IFS directory contents to a virtual or tape volume (SAV).
    • restore: Recovers IFS files from backup media (RST).

Network & Services

manage_tcp_server

Starts or stops network daemons.

  • Supported Operations:
    • start: Starts a standard TCP server (e.g. *FTP, *SMTP, *HTTP).
    • end: Terminates an active TCP server instance.

manage_messages

Interacts with operator and system message queues.

  • Supported Operations:
    • reply: Sends a reply to an outstanding inquiry message.
    • send: Dispatches a message to a target user or queue.
    • clear: Deletes all messages inside a named queue.

User & Object Security

manage_user_profile

Manages user accounts and administrative profiles safely.

  • Supported Operations:
    • create: Provisions a new *USER profile with safe defaults.
    • disable: Disables a user profile to block logins (STATUS(*DISABLED)).
    • reset_password: Sets a new password for the user.
    • change: Updates profile parameters (e.g. description, home directory, initial program).
    • delete: Deletes a user profile while transferring owned objects safely.

manage_object_security

Configures object ownership and permissions.

  • Supported Operations:
    • grant_authority: Grants explicit privileges to users or groups (GRTOBJAUT).
    • revoke_authority: Revokes privileges from users or groups (RVKOBJAUT).
    • change_owner: Transfers object ownership to a new profile (CHGOBJOWN).
    • restore_library: Restores a library from a save file or media (RSTLIB).

3. General & Context Management

plan_run_ibmi_command

Normalizes and previews any administrative CL command.

  • Previews execution impact and generates the approval ticket context for execution.

run_ibmi_command

Executes any arbitrary CL command after receiving an approved ticket from the planning phase.

  • Requires Approval: Yes.

manage_session

Manages the MCP session environment.

  • Sets or retrieves active target settings, including library lists (*LIBL), without needing a preview cycle.

Teach Moments & Beginner Safeguards

If you are a new operator or learning IBM i systems, remember:

  1. Observe first: Always use inspect_* tools to review current states before attempting updates.
  2. Review your pre-checks: When running a manage_* preview, inspect the generated preview summary carefully. It will highlight potential risks and affected objects before anything changes.
  3. Audit Trail: Every mutating action requires a reason. Be descriptive; this text is saved in the platform logs for security reviews.