Better Tavily Search

Use Tavily when the task needs fresh external evidence, links, current facts, official documentation, or source discovery.

This skill is not a rigid search policy.
The model should still plan.
Use Tavily's controls to express that plan more precisely:

• - choose the right query
• choose the right profile
• keep the first pass small
• escalate only when the first pass is insufficient

Core Idea

Prefer evidence-first retrieval over answer-first retrieval.

Default pattern:

1. 1. Run a small Tavily search with an intent-aligned profile.
2. Inspect titles, URLs, domains, snippets, dates, and scores.
3. Rewrite the query or refine Tavily parameters if the first pass is weak.
4. Extract content from the best 1–3 URLs only when more detail is needed.
5. Use site mapping only for documentation or site-navigation tasks.

Do not start with large raw-content payloads unless the task clearly requires them.

Requirements

Authentication is loaded by the script itself.
Either of these is valid:

• - environment variable: INLINECODE0
• INLINECODE1 containing INLINECODE2

The skill metadata only requires python3, because the script can load the API key from either location.

Quick Start

CODEBLOCK0

Working Principles

• - Keep search queries compact, entity-heavy, and task-specific.
• Keep the first pass small: usually max_results=3..5.
• Prefer explicit parameters over broad, vague prompting.
• Use Tavily-native knobs to match intent instead of stuffing instructions into the query.
• Default to --include-answer off and let downstream reasoning synthesize the answer.
• Default to --include-raw-content off on the first pass.
• Prefer search -> extract over search + huge raw content.
• Use --auto-parameters only as a recovery step or when the intent is genuinely ambiguous.

Intent Profiles

Think in profiles, not in a flat list of low-level flags.
Choose the smallest profile that matches the task.

general

Default shape:

• - INLINECODE11
• INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15

news

Default shape:

• - INLINECODE17
• add time_range or start_date/end_date when the time window matters
• start with INLINECODE20

finance

Default shape:

• - INLINECODE22
• start with INLINECODE23
• add time_range or domain filters if needed

official

Default shape:

• - INLINECODE26
• use INLINECODE27
• keep max_results small
• escalate to advanced only if the first pass is noisy

precision

Default shape:

• - use quoted strings when appropriate
• consider INLINECODE31
• use INLINECODE32
• set INLINECODE33

regional

Default shape:

• - add INLINECODE35
• combine with general, news, or finance intent as needed

Query Planning

Plan the query at the semantic level, then let Tavily do the retrieval work.

Good first-pass queries usually have these properties:

• - one main information goal
• the main entities named explicitly
• little or no conversational filler
• no unnecessary formatting instructions
• optional date or source constraints only when they help retrieval

Prefer:

• - INLINECODE39
• INLINECODE40
• INLINECODE41

Avoid:

• - long essay prompts
• combining many unrelated asks in one query
• asking Tavily to already write the final answer inside the query

For detailed rewrite patterns, read:

• - INLINECODE42

Command Surface

The implementation lives at:

• - INLINECODE43

Search

CODEBLOCK1

Main flags:

• - INLINECODE44
• INLINECODE45
• INLINECODE46
• INLINECODE47
• INLINECODE48 or exact INLINECODE49
• INLINECODE50
• INLINECODE51
• INLINECODE52
• INLINECODE53
• INLINECODE54
• INLINECODE55
• INLINECODE56
• INLINECODE57
• INLINECODE58
• INLINECODE59
• INLINECODE60

Extract

CODEBLOCK2

Main flags:

• - --query ... for reranking extracted chunks
• INLINECODE62
• INLINECODE63
• INLINECODE64
• INLINECODE65
• INLINECODE66
• INLINECODE67
• INLINECODE68

Map

CODEBLOCK3

Main flags:

• - INLINECODE69
• INLINECODE70
• INLINECODE71
• INLINECODE72
• INLINECODE73
• INLINECODE74
• INLINECODE75
• INLINECODE76
• INLINECODE77 / --no-allow-external (default is to exclude external links)
• INLINECODE79
• INLINECODE80

For exact flag behavior, run --help on the relevant subcommand.

Escalation Ladder

Use the lightest step that can solve the task.

Step 1 — Small search

Step 2 — Rewrite the query

Step 3 — Refine parameters

• - INLINECODE83
• INLINECODE84 or INLINECODE85
• INLINECODE86 / INLINECODE87
• INLINECODE88
• INLINECODE89
• INLINECODE90
• INLINECODE91

Step 4 — Extract top URLs

Step 5 — Map then extract

Step 6 — Stop escalating

For the detailed decision tree, read:

• - INLINECODE94

Output Philosophy

Expose a stable shape to the model while preserving Tavily signals that help planning.

Preferred default output is agent, which preserves:

• - the original query
• the executed query and parameters
• the selected profile
• source domain
• score when available
• snippet or extracted content chunks
• usage metadata when available
• response time and request identifiers when available

Use raw when you need the closest representation of Tavily's response.
Use md for human inspection.
Use brave only when a downstream consumer expects a Brave-like result shape.

For the detailed schema, read:

• - INLINECODE99
• INLINECODE100

When Not to Use This Skill

Do not use this skill when:

• - the answer is fully contained in local files or already-open documents
• the task is pure writing or transformation with no need for external sources
• a specialized tool already exists for the target system
• the task is a large, asynchronous research workflow better handled by Tavily Research or another research-specific workflow

Notes for the Implementer

This wrapper should reflect Tavily's design, not fight it.
Expose the parameters that matter for model planning, but still protect context size and credit usage with conservative defaults and stable output contracts.