feat(simulation): add optional tools parameter to ToolSimulator (#208)

[kaghatim]

Description

Add an optional tools parameter to ToolSimulator.__init__ that gets passed through to the internal simulation Agent. This lets users provide helper tools (like calculator from strands-agents-tools) to improve the accuracy of simulated responses, especially for stateful, arithmetic-heavy simulations.

Currently the simulation agent is created with tools=[] hardcoded. This works fine for simple simulations, but when simulating APIs that require arithmetic consistency across multiple tool calls (e.g. inventory reconciliation, order metrics, settlement calculations), the LLM frequently gets the math wrong. Those errors compound because the StateRegistry feeds previous responses back into subsequent prompts.

The change is minimal and fully backward compatible. tools defaults to None (stored as []), so existing behavior is unchanged.

What changed

• ToolSimulator.__init__ accepts an optional tools parameter
• _simulate_tool_call passes self.tools to the Agent constructor instead of []
• 5 new unit tests covering default behavior, storage, and pass-through to Agent

Example usage

from strands_tools import calculator
from strands_evals.simulation import ToolSimulator

simulator = ToolSimulator(
    model="us.anthropic.claude-sonnet-4-20250514",
    tools=[calculator],
)

Related Issues

Closes #208

Documentation PR

No documentation changes needed. The new parameter follows existing patterns and is optional with a sensible default.

Type of Change

New feature

Testing

• I ran hatch run prepare
• All 982 existing tests continue to pass
• 5 new unit tests added covering:
  • Default tools is []
  • Tools parameter is stored correctly
  • None becomes []
  • Tools are passed through to the internal Agent
  • Default simulator passes empty list to Agent

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ybdarrenwang]

👍