Skip to main content
Glama
Khamel83

Argus

by Khamel83
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Argus

Python 3.11+ PyPI Version PyPI Downloads License: MIT CI MCP Registry Docker

Retrieval platform for AI agents. Argus routes search across 14 providers, recovers dead URLs, captures important site content, builds local docs-plus-research packs, and persists everything with traceable local artifacts.

Features at a glance:

  • Topology-aware acquisition — Argus knows if it's on a residential IP or datacenter, routing search and extraction automatically to avoid blocks and minimize network hops.

  • 14 providers, one API — free-first tier routing, budget-exhausted providers skipped automatically

  • Zero-key start — pip install argus-search gives you DuckDuckGo + Yahoo immediately, no accounts needed

  • SearXNG self-host = 70+ engines — Google, Bing, Yahoo, Startpage, Ecosia, Qwant and more via one Docker container

  • 12-step content extraction — returns full page text with quality gates, not just links

  • Opinionated retrieval workflows — recover dead articles, capture important pages from a site, and build local docs-plus-research packs

  • Argus-owned corpus storage — runtime data goes to a writable user data directory, not your repo checkout

  • Multi-turn sessions — pass session_id for conversational context across searches

  • Score attribution — optionally show which providers contributed to each fused RRF score

  • Usage dashboard — inspect provider budgets, recent query volume, and machine-level usage at /dashboard

  • 4 search modes — discovery, research, recovery, grounding

  • Dead URL recovery — /recover-url with Wayback Machine and archive fallbacks

  • 4 integration paths — HTTP API, CLI, MCP server, Python SDK

Built for AI agent builders, RAG pipelines, and ops teams who need reliable search, capture, and local evidence without stitching APIs together.

Status: beta. The retrieval workflows and corpus model are production-oriented, but still maturing.

Status: see the public status page. Authorized maintainers can use the private argus-ops README for the latest dated reports.

Contents

Related MCP server: GroundRoute

Quickstart

Mode 1: Local CLI (zero config)

pip install argus-search && argus search -q "python web frameworks"

That's it. DuckDuckGo handles the search — no accounts, no keys, no containers. You get unlimited free search from your laptop right now. Add API keys whenever you want more providers, or don't.

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Works on any machine with Python 3.11+ — laptop, Mac Mini, Raspberry Pi, cloud VM. Nothing to host.

For MCP (Claude Code, Codex, OpenCode, Cursor, VS Code):

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

That writes native config for Claude Code, Codex CLI, OpenCode, and Cursor. Restart the client after configuration. For manual stdio setup:

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

Or install from the MCP Registry:

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

Standalone development needs no server or keys, but it must be explicitly enabled. Production MCP always delegates to an authenticated HTTP authority.

See MCP Client Setup for exact config files, verification commands, remote HTTP setup, and troubleshooting.

Mode 2: Full Stack Server

Got a Raspberry Pi running Pi-hole? A Mac Mini on your desk? An old laptop? That's enough to run the full stack — SearXNG (your own private search engine, disabled by default) plus local JS-rendering content extraction.

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

What you have

What you get

Any machine with Python 3.11+

DuckDuckGo + API providers (no server)

Home server / old laptop (4GB+)

Everything — SearXNG, all providers, Crawl4AI, Obscura

Mac Mini M1+ (8GB+)

Full stack with headroom

Free cloud VM (1GB)

SearXNG + search providers (use residential workers for extraction)

SearXNG takes 512MB of RAM and gives you a private Google-style search engine (disabled by default — set ARGUS_SEARXNG_ENABLED=true) that nobody can rate-limit, block, or charge for. It runs alongside Pi-hole on hardware millions of people already own.

Where Argus Writes Data

Argus code and Argus runtime data are different things.

  • Code lives wherever you install or clone Argus.

  • Runtime corpus data lives in a writable user data directory resolved by platformdirs, or in ARGUS_DATA_ROOT if you override it.

Inspect the exact paths on your machine:

argus paths

By default Argus writes:

  • official docs cache under the resolved docs/cache/

  • research packs under docs/research/

  • workflow run state under workflows/runs/

  • versioned workflow snapshots under snapshots/

This means Argus does not require a sibling ../docs-cache checkout. If you have an older docs-cache tree, import it once with:

argus corpus import-docs-cache -s /path/to/docs-cache

Opinionated Workflows

These workflows build local artifacts, not just transient JSON responses.

Recover A Dead Article

argus recover-article -u "https://example.com/old-post" -t "Example Post"

Argus searches for recovery candidates, extracts the best result, saves the recovered sources locally, and writes a citation-backed report plus manifest.

Capture The Important Parts Of A Site

argus capture-site -u "https://docs.example.com"

Argus stays on-domain, uses sitemap-assisted discovery plus heuristic link scoring, saves the important pages it finds, and writes a detailed summary with references.

Build A Docs + Research Pack

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Argus captures official docs into its local docs cache, adds non-official supporting sources from search, and writes a combined research pack with traceable artifacts.

Development

Repo development is pinned to Python 3.12. The package runtime floor remains Python 3.11, but contributors should use the uv workflow below so local verification matches CI and avoids accidentally using an older system interpreter.

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

The repo includes .python-version with 3.12 so uv, pyenv, and similar tools pick the right interpreter by default. More contributor guidance lives in CONTRIBUTING.md.

Providers

Provider

Credit type

Free capacity

Setup

DuckDuckGo

Free (scraped)

Unlimited

None

Yahoo

Free (scraped)

Unlimited

None — fragile, auto-skipped if broken

SearXNG

Free (self-hosted, off by default)

Unlimited — 70+ engines¹

Docker

GitHub

Free (API)

Unlimited

None (token for higher rate limit)

WolframAlpha

Free (API key)

2,000 queries/month

free key

Brave Search

Monthly recurring

2,000 queries/month

dashboard

Tavily

Monthly recurring

1,000 queries/month

signup

Exa

Monthly recurring

1,000 queries/month

signup

Linkup

Monthly recurring

1,000 queries/month

signup

Parallel AI

Monthly recurring

$5 credit with card on file, up to 5,000 searches/month

signup

Serper

One-time signup

2,500 credits

signup

You.com

One-time signup

$20 credit

platform

Valyu

One-time signup

$10 credit

platform

¹ SearXNG aggregates Google, Bing, Yahoo, Startpage, Ecosia, Qwant, Wikipedia, and 60+ more — all behind a single self-hosted endpoint. Run docker compose up -d on any machine with 512MB of free RAM.

² WolframAlpha returns computed answers (math, unit conversions, factual lookups), not web search results. It only activates in grounding and research modes. Queries it can't compute (general web searches) return empty — no error, no health penalty.

7,000+ free queries/month from recurring free-tier providers with API keys (WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k), or up to 12,000+ when Parallel's monthly credit is available to an eligible account with a card on file. DuckDuckGo, Yahoo, and GitHub have no monthly cap. SearXNG is disabled by default (enable in .env). Routing priority: Tier 0 (free: SearXNG*, DuckDuckGo, Yahoo, GitHub, WolframAlpha) → Tier 1 (monthly recurring: Brave, Tavily, Exa, Linkup, Parallel) → Tier 3 (one-time: Serper, You.com, Valyu, SearchAPI). Budget-exhausted providers are skipped automatically.

HTTP API

All endpoints prefixed with /api. OpenAPI docs at http://localhost:8000/docs.

Local loopback calls can use the API without auth. Remote HTTP callers must send ARGUS_API_KEY as either Authorization: Bearer ... or X-API-Key: .... Privileged routes under /api/admin/* require ARGUS_ADMIN_API_KEY (or fall back to ARGUS_API_KEY if no separate admin key is configured).

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

/api/health remains a 200 liveness compatibility route. It intentionally does not check PostgreSQL, providers, Maya, or the browser, so a dependency outage cannot cause container restart storms. See production operations for the canonical topology and operator procedures, and operational status for endpoint semantics, readiness classification, observation expiry, and safe telemetry.

Search modes

Mode

Use for

Example

discovery

Related pages, canonical sources

"Find the official docs for X"

research

Broad exploratory retrieval

"Latest approaches to Y?"

recovery

Finding moved/dead content

"This URL is 404"

grounding

Fact-checking with live sources

"Verify this claim about Z"

Tier-based routing always applies first. Within each tier, the mode selects provider order.

Response format

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

Each result includes url, title, snippet, domain, provider, and score. The traces array shows which providers were called and their outcomes.

When include_attribution is true, each result also includes score_attribution: a provider-to-score map that decomposes the result's Reciprocal Rank Fusion score. RRF is additive, so each provider's attribution is exactly its own rank contribution, and the values sum to score. Attribution is off by default and cached separately from non-attributed searches.

Budgets

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

Each provider tracks usage. Tier 1 (monthly) uses a 30-day rolling window; tier 3 (one-time) uses a lifetime counter that never resets. When a provider hits its budget, Argus skips it and moves to the next. Free providers (DuckDuckGo, GitHub) have no limit. SearXNG is free but disabled by default. Set ARGUS_*_MONTHLY_BUDGET_USD to enforce custom limits per provider.

Dashboard

Run the HTTP server and open /dashboard:

argus serve
# http://127.0.0.1:8000/dashboard

The dashboard shows provider budget burn, over-pace and exhausted providers, query volume for the last 30 days, usage by machine, and recent provider activity. Budget cards refresh automatically.

Set ARGUS_ADMIN_API_KEY to require dashboard login. If no admin key is set, the dashboard is open to anyone who can reach the server, which is suitable only for trusted local use.

For subpath deployment behind a reverse proxy, set ARGUS_ROOT_PATH to the external path prefix:

ARGUS_ROOT_PATH=/argus argus serve

That makes dashboard redirects, links, and HTMX fragment URLs work when the proxy serves Argus at a path such as https://khamel.com/argus/.

For direct public HTTPS, the repo includes a Caddy profile:

ARGUS_DOMAIN=argus.example.com ACME_EMAIL=you@example.com \
  docker compose --profile proxy up -d

For an existing Authentik/nginx deployment, keep authentication at the proxy layer and set ARGUS_ROOT_PATH to the public prefix.

Integration

CLI

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

All commands support --json for structured output.

Pass session_id to any search call. Argus stores each query and extracted URL through the same SQLAlchemy repository used by the retrieval ledger (ARGUS_DB_URL, PostgreSQL in production and SQLite for direct local use). Reusing the same session_id gives the broker context from prior queries — follow-up searches are automatically refined using earlier conversation context. Sessions persist across restarts. Omit session_id for stateless, one-shot searches.

Legacy sessions from the former budget SQLite database can be reconciled without mutating the target first:

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

The import is idempotent: an identical existing session is skipped and a different session with the same ID is reported as conflicting.

MCP

MCP is a stateless execution adapter over the authenticated HTTP API. It does not construct providers or a broker and does not own browser, database, budget, session, health, or outbox state. Configure the adapter process with:

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

The deployed production endpoint supports both the verified MCP 2025-11-25 compatibility contract and the MCP 2026-07-28 stateless transport revision. The newer path is one-shot and does not require an initialize handshake or Mcp-Session-Id; durable policy, budgets, sessions, and evidence remain owned by the HTTP authority. See docs/research/2026-08-11-mcp-stateless-production-authority.md for the source-backed boundary and required no-spend probes.

Option A — Local adapter (stdio)

Install the adapter on the same machine as your MCP client:

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

Use the full path if argus isn't on PATH: "/home/you/.local/bin/argus". The adapter inherits ARGUS_AUTHORITY_URL and ARGUS_AUTHORITY_TOKEN from the client process. To run a local broker instead, development environments must explicitly set ARGUS_MCP_STANDALONE=true; production rejects it.

Works with Claude Code, Codex CLI, OpenCode, Cursor, and any stdio-based MCP client. Use argus mcp init --global --client all to write native client configs for the current machine.

Detailed client setup and verification commands live in docs/mcp-clients.md.

Option B — Remote MCP adapter (clients over Tailscale)

Run Argus on one machine, connect every client over the network. No local install on clients.

On the adapter host:

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

Remote MCP credentials must also be valid scoped credentials at the HTTP authority because the adapter forwards each authenticated bearer token unchanged. For stdio, ARGUS_AUTHORITY_TOKEN is the caller credential.

To keep the HTTP API and remote MCP service running after reboot on a systemd host:

cat >mcp.env <<'EOF'
ARGUS_AUTHORITY_URL=http://argus-api:8000
ARGUS_AUTHORITY_TOKEN=replace-with-scoped-caller-token
ARGUS_API_KEY=replace-with-the-same-scoped-caller-token
EOF
chmod 600 mcp.env
ARGUS_MCP_ENV_FILE="$PWD/mcp.env" scripts/install-systemd.sh
systemctl status argus argus-mcp --no-pager

The installer validates the minimal adapter environment, installs it as root-only /etc/argus/mcp.env, then installs and starts both units. The MCP unit never loads the authority's .env, provider vaults, database settings, browser paths, or writable data volumes.

On each client:

Client

Config

Claude Code

{"mcpServers":{"argus":{"type":"http","url":"http://<server>:<port>/mcp","headers":{"Authorization":"Bearer <ARGUS_API_KEY>"}}}} in ~/.claude.json (global) or .mcp.json (project)

OpenCode

{"mcp":{"argus":{"type":"remote","url":"http://<server>:<port>/mcp","enabled":true,"headers":{"Authorization":"Bearer <ARGUS_API_KEY>"}}}} in ~/.config/opencode/config.json (global) or .opencode/opencode.json (project)

Cursor

Same as Claude Code — reads .mcp.json

Codex CLI

[mcp_servers.argus] section in ~/.codex/config.toml with url and bearer_token_env_var = "ARGUS_API_KEY" — export that variable in the shell that launches Codex; argus mcp init never writes the token to disk

Gemini CLI

gemini mcp add argus http://<server>:<port>/mcp -t http -H "Authorization: Bearer <ARGUS_API_KEY>"

Antigravity

{"mcpServers":{"argus":{"serverUrl":"http://<server>:<port>/mcp","headers":{"Authorization":"Bearer <ARGUS_API_KEY>"}}}}

With Tailscale, <server> is your machine's Tailscale IP (e.g. 100.x.x.x). One server, every machine on your mesh gets search.

One-command provisioning:

# Load secrets, then push config to any machine:
eval $(secrets decrypt argus | grep -E 'ARGUS_REMOTE_URL|ARGUS_API_KEY' | sed 's/^/export /')

curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s local              # this machine; uses local stdio if argus is installed
curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s user@100.x.x.x    # remote machine

The script writes Claude/Cursor, Codex, and OpenCode configs on the target. Local stdio does not require an MCP listener key, but the adapter still requires its scoped ARGUS_AUTHORITY_TOKEN. Remote MCP mode requires ARGUS_REMOTE_URL and ARGUS_API_KEY. Requires Python 3.

argus mcp init also generates configs automatically:

argus mcp init --global              # local stdio adapter for Claude Code + OpenCode + Cursor
argus mcp init --client codex        # local stdio for Codex (writes ~/.codex/config.toml)
argus mcp init --client opencode     # local stdio for OpenCode
ARGUS_REMOTE_URL=http://argus.local:8271 ARGUS_API_KEY=... argus mcp init --global --client all
argus mcp init --client gemini       # prints gemini mcp add command
argus mcp init --global --client all # everything above

Release Status

Pushing main does not publish PyPI. Package and MCP Registry publication happens through the GitHub publish workflow on release creation or manual dispatch. See docs/releasing.md for version sync, preflight checks, and publish verification.

Transports: stdio (default local adapter), sse (legacy remote), and streamable-http (modern remote, "type":"http" in config). Remote MCP transports require ARGUS_API_KEY; every transport delegates execution to ARGUS_AUTHORITY_URL.

Available tools:

  • HTTP-backed stdio and remote MCP: search_web, extract_content, recover_url, expand_links, search_health, search_budgets, recover_dead_article, capture_site, and build_research_pack

  • Explicit standalone development additionally exposes local-only test_provider, cookie_health, valyu_answer, path/file tools, and resources. These are intentionally absent from production adapters.

search_web accepts free_only=true to restrict results to free (tier-0) providers only, and include_attribution=true to include per-provider score attribution in the Markdown response.

Using Argus from MCP vs HTTP

Two transports, one rule: agents use MCP, everything else uses HTTP.

  • MCP (argus mcp serve) — a stateless authenticated adapter for AI harnesses that speak MCP natively. Core tools delegate to the HTTP authority: search_web, extract_content, recover_url, expand_links, and workflow starts. MCP restarts cannot fork accounting, sessions, health, or outbox state.

  • HTTP (POST /api/search, POST /api/extract, POST /api/workflows/...) — for scripts, cron jobs, and service integrations (including Maya). Send a scoped caller credential in Authorization; body "caller" values are diagnostic labels and cannot override the authenticated identity.

The cross-service transport and role contract for the wider fleet (Maya / Hermes / Argus) is canonical in Maya's architecture documentation.

Python

Direct broker and extraction imports are a standalone development convenience. Production Python callers use the authenticated HTTP API so all execution and durable accounting remain in one authority.

from argus.broker.router import create_broker
from argus.models import SearchQuery, SearchMode
from argus.extraction import extract_url

broker = create_broker()

response = await broker.search(
    SearchQuery(query="python web frameworks", mode=SearchMode.DISCOVERY, max_results=10),
    compute_attribution=True,
)
for r in response.results:
    print(f"{r.title}: {r.url} (score: {r.score:.3f})")
    print(r.score_attribution)

content = await extract_url(response.results[0].url)
print(content.title)
print(content.text)

Content Extraction

Argus tries up to twelve methods to extract content from any URL: auth extraction for paywalls, then local extractors (trafilatura, Crawl4AI, Obscura, Playwright, residential IP), then external APIs (Jina, Valyu Contents, Firecrawl, You.com, Wayback, archive.is). Each attempt is quality-checked for completeness and garbage output. See docs/providers.md for the full extractor comparison.

Completeness assessment runs automatically after every successful extraction. Argus scores five signals — trailing ellipsis, feed truncation markers ("Read more", WordPress RSS footers), mid-sentence endings, abrupt final paragraphs, and suspicious round word counts — and returns is_complete, completeness_confidence, and truncation_type alongside the text. When confidence is ≥ 85%, Argus continues trying the next extractor rather than returning a partial result; this means a trafilatura fetch that ends with "..." will automatically fall through to Playwright, Jina, Wayback, etc. Callers that already have text (e.g. RSS feed items) can use POST /api/assess-content to check completeness without triggering extraction.

Obscura (optional) is a lightweight Rust headless browser (~70MB binary, 30MB RAM) with built-in stealth mode — it sets navigator.webdriver=undefined, randomizes canvas/GPU/audio fingerprints per session, and blocks 3,520 tracker domains. This directly addresses bot detection on JS-heavy and anti-scraping sites that block standard Playwright/Chrome. No API key, no rate limit — fully local.

Two ways to use it:

Mode

Setup

What you get

CLI extraction step

Install binary on $PATH

Argus auto-detects it; stealth browser as fallback step before Playwright

CDP backend for Playwright

Run obscura serve --stealth --port 9222, set ARGUS_OBSCURA_CDP_URL=ws://127.0.0.1:9222

Playwright uses Obscura as its browser engine — stealth + 30MB vs 200MB + DOM-to-Markdown output

Install the binary: github.com/h4ckf0r0day/obscura/releases

Extract gets the full text of a working URL and tells you whether that text is complete. Recover-URL finds alternatives when a URL is dead, paywalled, or radically changed.

Architecture

Caller (CLI/HTTP/MCP/Python) → SearchBroker → tier-sorted providers → RRF ranking → response
                                     ↕ SessionStore (optional)
                            Extractor (on demand) → 12-step fallback chain with quality gates

Module

Responsibility

argus/broker/

Tier-based routing, ranking, dedup, caching, health, budgets

argus/providers/

Provider adapters (one per search API)

argus/extraction/

12-step URL extraction fallback chain with quality gates

argus/sessions/

Multi-turn session store and query refinement

argus/api/

Authenticated production execution authority

argus/cli/

HTTP caller in production; direct execution in development

argus/mcp/

Stateless MCP-to-HTTP adapter

argus/persistence/

Shared PostgreSQL authority state; SQLite standalone development

argus/operations/

Cached readiness, typed dependency observations, process identity, bounded metrics

Add new providers or extractors with a single adapter file. See CONTRIBUTING.md for the interface.

How a Query Works

query arrives → cache? → build provider queue → execute sequentially → RRF fuse → dedup → respond

  1. Cache check. SearchCache hashes the normalized query, mode, and whether attribution was requested (SHA256). Hit returns immediately with a TTL of 168 hours (7 days).

  2. Provider queue. resolve_routing() takes the mode-specific preference list and stable-sorts by tier: tier 0 (free) first, tier 1 (monthly) next, tier 3 (one-time) last. Example for discovery mode:

    searxng → duckduckgo → yahoo → github → brave → exa → tavily → linkup → parallel → serper → you → valyu

  3. Sequential execution with gates. Each provider is checked in order. Four gates must pass before an API call:

    • Config — is the provider enabled and configured (API key present)?

    • Health — has it failed 5+ consecutive times (triggers 60-minute cooldown)?

    • Budget — for tier 1+: is the budget exhausted? For tier 1 (monthly), pacing checks if the 7-day usage rate would drain the remaining budget in under a week — empty days bank headroom. For tier 3 (one-time), a lifetime counter gates access — exhaustion is the sole check.

    • Execute — the actual HTTP call. Successes reset failure counters; failures increment them.

  4. RRF fusion. Results from all queried providers are merged using Reciprocal Rank Fusion (k=60). Each result's score is the sum of 1/(k + rank) across every provider that returned it. Results appearing in multiple providers rank higher.

  5. Dedup and truncate. URLs are normalized (stripped www., tracking params like utm_*, trailing slashes) and deduplicated. The merged list is truncated to max_results (default 10).

  6. Cache and persist. The authority writes the final response to its in-memory cache and configured SQL repository (PostgreSQL in production, SQLite for standalone development). Search results and extractions include provenance metadata (egress, machine, source_type) for downstream audit. Existing databases are upgraded additively at startup.

Configuration

All config via environment variables. See .env.example for the full list. Limited API-key providers are opt-in: set both the API key and ARGUS_<PROVIDER>_ENABLED=true. Missing keys degrade gracefully — providers are skipped, not errors.

When running from the repo, Argus now auto-loads .env and .env.local (without overriding already-exported environment variables). Disable this behavior with ARGUS_AUTOLOAD_DOTENV=false.

Variable

Default

Description

ARGUS_NODE_ROLE

primary

Production authority is primary; adapters are caller; direct/worker execution is development-only

ARGUS_AUTHORITY_URL

—

HTTP API base URL required by production CLI and MCP adapters

ARGUS_AUTHORITY_TOKEN

—

Scoped caller token for production CLI and MCP adapters

ARGUS_MCP_STANDALONE

false

Explicit development-only local MCP execution

ARGUS_EGRESS_TYPE

unknown

residential, datacenter, or unknown

ARGUS_RESIDENTIAL_POLICY

fallback

off, fallback, prefer_on_datacenter, prefer_for_domains, or always

ARGUS_SEARXNG_ENABLED

false

Set true when you have a SearXNG Docker container

ARGUS_SEARXNG_BASE_URL

http://127.0.0.1:8080

SearXNG endpoint

ARGUS_SEARXNG_RESIDENTIAL_BASE_URL

—

Remote residential SearXNG endpoint (e.g. over Tailscale)

ARGUS_<PROVIDER>_ENABLED

false for limited API-key providers

Opt in to providers that consume limited credits or quotas

ARGUS_BRAVE_API_KEY

—

Brave Search API key

ARGUS_SERPER_API_KEY

—

Serper API key

ARGUS_TAVILY_API_KEY

—

Tavily API key

ARGUS_EXA_API_KEY

—

Exa API key

ARGUS_LINKUP_API_KEY

—

Linkup API key

ARGUS_PARALLEL_API_KEY

—

Parallel AI API key

ARGUS_YOU_API_KEY

—

You.com API key

ARGUS_VALYU_API_KEY

—

Valyu API key (search, contents, answer)

ARGUS_FIRECRAWL_API_KEY

—

Firecrawl API key (content extraction)

ARGUS_GITHUB_API_KEY

—

GitHub token (higher rate limit)

ARGUS_DATA_ROOT

platformdirs user data dir

Override the Argus runtime corpus root

ARGUS_*_MONTHLY_BUDGET_USD

provider-specific

Query-count budget for most providers; USD budget for Valyu

ARGUS_CRAWL4AI_ENABLED

false

Enable Crawl4AI extraction step

ARGUS_YOU_CONTENTS_ENABLED

false

Enable You.com Contents API extraction

ARGUS_OBSCURA_CDP_URL

—

Obscura CDP endpoint (e.g. ws://127.0.0.1:9222) — makes Playwright use Obscura as its browser engine

ARGUS_OBSCURA_TIMEOUT_SECONDS

20

Timeout for Obscura CLI subprocess calls

ARGUS_CACHE_TTL_HOURS

168

Result cache TTL

ARGUS_BIND_HOST

127.0.0.1

Host used by argus serve unless --host is passed

ARGUS_PORT

8000

Port used by argus serve unless --port is passed

ARGUS_AUTOLOAD_DOTENV

true

Auto-load .env / .env.local from cwd and repo root for CLI/API/MCP processes

ARGUS_API_KEY

—

Required for non-local HTTP API and remote MCP callers

ARGUS_ADMIN_API_KEY

—

Enables dashboard login and admin API authentication

ARGUS_ACCEPTED_OPERATION_AUTHORITY

legacy

Atomic authority selection. evidence activates the registered planner, readiness, evidence repository, extraction finalizer, and HTTP presenters as one unit

ARGUS_ALLOWED_HOSTS

—

Exact comma-separated HTTP Host allowlist; required for a remote production listener

ARGUS_ALLOWED_ORIGINS

—

Exact comma-separated browser Origin allowlist. Set explicitly, including an empty value, for remote production

ARGUS_RETRIEVAL_SESSION_SECRET

—

Stable random secret of at least 32 characters used to bind v2 retrieval sessions to authenticated principals

ARGUS_ORGANIZATION_POLICY_VERSION

1

Stable organization-policy identity included in accepted execution cohorts

ARGUS_ROOT_PATH

—

Public subpath prefix for dashboard links and redirects, e.g. /argus

ARGUS_MAYA_CAPTURE_URL

—

Maya's dedicated Argus retrieval-capture endpoint; delivery stays disabled when unset

ARGUS_MAYA_CAPTURE_TOKEN

—

Dedicated shared secret for Maya capture delivery; never reuse the generic Maya ingest token

ARGUS_MAYA_OUTBOX_BATCH_SIZE

20

Maximum durable captures claimed by one delivery pass (bounded to 100)

ARGUS_MAYA_ACKNOWLEDGED_RETENTION_DAYS

7

Days to retain acknowledged capture bodies before preserving audit metadata only

/api/v2/* is additive and returns a canonical version-2 envelope. It remains fail-closed with unready while the evidence authority is disabled. Unsafe Host, Origin, credential, media-type, and body-size combinations are rejected before provider, extractor, session, or persistence work. Version-1 routes retain their established response shapes.

When Not To Use Argus

Argus is best when you need search, capture, provenance, and local artifacts together.

Avoid it when:

  • you only need one search API and do not need fallback or budget controls

  • you only need a one-off page scrape with no persistent corpus or report output

  • you need an end-user search UI rather than backend retrieval infrastructure

  • you need fully deterministic summarization with no heuristic or LLM-assisted steps

FAQ

How is this different from calling Tavily/Serper directly? Argus calls them for you — plus 13 other providers. You get one ranked, deduplicated result set instead of managing multiple API keys and stitching results together. Free providers are tried first, so you only burn credits when needed.

Can I run only one provider? Yes. Set only the API key for the provider you want. All others are silently skipped. For zero-config, just install and go — DuckDuckGo + Yahoo handle search with no keys.

Do I need Docker? No. pip install argus-search works immediately on any machine with Python 3.11+. Docker is only needed for SearXNG (set ARGUS_SEARXNG_ENABLED=true in .env) or Crawl4AI (local JS rendering).

Which Python version should contributors use? Use Python 3.12 for repo development and verification: uv sync --python 3.12 --extra dev --extra mcp then uv run pytest tests/ -v --tb=short. The published package still supports Python 3.11+.

What is the safest way to deploy Argus on a network? Use Tailscale or another private network, bind explicitly to the trusted interface, set ARGUS_API_KEY, and reserve /api/admin/* for ARGUS_ADMIN_API_KEY. Treat direct internet exposure as an advanced mode behind a reverse proxy.

License

MIT — see CHANGELOG.md for release history.

Available Tools

13 tools
argus_pathsA

Show the resolved Argus runtime storage paths.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description uses 'Show', indicating a read-only operation, but it does not elaborate on any behavioral traits such as permissions or side effects. With no annotations, the description carries the full burden, and while adequate for a simple tool, it lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no parameters and an output schema that documents return values, the description provides sufficient information to understand the tool's purpose and use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the input schema fully defines the tool's inputs. The description does not add any parameter information, but the baseline score of 3 is appropriate for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Show' and the specific resource 'resolved Argus runtime storage paths', which distinctly identifies the tool's purpose and differentiates it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or any context for its use, leaving the agent to infer its applicability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

build_research_packC

Build a local pack with official docs plus external research.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
official_urlNo
max_research_pagesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states the function. No behavioral traits like side effects, idempotency, or limits are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, very concise. However, it sacrifices informativeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and 3 parameters, the description lacks completeness. It does not explain output, parameter roles, or behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no parameter meaning. The three parameters (topic, official_url, max_research_pages) are unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool builds a local pack combining official docs and external research. However, 'local pack' is vague and doesn't clearly differentiate from sibling tools like search_web or extract_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives, nor any prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

capture_siteC

Capture the important parts of a site and summarize them.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
hard_page_limitNo
soft_page_limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only mentions capture and summarize, but does not disclose if the tool modifies any state, requires authentication, has rate limits, or any side effects. The description is too brief to provide adequate transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but overly brief. It lacks structure and important details. While it has no wasted words, it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description does not explain what the tool returns (e.g., a summary text or structured data). With three parameters, no annotations, and insufficient context, the description fails to provide a complete picture for an AI agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has three parameters (url, hard_page_limit, soft_page_limit) with 0% description coverage in the schema. The description adds no meaning for these parameters, such as what the page limits control (e.g., number of pages to crawl or summarize). The agent gets no help understanding how to set them effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool captures and summarizes important parts of a site, using a specific verb+resource. However, 'important parts' is somewhat vague, and it could be improved by specifying criteria or scope, but it is sufficiently distinct from sibling tools like expand_links or extract_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as extract_content or search_web. There is no mention of prerequisites, limitations, or typical use cases, leaving the agent to infer usage entirely from the generic description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extract_contentA

Extract clean text content from a URL. Pass domain for authenticated extraction on paywall sites.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
domainNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose that this is a read-only operation or any safety behaviors. Without annotations, the description should communicate that it only extracts without modifying resources.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the core action, no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description adequately covers the main intent, though it could better differentiate from similar tools like capture_site.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description partially compensates by explaining domain's role for paywall, but the url parameter is merely implied as the target URL without further semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Extract' and resource 'clean text content from a URL', distinguishing it from siblings that capture full pages or recover articles. The mention of domain for paywall further clarifies scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on using domain for authenticated paywall extraction, but does not specify when to avoid this tool in favor of alternatives like capture_site or recover_url.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recover_dead_articleC

Recover a dead article into a local report with citations.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
titleNo
domainNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states the core transformation (recover into a report) but does not disclose behaviors such as whether it fetches content, requires permissions, modifies external state, or has rate limits. The agent is left to guess what 'recover' implies operationally.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 11 words, which is maximally concise. However, it sacrifices clarity and completeness for brevity. The structure is front-loaded with the core action, but it lacks supporting detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three parameters and an output schema exists, the description is too minimal. It fails to explain what a 'dead article' is, how 'recovery' works, what the local report contains, or any side effects. The output schema may cover return structure, but the overall process remains unclear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has three parameters (url required, title and domain optional) with 0% schema description coverage. The description adds no information about these parameters, leaving the agent to infer their purpose from names alone. For a tool with three parameters, this is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Recover a dead article into a local report with citations.' It specifies the resource (dead article) and the outcome (local report). However, it does not explicitly differentiate from the sibling tool 'recover_url', which may share a similar purpose, so it misses the opportunity to clarify when this tool is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like 'recover_url'. There is no mention of prerequisites, context (e.g., what constitutes a 'dead' article), or when not to use it. The description is purely functional without any contextual hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recover_urlC

Recover a dead, moved, or unavailable URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
titleNo
domainNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description should disclose behavior thoroughly. It only says 'recover' without explaining what that entails (e.g., fetching from archive, requesting redirection, or requiring authentication).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks necessary detail. It is front-loaded but could be expanded to cover parameters and behavior without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no parameter descriptions, the description is incomplete. It does not address what happens after recovery, error conditions, or output structure, despite an output schema existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and description does not explain any parameters beyond implying 'url' is the target URL. The optional 'title' and 'domain' parameters are not mentioned, leaving their purpose ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool recovers dead, moved, or unavailable URLs. It uses a specific verb and resource. While it does not explicitly distinguish from the sibling 'recover_dead_article', the focus on URL is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'recover_dead_article' or 'extract_content'. No context on prerequisites or typical scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_budgetsB

Get budget status for all providers.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states a read operation ('Get budget status'), but does not disclose any additional behavioral traits like rate limits, authentication requirements, or side effects. For a simple read, the description is minimally sufficient but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that effectively communicates the tool's purpose without unnecessary words. It is appropriately front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has no parameters, no nested objects, and an output schema exists (though not described), the description is nearly complete. It lacks a hint about the output structure, but since the output schema is present, this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and 100% schema description coverage, so the baseline is 4. The description does not need to add parameter information, but it is fine as is.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'budget status for all providers', indicating a read operation scoped to all providers. However, it does not differentiate from sibling tools like 'search_health' which might also provide status, so not a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'search_health' or 'cookie_health'. There are no exclusions or context about prerequisites, making it difficult for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_healthB

Get health status of all search providers.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It indicates a read operation ('Get') but omits any side effects, response expectations, or requirements. While the tool is simple, the description is too minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with no extraneous words. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description does not need to detail return values. It adequately states the tool's purpose, though it could hint at the output structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and 100% schema coverage, so the baseline is 4. The description adds no param details, but none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'health status of all search providers', distinguishing it from sibling tools like search_web which perform actual searches. However, it could be more specific about what 'health status' includes (e.g., uptime).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like search_web or search_budgets. It simply states the function without context or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_webC

Search the web using the Argus broker.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNodiscovery
queryYes
callerNomcp
free_onlyNo
session_idNo
max_resultsNo
include_attributionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only repeats the action and broker, with no disclosure of destructive potential, rate limits, auth requirements, or result behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence is too brief for a tool with 7 parameters and a complex schema. It under-specifies rather than being concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 params, 0% schema description coverage, output schema exists but unused), the description is completely inadequate. It fails to explain output, usage, or any contextual detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning no parameter explanations in the description. The schema has 7 parameters with defaults, but the description adds no meaning to any of them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: search the web using the Argus broker. It is a specific verb/resource pair. However, it does not differentiate from sibling tools like search_budgets or valyu_answer, leaving ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. There are multiple search-related siblings, but the description provides no context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test_providerC

Smoke-test a single provider.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoargus
providerYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It only states 'Smoke-test a single provider' without disclosing side effects, permissions, or output behavior, which is insufficient for a test tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise but overly brief, lacking essential details. True conciseness should retain clarity, which is missing here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 2 parameters, no annotations, and an output schema not visible, the description should provide more context. It fails to explain what the output indicates or how the tool interacts with providers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 2 parameters with no descriptions, and the tool description adds no meaning beyond the schema. Schema description coverage is 0%, yet the description does not explain what 'query' or 'provider' are or how they affect the test.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb (smoke-test) and resource (single provider), making the purpose clear. However, it lacks differentiation from sibling tools, which would elevate it to a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., valyu_answer, search_web). No context about use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

valyu_answerB

Get an AI-synthesized answer with citations. Uses Valyu Answer API ($0.10+/request).

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
fast_modeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It mentions cost ($0.10+/request) and that answers include citations. However, it does not disclose latency, rate limits, or whether the tool is idempotent or resouce-intensive. The cost hint adds value but behavioral coverage is moderate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, no redundant phrasing. Every word serves a purpose: the core function, the API source, and the cost. Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists (though not shown), return values are covered. But the tool has 0% parameter schema coverage and no usage guidance. The description is adequate for a simple tool but insufficient given the context of multiple sibling tools and lack of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description adds no parameter details. It does not explain what 'query' should contain (e.g., length, format) or what 'fast_mode' does (e.g., trade-off between speed and quality). This is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides an AI-synthesized answer with citations, using the Valyu Answer API. This distinguishes it from sibling tools like search_web (search results) and extract_content (raw extraction). The verb 'Get' and resource 'AI-synthesized answer' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., search_web, recover_article). The cost hint ($0.10+/request) is a usage consideration but does not provide when-not-to-use or compare to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.6.2
    • Changedsearch_web3 fields changed
      • addedInput schema / properties / caller
        Added value: +{
+  "default": "mcp",
+  "title": "Caller",
+  "type": "string"
+}
      • addedInput schema / properties / free_only
        Added value: +{
+  "default": false,
+  "title": "Free Only",
+  "type": "boolean"
+}
      • addedInput schema / properties / include_attribution
        Added value: +{
+  "default": false,
+  "title": "Include Attribution",
+  "type": "boolean"
+}
  2. 7 tool updatesv1.5.0
    • Addedargus_paths
    • Addedbuild_research_pack
    • Addedcapture_site
    • Addedcookie_health
    • Changedextract_content1 field changed
      • addedInput schema / properties / domain
        Added value: +{
+  "default": null,
+  "title": "Domain",
+  "type": "string"
+}
    • Addedrecover_dead_article
    • Addedvalyu_answer
  3. 7 tool updatesv0.1.0
    • First observedexpand_links
    • First observedextract_content
    • First observedrecover_url
    • First observedsearch_budgets
    • First observedsearch_health
    • First observedsearch_web
    • First observedtest_provider
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
Disambiguation4/5

Most tools have distinct purposes, but the pair recover_dead_article and recover_url could cause confusion, as both deal with recovery. Descriptions help differentiate, but slight overlap remains.

Naming Consistency4/5

The majority follow a verb_noun pattern (e.g., search_web, capture_site). Three tools (argus_paths, cookie_health, valyu_answer) deviate with noun_noun patterns, but the inconsistency is minor.

Tool Count5/5

With 13 tools, the set covers essential research and archiving tasks without being overwhelming. Each tool feels justified for the domain.

Completeness4/5

Core workflows (search, capture, extract, recover, ask) are covered. Minor gaps exist, like missing management of saved packs, but these are not critical for the intended use.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • entroute by entroute

    entrouteofficial

    entroute
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables web search for AI agents with pay-per-search in USDC, no API keys needed.
    MIT

  • GroundRoute

    PROJECT-B-26
    A
    license
    A
    quality
    B
    maintenance
    Web search for AI agents across 6 engines (Serper, Brave, Exa, Tavily, Firecrawl, Perplexity) through one search tool. Routes each query to the cheapest engine that clears a quality bar and caches repeats. Hosted, streamable-HTTP, BYOK supported.
    1
    1
    MIT

  • Agent Search MCP

    lennney
    A
    license
    A
    quality
    F
    maintenance
    Free multi-source web search server for AI agents, with confidence scoring and token optimization.
    3
    181
    Apache 2.0

  • Search MCP Server

    ilgizar-valiullin
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to perform unified web searches, GitHub, and GitLab searches with caching, reranking, and fallback across multiple providers.
    4
    49
    18
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Khamel83/argus'

If you have feedback or need assistance with the MCP directory API, please join our Discord server