1# Web Search Tool
2 
3## Purpose
4 
5Search the web for relevant information on a given topic. Returns structured results with snippets, URLs, and metadata.
6 
7## Tool Definition
8 
9```typescript
10import { tool } from "ai";
11import { z } from "zod";
12 
13export const webSearch = tool({
14  description: `Search the web for information on a topic.
15Returns relevant results with snippets and URLs.
16Use for gathering current information, verifying facts, or research.`,
17 
18  parameters: z.object({
19    query: z.string()
20      .describe("Search query - be specific for better results"),
21    
22    maxResults: z.number().min(1).max(20).default(10)
23      .describe("Maximum number of results to return"),
24    
25    filters: z.object({
26      dateRange: z.enum(["day", "week", "month", "year", "any"]).default("any")
27        .describe("Limit results to a time period"),
28      
29      sourceType: z.enum(["all", "news", "academic", "documentation"]).default("all")
30        .describe("Type of sources to prioritize"),
31      
32      excludeDomains: z.array(z.string()).optional()
33        .describe("Domains to exclude from results")
34    }).optional()
35  }),
36 
37  execute: async (input) => {
38    return performWebSearch(input);
39  }
40});
41```
42 
43## Input Schema
44 
45| Field | Type | Required | Description |
46|-------|------|----------|-------------|
47| query | string | Yes | Search query |
48| maxResults | number | No | Max results (default: 10) |
49| filters.dateRange | enum | No | Time period filter |
50| filters.sourceType | enum | No | Source type priority |
51| filters.excludeDomains | string[] | No | Domains to exclude |
52 
53## Output Schema
54 
55```typescript
56interface WebSearchResult {
57  success: boolean;
58  
59  results: {
60    title: string;
61    url: string;
62    snippet: string;
63    source: string;      // Domain name
64    publishedDate?: string;
65    relevanceScore: number;
66  }[];
67  
68  totalResults: number;
69  
70  metadata: {
71    query: string;
72    searchTimeMs: number;
73    filtersApplied: string[];
74  };
75}
76```
77 
78## Usage Example
79 
80```typescript
81const results = await webSearch.execute({
82  query: "LLM-as-a-Judge evaluation methods 2024",
83  maxResults: 10,
84  filters: {
85    dateRange: "year",
86    sourceType: "academic"
87  }
88});
89 
90// Result:
91// {
92//   success: true,
93//   results: [
94//     {
95//       title: "Judging LLM-as-a-Judge with MT-Bench",
96//       url: "https://arxiv.org/abs/...",
97//       snippet: "We study the effectiveness of LLM-as-a-Judge...",
98//       source: "arxiv.org",
99//       publishedDate: "2024-01-15",
100//       relevanceScore: 0.95
101//     },
102//     ...
103//   ],
104//   totalResults: 10,
105//   metadata: {
106//     query: "LLM-as-a-Judge evaluation methods 2024",
107//     searchTimeMs: 342,
108//     filtersApplied: ["dateRange:year", "sourceType:academic"]
109//   }
110// }
111```
112 
113## Query Optimization Tips
114 
1151. **Specific Terms**: Use precise terminology
1162. **Quotes**: Use quotes for exact phrases
1173. **Operators**: Support site:, -term, OR
1184. **Context**: Include relevant context terms
1195. **Recency**: Add year for recent info
120 
121## Implementation Notes
122 
1231. **Rate Limiting**: Implement appropriate rate limits
1242. **Caching**: Cache results for repeated queries
1253. **Result Quality**: Filter out low-quality sources
1264. **Error Handling**: Handle API failures gracefully
1275. **Privacy**: Log queries appropriately
128 
129