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

[Ju-usc]

Description

Adds tool description optimization capability to GEPA optimizer for multi-agent systems.

When optimize_tool_descriptions=True, GEPA now:

1. Extracts tool descriptions from all nested modules (via named_sub_modules())
2. Includes them in the optimization process alongside signature instructions
3. Returns optimized system with improved tool descriptions

This enables holistic optimization where both agent reasoning (signatures) and tool usage (descriptions) are improved based on end-to-end execution traces.

Issue

Closes #8706

Changes

• Add optimize_tool_descriptions parameter to GEPA (default False)
• Extract tool descriptions using named_sub_modules() traversal in compile()
• Apply optimized descriptions in DspyAdapter.build_program()
• Add 4 comprehensive tests covering single-agent and multi-agent scenarios

Usage Example

import dspy

# Create multi-agent system
class ResearchAssistant(dspy.Module):
    def __init__(self):
        super().__init__()
        search_tool = dspy.Tool(search_fn, name="search", desc="Searches web")
        self.researcher = dspy.ReAct("query -> findings", tools=[search_tool])
        
        def delegate_research(query):
            return self.researcher(query=query).findings
        
        research_tool = dspy.Tool(delegate_research, name="research", desc="Research things")
        calc_tool = dspy.Tool(calc_fn, name="calculator", desc="Does math")
        self.assistant = dspy.ReAct("question -> answer", tools=[research_tool, calc_tool])

# Enable tool optimization
optimizer = dspy.GEPA(
    metric=my_metric,
    reflection_lm=lm,
    auto="light",
    optimize_tool_descriptions=True,  # ← Enable tool optimization
)

# Optimizes ALL tools (calculator, research, search) holistically
optimized = optimizer.compile(ResearchAssistant(), trainset=train, valset=val)

Backward Compatibility

✅ Fully backward compatible - default optimize_tool_descriptions=False

Tests

• All 16 tests pass (4 new + 12 existing GEPA tests)
• Tests cover: adapter functionality, single-agent, multi-agent nested discovery, end-to-end optimization

[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]

still working on nested agent test, doc refine, and tutorial

[LakshyAAAgrawal]

Does dspy.Tool not work with any other components than dspy.React?

[LakshyAAAgrawal]

I suppose what you have built is truly general. We should be easily able to extend this to issues like #8962 (not suggesting we need to do it right here in this PR, but just trying to future proof!)

[Ju-usc]

I do agree that the right direction is to make the system extendable to other component types beyond dspy.ReAct and to handle cases like #8962.

GEPA should automatically detect all modules in a program and optimize them based on how each module is structured for example:

• a ReAct module → predictor, extractor, and tools
• other modules → their own configurable predictors or tool sets.

Conceptually, we can reduce everything to two fundamental abstractions that cover most applications:

1. Instruction — directive text that tells the model what to do (system prompt)
   example: signature docstrings (signature.instruction)

2. Description — descriptive text that tells the model what something is (data model metadata)
   example: signature field descriptions, tool descriptions, argument descriptions

Do instruction and description seem like the right foundational abstractions for generalizing optimization across modules (beyond dspy.ReAct)?

[LakshyAAAgrawal]

Has your experience been that generating improved version of all components (2 prompts + N tool descriptions) at once has been good?

[Ju-usc]

Did some experiments- here's the gist with baseline/optimized prompts:
https://gist.github.com/Ju-usc/0298732be01123486c831d8f210abd36

Used nested ReAct (lead agent → subagent → web search) with 10 BrowseComp examples. GEPA updated both modules + tool descriptions together and the optimized prompts look pretty interesting although it didn't improve much due to simple setup.

Would love to hear your thoughts or feedback!