Definition
Tool calling is the ability of an AI agent to invoke external programs, APIs, or system interfaces in order to complete a task. In practical terms, the agent selects a tool, prepares inputs, executes it, and interprets the result.
A domain model is an internal representation of how a system behaves. It includes structure, execution rules, state transitions, and expected outcomes. For IBM Z environments, this model must include concepts such as JCL execution, job steps, datasets, return codes, and spool behavior.
An agent that relies only on tool calling operates at the surface level of interaction. It can issue commands, but it does not understand the system it is interacting with. This distinction is critical in a job-centric environment.
How it works
Tool calling without a domain model
A generic AI agent typically follows this sequence:
- Receive a task description
- Select a tool that appears relevant
- Generate input parameters
- Execute the tool
- Interpret the output
This process assumes that the system behaves like loosely coupled services or command-line utilities. The agent treats each interaction as a standalone action.
In a Z environment, this assumption is incorrect. Execution is not isolated. It is coordinated through jobs, step sequencing, and system-managed resources.
Execution model on IBM Z
A job is the primary unit of execution. It is defined using Job Control Language (JCL) and submitted to the system for processing.
The system then performs the following steps:
- Parses the JCL
- Allocates datasets and resources
- Executes each step in sequence
- Produces output in the spool, including SYSOUT datasets
- Assigns return codes at the step and job level
This process is deterministic and stateful. Each step depends on the configuration and outcome of previous steps. Resource allocation, dataset disposition, and condition codes all influence behavior.
An agent must understand this structure in order to act correctly.
Failure mode 1: JCL treated like shell scripts
JCL defines system execution, which means it allocates resources and controls job behavior before any step runs. A generic agent treats JCL as procedural script logic and attempts to modify it accordingly. In literal terms, this ignores that dataset definitions are pre-execution system directives and that conditional flow is driven by return code evaluation. The result is syntactically valid but semantically incorrect JCL.
Failure mode 2: SYSOUT treated like logs
SYSOUT is structured spool output that encodes job execution through message formats and step boundaries. A generic agent treats it as unstructured log data and applies keyword-based interpretation. In literal terms, this ignores the structure that defines execution state, which leads to incorrect conclusions about job behavior and outcomes.
Failure mode 3: Return codes misunderstood
Return codes define graded execution outcomes and control step progression within a job. A generic agent treats non-zero values as failures and reacts by retrying or escalating. In literal terms, this misinterprets control signals as errors, which produces incorrect decisions that disrupt valid execution flow.
Why tools alone are insufficient
Tools enable execution. A domain model enables correct interpretation and decision-making.
Without a domain model, the agent cannot:
- Predict the effect of a JCL change
- Correctly interpret execution outcomes
- Maintain consistency across job steps
- Respect system-level constraints
The agent operates syntactically instead of semantically. It produces actions that appear correct but violate system behavior.
Key takeaways
- Tool calling provides execution capability but not system understanding
- IBM Z environments require a domain model centered on jobs, steps, and system state
- JCL is a declarative control language, not a procedural script
- SYSOUT is structured spool output, not generic logging data
- Return codes encode control flow decisions, not binary success or failure
- An agent without a platform model will produce confident but unsafe actions
#community-stories1