When a workflow step calls a tool, the AI agent usually copies the data. It reads a property on the work item, writes that value into the tool call, then copies the tool's result back into a property. For a short id that is cheap. For a long invoice, a parsed record, or any other large value, that copy is slow and expensive: the model has to write every token of that value, and later turns of the same run read it again.
Map I/O skips that second copy. You wire a tool input to one of the step's input properties, and a tool output to one of the step's output properties. The platform fills the call from the work item and writes the result back. The agent still decides when to call the tool, and still fills any arguments you leave unmapped.
This article has two parts. Concepts explains when Map I/O is the right fix, and what it does not change. Details explains how to spot the copy in a step's run, and how to set the mapping.
Concepts
When the agent is only passing data along
A step's agent has two jobs that are easy to mix up:
Decide — whether to call a tool, which unmapped arguments to pass, how to read a result.
Pass along — take a value that already lives on the work item, put it into a tool call, then put the tool's result back onto the work item.
Passing a large value along is work the model should not do. It is not judgment. It is typing. Each token it writes is billed as output, which is the expensive kind, and a large tool result stays in the run's context for every later turn. See Understanding LLM costs and latency.
Use Map I/O when all of these are true:
The value already lives on the work item as a step input, or should be stored as a step output when the tool returns.
The agent does not need to transform that value — it should go through as-is.
The value is large, or it must not be rewritten on the way (a long document, a parsed object, a full record, an id that has to stay exact).
Typical cases:
A custom code tool that parses an Invoice property and returns a structured ParsedInvoice.
A custom AI tool that takes a long document body the previous step already stored, and returns extracted fields.
A connection tool that should receive a full record a previous step wrote, rather than have this step's agent re-type it.
Leave a field unmapped (Model fills / Model sees) when the agent should choose or construct it: a vendor name, a search query, a yes/no, a summary written from the result.
What Map I/O does not do
Map I/O stops a second copy through the tool call. It does not hide the value from the step.
Mapped inputs still appear in the step's current data, so the agent can still see them while it decides whether to call the tool.
Mapped outputs still appear on the work item after they are written, so later turns of the same step can read them.
If the goal is that the model never sees the data, do not bind that property as a step input. Map I/O is the wrong control for that.
Map I/O is also not:
A Reference on a custom tool's input. A Reference copies the property's type. The agent still has to pass the value. See Custom Tools.
A Tool Wrapper. A wrapper pins constant arguments; the agent still passes the work item's data. See How to build a Tool Wrapper.
Convert URLs to signed download URLs, which is for a connected tool that fetches a file itself. See Pass a file to a connected tool with a signed download URL.
Where it belongs, and where it does not
Map I/O is a setting on a workflow step, on one enabled tool. It is not available on the thunk-level Connections page, and it is not shown in the custom tool builder. Try It and tool tests still take full arguments, because those runs have no work item to read from.
You can map some fields of a tool and leave the rest with the model. Map only the fields that are being copied.
Builder API and Builder MCP
You can set the same mapping from the Builder API or Builder MCP, not only from the step's AI Tools panel.
On a workflow step, send toolConfig with op: "set_io_bindings". Name the library with libraryId copied from that step's toolConfig[].id, name the tool, and pass ioBindings as { inputs, outputs }. Each pair is { fieldName, propertyName }: a top-level field on the tool, and a property already listed on the step's input or output properties. An omitted side means none on that side. null, or empty inputs and outputs, clears the mapping. A mapping that is in use also enables the tool. Turning the tool off clears the mapping.
Map I/O is a workflow-step setting. A custom tool's own toolConfig (what an AI or code tool may call) does not take this operation.
Details
Look at the step's run
The mapping to add is visible in a run that already happened.
Open a work item that was slow or expensive on this step. Time Analysis and Token Costs name those items; Analysis of AI behavior is how you open the run.
Expand the run and look at each tool call — the arguments the agent passed, and the result that came back.
Ask two questions:
Did this argument already live on the work item? If the call contains a long property value the step was given as an input, the agent copied it. Map that tool input to that step input.
Did the agent then write a large result into a property? If the tool returned a large result the agent recorded as a step output, map that tool output to that step output.
Those copies are the opportunity. A tool that takes a short query and returns a short answer is not. A tool whose arguments the agent constructed (a search string, a filter, a judgment) should stay Model fills.
After you add a mapping, run the same kind of work item again and confirm the tool call no longer contains the large value. The mapped output is written onto the work item without the agent copying it.
Where to configure it
Open the workflow step in the thunk builder.
Open AI Instructions for that step.
Expand the AI Tools section.
Expand the tool you want to map.
Find Map I/O, after Availability.
By default, Map I/O shows No mappings, with Add.
After you save a mapping, the row shows the pairs, with Edit.
The row is hidden when the tool has no listed top-level inputs or outputs to map.
How to set a mapping
Expand an enabled tool in the step's AI Tools list.
In Map I/O, choose Add (or Edit if a mapping already exists).
The Map I/O dialog has two sides:
Into the tool — each tool input. Pick a Step in property, or leave Model fills.
Out of the tool — each tool output. Pick a Step out property, or leave Model sees.
Choose Done. Cancel discards the draft.
The dialog lists the tool's top-level fields. Fields nested inside a list of items are not mapped. A property that is no longer bound on the step shows as (missing) until you pick another or clear the mapping. Properties whose type does not match the tool field sit at the bottom of the list under Wrong type and cannot be chosen. A mapping that is already saved with a type mismatch still shows a warning, and it still runs.
You can map only inputs, only outputs, or both. Unmapped fields stay with the model.
The step still has to list those properties under Input properties and Output properties. Map I/O does not add a binding; it uses the ones the step already has. See AI Instructions.
What happens when the tool runs
For each mapped field:
Mapping | What the platform does | What the agent does |
Tool input ← step input | Fills the argument from the work item at call time | Does not pass that argument. A value it does pass for that field is ignored |
Tool output → step output | Writes the result onto the work item | Does not copy that result into the property |
The agent still chooses when to call. Remaining unmapped arguments are still its to fill.
If a mapped input property is empty on that work item, the tool call fails and names the property. The step does not start the tool. Mark that property Required to start when the tool cannot run without it; see Schematized State.
Turning the tool off on the step clears its Map I/O mappings. Turn the tool back on and add the mappings again if you still need them.
How Map I/O relates to other tool settings
Map I/O is one of several per-tool controls on a workflow step. They do different jobs:
Setting | What it does |
Tool enable toggle | Turns the tool on or off for the step for every work item |
Availability | Further limits an enabled tool to work items that match a condition. See Conditional tool availability |
Map I/O | Fills chosen inputs from the work item and writes chosen outputs back, so the agent does not copy them |
Approval | Requires a person to approve before the tool runs |
Constraints | Natural-language rules checked against the tool call before it runs |
A few practical details:
The tool must already be enabled for the thunk and for the step.
Approval still sees the filled-in call — the arguments a person is asked to approve include the mapped values, not only what the agent typed.
Map I/O does not change which tools the step can use, and Availability does not copy data.
Tips
Start from a real run, not from the tool's list of fields. The copy you can see is the mapping to add.
Map the large or exact-copy fields only. A short argument the agent should choose is cheaper to leave as Model fills than to over-map.
After you map an output, you do not need to tell the directions to record it. The platform writes it. Directions that still say "copy the result into ParsedInvoice" are leftover; remove them. See How to Write Effective AI Instructions.
For values that must not be rewritten — an order number, a customer id — Map I/O is stronger than relying on the agent to copy carefully. A Reference input still helps on tools you are not mapping, because it refuses a mistyped value before the tool runs. See "Values the AI agent copies" in Schematized State.