Skip to main content

Test Tavily Search

Overview​

The admin-test-tavily-search tool validates the Tavily web search integration and returns detailed diagnostic information. Use this tool to test search parameters, inspect result structure, and verify the provider implementation.

Tool ID: admin-test-tavily-search

The examples use the direct runtime/operator route. Replit/Admin UI browser code should call the Admin UI BFF instead: local /admin-api/*, testing /dashboard/admin-api/*.

Input Schema​

{
  query: string;                      // Search query (required, 1-400 chars)
  searchDepth?: 'basic' | 'advanced'; // Search depth (default: 'basic')
  topic?: 'general' | 'news' | 'finance'; // Topic category
  maxResults?: number;                // Max results 1-20 (default: 5)
  includeDomains?: string[];          // Filter to these domains only
  excludeDomains?: string[];          // Exclude these domains
  includeAnswer?: boolean;            // Include AI-generated summary (default: true)
  includeImages?: boolean;            // Include image results (default: false)
  days?: number;                      // Limit to results from N days back
}

Example Usage​

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/test-tavily-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{
    "data": {
      "query": "What is COSO framework?",
      "maxResults": 5,
      "includeAnswer": true
    }
  }'
curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/test-tavily-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{
    "data": {
      "query": "machine learning interpretability",
      "includeDomains": ["arxiv.org", "nature.com"],
      "searchDepth": "advanced",
      "maxResults": 10
    }
  }'
curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/test-tavily-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{
    "data": {
      "query": "AI regulation updates",
      "topic": "news",
      "days": 7,
      "maxResults": 5
    }
  }'
const response = await fetch(`${MASTRA_BASE_URL}/admin/tools/test-tavily-search`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.BEARER_TOKEN}`,
  },
  body: JSON.stringify({
    data: {
      query: 'latest quantum computing breakthroughs',
      searchDepth: 'advanced',
      maxResults: 5,
      includeAnswer: true
    }
  })
});

const result = await response.json();
console.log('AI Summary:', result.answer);
console.log('Found', result.resultCount, 'results in', result.responseTime, 'ms');
result.results.forEach(r => {
  console.log(`\n${r.title} (score: ${r.score})`);
  console.log(r.url);
  console.log(r.content.substring(0, 200) + '...');
});

Output Schema​

{
  success: boolean;                   // Whether search completed
  configured: boolean;                // Whether TAVILY_API_KEY is set
  query: string;                      // Query that was executed
  answer?: string;                    // AI-generated summary
  results: [
    {
      title: string;                  // Result title
      url: string;                    // Source URL
      content: string;                // Content snippet
      score: number;                  // Relevance score (0-1)
      publishedDate?: string;         // Publication date (if available)
    }
  ];
  images?: [                          // Image results (if requested)
    {
      url: string;
      description?: string;
    }
  ];
  followUpQuestions?: string[];       // Suggested follow-up queries
  responseTime: number;               // API response time in ms
  resultCount: number;                // Number of results returned
  parameters: object;                 // Search parameters used
  error?: string;                     // Error message (if failed)
  errorDetails?: any;                 // Detailed error info (if failed)
}

Configuration​

The tool requires the Tavily API key to be configured:

TAVILY_API_KEY=tvly-dev-...

Get your API key from tavily.com (https://tavily.com).

Optional configuration:

TAVILY_DEFAULT_SEARCH_DEPTH=basic
TAVILY_DEFAULT_MAX_RESULTS=5
TAVILY_TIMEOUT_MS=30000
TAVILY_DEBUG_TIMINGS=false

Understanding Results​

Search Depth​

  • basic - Faster, uses cached results when available
  • advanced - More thorough, always fresh results

Relevance Scores​

Results include a score from 0-1 indicating relevance:

  • 0.9-1.0 - Highly relevant, directly answers query
  • 0.7-0.9 - Very relevant, contains key information
  • 0.5-0.7 - Moderately relevant, partial match
  • less than 0.5 - Lower relevance, tangential information

AI Answer​

When includeAnswer: true, Tavily provides an AI-generated summary synthesizing information from all results. This is useful for quick insights without parsing individual results.

Use Cases​

  • Integration Testing: Verify Tavily API connectivity and configuration
  • Query Testing: Test different search parameters and see what results are returned
  • Result Inspection: Understand result structure for downstream processing
  • Performance Monitoring: Track response times and result quality
  • Debugging: Diagnose issues with domain-retrieval in reasoning engine

Reasoning Engine Integration​

This tool tests the same provider used by the reasoning engine's domain-retrieval step:

  1. Domain step receives query from reasoning workflow
  2. Calls quickSearch() from Tavily provider (same function this tool uses)
  3. Extracts knowledge items from results
  4. Passes knowledge to explanation and validation steps

Use this tool to preview what knowledge the reasoning engine will retrieve for a given query.

Troubleshooting​

Error: TAVILY_API_KEY not set

Set the TAVILY_API_KEY environment variable. Get your key from tavily.com.

Error: Rate limit exceeded

Tavily free tier has rate limits. Consider upgrading your plan or reducing request frequency.

Zero results returned

Try: (1) broader query, (2) remove domain filters, (3) use 'basic' depth for cached results, (4) increase maxResults.

Timeout errors

Increase TAVILY_TIMEOUT_MS or try 'basic' depth instead of 'advanced'.