WEB_SEARCH_TOOL_ASSESSMENT.md

Web Search Tool Assessment

Executive Summary

The application has two separate web search implementations with different readiness levels:

1. WebSearchTool (src/tools/web_search.py) - Partially Ready ⚠️

   • Functional but NOT compliant with SearchTool protocol
   • NOT integrated into main search handler
   • Only used in magentic orchestrator's retrieval agent

2. web_search_adapter (src/tools/web_search_adapter.py) - Functional ✅

   • Used by tool executor for WebSearchAgent tasks
   • Relies on legacy folder/tools/web_search.py implementation

Detailed Analysis

1. WebSearchTool (src/tools/web_search.py)

Current Implementation

• Location: src/tools/web_search.py
• Provider: DuckDuckGo (no API key required)
• Status: ⚠️ Partially Ready

Issues Identified

❌ Protocol Non-Compliance:

# Missing required 'name' property
class WebSearchTool:
    # Should have: @property def name(self) -> str: return "web"
    
    # Wrong return type - should return list[Evidence], not SearchResult
    async def search(self, query: str, max_results: int = 10) -> SearchResult:
        # Returns SearchResult instead of list[Evidence]

Comparison with other tools:

• PubMedTool has @property def name(self) -> str: return "pubmed"
• PubMedTool.search() returns list[Evidence]
• WebSearchTool returns SearchResult (contains evidence list inside)

❌ Not Integrated:

• NOT included in SearchHandler initialization in src/app.py:

  search_handler = SearchHandler(
      tools=[PubMedTool(), ClinicalTrialsTool(), EuropePMCTool()],
      # WebSearchTool() is missing!
  )
  

✅ Current Usage:

• Used in src/agents/retrieval_agent.py (magentic orchestrator):

  from src.tools.web_search import WebSearchTool
  _web_search = WebSearchTool()
  

Fix Required

To make WebSearchTool compliant and usable:

1. Add name property:

   @property
   def name(self) -> str:
       return "web"
   

2. Fix return type:

   async def search(self, query: str, max_results: int = 10) -> list[Evidence]:
       # ... existing code ...
       return evidence  # Return list[Evidence] directly, not SearchResult
   

3. Register in SearchHandler:

   from src.tools.web_search import WebSearchTool
   
   search_handler = SearchHandler(
       tools=[
           PubMedTool(), 
           ClinicalTrialsTool(), 
           EuropePMCTool(),
           WebSearchTool()  # Add this
       ],
   )
   

---

2. web_search_adapter (src/tools/web_search_adapter.py)

Current Implementation

• Location: src/tools/web_search_adapter.py
• Status: ✅ Functional
• Provider: Uses legacy folder/tools/web_search.py (Serper/SearchXNG)

Usage

• Used by src/tools/tool_executor.py for WebSearchAgent tasks:

  if task.agent == "WebSearchAgent":
      result_text = await web_search(task.query)
  

• Used by src/orchestrator/planner_agent.py for background context

Dependencies

• Requires folder/tools/web_search.py (legacy implementation)
• Supports Serper API (requires SERPER_API_KEY)
• Supports SearchXNG API (requires SEARCHXNG_HOST)

Limitations

• Returns formatted string (not Evidence objects)
• Not integrated with SearchHandler (different execution path)
• Depends on legacy folder structure

---

Integration Status

SearchHandler Integration

Current State: ❌ NOT Integrated

The main SearchHandler in src/app.py only includes:

• PubMedTool()
• ClinicalTrialsTool()
• EuropePMCTool()

WebSearchTool is missing from the main search flow.

Tool Executor Integration

Current State: ✅ Integrated

web_search_adapter is used via tool_executor.py:

• Executes when AgentTask.agent == "WebSearchAgent"
• Used in iterative/deep research flows
• Returns formatted text (not Evidence objects)

Magentic Orchestrator Integration

Current State: ✅ Integrated

WebSearchTool is used in retrieval_agent.py:

• Direct instantiation: _web_search = WebSearchTool()
• Used via search_web() function
• Updates workflow state with evidence

---

Can It Be Used?

WebSearchTool (src/tools/web_search.py)

Status: ⚠️ Can be used, but with limitations

Can be used:

• ✅ In magentic orchestrator (already working)
• ✅ As standalone tool (functional)

Cannot be used:

• ❌ In SearchHandler (protocol non-compliance)
• ❌ In parallel search flows (not registered)

To make fully usable:

1. Fix protocol compliance (add name, fix return type)
2. Register in SearchHandler
3. Test integration

web_search_adapter

Status: ✅ Can be used

Can be used:

• ✅ Via tool_executor for WebSearchAgent tasks
• ✅ In planner agent for background context
• ✅ In iterative/deep research flows

Limitations:

• Returns string format (not Evidence objects)
• Requires legacy folder dependencies
• Different execution path than SearchHandler

---

Recommendations

Priority 1: Fix WebSearchTool Protocol Compliance

Make WebSearchTool fully compliant with SearchTool protocol:

1. Add name property
2. Change return type from SearchResult to list[Evidence]
3. Update all callers if needed

Priority 2: Integrate into SearchHandler

Add WebSearchTool to main search flow:

from src.tools.web_search import WebSearchTool

search_handler = SearchHandler(
    tools=[
        PubMedTool(), 
        ClinicalTrialsTool(), 
        EuropePMCTool(),
        WebSearchTool()  # Add web search
    ],
)

Priority 3: Consolidate Implementations

Consider consolidating the two implementations:

• Keep WebSearchTool as the main implementation
• Deprecate or migrate web_search_adapter usage
• Remove dependency on folder/tools/web_search.py

Priority 4: Testing

Add tests for:

• Protocol compliance
• SearchHandler integration
• Error handling
• Rate limiting (if needed)

---

Summary Table

Component	Status	Protocol Compliant	Integrated	Can Be Used
WebSearchTool	⚠️ Partial	❌ No	❌ No	⚠️ Limited
web_search_adapter	✅ Functional	N/A	✅ Yes (tool_executor)	✅ Yes

---

Conclusion

The web search functionality exists in two forms:

1. WebSearchTool is functional but needs protocol fixes to be fully integrated
2. web_search_adapter is working but uses a different execution path

Recommendation: Fix WebSearchTool protocol compliance and integrate it into SearchHandler for unified search capabilities across all orchestrators.