# How to Configure Tool Arguments Override in Agent Network Config in Neuro-San Studio

> Learn to configure tool arguments override in Neuro-San Studio by adding a tool_args block to your agent network HOCON file for runtime merging with toolbox defaults.

- Repository: [Cognizant AI Lab/neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**You configure tool arguments override in Neuro-San Studio by adding a `tool_args` block to the tool definition in your agent network HOCON file, which merges with the toolbox defaults at runtime.**

Neuro-San Studio uses HOCON configuration files to define agent networks and their available tools. When you need to customize tool behavior for specific agents without modifying global defaults, you configure tool arguments override in the agent network config files located in the `registries/` directory. This approach allows you to maintain reusable toolbox definitions while tailoring parameters for individual agent interactions.

## Default Tool Arguments in the Toolbox

Before configuring overrides, you must understand how default tool arguments are structured. In the cognizant-ai-lab/neuro-san-studio repository, each tool available to agents is defined in a toolbox HOCON file such as `toolbox/agent_network_designer_toolbox_info.hocon`. These files contain a `tool_args` map that specifies the default parameters passed to the tool during execution.

### Structure of Toolbox tool_args

The toolbox entry defines the tool class and its default arguments:

```hocon
tool {
  name = "search_google"
  class = "cognify.google_search.GoogleSearchTool"
  tool_args = {
    api_key = "YOUR_DEFAULT_KEY"
    num_results = 5
    safe_search = true
  }
}

```

These values serve as the baseline configuration whenever an agent invokes this tool.

## Override Tool Arguments in Agent Network Configurations

To customize tool behavior for a specific agent, you add a `tool_args` block within the tool definition in your network configuration file (e.g., `registries/example_agent_network.hocon`). This enables you to configure tool arguments override in agent network config files without altering the global toolbox definition.

### Adding tool_args to Network HOCON

Reference the tool by name and supply the override values:

```hocon
agents {
  web_assistant {
    tools = [
      {
        name = "search_google"
        tool_args = {
          # Override only the parameter you need

          num_results = 20
        }
      }
    ]
  }
}

```

In this example, `num_results` becomes `20` while `api_key` and `safe_search` retain their default values from the toolbox.

### Merge Behavior and Precedence

During runtime, the framework merges the toolbox defaults with the per-agent overrides using dictionary unpacking. The override values replace defaults, while omitted keys preserve their original values. According to the source code, the merge logic follows this pattern:

```python

# Simplified merge logic from the tool-calling path

override_args = tool_config.get("tool_args", {})
merged_args = {**default_tool_args, **override_args}
await agent_caller.call_agent(tool_args=merged_args, sly_data=sly_data)

```

The resulting argument map passed to the tool at execution time would be:

```json
{
  "api_key": "YOUR_DEFAULT_KEY",
  "num_results": 20,
  "safe_search": true
}

```

## Runtime Implementation in call_agent.py

The actual extraction and forwarding of tool arguments occurs in [`coded_tools/tools/call_agent.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/call_agent.py). Lines 64-73 of this file handle retrieving the `tool_args` from the configuration and passing them to the agent caller:

```python

# coded_tools/tools/call_agent.py

def tool(self, args):
    # ...

    tool_args: Dict[str, Any] = args.get("tool_args")
    if not tool_args:
        raise ValueError("Error: No tool_args provided.")
    # Log the final args (after merge happens later)

    logger.debug("tool_args: %s", tool_args)
    return await agent_caller.call_agent(tool_args=tool_args, sly_data=sly_data)

```

The `agent_caller` (implemented in [`coded_tools/tools/coded_tool_agent_caller.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/coded_tool_agent_caller.py)) receives these arguments and performs the merge with toolbox defaults before invoking the target tool.

## Key Files for Tool Argument Configuration

- **`toolbox/agent_network_designer_toolbox_info.hocon`** — Defines default `tool_args` for each toolbox-provided tool.
- **[`coded_tools/tools/call_agent.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/call_agent.py)** — Extracts `tool_args` from the network spec and forwards them to the agent caller (see lines 64-73).
- **[`coded_tools/tools/coded_tool_agent_caller.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/coded_tool_agent_caller.py)** — Receives the merged `tool_args` and invokes the target tool.
- **`registries/*.hocon`** — Agent network definition files where you place `tool_args` overrides for specific agents.
- **[`plugins/log_bridge/process_log_bridge.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/plugins/log_bridge/process_log_bridge.py)** — Demonstrates a similar pattern for merging configuration dictionaries with overrides.

## Summary

- **Define defaults** in the toolbox HOCON file (`toolbox/agent_network_designer_toolbox_info.hocon`) using the `tool_args` map.
- **Configure overrides** by adding a `tool_args` block to the tool entry in your agent network HOCON file (e.g., `registries/example_agent_network.hocon`).
- **Merge behavior** performs a dictionary update where network-level values replace toolbox defaults, preserving unmodified keys.
- **Runtime processing** occurs in [`coded_tools/tools/call_agent.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/call_agent.py), which extracts arguments and forwards them to [`coded_tool_agent_caller.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tool_agent_caller.py) for execution.

## Frequently Asked Questions

### What file format does Neuro-San Studio use for configurations?

Neuro-San Studio uses HOCON (Human-Optimized Config Object Notation) files for both toolbox definitions and agent network configurations. This format supports comments, object merging, and inheritance patterns that make it ideal for defining hierarchical tool configurations and overrides.

### Can I override multiple tool arguments at once?

Yes. You can override any number of parameters by including them in the `tool_args` block within your agent network configuration. Only the keys you specify will replace the defaults; all other parameters from the toolbox `tool_args` will remain unchanged in the merged dictionary passed to the tool.

### What happens if I don't specify tool_args in the network config?

If you omit the `tool_args` block in the network configuration, the tool will execute using only the default values defined in the toolbox HOCON file. The merge logic defaults to an empty dictionary for overrides, resulting in `{**default_tool_args, **{}}`, which preserves all original defaults.

### Where is the merge logic implemented in the source code?

The merge logic is implemented in the tool-calling path within the Neuro-San Studio framework, specifically in [`coded_tools/tools/call_agent.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/call_agent.py) where arguments are extracted (lines 64-73), and subsequently in [`coded_tools/tools/coded_tool_agent_caller.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/tools/coded_tool_agent_caller.py) where the dictionary merge occurs before invoking the target tool. A similar configuration merging pattern is also demonstrated in [`plugins/log_bridge/process_log_bridge.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/plugins/log_bridge/process_log_bridge.py).