Insights

Designing datasets for reliable tool use

How to teach tool selection, argument construction, recovery, and authority boundaries through realistic examples.

In brief

What should a model learn from a tool-use training example?

  • Represent complete trajectories, tool state, and external effects.
  • Teach clarification, restraint, and the distinctions between recoverable and terminal errors.
  • Split and evaluate by underlying workflows, rather than near-duplicate calls.

The dataset defines what the agent learns to do

A tool-using model needs to make several decisions correctly in sequence. It must recognize that a tool is useful, select the right operation, construct valid arguments, interpret the result, and decide whether another action is justified. A dataset containing only successful calls teaches a narrow version of that task.

Production tools return partial data, reject requests, time out, and expose changing state. Users provide ambiguous identifiers. Permissions can be narrower than a model assumes. A useful training collection should represent these conditions and show the behavior expected when progress is constrained.

NYIC’s perspective is to treat tool-use data as a behavioral specification connected to the execution architecture. The model learns decisions and communication. The runtime enforces permissions, validates effects, and maintains durable state. Training examples should reflect that division so that model fluency never becomes the sole control over an external action.

Start with the action surface

Inventory the available operations before collecting examples. For each tool, record the purpose, inputs, output schema, prerequisites, side effects, and failure states. Distinguish read operations from writes and reversible actions from commitments that need stronger review. These properties determine which examples are necessary.

The schema should describe semantics as well as types. An account identifier represented as a string may need to refer to a verified internal account. A date field may use a particular timezone. A quantity may be expressed in units that differ from the user’s language. Type correctness alone cannot establish that an argument means the right thing.

Toolformer studied learning API selection, arguments, and incorporation of results into language-model behavior. It provides a research foundation for treating tool use as a learned capability. Enterprise datasets need additional examples for authorization, state reconciliation, and operational recovery. Read the Toolformer paper.

Represent trajectories rather than isolated calls

An isolated correct tool call does not explain why it was chosen. A trajectory connects the user request, available context, selected action, observation, and subsequent decision. This structure helps distinguish a justified call from an accidentally plausible one.

Store only the reasoning information needed for supervision and review. A concise decision rationale can identify the missing fact or relevant precondition without requiring a verbose narrative. The dataset should focus on observable decisions, evidence, and outcomes. Long explanations can distract from whether the action was correct.

ReAct explored interleaving reasoning, actions, and observations. For dataset design, the useful lesson is to preserve the feedback loop. A tool result should change the subsequent behavior when it changes the task state. Read the ReAct paper.

A worked scheduling example

Consider an illustrative assistant that helps an employee arrange an internal review meeting. It can inspect availability, identify participants, and prepare an invitation. Sending the invitation may require an explicit user instruction or a configured workflow permission. The dataset should capture that authority context.

Scenario Expected behavior What the example teaches
Two employees share a name Request or retrieve a disambiguating identifier Identity resolution
Requested time lacks a timezone Resolve the ambiguity before committing Argument semantics
Calendar lookup fails Report the limitation and retry within policy Bounded recovery
Availability changes Refresh before the final action State freshness
Send result is uncertain Reconcile whether an invitation exists Duplicate prevention
User changes the participant list Update the plan and invalidate stale assumptions Context revision

A complete trajectory can begin with a clear request, show identity resolution, retrieve available times, present a proposal, receive authorization, and execute the send. Another trajectory should stop before sending because authorization is absent. Both teach useful behavior. The second is essential for preventing the model from treating every planning conversation as permission to act.

Include negative examples that are plausible. A wrong meeting identifier can have the correct format. A stale availability response can look valid. An operation can succeed against the wrong calendar. These cases test semantic understanding rather than simple JSON validity.

Teach the difference between error classes

Failures require different responses. A transient network error may justify a retry. A validation error may require corrected arguments. An authorization error may require stopping or requesting a legitimate access change. A successful operation with an uncertain response may require reconciliation before another attempt.

The dataset should label these distinctions explicitly. It should avoid a universal retry pattern that treats every error as temporary. It should also show bounded attempts and a useful terminal state. A model that retries indefinitely can consume resources and make incident recovery harder.

For tools with side effects, include idempotency identifiers and status checks where the interface supports them. The model should learn to preserve the identifier across a retry of the same intended operation. A new identifier can represent a new action and defeat duplicate protection.

Include restraint and information gathering

Reliable tool use includes deciding that no tool call is appropriate yet. The user may be asking for an explanation. Required fields may be missing. The requested operation may be outside the agent’s scope. A dataset dominated by action examples can create a bias toward doing something whenever a tool is available.

Build examples where clarification is the successful outcome. Make the clarification specific to the missing information. Asking a generic question after every ambiguous request burdens users and teaches little. The model should identify the smallest uncertainty that blocks a correct next step.

Include cases where a deterministic computation or existing observation is sufficient. Repeated calls for unchanged information waste resources and can introduce inconsistency. The model should learn when evidence is fresh enough, with that policy defined by the application rather than improvised.

Control data generation and labeling

Synthetic trajectories can expand coverage, especially for rare failures. They require validation against actual tool schemas and plausible state transitions. A generated example that references an impossible API response teaches behavior the production system cannot support.

Use a simulator or test double to execute trajectories where practical. Validate arguments, transitions, and final state. Human review should focus on semantic correctness, authority, and whether the example demonstrates the intended behavior. Deterministic validators can handle schema checks and invariant violations efficiently.

Keep source lineage and version information. Tool schemas evolve. An example that was correct for an earlier version can become misleading after a field changes meaning. The training pipeline should identify affected examples when interfaces change and retain enough metadata to reproduce prior datasets.

Split by workflow and underlying state

Randomly splitting turns from the same trajectory leaks context. Similar generated scenarios can also appear in both training and evaluation with only names changed. Split complete trajectories and consider holding out workflow families, tool combinations, or state configurations.

A useful evaluation set includes unfamiliar compositions of known operations. The model may know how to search a record and how to update a field independently, yet fail when a verification step must connect them. Composition tests reveal whether it learned dependencies or memorized common sequences.

Hold out failure patterns as well. If training contains one timeout example for every tool, the model may learn a superficial phrase-based response. Vary wording and response structure while preserving the underlying semantics. Test whether recovery remains appropriate.

Evaluate effects, cost, and communication

The final environment state is often the strongest correctness signal. Did the intended record change once, with the correct values and authorization? Did unrelated state remain intact? A convincing final message cannot compensate for the wrong external effect.

Measure intermediate behavior to diagnose failures. Tool selection accuracy, argument validity, unnecessary calls, recovery success, and boundary violations each reveal different weaknesses. Include latency and total tool usage because a correct trajectory can still be impractical at production scale.

The user-facing response should reflect verified outcomes. If an operation was accepted but completion is pending, the response should say so. If a tool failed, the model should avoid claiming success. This communication behavior belongs in both training examples and evaluation rubrics.

Build a dataset that can evolve

Production observations can reveal missing scenario classes and confusing interfaces. Convert them into reviewed examples after removing unnecessary sensitive information and confirming the right to use the data. Preserve the distinction between a user complaint, a verified failure, and an approved correction.

A reliable tool-use dataset becomes a maintained specification of how the agent should behave as its environment changes. Its quality comes from coverage of decisions, consequences, and recovery. That foundation gives model training a clear target and gives the production system a more meaningful basis for trust.

Sources & further reading

  1. Toolformer ↗
  2. ReAct ↗