Search

Search web, library docs, and GitHub code using progressive escalation.

Quick Start

Decision Tree:

• Library/framework docs? → Context7 get-library-docs
• Code examples/patterns? → GitHub Grep grep_searchGitHub
• Web info/tutorials? → Tavily tavily_search (fallback chain: Exa → Z.AI webSearchPrime)
• Error screenshot/diagram? → Z.AI Vision diagnose_error_screenshot / understand_technical_diagram
• Multiple sources needed? → Run tools in parallel

Default Workflow:

1. Start simple: search_depth: "basic", maxResults: 5
2. If insufficient: Escalate to Level 2 (expand query, increase results)
3. If repeated problem: Escalate to Level 3 (parallel queries, extraction, crawling)

Agent Roles

If you are the main agent (orchestrator):

• External questions → Fire 3-5 librarian agents in parallel with different angles
• Local codebase patterns → Fire explore in background
• Quick web lookups → Do Tavily yourself (faster than delegation overhead)
• Build confidence → Fire multiple librarians: 2 for docs, 2 for real-world examples, 2 to find edge cases/gotchas
• Collect results with background_output, synthesize, cross-validate

If you are the librarian (subagent):

• You are the WORKHORSE - do NOT be lazy or return minimal results
• Fire 3-5 parallel tool calls depending on request complexity (see TYPE A/B/C/D in your system prompt)
• Vary your queries - different angles, not the same pattern repeated
• Always cite with permalinks - every claim needs [Source](url#L10-L20) format
• Rate your confidence - end with: CONFIDENCE: HIGH/MEDIUM/LOW and why

Subagent Calling Example

// GOOD: Fire multiple librarians with different angles for comprehensive coverage
background_task({
  agent: "librarian",
  prompt: `Find OFFICIAL documentation for Next.js 15 App Router authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - parallel queries, thorough extraction)
FOCUS: Official Next.js and next-auth docs only
TOOLS: Context7 for Next.js, next-auth docs
FORMAT: Use markdown tables for comparisons, code blocks for snippets
OUTPUT: Official recommended approach with doc permalinks
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

background_task({
  agent: "librarian", 
  prompt: `Find REAL-WORLD implementations of Next.js 15 authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - multiple pattern variations, cross-repo)
FOCUS: Production codebases on GitHub
TOOLS: grep_searchGitHub with queries: "getServerSession(", "auth(", language: TypeScript
FORMAT: For each example: repo name, permalink, architecture notes
OUTPUT: 3-5 code examples with GitHub permalinks, note patterns/variations
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

background_task({
  agent: "librarian",
  prompt: `Find EDGE CASES and GOTCHAS for Next.js 15 authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - cross-reference multiple sources)
FOCUS: Issues, discussions, Stack Overflow
TOOLS: zai-zread_search_doc for repo issues/discussions (thorough), tavily_search for blog posts/SO
FORMAT: Problem → Evidence → Solution table
OUTPUT: Common pitfalls, breaking changes, migration issues
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

// Then collect and cross-validate:
// - Do real-world examples match official docs?
// - Are there gotchas the docs don't mention?
// - Synthesize into recommendation with overall confidence

// BAD: No skill loading, no structure
background_task({
  agent: "librarian", 
  prompt: "How does Next.js auth work?"  // Missing FIRST step, no level, no format = lazy results
})

Tools Overview

Tavily (Web Search)

Web Fallback Providers

Context7 (Library Docs)

GitHub Grep (Code Search)

Critical: GitHub Grep searches literal code patterns, not keywords!

• ✅ Good: useState(, getServerSession, (?s)try {.*await
• ❌ Bad: react tutorial, how to authenticate

Z.AI Zread (Semantic GitHub Search)

Use when: Code/keyword search misses context, need discussion threads, searching for "why" not "what".

Z.AI Vision (Visual Content)

Use when: User provides screenshot, error image, architecture diagram, or UI mockup.

GitHub CLI (Repo Search)

# Repository structure
gh api "repos/{owner}/{repo}/git/trees/{branch}?recursive=1"

# Search issues
gh api -X GET search/issues -f q="repo:{owner}/{repo} is:issue {keywords}"

# Read file directly
webfetch("https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}")

Progressive Escalation Levels

Level 1: Simple Search (Default)

When: Quick lookups, straightforward questions, first encounter

1. Tavily: search_depth: "basic", maxResults: 5
2. Context7: mode: "code" for API, mode: "info" for concepts
3. GitHub Grep: literal code patterns with language filter
4. Parallel execution when appropriate

Sufficient? → Done. Insufficient? → Level 2

Level 2: Enhanced Search

When: Initial results incomplete, need more examples, outdated results

1. Expand query: Add synonyms, context (keep <400 chars)
2. Increase: maxResults: 10-15, search_depth: "advanced"
3. Filter domains: include_domains: ["stackoverflow.com", "github.com"]
4. Time filter: time_range: "year" for recent info
5. Two-step extraction: Search → Filter by score (>0.5) → Extract top URLs
6. Discussions/docs gap: Use search_doc or gh api search/issues when keyword/code search misses context

Sufficient? → Done. Insufficient? → Level 3

Level 3: Deep Research

When: Problem encountered 2+ times, complex topic, building knowledge base

1. Parallel queries: 3-5 query variations with synonyms
2. Systematic extraction: Top 5-10 URLs with extract_depth: "advanced"
3. Website exploration: tavily_map → tavily_crawl
4. GitHub deep dive: Multiple pattern variations, regex, cross-repo comparison
5. Cross-reference: Verify across multiple sources

Key Tips (Reminders)

Query Formulation

• 400 char limit - Break complex queries into sub-queries
• Natural language works better - Full sentences > keywords
• Be specific - Include technology, use case, context
• For full guide: See references/query-guide.md

Score-Based Filtering

• Tavily results include score (0-1)
• >0.5 typically good - Adjust based on distribution
• Filter before extracting to save credits

Two-Step Extraction Pattern

1. Search with search_depth: "advanced"
2. Filter URLs by score (>0.5)
3. Extract top 2-5 URLs with extract_depth: "basic"
4. Upgrade to "advanced" only if needed

GitHub Grep Patterns

# API usage
Query: getServerSession
Language: ['TypeScript'], Path: '/api/'

# Multiline with regex
Query: (?s)useEffect\(\(\) => {.*cleanup
useRegexp: true

Cost Optimization

• basic = 1 credit, advanced = 2 credits
• Prefer two-step extraction over include_raw_content: true
• Use tavily_map before tavily_crawl

Quota Management:

• Default to Tavily for important/critical searches (better relevance when quota available)
• If Tavily fails due to quota/rate limit (429), fail over immediately to Exa (no retry)
• For other transient Tavily failures (timeout/5xx), do one jittered retry (~300-800ms)
• Fallback to Exa (websearch_web_search_exa) when Tavily still fails after that retry
• If Exa fails due to quota/rate limit, fail over immediately to Z.AI webSearchPrime (no retry)
• For other transient Exa failures (timeout/5xx), do one jittered retry (~300-800ms), then fail over to Z.AI
• If Exa is empty/low-quality, fallback to Z.AI webSearchPrime
• Don't loop retries across providers; fail over immediately to next provider

For advanced techniques: See references/advanced-techniques.md

Common Patterns

For workflow examples: See references/examples/example-workflows.md

References

• references/reference-parameters.md - Complete parameter reference for all tools
• references/query-guide.md - Query structuring, 400 char limit, expansion strategies
• references/advanced-techniques.md - Two-step extraction, post-processing, cost optimization
• references/examples/example-workflows.md - Practical workflow examples

Output

Search results are used directly in context. No files saved unless requested. For comprehensive research with evidence cards, use the research skill.