Skip to main content
Glama
deenesjakoruzh
Mr-remon219

search-boost-mcp

by Mr-remon219
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

SearchBoost

Multi-engine web search & evidence synthesis for AI coding agents
One shared core runtime, deeply adapted for MCP, Pi, and DeepSeek Harness

version npm version Node version License Architecture Free tier

English · 中文文档

NOTE

Release & Branch Notice: The formerly standalone pi-search-boost and dsh-search-boost projects are merged into one codebase under lib/. Documented commands specifying @latest retrieve the official published npm package. To test code that is not in a published release, check out the branch or tag you need and follow Installation from Source & Development.

v0.2.2: adds AnySearch, correlation-aware fusion scoring and batched Jev target research with approved-result pagination. Includes release-audit fixes for version matching, publication timestamps and cache clearing. See the release and migration notes. A source merge does not publish npm; @latest only includes this version after a separate npm publication.

Table of Contents

Related MCP server: gemini-search-mcp

Key Features

  • Multi-Engine Parallel Fusion (fused_search)
    Queries multiple search providers in parallel. Features an out-of-the-box keyless free pool (Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch) and a keyed API pool (Tavily, Brave, Exa, AnySearch). Automatically performs cross-engine URL deduplication, domain routing, and relevance re-ranking.

  • Clean Webpage Content Extractor (fetch_page)
    Fetches the origin first for low latency, with optional same-route curl compatibility fallback and Jina Reader backup. Strips CSS, JS, and ad clutter. Supports focused contextual paragraph extraction via focus, backed by in-memory caching and size limits.

  • X / Twitter Community Intelligence (x_search)
    Retrieves public posts, user timelines, and discussion threads via official xAI API or an anonymous fallback channel. Recovers accurate UTC timestamps from Snowflake post IDs and enforces local author/date filtering without hallucination.

  • Jev Adaptive Evidence Loop (adaptive_search · Experimental)
    Accepts task context, keyword alternatives and acceptance targets. Each round uses at most three Jev calls: plan, score and coverage. Returns approved URLs, titles and descriptions with cursor pagination and no fixed cumulative result-count cap; execution remains budgeted.

  • Native Multi-Agent Parallel Research
    Bundles search-boost and search-boost-parallel-research skills. In hosts supporting subagents (Cursor, Claude Code, Pi, DSH), tasks can be dispatched to parallel Searchers (gathering evidence) and Summarizers (pure synthesis without tools), supporting both Fast and Complex waves.

  • Unified Core Across All Host Ecosystems
    A single, host-neutral core runtime powering standard Model Context Protocol (MCP) servers, alongside native extensions for Pi and Cordis plugin bundles for DeepSeek Harness (DSH).

  • Zero-Config Onboarding & Strict Security
    Requires zero API keys to start using the free engine pool. Sensitive credentials are stored as plaintext in local private configs with restricted file permissions (POSIX 0600); this is not encryption at rest. Uses local networking and proxy DNS, with bounded requests and explicit fallback, with zero credential leakage into model prompts.

System Architecture

SearchBoost follows a "One Core, Three Adapters" architecture. All search logic, content parsing, deduplication algorithms, and network safety mechanisms reside in the shared core:

                    SearchBoost TUI / CLI
             installation · configuration · updates
                              │
                    Shared SearchBoost Core
                    lib/runtime.mjs facade
              search · fetch · X · adaptive evidence
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         MCP Adapter      Pi Adapter     DSH Adapter
         stdio server     extension      Cordis bundle
              │               │               │
     ┌────────┴────────┐      ▼               ▼
     │ Cursor / Claude │      Pi       DeepSeek Harness
     │ Codex / Grok    │
     │ Antigravity     │
     └─────────────────┘

  • Core (lib/): Host-neutral algorithms, engine orchestration, Jev client protocol, and network safety policies.

  • Adapters (adapters/): Maps core operations into host-specific protocols (MCP JSON-RPC, Pi Extension API, DSH Cordis lifecycle).

  • Agents (agents/): Host prompt contracts, workflow templates, and native skill definitions.

Supported Hosts Matrix

Host

Integration Type

Files / Mechanism

Capabilities & Notes

Cursor / Cursor CLI

MCP + Skills

~/.cursor/mcp.json / skills/

Supports CLI auto-approval (cli-config.json), session start injection, parallel research skill

Claude Code

MCP + Prompts

Official claude MCP config

Full multi-engine search and page extraction tools with prompt boundaries

Codex

MCP + Prompts

Host MCP configuration

Seamless access to fused search, X retrieval, and reader tools

Grok Build

MCP + Plugin

MCP config + bundled plugin

Automatically syncs and installs companion plugin when grok CLI is available

Google Antigravity

MCP + Workspace

Workspace MCP configuration

Per-project workspace guidance and full search tool suite

Pi

Native Extension

~/.pi/agent/extensions/ / prompts/

Registers native extension, /fast-parallel, /complex-parallel, searcher/summarizer roles

DeepSeek Harness

Native Bundle

cordis.patch.yml / dsh plugin

Integrated with Cordis runtime; provides native research_parallel subagents and call cards

Quick Start (30 Seconds)

Prerequisites

  • Node.js: >= 22.13.0

  • Package Manager: npm (or pnpm)

1. Install & Launch the Dashboard

# Install globally
npm install -g search-boost

# Launch the interactive terminal UI (TUI)
search-boost
TIP

Zero API Keys Required to Start: SearchBoost includes a robust free engine pool (Bing, DuckDuckGo, Yahoo, Exa-free). You can begin searching immediately without signing up for any paid provider!

2. 3-Step Setup Wizard

  1. Select Setup in the TUI menu. Configure engine keys (or skip to use free tier) and optional X credentials.

  2. Check the agents you want to integrate (Cursor, Claude Code, Pi, etc.), confirming auto-approval and native search replacement.

  3. Restart or reload your chosen agents, then ask them to research anything in conversation!

Upgrade & Migration Guide

1. Routine Updates: Upgrading via TUI

Whether you run unified search-boost or have legacy pi-search-boost / dsh-search-boost installations, select Update in the TUI to upgrade everything:

# Option 1: Open the interactive menu
search-boost
# -> Select "Update"

# Option 2: Run headless update
search-boost upgrade -y

Update Behavior: Fetches the latest published release, updates SearchBoost, and refreshes prompt assets across all configured agents while preserving existing keys, layer choices, and permission settings.

2. Migrating from Legacy search-boost-mcp

IMPORTANT

If you have the old global packagesearch-boost-mcp installed, npm cannot automatically replace the global binary across package renames. Use the one-line npx migration command:

# Execute safe migration via npx
npx --yes --package=search-boost@latest -- search-boost migrate -y

# Once migrated, routine updates only require:
search-boost
# -> Select "Update" (or search-boost upgrade -y)

Interactive Console (TUI)

Launch search-boost without arguments to access the interactive dashboard built with Clack. Manage installation, updates, and credentials effortlessly:

Menu Option

Purpose

Setup

Complete initial walkthrough: configure engines, search layers, X credentials, and install agents.

Install / update agents

Install or refresh selected host integrations, preserving existing credentials and layer settings.

Update

One-click upgrade: checks npm for updates, upgrades SearchBoost, and refreshes all installed agents (including legacy Pi/DSH adapters).

API keys / Search layer

Manage Tavily, Brave, Exa and optional AnySearch credentials, and change the default search layer (free / api).

X credentials

Manage X (Twitter) authentication; supports one-click import from local Grok login.

Jev credentials (experimental)

Configure TypeSafe Jev cognitive engine endpoint and Bearer token.

Native web search

Enable or disable host-native search for hosts supporting config switches.

Status

Inspect current engine availability, configuration status, and active integrations.

Print MCP snippet

Print MCP JSON configuration snippets to stdout for manual setups.

Uninstall

Safely remove SearchBoost integrations from selected agents, keeping user configurations intact.

Tool Suite & Usage Guide

When integrated, agents automatically receive standard tool definitions and autonomously determine when to call them.

Tool Responsibilities & Boundaries

Tool

Best Used For

Boundary / Non-Goals

fused_search

Parallel multi-engine querying, deduplication, and diversity re-ranking

A single search step; follow-up decisions remain with the parent agent

fetch_page

Reading clean content from public URLs with optional keyword focus

Not a browser with login state; cannot access internal/private networks

x_search

Retrieving public X posts, author timelines, or discussion threads

Does not guarantee exhaustive comment threads or total sentiment sampling

adaptive_search

Experimental: Jev-guided autonomous follow-up and evidence evaluation

Approved URLs and descriptions; model approval is not independent verification

search_stats

Reading engine status, memory cache hits, and recent diagnostic stats

Read-only; configuration readiness does not guarantee active external network reachability

search_layer

Viewing or switching compatibility search layer in MCP

show is read-only; changing layers mutates persistent configuration on disk

1. fused_search Multi-Engine Search

Dispatches queries across engines concurrently, normalizes URLs, strips redirects, and applies diversity filters.

Tool Arguments Example (JSON):

{
  "query": "Node.js 22 built-in WebSocket API guide",
  "include_domains": ["nodejs.org", "developer.mozilla.org"],
  "engine_pool": "free",
  "ranking": "balanced",
  "complexity": "simple",
  "max_results": 5
}

  • engine_pool: free (keyless Bing, DuckDuckGo, Yahoo, Exa-free), api (configured paid engines only), or hybrid (all available engines).

  • ranking: Scoring presets: balanced (default), research (favors authoritative/documentation sources), or fresh (favors recent publications).

  • complexity: simple (1 query variant), medium (up to 2 variants), complex (up to 3 deep variants).

  • community: Boolean (false by default). Set to true to blend real-time X developer discussions into the final result quota.

2. fetch_page Smart Content Reader

Reads webpage content from search URLs. Reads and cleans the origin first; curl handles transport compatibility when installed, and Jina Reader is the backup.

Tool Arguments Example:

{
  "url": "https://nodejs.org/api/globals.html",
  "focus": "AbortSignal.any"
}

  • focus (Optional): Filters and retains paragraphs matching the target keywords.

    TIP

    Afocus miss does not prove the information is absent from the page. If in doubt, re-fetch without focus to inspect the full context.

3. x_search X (Twitter) Intelligence

Designed for real-time technical tracking and first-party developer updates. Supports keyword search, author timelines, and thread conversations.

Tool Arguments Example:

{
  "query": "Claude 3.7 Sonnet hybrid reasoning from:AnthropicAI",
  "mode": "keyword",
  "max_results": 5
}

  • Precise Timestamps: When platform timestamps are missing or inconsistent, recovers true UTC creation times from 64-bit Snowflake IDs.

  • Native Operators: Full support for from:username, since:YYYY-MM-DD, and until:YYYY-MM-DD.

4. adaptive_search Jev Evidence Loop (Experimental)

Vercel support: in TUI → Jev credentials, enter https://ai-gateway.vercel.sh/v1 and a Vercel AI Gateway key. SearchBoost selects the official SDK evaluation model typesafe-ai/jev, not chat completions. The default TypeSafe /systemone path remains supported. Both paths use only the canonical user Jev credential, not environment keys, and respect server rate-limit delays.

The caller supplies task context, keyword alternatives and explicit acceptance questions. Jev chooses query strategies and engines, then scores retrieved evidence and judges which targets need another round. Each round has at most three logical requests, not one request per URL.

{
  "tasks": [{
    "context": "ExampleDB 4.2 upgrade impact",
    "targets": [{
      "id": "migration",
      "keywords": ["migration guide", "upgrade guide"],
      "question": "What migration steps are required from 4.1 to 4.2?"
    }]
  }],
  "page_size": 20
}

  • Up to 6 tasks, 4 targets per task, 12 total targets; legacy questions input remains supported.

  • results is a flat {url, title, description} list containing only assessed, approved material, not unassessed/rejected candidates.

  • Read more with {"cursor":"<nextCursor>"}: no new search or Jev call. Pages default to 20 results (max 50) and have a byte budget, but cumulative approved results have no fixed count cap.

  • Inspect coverageComplete and warnings. End of pagination is not exhaustive search, and model approval is not independent fact verification.

  • Results are process-local, retained for up to 30 minutes / 32 recent result sets; expiry, eviction or restart invalidates cursors.

  • Optional task time_range distinguishes publication dates from event dates; unknown dates cannot qualify as today's evidence.

See the adaptive-search contract and limitations.

Engine Pools & Scoring Presets

engine_pool selects engines, ranking selects shared cross-pool weights, and complexity controls only budget. AnySearch is one logical engine: anonymous in free, key-required in api, and key-preferred in hybrid. Configure ANYSEARCH_API_KEY or config keys --set anysearch=KEY.

Engine

balanced

research

fresh

bing

0.957

0.927

1.020

ddg

0.981

0.903

0.927

yahoo

0.957

0.877

0.902

exa-free

1.004

1.085

0.951

tavily

1.049

1.105

1.084

brave

1.004

0.951

1.125

exa

1.049

1.146

1.063

anysearch

1.004

1.042

0.951

These are uncalibrated cold-start priors, not measured quality rankings. consensus-v2.1 combines original ranks, related-provider discounts and max+log consensus, with metadata adjustments capped at 20%. Quality and list-selection scores stay separate; zero-weight sources cannot vote. Recalibrate old min_score thresholds. See scoring and migration and pool routing.

Parallel Multi-Agent Research Workflows

One shared workflow with three host bindings. The parent agent splits a question into independent tracks; each searcher gathers evidence with fused_search and fetch_page; a tool-less summarizer (or the parent itself) then turns the reports into one answer.

                        [ Parent Agent ]
                   splits tracks · owns the answer
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
       [ Searcher A ]                  [ Searcher B ]
   fused_search · fetch_page       fused_search · fetch_page
              │                               │
              └───────────────┬───────────────┘
                              ▼
                      [ Summarizer ]
                   no tools · synthesis only
                              ▼
                     [ Parent Report ]

Host

Entry point

How children run

Pi

/fast-parallel and /complex-parallel prompts; the search-parallel-subagent tool; searcher / summarizer roles

Each searcher is a child process that explicitly loads the SearchBoost Pi extension (adapters/pi/index.js) and may call only fused_search and fetch_page; summarizers launch with --no-tools. The caller chooses the wave size — this runner sets no concurrency cap.

DeepSeek Harness

Native research_parallel tool

Children spawn on the same Cordis context through the host's subagent service. Searchers receive toolFilter.allow = ['fused_search','fetch_page']; summarizers receive an empty allowlist. Before a wave, research_parallel verifies both tools are registered and refuses to spawn otherwise. Handles are disposed on success and failure, and maxDepth stays at 1, so children cannot nest further research.

MCP hosts (Cursor, Claude Code, Codex, Grok, Antigravity)

Bundled search-boost-parallel-research skill

The skill embeds the same roles and workflow and runs them through whatever subagent mechanism the host provides. A host without usable delegation falls back to serial research by the parent.

Installing into an MCP host also installs the companion search-boost routing skill, which picks the right tool for an open-ended question.

  • Fast mode: one searcher wave, then parent synthesis — no summarizer and no second wave.

  • Complex mode: one to three waves with a gap review in between; another wave starts only when a material gap remains, and the run stops early when the evidence is sufficient. These wave limits are workflow instructions, not global quotas enforced across independent tool calls.

  • Fallback: if the host cannot delegate, the parent researches serially and says so instead of pretending a wave ran.

IMPORTANT

A child returningok means it finished with non-empty text, not that its claims are verified. Failed or partial reports stay visible, but their URLs are excluded from the successful aggregate, and final judgment always belongs to the parent.

For Pi/DSH child-tool loading, stale pi-search-boost references, and the retired deep_research tool, see Subagent tool setup and diagnosis.

Security

API keys use a credential store this tool owns. They are not written into prompts, tool results or shell profiles:

  • Private file permissions: keys live in ~/.search-boost/config/keys.json (redirect the root with SEARCH_BOOST_HOME). On POSIX the store directory is 0700 and the file is 0600; a rewrite is built from a fresh 0600 temporary file rather than written in place, so an existing file is never widened. Backups and upgrade receipts under the same root are 0600 as well. An env-overridden directory keeps its own mode, while the credential file is still created 0600. Windows has no POSIX mode bits — ACL inheritance applies there.

  • Atomic, locked writes: replacement uses an O_EXCL temporary file plus rename, so a reader sees either the old or the new file and never a partial one; a failed write cleans up after itself and leaves the previous file untouched. Read-modify-write cycles take an exclusive lock, so two writers cannot silently lose each other's update, and a rejected change does not touch the file at all.

  • Never echoed back: a key is only sent to the engine it belongs to (Tavily, Brave, Exa and AnySearch request parameters/headers). Status output, search-boost config keys --show and the doctor report print masked values (abcd****wxyz); error messages are tested not to contain credential material, and Jev evaluation payloads deliberately carry no key, masked key or fingerprint. AnySearch uses anonymous quota in free, requires a key in api, and prefers a configured key in hybrid. Its potentially credential-bearing error envelopes are never echoed or persisted.

CLI Command Reference (Headless & CI)

In addition to the interactive TUI, SearchBoost provides a comprehensive CLI for scripting and automation:

# ----------------- Core & Interactive -----------------
search-boost                                # Launch interactive dashboard (TUI)
search-boost status                         # Print active configuration and host summary
search-boost --help                         # Display full CLI documentation

# ----------------- Headless Installation -----------------
search-boost install -t cursor -y           # Install for Cursor with auto-approval
search-boost install -t claude,codex --keep-native  # Install while preserving host native search
search-boost install -t antigravity --workspace /path/to/project # Target a specific workspace
search-boost install -t pi -y               # Mount Pi extension and prompt templates
search-boost install -t dsh --profile web   # Connect to DeepSeek Harness web profile
search-boost install -t cursor --dry-run    # Preview installation without writing files

# ----------------- Configuration Management -----------------
search-boost config keys                    # Manage API keys from CLI
search-boost config keys --set anysearch=KEY  # Configure the AnySearch key (ANYSEARCH_API_KEY)
search-boost config layer                   # Switch default layer (free / api)
search-boost config x --import-grok         # Import X credentials from local Grok login
search-boost config jev                     # Configure Jev endpoint and token

# ----------------- Diagnostics & Health -----------------
search-boost doctor                         # Run offline diagnostic checks
search-boost doctor --strict                # Strict mode (exits non-zero on warnings)
search-boost doctor --json                  # Output machine-readable JSON report

# ----------------- Uninstall -----------------
search-boost uninstall -t cursor,claude -y  # Remove integrations from selected hosts

Installation from Source & Development

Use this path to contribute to SearchBoost, or to test code that is not in a published release yet. Everywhere else, @latest refers to the published package.

Prerequisites

  • Node.js >= 22.13.0 (matching package.json)

  • git and npm

  • Optional: curl, for the same-route transport-compatibility fallback in fetch_page

Set up a checkout

# 1. Clone the repository
git clone https://github.com/Mr-remon219/search-boost.git
cd search-boost

# 2. Install dependencies exactly as CI does
npm ci

# 3. Regenerate the bundled Grok plugin assets
npm run plugin:sync-grok

The clone lands on the repository's default branch. To test a different branch or tag, check it out before installing dependencies (git checkout BRANCH_OR_TAG).

Run it without a global install

node cli.mjs                  # interactive TUI straight from the checkout
node cli.mjs status           # one-shot status summary
node cli.mjs install -t pi -y # mount the Pi extension from this checkout
node cli.mjs install -t dsh --profile web

node cli.mjs accepts the same commands as the installed search-boost binary. If you want the bare command in your terminal, link the checkout instead of installing from npm:

npm link        # or: npm install -g .
search-boost

After changing adapter or agent assets, re-run the same install command for that host (node cli.mjs install -t HOST) so the host picks up the new files, then restart or reload that host.

Test gates before a PR

Command

What it covers

npm run check

Syntax check across the CLI, core, adapters and scripts

npm run prepublishOnly

The full offline suite: plugin sync, syntax, CLI, install, doctor, fusion, X, engines, X auth, Jev, key authority, dry-run, network, search routing, adapters, parallel research, upgrade, MCP and smoke

npm run test:network

Proxy retries, curl fallback, request bounds and compatibility regressions

npm run test:adapters

MCP, Pi and DSH adapter protocol suites plus Pi subagent settings migration/diagnosis

npm run test:parallel

Searcher/summarizer contracts, DSH dispatch preflight, cancellation and tool isolation

npm run test:adaptive

Jev adaptive evidence loop

npm run smoke

MCP JSON-RPC protocol smoke test

These suites run against loopback fixtures and process doubles, so no engine keys are needed; a green npm run prepublishOnly is the bar for a PR.

Friendly Links

License

This project is licensed under the MIT License.

Available Tools

6 tools
fetch_pageFetch PageA
Read-only

Read a known http(s) URL without searching again. Fetches the origin first, cleans HTML, and uses same-route curl compatibility fallback and Jina Reader backup when needed. Strips CSS/JS/ad chrome. Use focus for matching paragraphs, or omit it for the readable body. A focus miss is not proof the page lacks the answer: retry without focus. Proxies handle destination DNS; direct routes use local networking. Five proxy connection failures permit direct fallback. HTTP(S), TLS, cancellation and response-size limits still apply. Not an authenticated browser.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYeshttp(s) URL to fetch
focusNoKeep paragraphs matching these terms (optional; full page is returned when omitted)

Output Schema

ParametersJSON Schema
NameRequiredDescription
urlYes
viaYes
tookMsYes
contentYes
focusMissNo
truncatedNo
limitationNo
word_countYes

TDQS

A4.7/5.0
Behavior5/5

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

Even with readOnlyHint and destructiveHint annotations already present, the description adds substantial behavioral detail: it fetches origin first, cleans HTML, uses curl compatibility and Jina Reader fallbacks, strips chrome, handles proxy/DNS routing, permits direct fallback after five proxy failures, and notes it is not an authenticated browser. This goes well beyond the annotations and gives the agent a realistic picture of what will happen.

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 front-loaded with the core purpose, and every subsequent sentence contributes useful operational detail such as fallback behavior, stripping, proxy handling, and limitations. It is dense but not bloated, avoiding jargon-filled filler and keeping all content relevant to correct invocation.

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?

Given the tool has an output schema, the description does not need to explain return formats. It sufficiently covers intended use, parameter behavior, fallback mechanisms, network/proxy behavior, limits, and non-authentication. The definition is complete enough for an agent to know when and how to call it correctly and what caveats apply.

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?

Schema coverage is 100% and both parameters already have clear descriptions, so the baseline is 3. The description adds value beyond the schema by explaining the intended semantics of focus as paragraph matching, noting that a focus miss does not prove absence of an answer, and reinforcing that url is a known URL to fetch rather than a search query.

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 opening sentence 'Read a known http(s) URL without searching again' states a specific verb, resource, and clear scope. It distinguishes the tool from the sibling search tools by focusing on fetching an existing URL rather than discovering one, leaving no ambiguity about its role.

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

Usage Guidelines4/5

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

The description clearly tells the agent to use this tool when a URL is already known and not to search again. It also gives explicit guidance for the focus parameter and instructs retrying without focus on a miss. However, it does not name the sibling search tools explicitly as alternatives, so the contrast is implied rather than fully explicit.

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

search_layerSearch LayerA

Inspect the current search layer with layer=show (default, no change). layer=free or api persists a new default: only change it when authorized. free = free — compatibility default engine_pool=free (keyless). api = api — compatibility default engine_pool=hybrid (keyless plus configured APIs). For a single search, use fused_search.engine_pool instead; legacy api maps to hybrid, not the strict api pool.

ParametersJSON Schema
NameRequiredDescriptionDefault
layerNoshow (default) reads current state; free/api persist a new default and require authorization

TDQS

A4.7/5.0
Behavior4/5

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: layer=show causes no change, while free/api persist a new default and require authorization. It also discloses the compatibility mapping (legacy api maps to hybrid, not strict api pool), which goes beyond the structured fields.

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 dense but mostly earns its length, with the default behavior and key warning front-loaded. The 'free = free' and 'api = api' phrasing is slightly redundant and could be tightened, but it remains efficient and readable.

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 tool with one optional parameter, full schema coverage, and no output schema, the description covers all essential context: default behavior, persistence side effects, authorization requirement, engine_pool mapping, and the alternative tool for single searches. Nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds meaning beyond the enum descriptions by explaining the engine_pool implications of each value: free maps to engine_pool=free (keyless), api maps to engine_pool=hybrid, and legacy api does not map to the strict api pool. This is valuable semantic nuance that the schema alone does not convey.

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 names a specific resource (the search layer) and a clear action set: inspect with layer=show or persist a new default with free/api. It also explicitly differentiates this tool from fused_search, making its purpose and scope unambiguous.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: use layer=show to inspect, only change the default when authorized, and for a single search use fused_search.engine_pool instead. This routes the agent to the correct sibling in the exact condition that matters.

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

search_statsSearch StatsA
Read-only

Read-only diagnostics for failed or empty searches: cache hits/misses, tier counts, engine availability, and recent activity. Call with no arguments. Inspect tool warnings too; an empty result alone does not imply missing credentials or justify changing configuration.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
layerYes
recentYes
enginesYes
xSourceYes
cacheHitsYes
startedAtYes
xOfficialYes
tierCountsYes
cacheMissesYes
keyedEnginesYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds valuable behavioral nuance: an empty result does not imply missing credentials or justify configuration changes, and tool warnings should be inspected. This goes beyond what annotations convey.

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 three short sentences with no filler. It leads with the tool's purpose, then the no-argument requirement, then the important interpretation caveat. Every sentence adds information.

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 no-argument diagnostics tool with an output schema and safety annotations, the description is complete. It covers what the tool reports, how it should be called, and how to interpret results, leaving no critical gap for an agent deciding whether and how to invoke it.

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 the schema already reflects that with an empty properties object. The description reinforces this with 'Call with no arguments,' which is helpful but does not need to add much. Baseline 4 is appropriate for a zero-parameter tool.

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 names a specific verb and resource: 'Read-only diagnostics for failed or empty searches' and enumerates concrete contents (cache hits/misses, tier counts, engine availability, recent activity). It is clearly distinguishable from the sibling search tools, which perform searches rather than diagnose them.

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

Usage Guidelines4/5

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

The description explicitly states when this tool is relevant ('diagnostics for failed or empty searches') and instructs 'Call with no arguments.' It does not name alternative tools or explicitly say when not to use it, but the diagnostic context and no-argument call convention provide clear usage guidance.

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.

  1. 7 tool updatesv0.2.2
    • Addedadaptive_search
    • Removeddeep_research
    • Changedfetch_page3 fields changed
      • changedInput schema / properties / focus / description
        Previous value: -"Keep paragraphs matching these terms (~90% token savings)"New value: +"Keep paragraphs matching these terms (optional; full page is returned when omitted)"
      • addedOutput schema / properties / focusMiss
        Added value: +{
+  "type": "boolean"
+}
      • addedOutput schema / properties / limitation
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "message"
+  ],
+  "type": "object"
+}
    • Changedfused_search37 fields changed
      • addedInput schema / properties / community
        Added value: +{
+  "description": "Add X developer/community voices when relevant; default false; shares final max_results",
+  "type": "boolean"
+}
      • addedInput schema / properties / complexity / description
        Added value: +"Budget, query variants and depth only; default medium"
      • changedInput schema / properties / complexity / enum
        Previous value: -[
-  "auto",
-  "simple",
-  "medium",
-  "complex"
-]New value: +[
+  "simple",
+  "medium",
+  "complex"
+]
      • addedInput schema / properties / engine_pool
        Added value: +{
+  "description": "Which engines to search. Omitted: compatibility layer free→free, api→hybrid",
+  "enum": [
+    "free",
+    "api",
+    "hybrid"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / engine_weights
        Added value: +{
+  "additionalProperties": false,
+  "description": "Override preset engine weights; never enables or selects engines",
+  "properties": {
+    "anysearch": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "bing": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "brave": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "ddg": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "exa": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "exa-free": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "tavily": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "yahoo": {
+      "minimum": 0,
+      "type": "number"
+    }
+  },
+  "type": "object"
+}
      • changedInput schema / properties / engines / description
        Previous value: -"Engine subset override"New value: +"Optional exact engine selection overriding engine_pool; unavailable or disabled engines are skipped with warnings"
      • changedInput schema / properties / engines / items / enum
        Previous value: -[
-  "bing",
-  "ddg",
-  "yahoo",
-  "exa-free",
-  "antigravity",
-  "tavily",
-  "brave",
-  "exa"
-]New value: +[
+  "bing",
+  "ddg",
+  "yahoo",
+  "exa-free",
+  "anysearch",
+  "tavily",
+  "brave",
+  "exa"
+]
      • addedInput schema / properties / engines / minItems
        Added value: +1
      • addedInput schema / properties / exclude_domains / description
        Added value: +"Exclude these hostnames from results"
      • addedInput schema / properties / include_domains / description
        Added value: +"Restrict results to these hostnames, e.g. nodejs.org; useful for official sources"
      • addedInput schema / properties / layer / description
        Added value: +"Deprecated compatibility alias: free→free pool, api→hybrid pool; engine_pool takes precedence; not persisted"
      • addedInput schema / properties / min_score
        Added value: +{
+  "description": "Minimum consensus-v2 quality score; old thresholds need recalibration, default 0",
+  "minimum": 0,
+  "type": "number"
+}
      • changedInput schema / properties / queries / description
        Previous value: -"Extra query variants (max 3)"New value: +"Distinct query angles, not paraphrases; use up to 3 variants"
      • addedInput schema / properties / ranking
        Added value: +{
+  "description": "Final engine-weight preset only; default balanced",
+  "enum": [
+    "balanced",
+    "research",
+    "fresh"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / recency / description
        Added value: +"Favor recent dated results; omit for historical or version-pinned documentation"
      • addedOutput schema / properties / communityUsed
        Added value: +{
+  "type": "boolean"
+}
      • addedOutput schema / properties / effectiveWeights
        Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "type": "object"
+}
      • addedOutput schema / properties / enginePool
        Added value: +{
+  "enum": [
+    "free",
+    "api",
+    "hybrid"
+  ],
+  "type": "string"
+}
      • addedOutput schema / properties / engineStats / additionalProperties / properties / attempts
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / engineStats / additionalProperties / properties / successes
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / ranking
        Added value: +{
+  "enum": [
+    "balanced",
+    "research",
+    "fresh"
+  ],
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / consensusBoost
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / contributions
        Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "type": "object"
+}
      • addedOutput schema / properties / results / items / properties / dateStatus
        Added value: +{
+  "enum": [
+    "known",
+    "unknown",
+    "conflicting"
+  ],
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / engineRanks
        Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "type": "object"
+}
      • addedOutput schema / properties / results / items / properties / evidenceScore
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / id
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / kind
        Added value: +{
+  "enum": [
+    "web",
+    "x"
+  ],
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / metadataDelta
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / provenance
        Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "engine": {
+        "type": "string"
+      },
+      "published": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "rank": {
+        "type": "number"
+      },
+      "snippet": {
+        "type": "string"
+      },
+      "title": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      },
+      "variant": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "engine",
+      "rank",
+      "url",
+      "title",
+      "snippet",
+      "published"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / results / items / properties / rankScore
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / scoreVersion
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / selectionScore
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / username
        Added value: +{
+  "type": "string"
+}
      • changedOutput schema / properties / results / items / required
        Previous value: -[
-  "title",
-  "url",
-  "domain",
-  "snippet",
-  "score",
-  "engines",
-  "published"
-]New value: +[
+  "title",
+  "url",
+  "domain",
+  "snippet",
+  "score",
+  "scoreVersion",
+  "rankScore",
+  "evidenceScore",
+  "consensusBoost",
+  "metadataDelta",
+  "engineRanks",
+  "contributions",
+  "provenance",
+  "dateStatus",
+  "engines",
+  "published"
+]
      • addedOutput schema / properties / scoreVersion
        Added value: +{
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "query",
-  "layer",
-  "tier",
-  "tookMs",
-  "cacheHit",
-  "resultCount",
-  "results"
-]New value: +[
+  "scoreVersion",
+  "query",
+  "layer",
+  "tier",
+  "tookMs",
+  "cacheHit",
+  "resultCount",
+  "enginePool",
+  "ranking",
+  "effectiveWeights",
+  "communityUsed",
+  "results"
+]
    • Changedsearch_layer1 field changed
      • addedInput schema / properties / layer / description
        Added value: +"show (default) reads current state; free/api persist a new default and require authorization"
    • Changedsearch_stats2 fields changed
      • addedOutput schema / properties / keyedEngines
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "configured": {
+      "type": "number"
+    },
+    "enabled": {
+      "type": "number"
+    },
+    "enabledNames": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "configured",
+    "enabled",
+    "total",
+    "enabledNames"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "startedAt",
-  "layer",
-  "cacheHits",
-  "cacheMisses",
-  "tierCounts",
-  "engines",
-  "xOfficial",
-  "xSource",
-  "recent"
-]New value: +[
+  "startedAt",
+  "layer",
+  "cacheHits",
+  "cacheMisses",
+  "tierCounts",
+  "keyedEngines",
+  "engines",
+  "xOfficial",
+  "xSource",
+  "recent"
+]
    • Changedx_search10 fields changed
      • addedInput schema / properties / allowed_x_handles
        Added value: +{
+  "description": "Only these authors; mutually exclusive with excluded_x_handles",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 20,
+  "type": "array"
+}
      • addedInput schema / properties / excluded_x_handles
        Added value: +{
+  "description": "Exclude these authors; mutually exclusive with allowed_x_handles",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 20,
+  "type": "array"
+}
      • changedInput schema / properties / from_date / description
        Previous value: -"YYYY-MM-DD"New value: +"Inclusive start date, YYYY-MM-DD (UTC)"
      • addedInput schema / properties / max_results / description
        Added value: +"Requested result limit, 1–10"
      • addedInput schema / properties / post_id / description
        Added value: +"Real X post ID or status URL for type=thread"
      • addedInput schema / properties / query / description
        Added value: +"Search terms and X filters (e.g. from:OpenAI), or a natural-language topic for semantic mode"
      • changedInput schema / properties / to_date / description
        Previous value: -"YYYY-MM-DD"New value: +"Inclusive end date, YYYY-MM-DD (UTC)"
      • addedInput schema / properties / type / description
        Added value: +"Mode: keyword (default) or semantic uses query; user uses username; thread uses post_id"
      • addedInput schema / properties / username / description
        Added value: +"X account handle for type=user"
      • addedOutput schema / properties / note
        Added value: +{
+  "type": "string"
+}
  2. 2 tool updatesv0.1.6
    • Changeddeep_research1 field changed
      • addedInput schema / properties / round
        Added value: +{
+  "description": "Research round number (auto-increments when omitted)",
+  "minimum": 1,
+  "type": "integer"
+}
    • Changedfused_search4 fields changed
      • addedOutput schema / properties / engineStats
        Added value: +{
+  "additionalProperties": {
+    "additionalProperties": false,
+    "properties": {
+      "errors": {
+        "type": "number"
+      },
+      "note": {
+        "type": "string"
+      },
+      "used": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "used",
+      "errors"
+    ],
+    "type": "object"
+  },
+  "type": "object"
+}
      • addedOutput schema / properties / enginesRequested
        Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / enginesUsed
        Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / warnings
        Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  3. 6 tool updatesv0.1.2
    • First observeddeep_research
    • First observedfetch_page
    • First observedfused_search
    • First observedsearch_layer
    • First observedsearch_stats
    • First observedx_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 6 tools

Disambiguation4/5

Each tool has a distinct role: fused_search for one-shot web search, x_search for X-specific retrieval, fetch_page for URLs, adaptive_search for multi-task research, search_stats for diagnostics, and search_layer for persistent configuration. fused_search and adaptive_search could be confused, but their descriptions clearly separate precise lookups from Jev-driven multi-task research.

Naming Consistency3/5

The names are readable and all lowercase snake_case, but they mix conventions: fused_search/x_search/adaptive_search use modifier_search, search_layer/search_stats use search_noun, and fetch_page is the only verb_noun. There is no single predictable pattern for an agent to rely on.

Tool Count5/5

Six tools is well-scoped for a search/retrieval server. Each tool earns its place by covering a distinct workflow: general search, specialized X search, page fetching, deep research, diagnostics, and layer configuration.

Completeness5/5

The tool surface covers the full retrieval workflow with no obvious dead ends: search, fetch specific content, X-specific lookups, deeper multi-step research, diagnostics for empty results, and configuration. Guidance is even provided for when to switch tools, so agents should not get stuck.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • grok-search-mcp

    z2z23n0
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enables coding agents to search X/Twitter and the web through the local Grok CLI, providing better search results than default Codex or Claude search without requiring an API key.
    18 npm
    6
    MIT

  • gemini-search-mcp

    Sophomoresty
    A
    license
    A
    quality
    F
    maintenance
    MCP server for web search powered by Google AI Mode (Gemini). Enables any AI agent to search the web in real-time for free and without rate limits.
    2
    182
    MIT

  • uvxwebsearchmcp

    DanielNMC
    A
    license
    Not graded
    quality
    B
    maintenance
    A zero-config web search and fetch MCP server for LLM agents, featuring multi-backend metasearch, persistent rolling cache, and structured error envelopes for retry-friendly interactions.
    MIT

  • web-mcp

    Chang-Tong
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for multi-engine web search and web page fetching, supporting parallel search, content extraction, and optional LLM-powered search summarization and deep search.
    5
    MIT

Appeared in Searches