feat(gepa): add tool description optimization for multi-agent systems

[Ju-usc]

Summary

Addresses #8706 which requested GEPA to optimize tool descriptions.

When enable_tool_optimization=True, GEPA jointly optimizes:

• ReAct modules: react instructions, extract instructions, tool descriptions, and tool argument descriptions
• Generic tool-using predictors: predictor instructions, tool descriptions, and tool argument descriptions

All components are optimized together based on shared execution traces, enabling the reflection LM to see how components work together.

Backward compatible - enable_tool_optimization=False (default) preserves existing behavior.

Issue

Closes #8706

Changes

Core Implementation

• enable_tool_optimization parameter on GEPA (default False)
• Type-based detection: Identifies tool-using predictors via signature field annotations (dspy.Tool, list[dspy.Tool], dict[str, Tool])
• Trace-based tool extraction: Discovers actual tools used at runtime from execution traces
• ToolModuleProposer: Specialized proposer with dynamic signature generation for each tool and argument
• ReAct handling: Discovers ReAct modules via isinstance() check, includes both react and extract predictors
• Routing: Tool-using modules → ToolModuleProposer; regular predictors → default/custom proposer
• Serialization: Tool modules stored as JSON configs with predictor instructions and tool schemas
• Application: Applies optimized descriptions to dspy.Tool objects by matching tool.name

Testing

9 tests covering:

• Single/multiple tool detection in custom modules
• Skip predictors without tool annotations
• Apply optimized tool descriptions via build_program
• ReAct module detection (single, multiple, nested)
• Apply optimized ReAct descriptions
• Selective optimization when LM returns None

Documentation

• GEPA_Advanced.md - Tool optimization guide with usage examples
• overview.md - Brief introduction linking to advanced guide

Usage Example

ReAct Agent

import dspy

def search_web(query: str) -> str:
    return f"Search results for: {query}"

search_tool = dspy.Tool(search_web, name="search_web", desc="Search the web")

agent = dspy.ReAct("question -> answer", tools=[search_tool])

gepa = dspy.GEPA(
    metric=my_metric,
    reflection_lm=dspy.LM("openai/gpt-4o-mini"),
    enable_tool_optimization=True,
    auto="medium"
)

optimized = gepa.compile(agent, trainset=trainset, valset=valset)

Custom Tool-Using Predictor

import dspy

class AgentSignature(dspy.Signature):
    query: str = dspy.InputField()
    tools: list[dspy.Tool] = dspy.InputField()
    answer: str = dspy.OutputField()

class Agent(dspy.Module):
    def __init__(self):
        super().__init__()
        self.tools = [dspy.Tool(search_web, name="search", desc="Search tool")]
        self.pred = dspy.Predict(AgentSignature)

    def forward(self, query):
        return self.pred(query=query, tools=self.tools)

gepa = dspy.GEPA(
    metric=my_metric,
    reflection_lm=dspy.LM("openai/gpt-4o-mini"),
    enable_tool_optimization=True,
    auto="medium"
)

optimized = gepa.compile(Agent(), trainset=trainset, valset=valset)

Key Features

• Joint Optimization: Predictor instructions and tool descriptions optimized together
• Selective Updates: LM returns None for unchanged components
• Multi-Agent Support: Discovers nested ReAct modules and tool-using predictors

[Ju-usc]

Apologies for accidentally closing #8927

Thank you for the thorough review, @LakshyAAAgrawal! I'll address your feedback:

1. Since tools are categorically different from prompts, they should use a different reflection meta prompt. The default reflection meta prompt is shown here https://dspy.ai/api/optimizers/GEPA/GEPA_Advanced/#default-implementation, whereas I assume that the tool must use somewhat different meta prompt. Can you implement a propose_new_texts method that mimics the default_proposer shown in the link above for all prompts, but calls to a tool description specific prompt/signature for tool evolution.
2. Can you also add some description to the documentation, explaining that this feature is beneficial for React agents.
3. (This is not a requirement to merge the PR) Would it be possible to add a simple and short tutorial demonstrating the use and performance improvement via tool evolution?

I'll start working on items 1 and 2 and update the PR soon. Please let me know if you have any specific preferences for the tutorial format!

[LakshyAAAgrawal]

Thanks a lot! For the tutorial, I think you can follow the current GEPA tutorial format (load a dataset, show an example from the dataset, build a dspy program, evaluate the baseline program on testset, run GEPA with new optimization settings, show the optimized programs' prompts and tool descriptions, and finally evaluate the optimized program).

Hopefully we should be able to see a nice and large gain on agentic tasks with this amazing contribution by you!

[Ju-usc]

Hi @LakshyAAAgrawal,

I've implemented the tool-specific proposer as requested! Here's what's included:

1. Tool-Specific Proposer Implementation ✅

• Added GenerateImprovedToolDescriptionFromFeedback signature with a specialized reflection prompt
• Implemented ToolProposer and SingleComponentToolProposer following the MultiModalInstructionProposer pattern
• Routing logic in DspyAdapter that directs tools to ToolProposer and signatures to custom/default proposers
• Fully backward compatible with existing custom instruction proposers

2. Documentation ✅

• Added comprehensive section to GEPA_Advanced.md
• Explains when to use tool optimization (ReAct agents, multi-agent systems)
• Includes usage examples for both simple and nested agent architectures
• Documents how to inspect optimized tool descriptions

Reflection Prompt Design:
The tool-specific prompt is intentionally open-ended to avoid prescriptive patterns that might lead to local minima. It asks the LM to identify patterns in successful/unsuccessful tool usage and extract domain-specific information, without suggesting specific heuristics.

Before I create a short tutorial (item #3), would you have any feedback on:

• The reflection prompt design - is it general enough? Any improvements you'd suggest?
• The implementation approach - does the routing logic make sense?
• The documentation - anything unclear or missing?

Any feedback would be helpful before I invest time in the tutorial. Thank you!

[Ju-usc]

wait there is a bug in the implementation working on it to fix. Also test has to be fixed.

[LakshyAAAgrawal]

which tool to use, when to use it, and how to use it. All three are captured by the description.

[LakshyAAAgrawal]

Let's avoid the word "fundamentally". One can imagine that all of tool descriptions can (and many times do) simply included in the system prompt itself.

[LakshyAAAgrawal]

Please also add a corresponding entry in GEPA Overview, that links to this file/section.

[LakshyAAAgrawal]

One should consider using this, when they use dspy.Tool anywhere in the DSPy program. Here are a few scenarios for using dspy.Tool:

[LakshyAAAgrawal]

I don't think we need to inform users about backward compatibility here. It should be implicit that there should be no behaviour changes for any program not containing dspy.Tool.

[LakshyAAAgrawal]

Add a link to GEPA Advanced/Tool section

[LakshyAAAgrawal]

Edge case: What should happen when user tries to provide both a custom proposer, and enables optimize_tool_descriptions

[LakshyAAAgrawal]

This is a slight deviation from this PR, but would be a large enhancement (feel free to ignore):

1. Create 2 fields, self.instruction_proposal_signature and self.tool_proposer, which are initialized to the default InstructionProposalSignature and ToolProposerSignature.
2. Take an argument from dspy.GEPA that can override the default signature values.

[LakshyAAAgrawal]

Is this robust? Might it be better to use isinstance or some other way?

[LakshyAAAgrawal]

Tool use. Also suggest identifying any failure modes of the tool?

[LakshyAAAgrawal]

Dear @Ju-usc,

This is a great PR. Thanks a lot! I have tried to be overly critical and made too many nits. Feel free to ignore if you disagree with something. Let me know if you'd like me to address anything!

Regarding the meta prompt, overall I think it looks great. However, I suggest that as you build the tutorial, you may find that the reflection prompt needs tweaking, or the content exposed in reflective_dataset for the tool may be lacking or need improvement. This is going to be an empirical exercise, which will guide what works in the reflection meta prompts. ! Looking forward to the tutorial on this too!

You may already have thoughts about what you'd like to show in the tutorial, but if not, you may consider building off (https://kargarisaac.medium.com/building-and-optimizing-multi-agent-rag-systems-with-dspy-and-gepa-2b88b5838ce2) by @kargarisaac.

[Ju-usc]

@LakshyAAAgrawal @chenmoneygithub

Thanks again for the thoughtful feedback — I've pushed toward as generic as safely possible while preserving ReAct behavior.

Core idea: Optimize tools jointly with the predictor that uses them.

For generic tool modules, I detect predictors with dspy.Tool in their signature at compile time, then discover actual tools from traces at runtime. For ReAct, we know tools statically from module.tools. Both share the same ToolModuleProposer and update path — the only difference is when tools are discovered.

Here are my thoughts on a few design choices. Feel free to comment on these or anything else:

1. Prefix-based grouping (react_module: / tool_module:) — I encode module type in string keys to preserve GEPA's dict[str, str] interface. A bit hacky, but avoids changing the core adapter API.

2. ReAct tracing uses extract only — The extract predictor's trace already contains the full trajectory, so this avoids the duplicated-prefix issue from Reflective dataset contains potentially redundant data for ReAct agent gepa-ai/gepa#97.

3. No separate tool tracing yet — Reflective dataset uses predictor-level traces only. Tool inputs are always captured (since dspy.Tool objects flow through predictor inputs), but tool outputs depend on how users design their module. If users need tool outputs in the reflective dataset, they can wire them back into a predictor. Is this enough for now, or should tool calls go into dspy.settings.trace?

4. ReAct still has special handling — Because it has 2 predictors (react + extract) that need joint optimization. Is this acceptable given the maintenance blackhole concern, or should I push for fully generic?

Ran an experiment with nested ReAct + custom tool module: https://gist.github.com/Ju-usc/80b9918fe07288204579df735e084cb4

Happy to iterate!

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Potential IndexError if predictor_keys is empty. Add validation to ensure at least one predictor key exists before accessing index 0. Consider: if not predictor_keys: logger.warning(...); continue or raising a more descriptive error.

Suggested change

	predictor_keys = [k for k, v in current_module_config.items() if isinstance(v, str)]
	predictor_keys = [k for k, v in current_module_config.items() if isinstance(v, str)]
	if not predictor_keys:
	logger.warning(f"No predictor keys found for module '{module_key}'. Skipping.")
	continue

[Ju-usc]

I don't think this is needed - config is built internally by GEPA and always contains predictor keys. Edge case seems impossible.

[Copilot]

Mutating the input data structure. tool_info is a reference to a dict in current_tools_dict (from line 460), so modifications on lines 464 and 470 mutate the original candidate data. This can cause unintended side effects across GEPA iterations. Create a deep copy: import copy and tool_info = copy.deepcopy(tool_info) after line 460.

[Ju-usc]

I don't think this is an issue - candidate[module_key] is a json string, so json.loads() creates a new dict. Mutations don't affect the original.