The Web Research Assistant is a comprehensive MCP server offering 13 specialized tools for technical web research, package management, content extraction, and infrastructure monitoring.
Search & Discovery:
Web Search: Federated search across multiple engines via SearXNG for general queries and recent information
Technical Content Search: Find code examples, tutorials, and technical articles with time filtering
Image Search: High-quality royalty-free stock photos, illustrations, and vectors via Pixabay
Package Management: Search and retrieve detailed metadata (license, downloads, versions) across npm, PyPI, crates.io, and Go registries
Content Extraction & Analysis:
Web Crawling: Extract full, cleaned page content from URLs with configurable character limits
Structured Data Extraction: Extract tables, lists, fields (via CSS selectors), or JSON-LD from web pages into clean JSON
API Documentation: Dynamically discover and crawl official API documentation with examples and explanations
Development Tools:
GitHub Analysis: Repository health metrics, stars, forks, issues, commits, and development activity
Error Resolution: Find Stack Overflow and GitHub solutions for stack traces and error messages with automatic language/framework detection
Technology Comparison: Side-by-side comparison of 2-5 technologies with popularity metrics and performance insights
Changelog Access: Release notes and breaking change detection for safe package upgrades
Infrastructure Monitoring:
Service Status Checks: Instant health checks for 25+ popular services (Stripe, AWS, GitHub, OpenAI, etc.)
Key Features: All tools require a reasoning parameter for usage analytics, include automatic response size limiting (8KB default), comprehensive error handling, and dynamic discovery for maximum flexibility.
Requires a local Docker instance to run SearXNG for federated search capabilities.
Provides repository health metrics including stars, forks, issues, recent commits, and project details for evaluating open source projects.
Allows searching for npm packages by keywords and retrieving detailed package metadata including versions, downloads, licenses, and dependencies.
Enables checking OpenAI service status including operational health, current incidents, and component status for production debugging.
Enables searching for high-quality royalty-free stock images, photos, illustrations, and vectors through the Pixabay API.
Enables searching for Python packages and retrieving package metadata including versions, downloads, licenses, and dependencies from PyPI.
Provides federated web search across multiple search engines via a local SearXNG instance, enabling comprehensive web research and content discovery.
Enables finding solutions for error messages and stack traces by searching Stack Overflow with automatic language/framework detection and filtering.
Enables checking Stripe service status including operational health, current incidents, and component status for production debugging.
Enables checking Vercel service status including operational health, current incidents, and component status for production debugging.
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., "@Web Research Assistant compare React vs Vue for a new dashboard project"
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.
Comprehensive Model Context Protocol (MCP) server that provides web research and discovery capabilities. Includes 14 tools, 4 resources, and 5 prompts for searching, crawling, and analyzing web content, powered by your local Docker SearXNG instance, Exa AI neural search, Scrapling, and Pixabay API:
web_search — federated search across multiple engines via SearXNG
search_examples — find code examples, tutorials, and articles (defaults to recent content)
search_images — find high-quality stock photos, illustrations, and vectors via Pixabay
crawl_url — full page content extraction with advanced crawling
package_info — detailed package metadata from npm, PyPI, crates.io, Go
package_search — discover packages by keywords and functionality
github_repo — repository health metrics and development activity
translate_error — find solutions for error messages and stack traces from Stack Overflow (auto-detects CORS, fetch, and web errors)
api_docs — auto-discover and crawl official API documentation with examples (works for any API - no hardcoded URLs)
extract_data — extract structured data (tables, lists, fields, JSON-LD) from web pages with automatic detection
compare_tech — compare technologies side-by-side with NPM downloads, GitHub stars, and aspect analysis (React vs Vue, PostgreSQL vs MongoDB, etc.)
get_changelog — NEW! Get release notes and changelogs with breaking change detection (upgrade safely from version X to Y)
check_service_status — NEW! Instant health checks for 25+ services (Stripe, AWS, GitHub, OpenAI, etc.) - "Is it down or just me?"
All tools feature comprehensive error handling, response size limits, usage tracking, and clear documentation for optimal AI agent integration.
package://{registry}/{name} - Package info from npm, PyPI, crates.io, or Go modules
github://{owner}/{repo} - Repository information and health metrics
status://{service} - Service health status for 120+ services
changelog://{registry}/{package} - Package release notes and changelogs
research_package - Comprehensive package evaluation
debug_error - Structured error debugging with solutions
compare_technologies - Side-by-side technology comparison
evaluate_repository - GitHub repository health assessment
check_service_health - Multi-service status monitoring
Everything runs in Docker - no Python installation needed:
./docker-start.shThis starts both SearXNG and the MCP server in containers. See DOCKER_SETUP.md for details.
Set up SearXNG (5 minutes):
# Using Docker (recommended)
docker run -d -p 2288:8080 searxng/searxng:latestThen configure search engines - see SEARXNG_SETUP.md for optimized settings.
Install the MCP server:
uvx web-research-assistant # or: pip install web-research-assistantConfigure Claude Desktop - add to claude_desktop_config.json:
{
"mcpServers": {
"web-research-assistant": {
"command": "uvx",
"args": ["web-research-assistant"]
}
}
}Restart Claude Desktop and start researching!
⚠️ For best results: Configure SearXNG with GitHub, Stack Overflow, and other code-focused search engines. See SEARXNG_SETUP.md for the recommended configuration.
Related MCP server: SearXNG MCP Server
Python 3.10+
A running SearXNG instance on http://localhost:2288
📖 See SEARXNG_SETUP.md for complete Docker setup guide
⚠️ IMPORTANT: For best results, enable these search engines in SearXNG:
GitHub, Stack Overflow, GitLab (for code search - critical!)
DuckDuckGo, Brave (for web search)
MDN, Wikipedia (for documentation)
Reddit, HackerNews (for tutorials and discussions)
See SEARXNG_SETUP.md for the full optimized configuration
Exa API key for neural search - Get API key (recommended for better search results)
Pixabay API key for image search - Get free key
Playwright browsers for advanced crawling (installed with scrapling install)
uv tool install uv # if you do not already have uv
uv sync --all-extras --all-groups # creates the virtual environment
uv run scrapling install # installs Chromium for ScraplingYou can also use
pip install -e .if you prefer pip over uv (deps come frompyproject.toml).
uvx web-research-assistantThis runs the server directly from PyPI without installing it globally.
pip install web-research-assistant
web-research-assistantuv tool install web-research-assistant
web-research-assistantBy default the server communicates over stdio, which makes it easy to wire into Claude Desktop or any other MCP host.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Option 1: Using uvx (Recommended - No installation needed!)
{
"mcpServers": {
"web-research-assistant": {
"command": "uvx",
"args": ["web-research-assistant"]
}
}
}Option 2: Using installed package
{
"mcpServers": {
"web-research-assistant": {
"command": "web-research-assistant"
}
}
}Add to ~/.config/opencode/opencode.json:
Using uvx (Recommended)
{
"mcp": {
"web-research-assistant": {
"type": "local",
"command": ["uvx", "web-research-assistant"],
"enabled": true
}
}
}Using installed package
{
"mcp": {
"web-research-assistant": {
"type": "local",
"command": ["web-research-assistant"],
"enabled": true
}
}
}For Claude Desktop:
{
"mcpServers": {
"web-research-assistant": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/web-research-assistant",
"run",
"web-research-assistant"
]
}
}
}For OpenCode:
{
"mcp": {
"web-research-assistant": {
"type": "local",
"command": [
"uv",
"--directory",
"/ABSOLUTE/PATH/TO/web-research-assistant",
"run",
"web-research-assistant"
],
"enabled": true
}
}
}Restart your MCP client afterwards. The MCP tools will be available immediately.
Tool | When to use | Arguments |
| Use first to gather recent information and URLs from SearXNG. Returns 1–10 ranked snippets with clickable URLs. |
|
| Find code examples, tutorials, and technical articles. Optimized for technical content with optional time filtering. Perfect for learning APIs or finding usage patterns. |
|
| Find high-quality royalty-free stock images from Pixabay. Returns photos, illustrations, or vectors. Requires |
|
| Call immediately after search when you need the actual article body for quoting, summarizing, or extracting data. |
|
| Look up specific npm, PyPI, crates.io, or Go package metadata including version, downloads, license, and dependencies. Use when you know the package name. |
|
| Search for packages by keywords or functionality (e.g., "web framework", "json parser"). Use when you need to find packages that solve a specific problem. |
|
| Get GitHub repository health metrics including stars, forks, issues, recent commits, and project details. Use when evaluating open source projects. |
|
| Find Stack Overflow solutions for error messages and stack traces. Auto-detects language/framework, extracts key terms (CORS, map, undefined, etc.), filters irrelevant results, and prioritizes Stack Overflow solutions. Handles web-specific errors (CORS, fetch). |
|
| Auto-discover and crawl official API documentation. Dynamically finds docs URLs using patterns (docs.{api}.com, {api}.com/docs, etc.), searches for specific topics, crawls pages, and extracts overview, parameters, examples, and related links. Works for ANY API - no hardcoded URLs. Perfect for API integration and learning. |
|
| Extract structured data from HTML pages. Supports tables, lists, fields (via CSS selectors), JSON-LD, and auto-detection. Returns clean JSON output. More efficient than parsing full page text. Perfect for scraping pricing tables, package specs, release notes, or any structured content. |
|
| Compare 2-5 technologies side-by-side. Auto-detects category (framework/database/language) and gathers data from NPM, GitHub, and web search. Returns structured comparison with popularity metrics (downloads, stars), performance insights, and best-use summaries. Fast parallel processing (3-4s). |
|
| NEW! Get release notes and changelogs for package upgrades. Fetches GitHub releases, highlights breaking changes, and provides upgrade recommendations. Answers "What changed in version X → Y?" and "Are there breaking changes?" Perfect for planning dependency updates. |
|
| NEW! Instantly check if external services are experiencing issues. Covers 25+ popular services (Stripe, AWS, GitHub, OpenAI, Vercel, etc.). Returns operational status, current incidents, and component health. Critical for production debugging - know immediately if the issue is external. Response time < 2s. |
|
Results are automatically trimmed (default 8 KB) so they stay well within MCP response expectations. If truncation happens, the text ends with a note reminding the model that more detail is available on request.
MCP Resources provide direct data access via URI templates - perfect for quick lookups without tool calls.
Resource URI | Description | Example |
| Package metadata (version, downloads, license, dependencies) |
|
| Repository info (stars, forks, issues, activity) |
|
| Service health status |
|
| Release notes and changelogs |
|
MCP Prompts are reusable message templates that guide AI assistants through common workflows.
Prompt | Arguments | Use Case |
|
| Evaluate a package before adding it as a dependency |
|
| Debug an error with context and solutions |
|
| Compare frameworks, databases, or languages |
|
| Assess a GitHub project's health and activity |
|
| Monitor multiple services at once |
Environment variables let you adapt the server without touching code:
Variable | Default | Description |
|
| Endpoint queried by |
|
| Category used when none is provided. |
|
| Default number of search hits. |
|
| Hard cap on hits per request. |
|
| Default character budget for |
|
| Overall response limit applied to every tool reply. |
|
| User-Agent header for outward HTTP calls. |
| (empty) | API key for Pixabay image search. Get free key at pixabay.com/api/docs. |
| (empty) | API key for Exa AI neural search. Get key at dashboard.exa.ai. |
|
| Search provider: |
|
| Location for usage analytics data. |
The codebase is intentionally modular and organized:
web-research-assistant/
├── src/searxng_mcp/ # Source code
│ ├── config.py # Configuration and environment
│ ├── search.py # SearXNG integration
│ ├── exa.py # Exa AI neural search client
│ ├── crawler.py # Scrapling wrapper
│ ├── images.py # Pixabay client
│ ├── registry.py # Package registries (npm, PyPI, crates, Go)
│ ├── github.py # GitHub API client
│ ├── errors.py # Error parser (language/framework detection)
│ ├── api_docs.py # API docs discovery (NO hardcoded URLs)
│ ├── tracking.py # Usage analytics
│ └── server.py # MCP server + 14 tools
├── docs/ # Documentation (27 files)
└── [config files]Each module is well under 400 lines, making the codebase easy to understand and extend.
All tools automatically track usage metrics including:
Tool invocation counts and success rates
Response times and performance trends
Common use case patterns (via the reasoning parameter)
Error frequencies and types
Analytics data is stored in ~/.config/web-research-assistant/usage.json and can be analyzed
to optimize tool usage and identify patterns. Each tool requires a reasoning parameter
that helps categorize why tools are being used, enabling better analytics and insights.
Note: As of the latest update, the reasoning parameter is required for all tools (previously optional with defaults). This ensures meaningful analytics data collection.
Comprehensive documentation is available in the docs/ directory:
Project Status - Current status, metrics, roadmap
API Docs Implementation - NEW tool documentation
Error Translator Design - Error translator details
Tool Ideas Ranked - Prioritization and progress
SearXNG Configuration - Recommended setup
Quick Start Examples - Usage examples
See the docs README for a complete index.
Search and fetch official API documentation with examples and explanations.
Documentation-first approach: fetches human-written docs with context, examples,
and best practices. Much more useful than OpenAPI specs alone.
Discovery strategy:
1. Try common URL patterns (docs.{api}.com, {api}.com/docs, etc.)
2. If patterns fail, search for "{api} API official documentation"
3. Crawl discovered docs and extract relevant content
No hardcoded URLs - works for ANY API by discovering docs dynamically.
Examples:
- api_docs("stripe", "create customer", reasoning="Setting up payments")
- api_docs("github", "create repository", reasoning="Automating repo creation")
- api_docs("spartan", "button component", reasoning="Learning UI library")
| Name | Required | Description | Default |
|---|---|---|---|
| api_name | Yes | ||
| reasoning | Yes | ||
| topic | Yes | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the dynamic discovery process (common URL patterns, search fallback, crawling) and notes no hardcoded URLs. With no annotations, this adds valuable behavioral context, though details like rate limits or auth are absent.
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 well-structured with front-loaded purpose, followed by comparison, strategy, and concise examples. Every sentence adds 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 tool's complexity, the description covers the key aspects: purpose, strategy, and examples. The presence of an output schema reduces the need to detail return values, making this sufficiently complete for an AI agent.
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 description and examples illustrate the role of 'api_name' and 'topic' and mention default for 'max_results'. But it does not fully explain the 'reasoning' parameter, and schema coverage is 0%, leaving some ambiguity.
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's purpose as searching and fetching official API documentation, distinguishing it from generic web searches or scraping. It explicitly contrasts with OpenAPI specs, emphasizing its value for human-written docs.
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 a documented discovery strategy and examples, guiding when to use the tool (e.g., for any API's official docs). However, it lacks explicit when-not-to-use guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if an API service or platform is experiencing issues.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| reasoning | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It fails to mention whether the tool is read-only, requires authentication, has rate limits, or how it obtains status information. The output schema exists but the description adds no behavioral context beyond the basic purpose.
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 a single sentence with no wasted words, achieving conciseness. However, it could be restructured to include more detail about parameters or behavior without becoming verbose. It is appropriately front-loaded but lacks depth.
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 and the simplicity of the tool (2 required string params), the description is too brief. It does not provide enough context for an agent to understand how to fill parameters or what to expect, especially since parameter semantics are absent. The description should elaborate on what constitutes a 'service' and how to interpret the reasoning input.
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, meaning no parameter descriptions are present. The tool description does not explain what 'service' (e.g., service name, URL) or 'reasoning' (e.g., purpose of check) represent, leaving the agent to guess the semantic meaning of these required parameters.
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's purpose: checking if an API service or platform is experiencing issues. It uses a specific verb ('check') and resource ('API service or platform'), and it distinguishes itself from sibling tools like web_search, api_docs, etc., which focus on different tasks.
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?
No guidance is provided on when to use this tool versus alternatives or when not to use it. The description simply states what it does without contextualizing usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare multiple technologies, frameworks, or libraries side-by-side.
Automatically gathers information about each technology and presents
a structured comparison to help make informed decisions.
Categories:
- "framework": Web frameworks (React, Vue, Angular, etc.)
- "library": JavaScript/Python/etc. libraries
- "database": Databases (PostgreSQL, MongoDB, etc.)
- "language": Programming languages (Python, Go, Rust, etc.)
- "tool": Build tools, CLIs, etc. (Webpack, Vite, etc.)
- "auto": Auto-detect category
Examples:
- compare_tech(["React", "Vue", "Svelte"], reasoning="Choose framework for new project")
- compare_tech(["PostgreSQL", "MongoDB"], category="database", reasoning="Database for user data")
- compare_tech(["FastAPI", "Flask"], aspects=["performance", "learning_curve"], reasoning="Python web framework")
| Name | Required | Description | Default |
|---|---|---|---|
| technologies | Yes | ||
| reasoning | Yes | ||
| category | No | auto | |
| aspects | No | ||
| max_results_per_tech | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It mentions automated information gathering and structured output, but lacks details on read-only behavior, rate limits, or reliability of auto-detection. It does not contradict any annotations, so 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?
The description is concise, well-structured with a purpose statement, category list, and clear examples. Every sentence adds value without redundancy, making it easy for an AI agent to parse.
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 with 5 parameters, the description covers the essential aspects: purpose, categories, and usage examples. It omits explanation of 'max_results_per_tech', but since an output schema exists, return values are not required. Overall, it provides sufficient context for correct invocation.
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 add meaning. It explains the 'category' parameter with an enum list and provides examples showing usage of 'technologies', 'reasoning', 'aspects'. However, 'max_results_per_tech' is not described, leaving a 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 it compares multiple technologies with specific verb 'Compare' and resource 'technologies, frameworks, or libraries'. It lists categories and examples, differentiating it from sibling tools that perform other tasks like crawling or searching.
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 categories and examples demonstrating when to use the tool. It does not explicitly state when not to use it or alternatives, but the sibling tools are functionally distinct, making misuse unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a URL and return the page text as markdown for quoting or analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| reasoning | Yes | ||
| max_chars | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the basic fetch-and-convert action. It does not mention authentication requirements, error behavior, rate limits, or any side effects. The presence of an output schema is not referenced.
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 a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core 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 4 parameters, an output schema, and no annotations, the description is insufficient. It explains neither the parameters nor the output format, and lacks any usage context or error handling information.
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 not describe any of the four parameters (url, reasoning, max_chars, country), leaving their purpose unclear. The description adds no value beyond the parameter names.
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 fetches a URL and returns page text as markdown for quoting or analysis. This is a specific verb-resource combination and distinguishes it from siblings like web_search (which likely returns search results) and stealth_scrape (which might have a different method).
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?
No explicit guidance on when to use this tool versus alternatives. The mention of 'for quoting or analysis' implies use cases, but there is no comparison to siblings like stealth_scrape or web_search, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract structured data from web pages.
Extracts tables, lists, or specific fields from HTML pages and returns
structured data. Much more efficient than parsing full page text.
Extract Types:
- "table": Extract HTML tables as list of dicts
- "list": Extract lists (ul/ol/dl) as structured list
- "fields": Extract specific elements using CSS selectors
- "json-ld": Extract JSON-LD structured data
- "auto": Automatically detect and extract structured content
Examples:
- extract_data("https://pypi.org/project/fastapi/", reasoning="Get package info")
- extract_data("https://github.com/user/repo/releases", reasoning="Get releases", extract_type="list")
- extract_data(
"https://example.com/product",
reasoning="Extract product details",
extract_type="fields",
selectors={"price": ".price", "title": "h1.product-name"}
)
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| reasoning | Yes | ||
| extract_type | No | auto | |
| selectors | No | ||
| max_items | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description explains extract types and behavior via examples and bullet points. It does not cover authorization, rate limits, or error handling, but the behavioral core is well explained.
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?
Description is well-structured with clear sections, bullet points for extract types, and multiple examples. No superfluous 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?
Given the presence of output schema, description appropriately focuses on input behavior. Covers main use cases but omits potential limitations like page size or dynamic content.
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 description compensates by explaining extract_type enums, selectors usage with examples, and implicitly covers url and reasoning. However, max_items is not explained.
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 clearly states 'Extract structured data from web pages' and specifies five extract types (table, list, fields, json-ld, auto), making the verb and resource specific. It differentiates from siblings like crawl_url and web_search by focusing on structured extraction from HTML.
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?
Description notes efficiency advantage over parsing full page text and provides examples, implying use for structured extraction. However, lacks explicit when-not-to-use instructions or comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get changelog and release notes for a package.
| Name | Required | Description | Default |
|---|---|---|---|
| package | Yes | ||
| reasoning | Yes | ||
| registry | No | auto | |
| max_releases | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as side effects, calling requirements, rate limits, or response structure. The agent receives no additional context beyond the basic action.
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 a single sentence, which is concise but at the expense of completeness. It is front-loaded with the key action, but the brevity leads to omissions in other dimensions.
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?
Despite having 4 parameters (2 required), an enum, and an output schema, the description provides no context on how to use parameters, what the output contains, or how the tool behaves. This is insufficient for a tool of this complexity.
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, and the description adds no information about the parameters. The schema provides types and defaults but the description does not explain the meaning of 'reasoning', 'registry', or 'max_releases', leaving the agent to infer usage.
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 'Get' and resource 'changelog and release notes for a package', indicating the tool's purpose. However, it does not explicitly distinguish it from sibling tools like 'package_info' or 'package_search', though the specialization is implied.
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?
No guidance is provided on when to use this tool versus alternatives. For example, if a user wants general package information, they might mistakenly use this tool instead of 'package_info'. The description should mention that this tool is specifically for changelogs or release notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch GitHub repository information and health metrics.
Returns stars, forks, issues, recent activity, language, license, and description.
Use this to evaluate open source projects before using them.
Examples:
- github_repo("microsoft/vscode", reasoning="Evaluate editor project")
- github_repo("https://github.com/facebook/react", reasoning="Research UI framework")
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| reasoning | Yes | ||
| include_commits | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only lists return values but fails to disclose behavioral traits such as rate limits, authentication requirements, error handling, or side effects. The fetch operation is implied read-only but not stated.
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 with three lines, front-loads the purpose, and includes useful examples. Every sentence adds value with no 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?
The description adequately covers the tool's purpose and returns, but missing parameter details (especially 'include_commits') and behavioral context limit completeness. An output schema exists, which reduces need for return value explanation, but gaps remain.
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 add explicit parameter semantics. Examples hint at repo format (owner/name or URL) but do not formally explain. The 'include_commits' parameter is not 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 explicitly states the action ('Fetch GitHub repository information and health metrics') and lists the specific data returned (stars, forks, issues, etc.). It clearly distinguishes the tool's purpose among siblings like package_info or web_search.
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 a clear use case ('Use this to evaluate open source projects before using them'), which implies context. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up package information from npm, PyPI, crates.io, or Go modules.
Returns version, downloads, license, dependencies, security status, and repository links.
Use this to quickly evaluate libraries before adding them to your project.
Examples:
- package_info("express", reasoning="Need web framework", registry="npm")
- package_info("requests", reasoning="HTTP client for API", registry="pypi")
- package_info("serde", reasoning="JSON serialization", registry="crates")
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| reasoning | Yes | ||
| registry | No | npm |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes output fields (version, downloads, etc.) but does not disclose additional behavioral traits such as read-only nature, error handling, or rate limits. Since no annotations exist, the description carries the full burden and this is a moderate gap.
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 with four sentences and three helpful examples, front-loading the purpose and key details without unnecessary 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?
Covers purpose, usage, output fields, and registry options adequately for a lookup tool. Missing details on error conditions or package not found, but overall complete given simplicity.
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 schema has 0% description coverage; the description partly compensates through examples showing parameter usage. However, the 'reasoning' parameter is required but its purpose remains ambiguous despite examples.
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 looks up package information from specific registries and lists returned fields. It distinguishes from sibling 'package_search' by focusing on detailed info for a specific package rather than searching.
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?
Provides a usage scenario ('evaluate libraries before adding them to your project') but does not explicitly mention when not to use or suggest alternatives like 'package_search' for searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for packages by keywords or description across registries.
Use this to find packages that solve a specific problem or provide certain functionality.
Perfect for discovering libraries when you know what you need but not the package name.
Examples:
- package_search("web framework", reasoning="Need backend framework", registry="npm")
- package_search("json parsing", reasoning="Data processing", registry="pypi")
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| reasoning | Yes | ||
| registry | No | npm | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only states 'search for packages' without mentioning side effects, authentication, rate limits, or result behavior. No details on pagination or filtering beyond the schema.
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?
Concise, with front-loaded purpose and examples. Every sentence adds value. Could be slightly more efficient, but no fluff.
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 4 parameters, 2 required, an enum, and an output schema, the description is incomplete. It lacks parameter details, output format, and behavioral context. The tool is complex enough to require more guidance than provided.
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%. Description does not explain any parameter meaning (query, reasoning, registry, max_results). Examples hint at usage but do not clarify semantics, types, or constraints. For a 4-parameter tool with 0% coverage, this is insufficient.
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?
Clearly states verb 'search' and resource 'packages', with specific context of discovering libraries by functionality. Examples reinforce purpose and differentiate from sibling tool 'package_info' which requires known package 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?
Provides explicit usage context: 'find packages that solve a specific problem' and 'when you know what you need but not the package name'. Lacks explicit when-not-to-use or alternatives, but the examples and phrasing offer clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code examples, tutorials, and technical articles.
Optimized for finding practical examples and learning resources. Can optionally filter by
time range for the most recent content. Perfect for learning new APIs, finding usage patterns,
or discovering how others solve specific technical problems.
Content Types:
- 'code': GitHub repos, code snippets, gists, Stack Overflow code examples
- 'articles': Blog posts, tutorials, documentation, technical articles
- 'both': Mix of code and written content (default)
Time Ranges:
- 'all': Search all available content (default, recommended for best results)
- 'year', 'month', 'week', 'day': Filter to recent content only
Examples:
- search_examples("FastAPI dependency injection examples", content_type="code")
- search_examples("React hooks tutorial", content_type="articles", time_range="year")
- search_examples("Rust lifetime examples", content_type="both")
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| reasoning | Yes | ||
| content_type | No | both | |
| time_range | No | all | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses filtering capabilities and default values, but does not clarify if the operation is read-only or if there are any side effects. Since no annotations are provided, the description carries the full burden. It lacks details on response structure (though output schema exists) and potential limitations.
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 well-structured with a clear purpose, bullet points for options, and usage examples. It is somewhat verbose but informative. The most critical 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?
The description adequately covers content_type and time_range but omits explanation for the 'reasoning' parameter, which is required and may be unclear. Additionally, it does not describe the return value or how the tool handles edge cases, despite having an output schema. Given the presence of 5 parameters and moderate complexity, it is partially 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?
The description explains the semantics of content_type and time_range parameters with enumerations and defaults, which adds value beyond the schema. However, it does not explain the 'reasoning' parameter (required) or 'max_results', leaving ambiguity. With 0% schema description coverage, more compensation is expected, but partial coverage is provided.
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's purpose: 'Search for code examples, tutorials, and technical articles.' The verb 'search' and resource 'examples' are specific. It distinguishes itself from sibling tools like web_search and search_images by focusing on code and learning resources.
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 context for when to use the tool: 'Perfect for learning new APIs, finding usage patterns, or discovering how others solve specific technical problems.' It also explains the two filtering dimensions. However, it does not explicitly mention when not to use it or direct users to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for high-quality stock images using Pixabay.
Returns royalty-free images that are safe to use. Perfect for finding photos,
illustrations, and vector graphics for projects, presentations, or design work.
Image Types:
- 'photo': Real photographs
- 'illustration': Digital illustrations and artwork
- 'vector': Vector graphics (SVG format available)
- 'all': All types (default)
Examples:
- search_images("mountain landscape", image_type="photo")
- search_images("business icons", image_type="vector")
- search_images("technology background", orientation="horizontal")
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| reasoning | Yes | ||
| image_type | No | all | |
| orientation | No | all | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions images are royalty-free and safe to use, but lacks details on limitations, rate limits, or authentication. Adequate but not comprehensive.
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, uses bullet points for clarity, and front-loads the main purpose. Every sentence adds 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 output schema exists, the description sufficiently covers source, usage, and image types. It is fairly complete for a search tool, though it omits details on output structure (mitigated by output 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%, so the description should compensate by explaining all parameters. It explains image_type and orientation via examples but does not clarify the 'reasoning' parameter, leaving a key required parameter 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?
The description clearly states the tool searches for high-quality stock images using Pixabay, specifying the resource (images) and source. It differentiates from sibling tools like web_search by focusing on image search.
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 examples and lists image types, helping users decide when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scrape a URL using a stealth browser that bypasses anti-bot protections.
Uses scrapling's StealthyFetcher with Patchright (hardened Playwright) to evade
Cloudflare, DataDome, and similar anti-bot systems. Much slower than crawl_url
but works on protected sites.
Requires browser binaries: run 'scrapling install' once before first use.
When to use:
- crawl_url returns a Cloudflare challenge page or empty content
- The target site blocks automated requests
- JavaScript rendering is required for the content to appear
- You need to wait for a specific element to load
Examples:
- stealth_scrape("https://protected-site.com/pricing")
- stealth_scrape("https://spa-app.com/data", wait_selector=".results-table")
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| reasoning | Yes | ||
| max_chars | No | ||
| wait_selector | No | ||
| solve_cloudflare | No | ||
| headless | No | ||
| country | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description explains it uses StealthyFetcher with Patchright, is slower than crawl_url, requires browser binaries setup, and can handle Cloudflare and JS rendering. However, it does not disclose error handling if binaries are missing or any 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?
Well-structured with a clear opening, setup note, usage list, and examples. Every sentence adds value, no 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?
Covers main purpose, context, and usage scenarios, but omits details on some parameters (reasoning, max_chars, headless, country) and potential error states. Output schema exists, so return values are not required.
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%, yet description explains wait_selector and solve_cloudflare implicitly via examples and text. However, it does not document reasoning, max_chars, headless, or country, leaving significant gaps beyond what the schema provides.
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 scrapes a URL using a stealth browser to bypass anti-bot protections, and distinguishes from sibling tool crawl_url by noting it is slower but works on protected sites.
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?
Provides explicit when-to-use conditions (e.g., crawl_url returns Cloudflare challenge, site blocks automated requests, JS rendering needed) and includes two concrete examples, aiding the agent in correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find solutions for error messages and stack traces from Stack Overflow and GitHub.
Takes an error message or stack trace and finds relevant solutions with code examples.
Automatically detects language and framework, extracts key error information, and
searches for the best solutions ranked by votes and relevance.
Perfect for:
- Debugging production errors
- Understanding cryptic error messages
- Finding working code fixes
- Learning from similar issues
Examples:
- translate_error("TypeError: Cannot read property 'map' of undefined", reasoning="Debugging React app crash")
- translate_error("CORS policy: No 'Access-Control-Allow-Origin' header", reasoning="Fixing API integration", framework="FastAPI")
- translate_error("error[E0382]: borrow of moved value", reasoning="Learning Rust ownership", language="rust")
| Name | Required | Description | Default |
|---|---|---|---|
| error_message | Yes | ||
| reasoning | Yes | ||
| language | No | ||
| framework | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses that the tool automatically detects language/framework, extracts key info, and ranks results by votes and relevance. With no annotations provided, these details are valuable, though it doesn't clarify interaction with optional language/framework parameters 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 moderately concise with bullet points and examples, but could be slightly more streamlined. It front-loads the key action and uses examples effectively.
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 complexity (5 params, 2 required, output schema), the description covers the main purpose and behavior but lacks explanation for the reasoning parameter and how optional parameters override auto-detection. Output schema existence reduces need for return value details, but there are still 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?
Examples illustrate use of language, framework, and reasoning, but the description does not explicitly define the purpose of the reasoning parameter, and language/framework are mentioned as auto-detected without clarifying that they are optional overrides. Schema coverage is 0%, so more explicit parameter descriptions would help.
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 finds solutions for error messages and stack traces from Stack Overflow and GitHub, with automatic detection and ranking. This distinguishes it from siblings like web_search or package_search which are more general.
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 'Perfect for' section lists specific use cases (debugging production errors, understanding cryptic messages, etc.), implicitly guiding when to use. However, it does not explicitly contrast with sibling tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this first to gather fresh web search results via the local SearXNG instance.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| reasoning | Yes | ||
| category | No | science | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only mentions the source (SearXNG) and freshness, but omits behavioral details such as rate limits, pagination, or return format. The output schema exists, but the description does not explain what the tool returns.
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 a single, front-loaded sentence with no wasted words. However, it is arguably too concise; it could include more detail without becoming verbose. Still, for a short description, it earns a high score for efficiency.
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 4 parameters (2 required), no annotations, and an output schema, the description is insufficient. It lacks context about when to use this over other search tools, parameter meanings, and what the output contains. The existence of an output schema does not excuse the lack of behavioral context in the description.
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%, yet the description provides no explanations for any of the 4 parameters. The purpose of 'reasoning', valid categories, and max_results limit are left undocumented. The description adds no value beyond the schema's parameter names and types.
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's action (gather fresh web search results) and resource (web, via SearXNG). The name 'web_search' matches the description. However, it does not differentiate from sibling search tools like 'search_images' or 'package_search', so it lacks explicit sibling differentiation.
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 phrase 'Use this first' gives a weak usage hint about sequencing, but no explicit when-not-to-use or alternative tools are mentioned. Given the siblings, more guidance would help an agent decide between this and other search tools.
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.3.0crawl_url1 field changedInput schema / properties / countryAdded value: +{
+ "default": "",
+ "title": "Country",
+ "type": "string"
+}stealth_scrapev1.0.0api_docs1 field changedInput schema / titleAdded value: +"api_docsArguments"check_service_status1 field changedInput schema / titleAdded value: +"check_service_statusArguments"compare_tech1 field changedInput schema / titleAdded value: +"compare_techArguments"crawl_url1 field changedInput schema / titleAdded value: +"crawl_urlArguments"extract_data1 field changedInput schema / titleAdded value: +"extract_dataArguments"get_changelog1 field changedInput schema / titleAdded value: +"get_changelogArguments"github_repo1 field changedInput schema / titleAdded value: +"github_repoArguments"package_info1 field changedInput schema / titleAdded value: +"package_infoArguments"package_search1 field changedInput schema / titleAdded value: +"package_searchArguments"search_examples1 field changedInput schema / titleAdded value: +"search_examplesArguments"search_images1 field changedInput schema / titleAdded value: +"search_imagesArguments"translate_error1 field changedInput schema / titleAdded value: +"translate_errorArguments"web_search1 field changedInput schema / titleAdded value: +"web_searchArguments"api_docscheck_service_statuscompare_techcrawl_urlextract_dataget_changeloggithub_repopackage_infopackage_searchsearch_examplessearch_imagestranslate_errorweb_searchScored across 14 tools
Each tool targets a distinct research task (e.g., web_search vs. api_docs vs. compare_tech), with clear descriptions that prevent overlap. Even similar tools like crawl_url and stealth_scrape are differentiated by use cases.
Names mostly follow a verb_noun or noun_noun pattern with underscores, but there are minor inconsistencies (e.g., 'github_repo' vs. 'check_service_status'). Overall readable and predictable.
14 tools are well-scoped for a web research assistant, covering searching, fetching, extracting, and analyzing without being overwhelming or too few.
Covers core research workflows (search, fetch, extract, compare, check status, find packages/images/errors). Minor gaps like direct social media scraping are acceptable for the stated purpose.
8-tool AI web intelligence suite: search, scrape, screenshot, SEO, docs, crypto, code.
Web search, URL content extraction to Markdown, site mapping, and recursive web crawler.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Search the agentic web. 4,100+ sites, 11 tools incl. check_url + verify_mcp for probe-before-use.
