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]

During reflection, routes the components to be modified by the right metaprompt...

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

Hi @LakshyAAAgrawal,

Thanks for the detailed review! I tried my best to address all the critical points, though I may have missed something or introduced new issues. Feel free to add any thoughts! I also have a few questions for you.

Implementation:
Built tool optimization by discovering tools through ReAct modules, creating reflective datasets that share full trajectories with each tool, and routing to a specialized tool proposer. Refactored the string-matching approach you flagged (replaced "react" in name.lower() with proper module traversal). Also streamlined tests and fixed the custom proposer routing to ensure independence.

Documentation:
Added comprehensive docs covering the tool-specific reflection prompt, implementation flow (Pass 1/Pass 2), usage examples with visualization, and design rationale in code comments. Restructured "When to Use" as a numbered list per your feedback and removed implementation details from user-facing sections.

Key design decision: For reflective dataset, we share/deepcopy the complete ReAct trajectory with each tool (not just tool-specific segments) because tools need full context to understand selection patterns and workflow dependencies. This trades token efficiency for richer optimization.

Future work - would love your thoughts:

For reflective dataset for tools, I documented two approaches to reduce token duplication (see code comments for details): joint optimization with ReAct instruction by a separate proposer, or extending the instruction proposer to include tools. The second seems more elegant. What's your take - should we pursue one of these, or is the current approach good enough?

Testing:
The existing tests cover the core functionality, but I'm not sure if they're robust/clean enough. Could you provide guidance on:

• What test scenarios should we add to make this production-ready?
• Any edge cases or failure modes I should be testing for?
• Test structure/organization improvements?

Ready for re-review!