Component Tool Naming: Comparing Prefix-Based, Parameter-Based and other Approaches

[akihikokuroda]

Description:

This discussion captures the design conversation from Issue #95 (#95) and PR #1432 (#1432) about how to handle tool naming when multiple components define tools with identical names.

Background

When a template includes multiple components with the same tool name (e.g., two search() functions), we need a strategy to avoid naming collisions. Currently, only the last tool survives in the tools dictionary, breaking the ability to call tools from earlier components.

Proposed Approaches

1. Prefix-Based (Current PR feat: add prefix to component tool names #1432)

• Prefix tool names with component ID: component_a1b2c3d4.search
• Stable across multi-turn interactions (same component = same ID)
• Trade-off: Slightly longer tool names (~10 more chars per tool, ~0.05% token increase)

2. Parameter-Based Alternative

• Keep tool names natural: search
• Add component_id as a required parameter
• More concise in token usage
• Challenge: How do we ensure the LLM can differentiate between multiple search tools?

3. List-Based Structure

• Change internal tools from dict[str, Tool] to list[tuple[str, Tool]]
• Preserves all tools naturally without prefixes
• Larger refactor (affects backends, tool extraction, JSON schema generation)

Open Questions

1. Model Behavior: Can the model reliably track and call the same prefixed tool multiple times with different component IDs? Do we need system prompt guidance?
2. Observability: How do we correlate prefixed tool calls back to their source component in telemetry and error messages?
3. Performance: What benchmarks/evaluations would validate that the chosen approach works across varied scenarios (many components, identical tool names, multi-turn interactions)?
4. API Stability: If we move to list-based or parameter-based routing, how do we minimize breaks to existing code that expects the tools dict?

Context

• PR feat: add prefix to component tool names #1432 Comment Thread (feat: add prefix to component tool names #1432) — Full design discussion with concerns about long-term resilience
• PR feat(telemetry): emit execute_tool spans for tool calls #1430 (feat(telemetry): emit execute_tool spans for tool calls #1430) — Related work on tool_call_id for tracing
• Metadata Proposal (feat: add prefix to component tool names #1432 (comment)) — Storing component metadata on TemplateRepresentation for observability

Next Steps

We'd like community input on:

1. Which approach feels most maintainable long-term?
2. What data/benchmarks would convince us a choice is solid?
3. Are there alternative strategies we haven't considered?

---

This framing captures the core design tension, the multiple options explored, and the genuine uncertainty about which path is best for Mellea's long-term architecture.

[ajbozarth]

Reading through both the draft PR and this outline I have a question: are we distinguishing properly between the Tool object and the ToolCall object? (ie the tool object itself and the object that represents one call to the tool?

[akihikokuroda]

I believe so. This discussion focus on the Tool objects that are sent to the model. The Tool object must be recognized / distinguished by the model and the model generates the ToolCall response if it wants execute the tool. Tool object has an associated tool schema including a function name, descriptions and argument information.

The model generates the ToolCall object when it needs to execute a tool. It uses the function name to specify the tool to be executed so the function name must be unique.

[ajbozarth]

It uses the function name to specify the tool to be executed so the function name must be unique.

In this case I'd argue that instead of adding an id to it we should just prevent duplicate tool names when adding tools

[ajbozarth]

see this comment part 1 #1457 (comment)