novada-agent

Novada Agent Skill

You have access to 11 Novada MCP tools. This skill tells you exactly which tool to use when and how to use it effectively.

Tool Selection — Decision Tree

Need web data?
├── Have specific URLs already? → novada_extract
├── Need to find URLs first?
│   ├── 1-2 targeted queries → novada_search
│   ├── Explore an entire site → novada_map or novada_crawl
│   └── Multi-faceted question → novada_research
└── Want a ready-made answer with sources? → novada_research

Need structured platform data (Amazon, Reddit, TikTok…)? → novada_scrape
Need proxy credentials for your own HTTP requests? → novada_proxy
Need to verify a factual claim? → novada_verify
Page blocked or JS-heavy, need raw HTML? → novada_unblock
Need to click/fill/screenshot a page? → novada_browser
Check API key product access? → novada_health

Also read novada://guide — it contains the full decision tree and workflow patterns.

The 11 Tools

novada_search

When: Find pages matching a query. You know what you're looking for, not where it lives.

Key parameters:

• query — your search string
• engine — google (default), bing, duckduckgo, yahoo, yandex
• num — results count, 1-20 (default 10)
• time_range — day, week, month, year
• include_domains / exclude_domains — up to 10 domains each
• country — ISO code for geo-targeting (195 countries supported)

When NOT to use: You already have the URL — use novada_extract instead.

Example:

{
  "query": "Claude API function calling examples 2025",
  "engine": "google",
  "num": 5,
  "time_range": "year",
  "include_domains": ["anthropic.com", "github.com"]
}

---

novada_extract

When: You have specific URLs and need their content.

Key parameters:

• url — single URL string, or array of up to 10 URLs for parallel batch
• urls — alias for url when passing multiple URLs; preferred for batch workflows
• format — markdown (default), text, html
• render — auto (default), static, render (Web Unblocker), browser (full CDP)
• query — optional: focuses the content summary on a specific aspect
• fields — optional: specific fields to extract, e.g. ["price", "author", "rating"] (max 20)
• max_chars — optional: max characters to return (default 25000, max 100000). Do NOT set to 100000 by default.

Batch mode: Pass url: ["url1", "url2"] or urls: ["url1", "url2"] to extract multiple pages in one call — faster than calling extract once per URL.

When NOT to use: You don't have URLs yet — use novada_search or novada_map first.

Example (single):

{ "url": "https://docs.anthropic.com/en/api/getting-started", "format": "markdown" }

Example (batch):

{
  "url": ["https://example.com/page1", "https://example.com/page2"],
  "format": "markdown",
  "query": "pricing information"
}

---

novada_crawl

When: You need content from multiple pages of a site but don't have all URLs.

Key parameters:

• url — starting URL (root)
• max_pages — 1-20 (default 5)
• strategy — bfs (breadth-first, broad coverage) or dfs (depth-first, deep paths)
• select_paths — regex patterns to restrict to specific paths, e.g. ["/docs/.*"]
• exclude_paths — regex patterns to skip, e.g. ["/blog/.*", "/changelog/.*"]
• instructions — natural language hint: "only API reference pages"

When NOT to use:

• You just want a list of URLs → use novada_map instead (no content extraction)
• You already have all URLs → use novada_extract batch

Example:

{
  "url": "https://docs.example.com",
  "max_pages": 10,
  "strategy": "bfs",
  "select_paths": ["/api/.*"],
  "instructions": "only API endpoint reference pages, skip tutorials"
}

---

novada_map

When: You need to discover URLs on a site without extracting their content. Site exploration, inventory, link collection.

Key parameters:

• url — root URL to map
• limit — max URLs to return, 1-100 (default 50)
• max_depth — link hops from root, 1-5 (default 2)
• search — optional keyword to filter returned URLs
• include_subdomains — include URLs on subdomains (default false)

Use then chain: novada_map → filter the URL list → novada_extract batch on selected URLs. This is more efficient than novada_crawl when you need selective extraction.

Example:

{
  "url": "https://docs.example.com",
  "limit": 100,
  "max_depth": 3,
  "search": "authentication"
}

---

novada_research

When: You have a question that needs multiple sources to answer well. You want synthesis, not raw search results.

What it does: Generates 3-10 parallel search queries, deduplicates up to 15 unique sources, returns a cited report with source list.

Key parameters:

• question — the research question (full sentence works best)
• depth — auto (default, server picks), quick (3 searches), deep (5-6), comprehensive (8-10)
• focus — optional: "technical implementation", "business impact", "recent news only"

When NOT to use: You need real-time data or very specific factual lookups — novada_search is more precise.

Example:

{
  "question": "What are the best practices for implementing JWT refresh token rotation in 2025?",
  "depth": "deep",
  "focus": "security and implementation"
}

---

novada_proxy

When: You need to route your own HTTP requests through residential, mobile, ISP, or datacenter IPs — for geo-targeting, IP rotation, or bypassing IP-based rate limits.

Key parameters:

• type — residential (default), mobile, isp, datacenter
• country — ISO 2-letter code (us, gb, de)
• city — city-level targeting (requires country)
• session_id — sticky session — same ID returns same IP for multi-step workflows
• format — url (default, for Node.js/Python), env (shell export commands), curl (--proxy flag)

When NOT to use: Web page extraction (use novada_extract — proxy is automatic). Web search (use novada_search).

Example:

{ "type": "residential", "country": "us", "session_id": "my-session", "format": "env" }

---

novada_scrape

When: You need clean, structured records from a known platform — not raw HTML but tabular data. Supports 129 platforms including Amazon, Reddit, TikTok, LinkedIn, Google Shopping, Glassdoor, GitHub, Zillow, Airbnb, and more.

Key parameters:

• platform — domain, e.g. amazon.com, reddit.com, tiktok.com
• operation — operation ID, e.g. amazon_product_by-keywords, reddit_posts_by-keywords
• params — operation-specific params, e.g. { "keyword": "iphone 16", "num": 5 }
• limit — max records (1-100, default 20)
• format — markdown (default, agent-optimized), json (programmatic)

Discover platforms: Read the novada://scraper-platforms MCP resource for the complete list with operation IDs and required params.

When NOT to use: General web pages not on the platform list (use novada_extract or novada_crawl). Unknown domains.

Example:

{
  "platform": "amazon.com",
  "operation": "amazon_product_by-keywords",
  "params": { "keyword": "iphone 16", "num": 5 },
  "format": "json"
}

---

novada_verify

When: You have a factual claim and need to check whether web sources support it before citing it.

What it does: Runs 3 parallel searches (supporting, skeptical, neutral fact-check angles) and returns a structured verdict: supported / unsupported / contested / insufficient_data. Confidence score 0–100 indicates how far from a 50/50 split.

Key parameters:

• claim — the factual statement to verify (min 10 chars)
• context — optional: narrows search scope, e.g. "as of 2024", "in the US"

When NOT to use: Open-ended questions (use novada_research). Reading a specific URL (use novada_extract). Verdict is signal-based, not a definitive ruling.

Example:

{ "claim": "The Eiffel Tower is 330 meters tall", "context": "as of 2024" }

---

novada_unblock

When: You need the raw rendered HTML of a blocked or JS-heavy page, and novada_extract with render="render" still fails or returns incomplete content.

Key parameters:

• url — URL to unblock
• method — render (Web Unblocker, faster/cheaper) or browser (full Chromium CDP, handles complex SPAs)

Requires: NOVADA_WEB_UNBLOCKER_KEY or NOVADA_BROWSER_WS

When NOT to use: If you want cleaned text (use novada_extract with render="render" first — it returns clean markdown). Structured platform data (use novada_scrape). This tool returns raw HTML.

Example:

{ "url": "https://example.com/protected", "method": "render" }

---

novada_browser

When: You need to interact with a web page — click buttons, fill forms, scroll, take screenshots, or execute JavaScript. Up to 20 chained actions per session.

Key parameters:

• actions — ordered list of browser actions (max 20)
• session_id — optional: maintain state (cookies, login) across multiple calls; sessions expire after 10 min of inactivity

Supported actions: navigate, click, type, screenshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select

Requires: NOVADA_BROWSER_WS

When NOT to use: Simple page reading (use novada_extract). Structured data from a known platform (use novada_scrape). Raw HTML without interaction (use novada_unblock).

Example:

{
  "actions": [
    { "action": "navigate", "url": "https://example.com/login" },
    { "action": "type", "selector": "#email", "text": "[email protected]" },
    { "action": "type", "selector": "#password", "text": "pass" },
    { "action": "click", "selector": "button[type=submit]" },
    { "action": "aria_snapshot" }
  ]
}

---

novada_health

When: First-time setup, diagnosing why a tool is failing, or confirming which Novada API products are active on your key.

Key parameters: None required.

What it returns: Status table for Search, Extract, Scraper API, Proxy, and Browser API — with activation links for any product not yet enabled.

When NOT to use: This is a diagnostic tool only. Don't call it in production workflows unless you're debugging.

Example:

{}

---

Common Workflows

Research + Extract

1. novada_research for the broad answer
2. Identify key sources from the report
3. novada_extract on the most relevant URLs for full content

Competitive Analysis

1. novada_search for competitor pages
2. novada_extract batch on top results
3. Synthesize findings

Full Site Documentation Extraction

1. novada_map to discover all doc URLs
2. Filter to relevant paths
3. novada_extract batch (up to 10 per call) on filtered list

Fresh News

1. novada_search with time_range: "week" or start_date
2. novada_extract on top 3-5 results

---

Rules

1. Batch > sequential: Always use novada_extract with a URL array instead of multiple single-URL calls.
2. Map before crawl for selective work: If you only need specific pages, novada_map + filter + novada_extract is more efficient than novada_crawl.
3. Use focus in research: A focused research question produces tighter, more relevant sub-queries.
4. Check novada://engines: Different engines have different strengths — Bing has better news freshness, DuckDuckGo has better privacy site support.
5. novada_research is not a search: It synthesizes. Don't use it when you need raw URLs or specific lookups.