Skip to main content

Map a tool's inputs and outputs to the work item

When a step would copy large work-item values through a tool call, map those fields onto the step's properties instead.

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 a host input, and a tool output to a host output. On a workflow step, the host is the step's input and output properties (the work item). On a custom AI tool, the host is that tool's own inputs and outputs: nested tools the AI tool calls can fill from the values it was given, and write back onto the values it returns. The platform fills the call and writes the result. 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 host as an input, or should be stored as an output when the tool returns. On a step, that host is the work item. On a custom AI tool, that host is the AI tool's own inputs and outputs.

  • 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 tool that reads a Document and writes the cleaned document back onto Document. List Document as both a step input and a step output, then map both sides of the tool onto it.

  • A custom AI tool that takes a long document body the previous step already stored, and returns extracted fields. If that custom AI tool then calls another tool with the same document, map the nested tool on the custom AI tool so the nested agent does not retype the document either.

  • 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:

Where it belongs, and where it does not

Map I/O is a setting on the caller — the AI that decides when to call the tool — not a setting inside the tool being called.

You set it:

  • On a workflow step, on one enabled tool in that step's AI Tools list. That tool can be a connection tool, a custom AI tool, or a custom code tool. Mapping a code tool on the step is the usual case: the step's agent would otherwise copy a large property into the call.

  • On a custom AI tool, on a nested tool in that AI tool's AI Tools list. The nested tool can also be a custom code tool. The host is the custom AI tool's own inputs and outputs.

You cannot set it:

  • On the thunk-level Connections page.

  • Inside a custom code tool, on the tools that code calls. The script already passes values itself, so there is nothing for Map I/O to skip. Map the code tool on the step or custom AI tool that calls it instead.

Try It of a connection tool still takes full arguments, because those runs have no work item to read from. Try It of a custom AI tool still takes that AI tool's own inputs; nested tools you mapped onto those inputs are filled from the values you pass.

You can map some fields of a tool and leave the rest with the model. Map only the fields that are being copied.

FDA API and FDA MCP

You can set the same mapping from the FDA API or FDA MCP, not only from the step's AI Tools panel.

On a workflow step, send toolConfig with op: "set_io_bindings". That maps any enabled tool, including a custom code tool. 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. The same property can appear on both sides when it is listed as both an input and an output. Each tool field maps to one property per side: a request that maps the same tool field to two different properties is refused with an error that names them. 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.

The same operation on a custom AI tool's nested toolConfig maps a nested tool (that nested tool may be a code tool) onto that AI tool's own inputs and outputs (propertyName is a field of the custom AI tool). A custom code tool's own nested toolConfig does not take this operation: the code already passes values to the tools it calls. The collect step (Add to Work Items) also does not take it.

Details

Look at the step's run

The mapping to add is visible in a run that already happened.

  1. 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.

  2. Expand the run and look at each tool call — the arguments the agent passed, and the result that came back.

  3. 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

On a workflow step:

  1. Open the workflow step in the thunk builder.

  2. Open AI Instructions for that step.

  3. Expand the AI Tools section.

  4. Expand the tool you want to map.

  5. Find Map I/O, after Availability.

On a custom AI tool:

  1. Open the custom AI tool.

  2. Expand the AI Tools section (the nested tools this AI tool may call).

  3. Expand the nested tool you want to map.

  4. Find Map I/O, after Availability.

By default, Map I/O shows No mappings, with Add.

Map I/O with no mappings, and Add

After you save a mapping, the row shows the pairs, with Edit.

Map I/O showing Invoice mapped to invoice and parsed mapped to ParsedInvoice, with Edit

The row is hidden when the tool has no listed top-level inputs or outputs to map.

How to set a mapping

  1. Expand an enabled tool in the step's AI Tools list.

  2. In Map I/O, choose Add (or Edit if a mapping already exists).

  3. The Map I/O dialog has two sides:

    • Into the tool — each tool input. Pick a Step in property (on a step) or an Input of this AI tool (on a custom AI tool), or leave Model fills.

    • Out of the tool — each tool output. Pick a Step out property (on a step) or an Output of this AI tool (on a custom AI tool), or leave Model sees.

  4. Choose Done. Cancel discards the draft.

Map I/O dialog for parse_invoice: Invoice fills invoice, parsed writes ParsedInvoice, vendor and summary stay with the model

The dialog lists the tool's top-level fields, including list fields. Fields nested inside a list of items are not mapped. A list property maps to a list-typed tool field; a single-value property cannot map onto a list field. 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.

A property that is both a step input and a step output (or both an input and an output of a custom AI tool) can be used on both sides of one mapping: the tool reads the current value and writes the result back onto the same property.

On a step, those properties still have to be listed under Input properties and Output properties. A mapped property shows a Map I/O chip. Click it to open that tool's Map I/O dialog. A mapped tool in the tool list also shows a Map I/O chip. Click it to open Map I/O. Map I/O does not add a binding; it uses the ones the step already has. See AI Instructions. On a custom AI tool, the names you pick are that tool's own input and output fields.

What happens when the tool runs

For each mapped field:

Mapping

What the platform does

What the agent does

Tool input ← host input

Fills the argument from the work item (on a step) or from this AI tool's input (on a custom AI tool) at call time

Does not pass that argument. A value it does pass for that field is ignored

Tool output → host output

Writes the result onto the work item, or onto this AI tool's result

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 is empty on that work item, or empty on the custom AI tool's input, the tool call fails and names the field. The step or nested run does not start the tool. On a step, mark that property Required to start when the tool cannot run without it; see Schematized State.

Turning the tool off on the step, or on the custom AI tool, 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 (and on a custom AI tool's nested tools). 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 host 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.

Did this answer your question?