The mcp-research server provides read-only tools for AI assistants to gather and process information from the web, academic sources, social media, and various file types, optimized for token efficiency and safety.
web_search: Search the web using a 3-tier cascade (Brave API → DuckDuckGo → HTML scraper), with options to summarize results and auto-fetch the top result's full content.
fetch_url: Fetch any URL and convert to clean markdown, with SSRF protection, 24-hour caching, CAPTCHA detection, and configurable content length limits.
research: Compound research pipeline that rewrites queries, searches, fetches pages in parallel, summarizes each source, and synthesizes a final cited answer — at three depth levels: quick (2 pages), standard (5 pages), or deep (10 pages).
youtube_essence: Extract transcripts, summaries, key points, chapters, and quotes from YouTube videos.
deep_ingest: Extract and optionally summarize text from files including PDFs, Office documents (DOCX, XLSX, PPTX), audio, video, and images.
academic_lookup: Resolve academic papers by DOI, ArXiv ID, or PubMed ID, fetching metadata and full text via institutional credentials.
twitter_extract: Extract tweets and full threads from X/Twitter using multiple strategies.
vault_status: Display loaded credential profiles and dependency status without exposing secrets.
Provides web search capabilities via the Brave Search API as the primary high-quality search tier for the web_search tool.
Enables web search via the DuckDuckGo library and HTML scraper, serving as automatic fallback tiers when the Brave API is unavailable or rate-limited.
Enables AI-powered content processing including query rewriting, page summarization, and research synthesis using configurable Ollama models.
1. Click on "Install Server".
2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
3. In the chat, type `@` followed by the MCP server name and your instructions, e.g., "`@
mcp-research` research recent advances in renewable energy storage"
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](https://glama.ai/blog/2025-07-08-how-to-install-and-use-mcp-servers).MCP server for web research, academic papers, Twitter/X, YouTube, and file ingestion. Eight tools for AI assistants — all via the MCP stdio protocol. Includes credential vault for institutional access, CAPTCHA detection, and token-efficient output.
Tool | Description |
| 3-tier search cascade: Brave API → DuckDuckGo → HTML scraper |
| Fetch any URL → clean markdown, with SSRF protection and 24h cache |
| Compound pipeline: query rewrite → search → parallel fetch → summarize → synthesize |
| YouTube video → transcript, summary, key points, chapters, quotes |
| Extract text from files: PDF, DOCX, XLSX, PPTX, audio, video, images |
| Resolve DOI / ArXiv / PubMed → metadata + full text via institutional access |
| Extract tweets and threads from X.com/Twitter |
| Show loaded credential profiles and dependency status (never exposes secrets) |
All tools are read-only — they fetch and transform content, never modify anything.
Related MCP server: The Web MCP
pip install mcp-researchOr run directly with uvx (zero-install):
uvx mcp-researchOptional extras:
pip install 'mcp-research[twitter]' # yt-dlp for Twitter extraction
pip install 'mcp-research[youtube]' # yt-dlp + faster-whisper for YouTube
pip install 'mcp-research[academic]' # PyPDF2 for academic PDFs
pip install 'mcp-research[ingest]' # PDF, DOCX, XLSX, PPTX, audio support
pip install 'mcp-research[all]' # everythingCheck your setup:
mcp-research doctorAdd to your Claude Code MCP config (~/.claude/settings.json or project .mcp.json):
{
"mcpServers": {
"research": {
"command": "uvx",
"args": ["mcp-research"],
"env": {
"BRAVE_API_KEY": "BSA...",
"OLLAMA_URL": "http://localhost:11434"
}
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"research": {
"command": "uvx",
"args": ["mcp-research"],
"env": {
"BRAVE_API_KEY": "BSA..."
}
}
}
}All configuration is via environment variables — no config files needed (except the optional vault).
Variable | Default | Description |
| (empty) | Brave Search API key. Falls back to DuckDuckGo if unset. |
|
| Ollama endpoint for summarization/synthesis. Set empty to disable. |
|
| Model to use for summarization and synthesis. |
|
| URL fetch cache directory. |
|
| Cache TTL in hours. |
|
| Search log directory (NDJSON). |
|
| Default max search results. |
|
| Credential vault file path. |
|
| Auto-reload vault when file changes. |
|
| Session idle timeout in seconds. |
web_searchweb_search(query, max_results=5, summarize=False, auto_fetch_top=False)Searches the web using a 3-tier cascade for maximum reliability:
Brave Search API — fast, high quality (requires BRAVE_API_KEY)
DuckDuckGo library — no API key needed, retries on rate limit
DuckDuckGo HTML scraper — last-resort fallback
Options:
summarize: Use Ollama to summarize results (requires running Ollama)
auto_fetch_top: Also fetch and return the full content of the top result
fetch_urlfetch_url(url, summarize=False, max_chars=15000)Fetches a URL and converts it to clean markdown:
SSRF protection: Blocks localhost, private IPs, non-HTTP schemes
Smart retry: Exponential backoff on 429/5xx, per-hop redirect validation
24h cache: SHA-256 keyed, configurable TTL
Content support: HTML → markdown, JSON → code block, binary → rejected
Smart truncation: Breaks at heading/paragraph boundaries, not mid-text
CAPTCHA detection: Flags Cloudflare, hCaptcha, reCAPTCHA, Akamai walls
Token-efficient: Default 15K chars (~4K tokens), adjustable via max_chars
researchresearch(query, depth="standard", context="")Compound research pipeline:
Query rewrite — Ollama optimizes your question into search keywords
Web search — finds relevant pages (with zero-result retry expansion)
Parallel fetch — fetches top N pages concurrently
Summarize — Ollama summarizes each page
Synthesize — Ollama produces a final cited answer
Depth levels:
Depth | Pages | Synthesis |
| 2 | No |
| 5 | Yes |
| 10 | Yes |
All steps gracefully degrade without Ollama — you still get search results and page content.
youtube_essenceyoutube_essence(url, mode="standard")Extracts structured content from YouTube videos:
Transcript: Auto-subtitles or Whisper transcription (local, private)
Summary: AI summary via Ollama
Key points: Bullet-point takeaways
Chapters: Timestamped segments
Quotes: Notable quotations (deep mode)
Modes: quick (TL;DR), standard (+ chapters), deep (+ quotes)
Requires yt-dlp. Optional: faster-whisper for audio-only videos, ffmpeg for media extraction.
deep_ingestdeep_ingest(path, include_types="", max_files=200, summarize=False)Extracts text from files in a directory or single file:
Text files: .txt, .md, .json, .csv, source code, etc.
PDF: Via PyPDF2 (optional dependency)
Office: .docx, .xlsx, .pptx (optional dependencies)
Audio/Video: Whisper transcription (optional)
Images: OCR via Ollama vision model (optional)
Type filter: text, pdf, audio, video, image, office
academic_lookupacademic_lookup(identifier, fetch_fulltext=True)Resolves academic papers from multiple identifier types:
DOI: 10.xxxx/... → Crossref metadata + publisher redirect
ArXiv: 2301.12345 → abstract + PDF
PubMed: PMID → E-utilities metadata → DOI chain
URL: Publisher page detection
Full text access via credential vault:
EZproxy rewriting (prefix and suffix modes)
Bearer token, API key, basic auth, cookie jar
Automatic publisher detection (IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR, etc.)
twitter_extracttwitter_extract(url, include_thread=False)Extracts tweets and threads from X.com/Twitter using a strategy cascade:
yt-dlp (primary) — works with cookie jar for authenticated access
Twitter API v2 — if bearer token configured in vault
HTML fetch — cookie-based last resort
Returns: text, author, timestamp, metrics (likes, retweets, replies), media URLs.
vault_statusvault_status()Shows loaded credential profiles, match patterns, and auth types — never exposes secrets. Also checks availability of optional dependencies.
Create ~/.mcp-research/vault.yaml to configure authentication for protected sources:
version: 1
profiles:
# University EZproxy for IEEE
ieee-university:
match: "*.ieee.org/**"
ezproxy:
base_url: "https://ezproxy.myuniversity.edu/login?url="
mode: prefix
# Springer via API key
springer:
match: "*.springer.com/**"
auth:
type: api_key
header: "X-ApiKey"
value: "${SPRINGER_API_KEY}"
# X.com via browser cookies
twitter:
match: "*.x.com/**"
auth:
type: cookie_jar
path: "${HOME}/.mcp-research/cookies/twitter.txt"${VAR} resolved from environment variables — secrets never stored in plain text
First matching profile wins (order matters)
Auth types: bearer, basic, api_key, cookie_jar, headers
EZproxy modes: prefix (prepend base URL) or suffix (domain rewriting)
Hot-reload: vault file changes are picked up automatically
All tools produce compact output by default to avoid wasting AI context window tokens:
Tool | Default output | Override |
| ~15K chars (~4K tokens) |
|
| ~500 tokens per source | Prefers summaries over raw content |
| ~10K chars full text | Truncates with notice |
| 15 files, 300 char excerpts |
|
| 3K char transcript excerpt | Full transcript in result object |
SSRF protection: Blocks localhost, private IPs, link-local, non-HTTP schemes on every hop
CAPTCHA detection: Identifies Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard walls
Input validation: Size limits, URL validation, safe redirect following
No eval/exec: No dynamic code execution
Vault security: Secrets resolved from env vars, repr() redacts all auth values
Cache isolation: Owner-only directory permissions (0o700)
Graceful degradation: Missing optional deps don't crash — features degrade with clear messages
mcp-research serve # Run MCP stdio server (default)
mcp-research search "query" # Search the web
mcp-research fetch https://example.com # Fetch URL to markdown
mcp-research youtube https://youtu.be/... # Extract YouTube video
mcp-research ingest ./docs/ # Extract text from files
mcp-research academic "10.1109/..." # Resolve academic paper
mcp-research tweet https://x.com/.../123 # Extract tweet
mcp-research vault # Show vault profiles
mcp-research doctor # Check dependenciesgit clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e ".[all]"
pytest tests/ -v
python -m mcp_researchCredential vault: YAML config at ~/.mcp-research/vault.yaml with env var interpolation, glob URL matching, EZproxy rewriting, hot-reload
Session pooling: Per-domain sessions with vault auth injection, cookie jar support, idle eviction
CAPTCHA detection: Identifies Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, generic bot walls
Academic lookup: DOI/ArXiv/PubMed resolution, Crossref metadata, institutional full text access via vault
Twitter/X extraction: yt-dlp, API v2, and cookie-based access with thread support
Token efficiency: Default output caps (~4K tokens for fetch, ~500 per research source) to preserve AI context
Doctor command: mcp-research doctor checks all dependencies and configuration
Windows encoding fix: UTF-8 stdout/stderr wrapper prevents cp1252 crashes
YouTube essence: Transcript extraction, AI summary, key points, chapters, quotes
Deep ingest: PDF, DOCX, XLSX, PPTX, audio, video, image text extraction
Ollama integration: Query rewriting, summarization, synthesis, vision OCR
Search logging: NDJSON event log for all operations
Brave Search: Primary search tier with API key support
Initial release: 3 tools (web_search, fetch_url, research), SSRF protection, caching
MIT
Resolve a DOI, ArXiv ID, or PubMed ID. Fetch paper via institutional access if configured in vault.
Args: identifier: DOI (10.xxxx/...), ArXiv ID (2301.12345), PubMed ID (12345678), or publisher URL. fetch_fulltext: Attempt to fetch the full paper text via vault credentials / EZproxy.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ||
| fetch_fulltext | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it mentions attempting to fetch full text via vault credentials/EZproxy, which is a key side effect. Annotations already declare readOnlyHint=true and idempotentHint=true, so there is no contradiction. The description supplements annotations well.
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 concise and front-loaded with the primary purpose, followed by parameter details. It contains no extraneous text. Slightly more structure (e.g., separating args clearly) could improve scannability, but it is already efficient.
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?
Given the presence of an output schema, the description appropriately focuses on input behavior. It covers the main use cases and mentions the vault configuration requirement. Minor gaps exist (e.g., what happens if fetch_fulltext fails), but overall it is sufficiently complete for a well-annotated 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?
The input schema has 0% description coverage, so the description must compensate. It explains that 'identifier' can be a DOI, ArXiv ID, PubMed ID, or publisher URL, and that 'fetch_fulltext' defaults to true. This provides necessary semantics that the schema alone lacks.
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 clearly states the tool resolves specific academic identifiers (DOI, ArXiv ID, PubMed ID) and optionally fetches full text via institutional access. The verb 'Resolve' and listing of identifier types provide a specific purpose that distinguishes it from siblings like web_search and fetch_url.
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 explicitly states when to use the tool (for resolving academic identifiers and fetching papers with vault access). While it does not provide explicit 'when not to use' guidance, the sibling tools offer natural alternatives, and the context is clear enough for an AI agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract text from files in a directory or single file. Supports text, PDF, DOCX, XLSX, PPTX, audio, video, images.
Args: path: Directory or file path to process. include_types: Comma-separated type filter (text,pdf,audio,video,image,office). Empty = all. max_files: Maximum files to process (1-5000). summarize: If true, generate an AI summary of the combined content.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| max_files | No | ||
| summarize | No | ||
| include_types | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm read-only, idempotent, non-destructive behavior. The description adds value by detailing the extraction process (text from various formats) and the optional AI summarization feature, which annotations do not cover.
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 concise: a one-line overview followed by a clean bullet-style Args section. Each sentence serves a purpose, and the essential information is front-loaded.
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?
Given the tool's complexity (many file types, 4 parameters, optional summarize), the description sufficiently covers purpose, parameters, and behavior. An output schema exists, so return values need not be detailed.
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%, but the description provides detailed parameter docs (path, include_types, max_files, summarize) with defaults and examples (e.g., 'Comma-separated type filter... Empty = all'). This fully compensates for the schema gap.
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 clearly states that the tool extracts text from files (directories or single files), listing supported formats (text, PDF, DOCX, etc.). This distinguishes it from sibling tools like fetch_url (URLs), web_search (web queries), and youtube_essence (YouTube).
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 explains the tool's scope (local file processing) and supported types, providing clear context. However, it does not explicitly state when not to use it or mention alternatives beyond implied differences from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a URL, convert to markdown. SSRF-protected and cached.
Args: url: The URL to fetch. summarize: If true and Ollama is available, include a summary. max_chars: Maximum content chars (default ~15K/4K tokens). Set higher for full pages.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| max_chars | No | ||
| summarize | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds SSRF protection, caching, and conditional summarization beyond annotations' readOnly/idempotent hints. No contradictions. More details on error handling would improve, but current info is solid.
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?
Extremely concise: single opening sentence plus a three-line bullet list. No fluff, every sentence adds value. Perfect structure for quick scanning.
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?
Given output schema exists, description doesn't need return details. It covers security (SSRF), caching, and parameter nuances. Missing authentication or error info, but overall adequate for a fetch 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?
With 0% schema description coverage, the description fully explains each parameter: url is the URL, summarize has Ollama condition, max_chars includes default and advice to increase for full pages. Adds significant value beyond 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?
The description clearly states 'Fetch a URL, convert to markdown' with specific verb and resource. It distinguishes from siblings like web_search and academic_lookup by focusing on fetching a single URL rather than searching or academic data.
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 usage: fetch a specific URL for markdown conversion. It doesn't explicitly compare to siblings but provides enough context (e.g., Ollama availability for summarization) to guide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compound research: search → fetch top pages → summarize → synthesize.
Args: query: The research question. depth: Research depth — "quick" (2 pages), "standard" (5 pages), or "deep" (10 pages). context: Optional context from prior research to inform synthesis.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | standard | |
| query | Yes | ||
| context | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the multi-step process (search, fetch, summarize, synthesize) and the meaning of depth, which goes beyond the annotations.
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 very concise with a front-loaded pipeline overview and bullet points for arguments. Every sentence adds value; no wasted words.
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?
Given that there is an output schema (not shown) and annotations cover safety, the description explains the tool's composite nature, parameter meanings, and pipeline stages. It is complete for an agent to understand and invoke the tool correctly.
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 carries full burden. It explains all three parameters: query is the research question, depth with three options, and context as optional prior research. This fully compensates for missing schema descriptions.
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 clearly states the tool does 'Compound research: search → fetch top pages → summarize → synthesize', which is a specific verb+resource and distinguishes it from sibling tools like web_search, fetch_url, or academic_lookup that perform only individual steps.
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 provides the research pipeline and explains the depth parameter with clear options. It implies use for comprehensive research combining multiple steps, but does not explicitly state when not to use or compare directly with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract tweet or thread from X.com/Twitter. Supports yt-dlp, API, and cookie-based access.
Args: url: Tweet URL (x.com/user/status/id or twitter.com/user/status/id). include_thread: If true, fetch the full conversation thread.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| include_thread | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds that it supports multiple access methods, which is useful context beyond annotations, but doesn't detail error handling or rate limits.
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 very concise: two sentences for purpose and two bullet-point args. No wasted words, front-loaded with main purpose.
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?
Given the tool has only 2 simple params and an output schema (not shown), the description covers the essential behavior and parameter semantics. It's mostly complete, though could mention output format briefly, but output schema covers that.
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?
With 0% schema description coverage, the description fully compensates by explaining the url format (x.com/user/status/id) and the purpose of include_thread (fetch full thread). Both parameters are clearly described.
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 clearly states the verb 'Extract' and the resource 'tweet or thread from X.com/Twitter', distinguishing it from siblings like fetch_url by being Twitter-specific.
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 provides technical details (yt-dlp, API, cookie-based access) but lacks explicit guidance on when to use this tool versus alternatives like fetch_url. No when-not-to-use or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show credential vault status, loaded profiles, and optional dependency availability. Never exposes secrets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds security assurance 'Never exposes secrets', which is valuable beyond annotations. No contradiction.
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?
Two sentences, front-loaded with purpose, second adds critical security note. Efficient and well-structured.
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?
Zero parameters, good annotations, output schema exists. Description fully covers the tool's behavior and safety. No 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?
No parameters, schema coverage 100%. Description adds meaning by specifying what the tool shows (status, profiles, dependencies) beyond the empty 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?
Description uses specific verb 'Show' and resource 'credential vault status', with clear scope including loaded profiles and dependency availability. Distinguishes from siblings by being the only vault-related tool.
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 context is clear: a status tool to check vault state. No explicit alternatives or exclusions, but the purpose implies when to use. Slight lack of when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web using a 3-tier cascade (Brave → DuckDuckGo → scraper).
Args: query: Search query string. max_results: Maximum number of results to return (1-20). summarize: If true and Ollama is available, summarize the results. auto_fetch_top: If true, also fetch the full content of the top result.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| summarize | No | ||
| max_results | No | ||
| auto_fetch_top | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable transparency by revealing the 3-tier cascade (Brave, DuckDuckGo, scraper) and optional Ollama summarization, which are beyond what annotations provide.
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 succinct, uses a bullet list for arguments, and front-loads the cascade mechanism. Every sentence provides value without redundancy.
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?
Given the presence of an output schema (not shown but indicated), the description adequately covers input parameters and behavior. It is complete for an AI agent to invoke the tool correctly.
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 explain parameters. It does so effectively: query as search string, max_results (1-20), summarize (if Ollama available), and auto_fetch_top (fetch top result content). This adds substantial meaning beyond the JSON 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?
The description clearly states it searches the web using a 3-tier cascade, differentiating it from siblings like academic_lookup, fetch_url, and research. The verb 'Search' and resource 'web' are specific, and the cascade detail adds precision.
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?
While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus alternatives like fetch_url or research. It lacks when-not conditions or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract essence from a YouTube video: transcript, summary, key points, chapters, quotes.
Args: url: YouTube URL (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). mode: Extraction depth — "quick" (TL;DR), "standard" (+ chapters), or "deep" (+ quotes).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| mode | No | standard |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral traits beyond these, such as external API dependency or rate limits. Despite annotations covering safety, the description misses contextual details like needing internet access.
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 very concise: a single sentence defining purpose followed by a well-structured Args list. Every sentence is meaningful, and the structure is front-loaded with the core action.
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?
Given the tool's simplicity (2 parameters, no nested objects), the description covers purpose, parameters, and output types. It lacks information on error handling or return format, but the existence of an output schema mitigates this. Overall, it is adequately complete.
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?
With 0% schema description coverage, the description fully compensates by explaining the 'url' parameter with allowed formats and the 'mode' parameter with three depth levels and their effects. This adds significant meaning beyond the raw 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?
The description clearly states the action ('Extract essence') and the resource ('YouTube video'), followed by a list of outputs (transcript, summary, key points, chapters, quotes). This distinguishes it from siblings like twitter_extract or fetch_url which target different sources or actions.
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 provides clear usage context via parameter explanations (allowed URL formats and mode options). However, it does not explicitly mention when to use this tool over alternatives or exclude scenarios, though the specificity to YouTube serves as implicit guidance.
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. Dates show when Glama detected each change.
v0.1.1academic_lookupdeep_ingestfetch_urlresearchtwitter_extractvault_statusweb_searchyoutube_essencev0.3.0academic_lookupdeep_ingestfetch_url1 field changedInput schema / properties / max_chars / defaultPrevious value: -50000New value: +0twitter_extractvault_statusyoutube_essencev0.1.0fetch_urlresearchweb_searchEach tool targets a distinct source or operation: academic references, local files, URLs, compound research, Twitter, vault status, web search, and YouTube. There is no ambiguity between tools.
Tool names use mixed conventions: verb_noun (fetch_url, web_search), noun_noun (vault_status, youtube_essence), platform_verb (twitter_extract), and single word (research). No consistent pattern.
8 tools is an appropriate scope for a research assistant, covering key sources (web, academic, social media, local files) without being overwhelming.
The toolset covers major research workflows: search, fetch, extract, and synthesize. Minor gaps like result organization or citation management are not critical for core functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Web research for agents: quality-scored Google search, webpage extraction, and deep research.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
Agent-native search engine with live web research optimized for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MABAAM/Maibaamcrawler'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
