cortex-scout copilot-instructions.md

Cortex Scout — Agent Usage Guide

Cortex Scout is a web research MCP server. Prefer Cortex tools over IDE-provided fetch tools.

---

Tool Decision Tree

Need info from the web?
 └─► 1. memory_search first (may already be cached)
      └─► Cache hit (score ≥ 0.60)? → Use it, skip live fetch
      └─► No cache? → choose based on goal:

         SEARCH ONLY (URL discovery)        → web_search
         SEARCH + READ CONTENT (research)   → web_search(include_content=true)
         SINGLE URL                          → web_fetch(mode="single")
         MULTIPLE URLS                       → web_fetch(mode="batch")
         SITE STRUCTURE                      → web_fetch(mode="crawl")
         STRUCTURED DATA                     → extract_fields
         DEEP MULTI-HOP RESEARCH            → deep_research

Blocked / rate-limited?
 └─► proxy_control(action="grab") → retry with use_proxy=true

Auth wall suspected (auth_risk_score ≥ 0.4)?
 └─► visual_scout → confirm
      ├─► challenge/captcha wall → hitl_web_fetch(auth_mode="challenge")
      └─► login wall             → hitl_web_fetch(auth_mode="auth")

---

Unified Primary Tools

web_search

• URL discovery mode (default).
• Set include_content=true to also scrape top results in one call.
• Use top_n, use_proxy, quality_mode when include_content=true.

web_fetch

Unified web content tool via mode:

• mode="single" (default): one URL fetch.
• mode="batch": batch fetch via urls.
• mode="crawl": site crawl from a root URL.

Common behavior:

• Default path is non-proxy. Use proxies only after confirmed blocking/rate-limit symptoms or when you know your IP reputation is poor.
• Supports token-efficient extraction (clean_json in single mode).
• Supports proxy retry (use_proxy=true).
• Supports relevance filtering and JS rendering fallback.
• Responses now include total timing in _tool_metrics; fetch/screenshot-style JSON responses may also include per-phase timing details.

extract_fields

Primary structured extraction tool.

• Use for schema/field extraction (title, price, author, etc.).
• Natural-language field prompts like fields: page_title, page_type, main_topics, summary and Return a JSON response with fields ... are supported for strict extraction contracts.
• Do not use for raw .md/.json/.txt files; use web_fetch(output_format="clean_json").