Provides arXiv search and paper retrieval: queries the arXiv API for entries, routes arXiv paper URLs through alphaxiv for AI overviews or full text, and converts PDFs to markdown, with built-in rate-limit handling.
Provides an automatic DuckDuckGo fallback for general web search when the local SearXNG backend is unavailable.
Provides GitHub search across repositories, issues, and code via the GitHub REST API; code search requires a GITHUB_TOKEN.
Enables general web searches using Google through the local SearXNG metasearch backend, with optional engine pinning.
Provides scholarly search against Google Scholar through SearXNG, returning academic search results without an offline fallback.
Uses a local SearXNG instance as the metasearch backend for general and scholarly web search, with JSON API access, engine selection, and time-range filtering.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@local-web search the web for recent papers on RAG evaluation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A thin local MCP server (FastMCP, HTTP transport) over three components:
Component | Role | Runs |
SearXNG | metasearch (Google/Bing/DuckDuckGo/Scholar/…), JSON API |
|
Crawl4AI | JS-rendered page → LLM markdown (Playwright Chromium) | inside the MCP server process |
PyMuPDF 2.x | PDF → markdown | inside the MCP server process |
arXiv / alphaxiv / GitHub / HuggingFace APIs | dedicated citation & code lookups | no local component |
Everything is managed with uv. The MCP project (this folder) is a uv project
(pyproject.toml + uv.lock); SearXNG is a git checkout with a uv-managed venv.
web_search(query, num_results=8, engine="auto", searx_engines="", time_range="")
— general web search (SearXNG: Google/Bing/…), automatic DuckDuckGo (ddgs)
fallback. Pin engines with searx_engines="google". time_range:
day|week|month|year.
scholar_search(query, num_results=8) — Google Scholar via SearXNG
(engines=google scholar); no offline fallback (SearXNG must be running).
github_search(query, kind="repo"|"issue"|"code", num_results=8) — GitHub REST
API. Code search needs GITHUB_TOKEN env var; unauthenticated limit is
10 search req/min.
huggingface_search(query, kind="model"|"dataset", num_results=8, pipeline="")
— HF API. query matches name/ID substrings (e.g. "wan"), not full
text; pipeline filters by task tag (e.g. "video-classification").
libgen_search(query, num_results=8) — scrapes libgen.li's index.php?req=
results table (best-effort; the site changes and may block). Returns title,
authors, publisher, year, language, pages, size, extension, md5, plus
item_url (edition page) and file_url (file page with download mirrors).
arxiv_search(query, max_results=5) — arXiv API entries (id, title, authors,
date, abstract, abs URL; PDF = same URL with .pdf). Retries up to 3× with
backoff on transient timeouts. arXiv policy: ≤1 req/3s, one connection at a
time; the server spaces arxiv.org requests 5s apart and, on a 429 ("Rate
exceeded"), pauses the whole domain ~5 min for all agents instead of retrying
into the burst counter.
alphaxiv_lookup(arxiv_id, lang="en") — AI overview of an arXiv paper
(blurb/problem/solution/key-insights/results, the machine-readable report,
abstract, bibtex, cited papers). Bare ID (2402.02085) or URL. For a short
blurb this is the fastest path. fetch_page/fetch_pdf of arXiv paper URLs
already route through alphaxiv first, so you rarely need to call these
directly — use them when you want the structured overview rather than raw text.
alphaxiv_fulltext(arxiv_id, offset=0, max_chars=20000) — full extracted
paper text as markdown, paginated like fetch_page. For equations/tables/
section detail the lookup card doesn't have.
fetch_page(url, offset=0, max_chars=20000) — rendered markdown, paginated:
call again with offset = offset + max_chars while offset < total_chars.
Browser concurrency is capped (semaphore, BROWSER_SLOTS, default 4).
arXiv paper URLs (abs/pdf) are routed through alphaxiv first — the result's
source field says which answered (alphaxiv | browser | arxiv-direct).
fetch_stealth(url, offset=0, max_chars=20000, solve_cloudflare=False) —
Scrapling StealthyFetcher (stealth-patched headless Chromium: real browser
UA, canvas noise, WebRTC blocking, spoofed locale/timezone). Use when
fetch_page gets blocked or returns a challenge page.
solve_cloudflare=True solves Cloudflare Turnstile/interstitials (slow,
1–3 min when it has to). Paginated the same way.
fetch_pdf(url, offset=0, max_chars=20000) — PDF → markdown (PyMuPDF 2.x),
paginated the same way. For arXiv paper PDFs the default route is alphaxiv's
extracted text; the direct download happens only when alphaxiv lacks the paper.
Related MCP server: mcp-web
Name | Transport | Lifecycle |
| stdio — the default | Claude Code spawns |
| HTTP :9000 | One long-lived server shared by all sessions (shared rate-limit gate + browser pool). Auto-starts at logon (scheduled task |
Both modes also use SearXNG on :8888 for web_search/scholar_search
(web_search falls back to DuckDuckGo if SearXNG is down). check-and-start.bat
is idempotent: it starts only whatever port is not listening.
Manual launch (visible windows): start-all.bat / ./start-all.sh, or
individually start-searxng.* / start-server.* (the server launchers set
MCP_TRANSPORT=http).
Re-register from scratch (both at user scope):
claude mcp add -s user local-web -- <path to uv> run --directory <this folder> python server.py
claude mcp add -s user local-web-shared --transport http http://127.0.0.1:9000/mcp
claude mcp list # both should show ConnectedNote: with both registered, a session sees the 11 tools twice (once per
server prefix). Use local-web (stdio) for everyday work; the shared one is
for running several sessions/agents concurrently against one browser pool.
uv run pytest # unit tests: pure helpers + domain gate
# (fake clock, no network, ~1s)
uv run python smoke_test.py # live end-to-end, all 11 tools
SKIP_ARXIV=1 uv run python smoke_test.py # skip arXiv while it's rate-limitingUnit tests run in CI (.github/workflows/ci.yml); the smoke test hits the
live HTTP server (start it with check-and-start.bat or start-all.bat),
so it's local-only.
# MCP project (this folder)
uv add fastmcp crawl4ai httpx pymupdf beautifulsoup4 ddgs "scrapling[fetchers]" markdownify
uv run python -m playwright install chromium # Crawl4AI + Scrapling browsers
uv run scrapling install # marks Scrapling's browser deps installed
# SearXNG (searxng/ — clone of github.com/searxng/searxng at depth 1)
uv venv searxng/.venv --python 3.11
uv pip install --python searxng/.venv -r searxng/requirements.txtSearXNG user settings live in searxng/searx/settings/user-settings.yml:
search.formats includes json (default is html-only → JSON returns 403) and
server.limiter: false. The dev runner generates no storage dependency; if you
see botdetection/limiter errors, keep limiter: false (there is no valkey/redis).
Note on cloning SearXNG on Windows: the repo contains a file whose name includes
a colon (utils/templates/etc/httpd/sites-available/searxng.conf:socket), which
Windows cannot check out. Clone with --no-checkout and restore only what is
needed: git checkout HEAD -- searx requirements.txt.
The MCP server binds to 127.0.0.1 only and has no auth layer — do not expose it (no tailscale/0.0.0.0 binding).
Fetched web content is untrusted data (prompt-injection vector). Keep side-effecting tools (shell, file writes) out of any agent that browses.
Search/fetch hit the public internet normally; be considerate (the semaphore and Crawl4AI's cache mitigate re-hammering).
web_search errors mention searxng: … → SearXNG not running (start it).
engine in the result shows which backend answered (searxng or ddg).
SearXNG JSON 403 → json missing from search.formats in user-settings.yml.
fetch_page browser errors → uv run python -m playwright install chromium.
Crawl4AI setup check: uv run python -c "import crawl4ai_doctor" or
uv run crawl4ai-doctor if the CLI is exposed by the installed version.
Ports in use: SearXNG 8888, MCP 9000 (SEARXNG_URL env var overrides the
SearXNG address in server.py).
arxiv_search returns a 429 error: the arXiv burst counter is active (can
last ~15 min). Don't retry in a loop — that refreshes the window. Fetch the
specific papers via alphaxiv_lookup/alphaxiv_fulltext meanwhile.
SKIP_ARXIV=1 uv run python smoke_test.py skips the arXiv case during a
throttle window.
Full extracted text of an arXiv paper as markdown from alphaxiv.org. Not subject to arXiv rate limits; use instead of fetch_page/fetch_pdf for arXiv papers when you need section-level detail. Paginated like fetch_page. Accepts a bare ID or an arxiv/alphaxiv URL.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| arxiv_id | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the burden and does disclose real behavioral traits: it is not subject to arXiv rate limits and it is paginated like fetch_page. It omits auth/permission requirements and failure modes (e.g. a paper not indexed by alphaxiv), which keeps it off a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the identity of the tool followed by the reason to prefer it. Nothing is repeated from the title and every clause adds routing or behavioral information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return format need not be restated, and the description covers routing, source, and pagination. The remaining gap is the undocumented max_chars parameter, which an agent must guess at to control response size.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema itself has no per-field descriptions for offset or max_chars. The description clarifies arxiv_id (bare ID or arxiv/alphaxiv URL) and hints that paging works via offset, but max_chars is never mentioned, leaving a third of the surface undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (extract), resource (full text of an arXiv paper) and format (markdown from alphaxiv.org). The scoping clause about rate limits and section-level detail lets an agent distinguish it from fetch_page/fetch_pdf without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternatives to use instead (fetch_page/fetch_pdf) and the condition that selects this tool: arXiv papers needing section-level detail. It also states the negative condition implicitly by limiting scope to arXiv papers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up an arXiv paper on alphaxiv.org: AI-generated structured overview (blurb, problem, solution, key insights, results), the machine-readable report, abstract, bibtex, and cited papers. Accepts a bare ID (2402.02085, version suffix ok) or an arxiv/alphaxiv URL. Use alphaxiv_fulltext when you need equations, tables, or section-level detail.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en | |
| arxiv_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It discloses the shape of the payload (overview fields, machine-readable report, abstract, bibtex, citations), which is real behavioral context, and the read-only nature is implied by 'look up'. However it says nothing about failure modes (paper not indexed on alphaxiv), rate limits, or whether the overview is cached/stale — gaps that matter for an agent deciding whether to trust the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and return content, then the input format flexibility, then the sibling routing rule. Every sentence earns its place; no filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the return-value enumeration is bonus context rather than a necessity, and the accepted input formats are fully covered. The only substantive gap for a 2-parameter lookup is the unexplained lang parameter and any note on behavior when a paper lacks an alphaxiv entry.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does well for arxiv_id: bare ID, version suffix, and arxiv/alphaxiv URL forms are all spelled out. But the second parameter, lang, is entirely undocumented in both schema and description, leaving half the surface unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (look up) and resource (an arXiv paper on alphaxiv.org), then enumerates exactly what is returned: structured overview, report, abstract, bibtex, cited papers. The distinction from alphaxiv_fulltext is made explicit, so the agent can discriminate without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear routing rule: use alphaxiv_fulltext when equations, tables, or section-level detail are needed. That's a genuine exclusion for the most confusable sibling. Other siblings (arxiv_search, fetch_pdf, fetch_page) aren't addressed, so the guidance is good but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search arXiv (all fields) via the official API. Returns entries with arxiv_id, title, authors, published (YYYY-MM-DD), abstract, and url (abs page; PDF = same URL with '.pdf'). Retries up to 3 times (15s apart) on transient timeouts; an HTTP 429 rate limit pauses the whole domain for all agents (see DOMAIN_COOLDOWNS) and returns immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a decent job: it discloses the retry policy (3 attempts, 15s apart on transient timeouts) and the important failure mode where an HTTP 429 pauses the domain for all agents and returns immediately. It does not state read-only semantics or the effect of hitting max_results bounds, but the operational behavior an agent needs to avoid hammering the API is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and scope, then dense operational caveats in the following sentences. The enumeration of returned fields is partly redundant given an output schema exists, but the derived PDF URL rule is genuinely additive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema means return fields need not be spelled out, and the retry/rate-limit disclosure covers the main operational risk. What's missing is query syntax, ordering, and any cap on max_results — the gaps an agent could actually trip over when invoking this two-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate; it only partially does with '(all fields)', which hints that the query string is a general search but gives no arXiv query-syntax guidance (author/field prefixes, boolean operators). 'max_results' is never mentioned, though its name and default of 5 make it largely self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search arXiv (all fields) via the official API'), and the 'all fields' phrasing tells the agent this is a broad query rather than a title-only lookup. It does not, however, explicitly differentiate itself from siblings like scholar_search or alphaxiv_lookup that also cover academic literature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The arXiv-specific scope implies when to reach for this tool (you want arXiv preprints), but there is no explicit when-to-use/when-not guidance and no named alternative such as scholar_search for non-arXiv or cross-publisher coverage. Usage is left to be inferred from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a web page (JS-rendered via headless Chromium) as markdown.
Paginated: returns the slice [offset, offset+max_chars) plus total_chars;
call again with a larger offset to continue. For arXiv paper URLs the
default route is alphaxiv.org's extracted text (not subject to arXiv rate
limits); the browser is used only when alphaxiv doesn't have the paper.
source says which one answered ("alphaxiv" | "browser" | "arxiv-direct").
On failure returns {"success": false, "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| offset | No | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the rendering backend, pagination model, the arXiv routing and its rate-limit implications, the `source` provenance field, and the exact failure shape. It omits auth/rate-limit behavior for non-arXiv sites and timeout characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action in the first sentence and then layers pagination, routing, provenance, and error contract. Dense but nearly every clause adds callable information; minor overlap between the pagination and source-provenance sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully described, and the description covers the pagination and error cases that matter. A note on non-arXiv fetch limits or timeouts would complete it, but nothing essential to a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it explains the offset/max_chars slice semantics and continuation pattern clearly, plus the url-dependent arXiv routing. It does not state the default values (0, 20000) or units, but the slice notation conveys enough to call correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: fetch a web page as markdown, rendered via headless Chromium. This implicitly distinguishes it from fetch_stealth/fetch_pdf (JS rendering, markdown output), though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operational guidance for continuing pagination ('call again with a larger offset') and for arXiv URLs (alphaxiv default, browser fallback). However, it offers no guidance on when to choose this tool over fetch_stealth, fetch_pdf, or web_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a PDF and convert it to markdown (PyMuPDF 2.x).
Paginated like fetch_page. For arXiv paper PDFs the default route is
alphaxiv.org's extracted text (not subject to arXiv rate limits); the
direct download is used only when alphaxiv doesn't have the paper.
source says which one answered ("alphaxiv" | "direct" | "arxiv-direct").
On failure returns {"success": false, "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| offset | No | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it names the conversion engine (PyMuPDF 2.x), explains pagination, discloses the routing logic and rate-limit rationale, identifies the `source` value, and states the failure response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and conversion detail, then adds routing and failure behavior without unnecessary repetition. Every sentence contributes useful operational context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not fully document return values, and it already covers routing and failure behavior. The main completeness gap is that parameter behavior is left almost entirely to an undocumented schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the `url`, `offset`, or `max_chars` parameters. The phrase "Paginated like fetch_page" gives only a weak hint about offset/max_chars and does not compensate for the missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Download a PDF and convert it to markdown." It also differentiates the tool from fetch_page by noting pagination behavior and explains the arXiv-specific routing, so an agent can distinguish its role without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditional guidance for arXiv paper PDFs: alphaxiv is the default extracted-text route, and direct download is used only when alphaxiv lacks the paper. However, it does not explicitly say when to choose fetch_pdf over siblings such as fetch_page, fetch_stealth, or alphaxiv_fulltext beyond the PDF conversion context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a page with Scrapling's StealthyFetcher (stealth-patched headless Chromium: real browser UA, canvas noise, WebRTC blocking, spoofed locale/timezone) as markdown. Use when fetch_page gets blocked or returns a challenge/error page. solve_cloudflare=True also solves Cloudflare Turnstile/interstitial challenges (slow: 1-3 min when it has to). Paginated like fetch_page. On failure returns {"success": false, "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| offset | No | ||
| max_chars | No | ||
| solve_cloudflare | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description carries the full burden well: it discloses the stealth emulation surface, the latency cost of Cloudflare solving, pagination parity with fetch_page, and the exact failure payload shape. Those are precisely the traits an agent needs before committing to a slow fallback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the sibling comparison in the second sentence, and every clause carries information. The long technical parenthetical is dense but earns its space by defining what 'stealth' actually means.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values needn't be spelled out, and the failure envelope is still noted. What remains thin is the pagination parameter behavior (offset/max_chars), which an agent must infer from 'paginated like fetch_page'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for all four parameters. It explains solve_cloudflare meaningfully (Turnstile/interstitial solving plus its cost) and implies offset via 'Paginated like fetch_page', but max_chars and offset semantics/defaults are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (fetch a page via Scrapling's StealthyFetcher) and immediately distinguishes it from the sibling fetch_page by naming the condition that selects it. The parenthetical on stealth features makes the capability concrete rather than tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing rule: 'Use when fetch_page gets blocked or returns a challenge/error page', with a named alternative and a stated tradeoff (1-3 min with solve_cloudflare). No inference required from the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GitHub. kind: "repo" or "issue" (code search requires a GITHUB_TOKEN env var, which the server picks up automatically). Unauthenticated rate limit is 10 search requests/minute.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | repo | |
| query | Yes | ||
| num_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral-disclosure burden. It usefully discloses the unauthenticated rate limit of 10 search requests/minute and the GITHUB_TOKEN requirement for code search. However, it omits authentication behavior for repo/issue search, error behavior, and result ordering or pagination constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the tool purpose. The token and rate-limit notes are relevant and compact. The parenthetical about code search is slightly ambiguous given that kind is only documented as repo/issue, but overall there is little wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with 0% schema description coverage and no annotations, the description is under-specified. It covers kind values and operational limits, but lacks query syntax guidance and any explanation of num_results. Output schema exists, so return-value detail is not required, but parameter completeness is still lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It enumerates kind values as "repo" or "issue", which is helpful, but it never mentions num_results, its default of 8, or query syntax. Query is self-evident in name only, leaving significant parameter meaning undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: "Search GitHub." The mention of repo/issue kinds clarifies the search target. It does not explicitly differentiate itself from sibling search tools like web_search or scholar_search, but the GitHub resource is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use or when-not-to-use guidance. It does not direct the agent toward or away from sibling tools such as web_search, scholar_search, or huggingface_search. The kind values describe a parameter, not tool-selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search HuggingFace. kind: "model" or "dataset". query matches name/ID
substrings (e.g. "wan", "detection"), NOT full text. pipeline filters by
task tag (models: "text-generation", "video-classification", ...;
datasets: "text-classification", ...).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | model | |
| query | Yes | ||
| pipeline | No | ||
| num_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the burden and usefully discloses that `query` matches name/ID substrings rather than full text — a non-obvious behavior that prevents wasted calls. It does not mention rate limits, ordering, or how many results are returned (output schema covers the latter).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then dense per-parameter clarifications with concrete example values. No filler sentences, though the parenthetical examples in the `pipeline` clause are slightly sprawling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and the main filtering params are well covered. However, with no annotations and no enum constraints in the schema, the description should state accepted `kind` values as a closed set and explain `num_results` to be fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate: it explains `kind` (model/dataset), `query` (substring on name/ID), and `pipeline` (task tag with example values per kind), which is strong added meaning. `num_results` is left entirely undocumented, leaving one of four params unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Search HuggingFace") and immediately narrows scope by distinguishing model vs dataset search. The resource is distinctive enough against siblings like arxiv_search, github_search, and web_search, though it never explicitly contrasts itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the parameter explanations — an agent can infer this is for finding HF models/datasets by name or task tag. There is no explicit when-to-use, when-not-to-use, or guidance on preferring a sibling tool (e.g. web_search for full-text discovery).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search libgen.li (scrapes the index.php?req= results table; best-effort, the site changes and may block datacenter-style requests). Per result: title, authors, publisher, year, language, pages, size, extension, md5, item_url (edition page) and file_url (the file page with download mirrors).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| num_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does well: it discloses that the tool scrapes an HTML results table, is best-effort, may break as the site changes, and may block datacenter-style requests. It omits rate limits or auth expectations, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The operational caveat is front-loaded and the field enumeration is compact. Slightly redundant since an output schema already exists, but the single readable sentence structure wastes little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter search tool with an output schema, the description covers what it does and its reliability limits, which is close to sufficient. The missing piece is any parameter-level explanation, which is the main gap against an otherwise complete definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description says nothing about either parameter. It never clarifies that 'query' is a free-text search string or what 'num_results' does (default 8, presumably a cap on returned rows), so it fails to compensate for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and a concrete resource (libgen.li, scraping index.php?req=), so the agent knows exactly what this does and where the data comes from. It does not explicitly contrast itself with siblings like arxiv_search or scholar_search, leaving the 'books vs. papers' distinction to inference from the 'libgen' name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a context (searching the Libgen index for book/edition results) but never states when to pick this over arxiv_search, scholar_search, or web_search. The note about reliability is a caveat, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Google Scholar search (via SearXNG, engines='google scholar'). No offline fallback. Returns {"engine": "searxng-scholar", "results": [...]}. For papers, arxiv_search is usually richer (abstracts + PDF links).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| num_results | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully states the backend, that there is no offline fallback, and gives a basic response shape, but it does not mention rate limits, authentication, result quality constraints, or other operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and every sentence contributes useful routing or behavioral context. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool with an output schema, the description covers the core purpose, backend constraint, no-fallback behavior, and a useful sibling alternative. Parameter guidance and deeper operational details are the main remaining gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain query or num_results semantics at all. While both parameters are relatively self-explanatory, the description adds no meaning about result count limits, formatting, or query expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: Google Scholar search via SearXNG with engines='google scholar'. It also distinguishes the tool from a relevant sibling by noting that arxiv_search is usually richer for papers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context and explicitly points agents to arxiv_search when richer paper metadata such as abstracts and PDF links are needed. It does not fully specify when to prefer scholar_search over web_search or other search siblings beyond the Google Scholar scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
General web search (Google/Bing/… via SearXNG). engine: "auto" (SearXNG, then DuckDuckGo fallback), "searxng", or "ddg". searx_engines pins SearXNG engines, e.g. "google" or "google, bing". time_range: day|week|month|year. Returns {"engine": str, "results": [{"title", "url", "snippet"}], "error"?: str}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| engine | No | auto | |
| time_range | No | ||
| num_results | No | ||
| searx_engines | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: the 'auto' path tries SearXNG then falls back to DuckDuckGo, and the response includes an optional 'error' field. Missing are any rate-limit, auth, or failure-mode details beyond the error key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then parameter notes, then the return shape – an efficient ordering with no filler. The run-together sentences are dense but each carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and the description still sketches the return shape, and four of five parameters are explained. A few words on num_results and selection from sibling search tools would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does for three params: it enumerates engine values, gives concrete searx_engines examples ('google' or 'google, bing'), and lists time_range values (day|week|month|year). Only num_results is left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('General web search') and lists the backends (Google/Bing via SearXNG). 'General' implicitly distinguishes it from the specialized siblings like scholar_search and github_search, though it never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'general' hints at when to use this over the specialized search siblings, but there is no explicit when/when-not statement or naming of alternatives. The agent must infer routing from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0alphaxiv_fulltextalphaxiv_lookuparxiv_searchfetch_pagefetch_pdffetch_stealthgithub_searchhuggingface_searchlibgen_searchscholar_searchweb_searchScored across 11 tools
The search tools are cleanly separated by domain (web, scholar, arXiv, GitHub, HF, libgen), and fetch_page/fetch_stealth/fetch_pdf have described fallback roles. There is still minor overlap between fetch_page, alphaxiv_fulltext, and fetch_pdf for retrieving arXiv/PDF content, but the descriptions mostly resolve when to use each.
All names are snake_case and readable, with fetch_* for retrieval and *_search for domain searches. The mix of verb-first (fetch_page), domain-first (arxiv_search), and prefixed tools (alphaxiv_lookup) is a minor inconsistency rather than a confusing one.
Eleven tools are well within a reasonable scope for a web research server. Each search domain and fetch variant covers a distinct source or retrieval mode, so the set does not feel bloated.
The surface covers general web search, academic/arXiv search, code/model/book search, plus page, PDF, stealth, and arXiv full-text fetching. Minor gaps remain around crawling/site mapping or generic file extraction, but core research workflows are covered.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
