Nimble Web Search

Real-time web intelligence using Nimble Search API with specialized focus modes and AI-powered result synthesis.

Prerequisites

Nimble API Key Required - Get your key at https://www.nimbleway.com/

Configuration

Set the NIMBLE_API_KEY environment variable using your platform's method:

Claude Code:
CODEBLOCK0

VS Code/GitHub Copilot:

• - Add to .github/skills/ directory in your repository
• Or use GitHub Actions secrets for the copilot environment

Shell/Terminal:
CODEBLOCK1

Any Platform:
The skill checks for the NIMBLE_API_KEY environment variable regardless of how you set it.

API Key Validation

IMPORTANT: Before making any search request, verify the API key is configured:

CODEBLOCK2

Overview

Nimble Search provides real-time web intelligence with 8 specialized focus modes optimized for different types of queries. Get instant access to current web data with AI-powered answer generation, deep content extraction, URL discovery, and smart filtering by domain and date.

IMPORTANT: Always Specify These Parameters

When using this skill, always explicitly set the following parameters in your requests:

• - deep_search: Default to false for 5-10x faster responses

• - focus: Default to "general" for broad searches

• - max_results: Default to 10 - Balanced speed and coverage

Performance Awareness: By explicitly setting deep_search: false, you're choosing fast mode and should expect results in 1-3 seconds. If you set deep_search: true, expect 5-15 seconds response time.

Quick Start

Use the wrapper script for the simplest experience:

CODEBLOCK3

The script automatically handles authentication, tracking headers, and output formatting.

When to Use Each Mode

Use deep_search: false (FAST MODE - 1-3 seconds) - Default for 95% of cases:

• - ✅ Finding URLs and discovering resources
• ✅ Research and topic exploration
• ✅ Answer generation and summaries
• ✅ Product comparisons
• ✅ News monitoring
• ✅ Any time you DON'T need full article text

Use deep_search: true (DEEP MODE - 5-15 seconds) - Only when specifically needed:

• - 📄 Archiving full article content
• 📄 Extracting complete documentation
• 📄 Building text datasets
• 📄 Processing full page content for analysis

Decision Rule: If you're not sure, use deep_search: false. You can always re-run with true if needed.

Core Capabilities

Focus Modes

Choose the appropriate focus mode based on your query type:

1. 1. general - Default mode for broad web searches
2. coding - Real-time access to technical documentation, code examples, programming resources
3. news - Real-time news articles, current events, breaking stories
4. academic - Research papers, scholarly articles, academic resources
5. shopping - Real-time product searches, e-commerce results, price comparisons
6. social - Real-time social media posts, discussions, trending community content
7. geo - Location-based searches, geographic information
8. location - Local business searches, place-specific queries

Search Features

LLM Answer Generation

• - Request AI-generated answers synthesized from search results
• Powered by Claude for high-quality summaries
• Include citations to source URLs
• Best for: Research questions, topic overviews, comparative analysis

URL Discovery

• - Extract 1-20 most relevant URLs for a query
• Useful for building reading lists and reference collections
• Returns URLs with titles and descriptions
• Best for: Resource gathering, link building, research preparation

Deep Content Extraction

• - Default (Recommended): deep_search=false - Fastest response, returns titles, descriptions, and URLs
• Optional: deep_search=true - Slower, extracts full page content
• Important: Most use cases work perfectly with deep_search=false (the default)
• Available formats when deepsearch=true: markdown, plaintext, simplified_html
• Only enable deep search for: Detailed content analysis, archiving, or comprehensive text extraction needs

Domain Filtering

• - Include specific domains (e.g., github.com, stackoverflow.com)
• Exclude domains to remove unwanted sources
• Combine multiple domains for focused searches
• Best for: Targeted research, brand monitoring, competitive analysis

Time Filtering

• - Recommended: Use time_range for real-time recency filtering (hour, day, week, month, year)
• Alternative: Use start_date/end_date for precise date ranges (YYYY-MM-DD)
• Note: time_range and date filters are mutually exclusive
• Best for: Real-time news monitoring, recent developments, temporal analysis

Usage Patterns

All examples below use the ./scripts/search.sh wrapper for simplicity. For raw API usage, see the API Integration section.

Basic Search

Quick search in fast mode (ALWAYS specify deep_search explicitly):

CODEBLOCK4

For technical content, specify coding focus (still fast mode):

CODEBLOCK5

Research with AI Summary

Get synthesized insights from multiple sources (fast mode works great with answer generation):

CODEBLOCK6

Domain-Specific Search

Target specific authoritative sources (fast mode):

CODEBLOCK7

Real-Time News Monitoring

Track current events and breaking news as they happen (fast mode):

CODEBLOCK8

Academic Research - Fast Mode (Recommended)

Find and synthesize scholarly content using fast mode:

CODEBLOCK9

When to use deep mode: Only use "deep_search": true if you need full paper content extracted for archiving:

CODEBLOCK10
Note: Deep mode is 5-15x slower. Use only when specifically needed.

Real-Time Shopping Research

Compare products and current prices (fast mode):

CODEBLOCK11

Parallel Search Strategies

When to Use Parallel Searches

Run multiple real-time searches in parallel when:

• - Comparing perspectives: Search the same topic across different focus modes
• Multi-faceted research: Investigate different aspects of a topic simultaneously
• Competitive analysis: Search multiple domains or competitors at once
• Real-time monitoring: Track multiple topics or keywords concurrently
• Cross-validation: Verify information across different source types in real-time

Implementation Methods

Method 1: Background Processes (Recommended)

Run multiple searches concurrently using the wrapper script:

CODEBLOCK12

Method 2: Loop with xargs (Controlled Parallelism)

Process multiple queries with rate limiting:

CODEBLOCK13

Method 3: Focus Mode Comparison

Search the same query across different focus modes:

CODEBLOCK14

Best Practices for Parallel Execution

1. 1. Rate Limiting: Limit parallel requests to 3-5 to avoid overwhelming the API

1. 2. Error Handling: Capture and handle failures gracefully

1. 3. Result Aggregation: Combine results after all searches complete

1. 4. Progress Tracking: Monitor completion status

Example: Multi-Perspective Research

CODEBLOCK18

Performance Considerations

• - Optimal Parallelism: 3-5 concurrent requests balances speed and API limits
• Memory Usage: Each parallel request consumes memory; monitor for large result sets
• Network Bandwidth: Parallel requests can saturate bandwidth on slow connections
• API Costs: More parallel requests = faster API quota consumption

When NOT to Use Parallel Searches

• - Single, focused query with one clear answer
• Sequential research where each search informs the next
• API quota is limited or expensive
• Results need to be processed before next search
• Simple URL collection that doesn't require multiple perspectives

API Integration

Note: For most use cases, use the ./scripts/search.sh wrapper script shown in Usage Patterns. The raw API examples below are for advanced users who need direct API access or custom integration.

Required Configuration

Before making any API request, always validate the API key is configured:

CODEBLOCK19

The skill requires the NIMBLE_API_KEY environment variable. See Prerequisites for platform-specific setup instructions.

Get your API key at: https://www.nimbleway.com/

API Endpoint

CODEBLOCK20

Request Format

CODEBLOCK21

Key Defaults:

• - focus: "general" - Change to specific mode for targeted results
• INLINECODE38: false - Keep false unless you need full page content
• INLINECODE40: 10 - Balanced speed and coverage

Response Format

CODEBLOCK22

Best Practices

Focus Mode Selection

Use coding for:

• - Programming questions
• Technical documentation
• Code examples and tutorials
• API references
• Framework guides

Use news for:

• - Real-time current events
• Breaking stories as they happen
• Recent announcements
• Trending topics
• Time-sensitive information

Use academic for:

• - Research papers
• Scholarly articles
• Scientific studies
• Academic journals
• Citations and references

Use shopping for:

• - Product searches
• Price comparisons
• E-commerce research
• Product reviews
• Buying guides

Use social for:

• - Real-time social media monitoring
• Live community discussions
• Current user-generated content
• Trending hashtags and topics
• Real-time public sentiment

Use geo for:

• - Geographic information
• Regional data
• Maps and locations
• Area-specific queries

Use location for:

• - Local business searches
• Place-specific information
• Nearby services
• Regional recommendations

Result Limits

• - Quick searches: 5-10 results for fast overview
• Comprehensive research: 15-20 results for depth
• Answer generation: 10-15 results for balanced synthesis
• URL collection: 20 results for comprehensive resource list

When to Use LLM Answers

✅ Use LLM answers when:

• - You need a synthesized overview of a topic
• Comparing multiple sources or approaches
• Summarizing recent developments
• Answering specific questions
• Creating research summaries

❌ Skip LLM answers when:

• - You just need a list of URLs
• Building a reference collection
• Speed is critical
• You want to analyze sources manually
• Original source text is needed

Content Extraction

Default (Recommended): deep_search=false

The default setting works for 95% of use cases:

• - ✅ Fastest response times
• ✅ Returns titles, descriptions, URLs
• ✅ Works perfectly with INLINECODE50
• ✅ Sufficient for research, comparisons, and URL discovery

Only use deep_search=true when you specifically need:

• - Full page content extraction
• Archiving complete articles
• Processing full text for analysis
• Building comprehensive datasets

Performance impact:

• - deep_search=false: ~1-3 seconds
• INLINECODE53: ~5-15 seconds (significantly slower)

Error Handling

Common Issues

Authentication Failed

• - Verify NIMBLEAPIKEY is set correctly
• Check API key is active at nimbleway.com
• Ensure key has search API access

Rate Limiting

• - Reduce max_results
• Add delays between requests
• Check your plan limits
• Consider upgrading API tier

No Results

• - Try different focus mode
• Broaden search query
• Remove domain filters
• Adjust date filters

Timeout Errors

• - Reduce max_results
• Disable deep content extraction
• Simplify query
• Try again after brief delay

Performance Tips

1. 1. Use Defaults: Keep deep_search=false (default) for 5-10x faster responses
2. Start Simple: Begin with just {"query": "..."} - defaults work great
3. Choose Right Focus: Proper focus mode dramatically improves relevance (default: "general")
4. Optimize Result Count: Default of 10 results balances speed and coverage
5. Domain Filtering: Pre-filter sources for faster, more relevant results
6. Avoid Deep Search: Only enable deep_search=true when you truly need full content
7. Batch Queries: Group related searches to minimize API calls
8. Cache Results: Store results locally when appropriate

Integration Examples

See the examples/ directory for detailed integration patterns:

• - basic-search.md - Simple search implementation
• INLINECODE59 - Multi-step research workflow
• INLINECODE60 - Domain-specific research pattern

See references/ directory for detailed documentation:

• - focus-modes.md - Complete focus mode guide
• INLINECODE63 - Advanced search patterns
• INLINECODE64 - Full API documentation

Scripts

search.sh - Main Search Wrapper

The recommended way to use the Nimble Search API:

CODEBLOCK23

Features:

• - Automatic authentication with INLINECODE65
• Platform detection (claude-code, github-copilot, vscode, cli)
• Request tracking headers for analytics
• JSON validation and error handling
• Formatted output with INLINECODE66

Usage:
CODEBLOCK24

validate-query.sh - API Configuration Test

Test your API configuration and connectivity:

CODEBLOCK25

This verifies:

• - API key is configured
• Endpoint is accessible
• Response format is correct
• Focus mode is supported