docs/api/tools.md

Tools API Reference

This page documents the API for DeepCritical search tools.

SearchTool Protocol

All tools implement the SearchTool protocol:

class SearchTool(Protocol):
    @property
    def name(self) -> str: ...
    
    async def search(
        self, 
        query: str, 
        max_results: int = 10
    ) -> list[Evidence]: ...

PubMedTool

Module: src.tools.pubmed

Purpose: Search peer-reviewed biomedical literature from PubMed.

Properties

name

@property
def name(self) -> str

Returns tool name: "pubmed"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches PubMed for articles.

Parameters:

• query: Search query string
• max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with PubMed articles.

Raises:

• SearchError: If search fails
• RateLimitError: If rate limit is exceeded

ClinicalTrialsTool

Module: src.tools.clinicaltrials

Purpose: Search ClinicalTrials.gov for interventional studies.

Properties

name

@property
def name(self) -> str

Returns tool name: "clinicaltrials"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches ClinicalTrials.gov for trials.

Parameters:

• query: Search query string
• max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with clinical trials.

Note: Only returns interventional studies with status: COMPLETED, ACTIVE_NOT_RECRUITING, RECRUITING, ENROLLING_BY_INVITATION

Raises:

• SearchError: If search fails

EuropePMCTool

Module: src.tools.europepmc

Purpose: Search Europe PMC for preprints and peer-reviewed articles.

Properties

name

@property
def name(self) -> str

Returns tool name: "europepmc"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches Europe PMC for articles and preprints.

Parameters:

• query: Search query string
• max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with articles/preprints.

Note: Includes both preprints (marked with [PREPRINT - Not peer-reviewed]) and peer-reviewed articles.

Raises:

• SearchError: If search fails

RAGTool

Module: src.tools.rag_tool

Purpose: Semantic search within collected evidence.

Properties

name

@property
def name(self) -> str

Returns tool name: "rag"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches collected evidence using semantic similarity.

Parameters:

• query: Search query string
• max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects from collected evidence.

Note: Requires evidence to be ingested into RAG service first.

SearchHandler

Module: src.tools.search_handler

Purpose: Orchestrates parallel searches across multiple tools.

Methods

search

async def search(
    self,
    query: str,
    tools: list[SearchTool] | None = None,
    max_results_per_tool: int = 10
) -> SearchResult

Searches multiple tools in parallel.

Parameters:

• query: Search query string
• tools: List of tools to use (default: all available tools)
• max_results_per_tool: Maximum results per tool (default: 10)

Returns: SearchResult with:

• evidence: Aggregated list of evidence
• tool_results: Results per tool
• total_count: Total number of results

Note: Uses asyncio.gather() for parallel execution. Handles tool failures gracefully.

See Also

• Architecture - Tools - Architecture overview
• Models API - Data models used by tools