WebSearch-MCP provides a web search and data extraction service using Grok for broad searches and Tavily for detailed content fetching and site mapping. You can:
Perform broad web searches (Grok-powered) to quickly locate information, get initial answers, and identify traceable sources (no full-text extraction).
Retrieve cached source information from a previous web_search session.
Extract full web page content (Tavily Extract) and convert it into high-fidelity Markdown, ideal for research papers or long articles.
Map website structures (Tavily Map) to discover URL hierarchies for subsequent content fetching.
Diagnose configuration and connectivity by checking the masked server config and testing the Grok API connection, including available models.
Dynamically switch and persist the Grok model used for subsequent search requests within the current process.
Optionally define structured search plans by setting a core question, query type, time sensitivity, complexity, sub-queries, search terms, tool mappings, and execution order.
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., "@WebSearch-MCP search for latest Python 3.13 release notes"
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.
English | 简体中文
面向 Cherry Studio、Claude Code 与 Codex 的标准 MCP 网络搜索服务
双引擎分工 · 短提示广搜 · 270 秒主动预算 · Grok 并发 2 · Tavily 每 Key 并发 1
WebSearch MCP 把 Grok 广搜 与 Tavily 全文抓取 / 站点映射 组合成标准 MCP stdio 服务（双引擎各取所长）。它不依赖某个客户端的私有能力，也不会修改 Cherry Studio、Claude Code 或 Codex 的本地配置。
Claude / 其他 MCP Client
│ stdio MCP
▼
Grok Search Server
├─ web_search ───► Grok API（AI 联网搜索：广、快、找信源）
├─ get_sources ───► 搜索信源 session 缓存
├─ web_fetch ───► Tavily Extract（工程化全文抓取：完整、保真）
└─ web_map ───► Tavily Map（站点映射 / agentic crawl 入口）红线分工：web_search 只走 Grok；web_fetch / web_map 必须 走 Tavily。论文与长文全文请 web_search 定位后用 web_fetch 读取，禁止用 Grok 代替全文抓取。仅配置 Grok 时搜索仍可用；未配置 Tavily 时 fetch/map 返回明确结构化错误。
Related MCP server: Tavily Web Search MCP Server
能力 | 实际行为 |
双引擎红线 | Grok 负责广搜与信源；Tavily Extract/Map 负责全文与站内结构；职责不混用。 |
短提示广搜 | Grok 侧使用短英文搜索提示（层 B），避免超长 system 注入导致超时；证据细则在客户端系统提示（层 A）。 |
强模型优先 | 始终使用用户配置的单一最强 Grok 模型；临时错误默认最多真实调用 5 次（可配置）。 |
可选上游协议 |
|
证据融合 |
|
可解释可靠性 | 约 270 秒服务端总预算、Grok 进程级并发 2、Tavily 每 Key 并发 1、熔断、 |
稳定兼容 | 标准 MCP stdio、固定工具 Schema、统一 |
适合以下场景：
让编码助手检索最新官方文档、Release、Issue 和技术资料。
获取带可追溯信源的实时搜索答案。
把网页正文提取为 Markdown，或发现文档站点的 URL 结构。
在多个 MCP 客户端之间复用相同工具 Schema 和环境变量。
P0 仓库与测试基线：已完成。
P1 旧抓取服务清理与模块化：已完成。
P2 Tavily 多 Key 可靠性：已完成。
P3 Grok 单强模型与重试：已完成。
P4 统一返回协议：已完成。
P5 搜索 Prompt 与搜索质量重构：已完成。
搜索超时与并发治理：已完成自动化实现；等待 Cherry Studio 300 秒外层超时人工复验。
外部项目代码审计和有界运行时缓存：已完成；运行时固定使用 Chat Completions。
下一阶段：P6 跨客户端真实人工验收。
完整需求与验收标准见 开发路线文档。
需要：
Python 3.10+
一个 OpenAI 兼容的 Grok API 地址和 Key
Tavily Key（fetch/map 必要）：web_fetch、web_map 必须配置；extra_sources 可选增强
以下配置可直接复制；将 API 地址、Key 和模型替换为你的实际值。GROK_API_URL 必须是以 /v1 结尾的 API 根地址。按 GROK_API_PROTOCOL 调用 /chat/completions 或 /responses，并使用 /models。
{
"mcpServers": {
"grok-search": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Timmyzzo/WebSearch-MCP",
"grok-search"
],
"env": {
"GROK_API_URL": "https://your-api-endpoint.example/v1",
"GROK_API_KEY": "your-grok-api-key",
"GROK_PRIMARY_MODEL": "grok-4-fast",
"GROK_MODEL_MAX_ATTEMPTS": "5",
"GROK_MAX_CONCURRENCY": "2",
"WEB_SEARCH_TOTAL_TIMEOUT": "270",
"GROK_SINGLE_ATTEMPT_TIMEOUT": "120",
"GROK_RETRY_MULTIPLIER": "1",
"GROK_RETRY_MAX_WAIT": "10",
"GROK_RETRYABLE_UPSTREAM_CODES": "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error",
"TAVILY_PER_KEY_MAX_CONCURRENCY": "1",
"TAVILY_API_KEYS": "tvly-key-1,tvly-key-2"
}
}
}
}Cherry Studio 还需把 MCP 工具调用超时设置为 300 秒。
把下面对象保存为 JSON，或将其作为 claude mcp add-json 的参数：
{
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Timmyzzo/WebSearch-MCP",
"grok-search"
],
"env": {
"GROK_API_URL": "https://your-api-endpoint.example/v1",
"GROK_API_KEY": "your-grok-api-key",
"GROK_PRIMARY_MODEL": "grok-4-fast",
"GROK_MODEL_MAX_ATTEMPTS": "5",
"GROK_MAX_CONCURRENCY": "2",
"WEB_SEARCH_TOTAL_TIMEOUT": "270",
"GROK_SINGLE_ATTEMPT_TIMEOUT": "120",
"GROK_RETRY_MULTIPLIER": "1",
"GROK_RETRY_MAX_WAIT": "10",
"GROK_RETRYABLE_UPSTREAM_CODES": "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error",
"TAVILY_PER_KEY_MAX_CONCURRENCY": "1",
"TAVILY_API_KEYS": "tvly-key-1,tvly-key-2"
}
}Linux/macOS 安装命令：
claude mcp add-json grok-search --scope user "$(cat grok-search.json)"PowerShell 安装命令：
claude mcp add-json grok-search --scope user (Get-Content .\grok-search.json -Raw)config.toml 格式）Codex 的持久化 MCP 配置格式是 TOML，不是 JSON。将以下完整配置加入 ~/.codex/config.toml：
[mcp_servers.grok-search]
command = "uvx"
args = [
"--from",
"git+https://github.com/Timmyzzo/WebSearch-MCP",
"grok-search",
]
startup_timeout_sec = 30
tool_timeout_sec = 300
[mcp_servers.grok-search.env]
GROK_API_URL = "https://your-api-endpoint.example/v1"
GROK_API_KEY = "your-grok-api-key"
GROK_PRIMARY_MODEL = "grok-4-fast"
GROK_MODEL_MAX_ATTEMPTS = "5"
GROK_MAX_CONCURRENCY = "2"
WEB_SEARCH_TOTAL_TIMEOUT = "270"
GROK_SINGLE_ATTEMPT_TIMEOUT = "120"
GROK_RETRY_MULTIPLIER = "1"
GROK_RETRY_MAX_WAIT = "10"
GROK_RETRYABLE_UPSTREAM_CODES = "rate_limit,rate_limit_exceeded,too_many_requests,upstream_error,server_error,service_unavailable,temporarily_unavailable,overloaded,overloaded_error,internal_error"
TAVILY_PER_KEY_MAX_CONCURRENCY = "1"
TAVILY_API_KEYS = "tvly-key-1,tvly-key-2"更详细的验证步骤见：
推荐客户端系统提示（层 A） — 粘贴到 Claude / Cherry Studio 系统提示
在客户端中确认能发现以下核心工具：
web_search
get_sources
web_fetch
web_map
get_config_info
switch_model建议先调用 get_config_info 检查脱敏配置和 Grok /models 连接，再执行一次 web_search。
变量 | 必填 | 默认值 | 说明 |
| 是 | - | OpenAI 兼容 API 根地址（通常以 |
| 是 | - | Grok API Key。 |
| 否 |
| 上游请求形态： |
| 否 |
| Responses 内置服务端工具（xAI tools）。 |
| 否 | - | Responses |
| 否 |
| Responses 是否在服务端保存会话（MCP 默认关闭）。 |
| 否 | 见下文 | 每次搜索使用的强模型名称，由用户自行填写。 |
| 否 |
| 当前模型对可恢复故障的最多真实请求次数，必须为正整数，不设固定上限。 |
| 否 |
| 同一 MCP 进程最多同时发出的 Grok |
| 否 |
| 单次 |
| 否 |
| 单次 Grok 流读取超时秒数；实际值不会超过当前剩余总预算。 |
| 否 |
| 指数退避初始乘数，允许大于或等于 0 的小数。 |
| 否 |
| 单次退避等待上限秒数，允许大于或等于 0。 |
| 否 | 见下文 | HTTP 200 错误体中仍应重试的上游错误码，支持逗号、分号或换行分隔。 |
| 否 |
| 兼容配置；未设置非空 |
| 否 | - | 单个 Tavily Key。 |
| 否 | - | 多个 Tavily Key，支持逗号、分号或换行分隔，优先于单 Key。 |
| 否 |
| Tavily API 根地址。 |
| 否 |
| 是否启用 Tavily。 |
| 否 |
| 临时限流或单 Key 临时异常的冷却秒数。 |
| 否 |
| 额度耗尽 Key 的默认冷却秒数。 |
| 否 |
| 触发服务级熔断所需的不同 Key 同类故障数，最小为 2。 |
| 否 |
| Tavily 服务级熔断冷却秒数。 |
| 否 |
| Search、Extract、Map 共享的每 Key 真实请求并发上限；当前必须为 1。 |
| 否 |
| 是否记录调试信息。 |
| 否 |
| 日志级别。 |
| 否 |
| 日志目录。 |
只配置 Grok 时，web_search 仍可使用。web_fetch / web_map 依赖 Tavily，未配置 TAVILY_API_KEY / TAVILY_API_KEYS 时返回可操作错误（不会静默空返回）。设置 TAVILY_ENABLED=false 会禁用 Tavily，即使环境中存在 Tavily Key。
模型解析优先级为：当前进程中 switch_model 设置的模型、非空 GROK_PRIMARY_MODEL、非空 GROK_MODEL、配置文件中的模型、默认值 grok-4-fast。环境变量仅包含空白时视为未设置。服务不会自动降级到较弱备用模型；请直接配置你希望使用的最强可用模型。
默认可重试上游错误码为 rate_limit、rate_limit_exceeded、too_many_requests、upstream_error、server_error、service_unavailable、temporarily_unavailable、overloaded、overloaded_error 和 internal_error。这解决了部分中转站用 HTTP 200 包装临时错误、导致标准 HTTP 状态判断失效的问题。设置 GROK_RETRYABLE_UPSTREAM_CODES 会替换默认列表；若要增加自定义错误码，请在配置中同时保留所需默认项。
对于单次请求成功率约 40% 的端点，默认 12 次尝试在各次结果近似独立时，理论成功概率约为 99.78%，平均真实请求数约为 2.5。实际调用仍受 WEB_SEARCH_TOTAL_TIMEOUT 限制；如果错误经常表现为长时间超时，而不是数秒内返回错误码，需要同步增大服务端总预算和客户端工具超时。
工具 | 引擎 | 用途 | 工具专属字段 |
| Grok | 广搜、快定位、初答 + 可追溯信源；不做全文抓取 |
|
| 本地缓存 | 读取某次搜索的完整信源 |
|
| Tavily Extract | 论文/长文/文档全文 → 高保真 Markdown |
|
| Tavily Map | 站内 URL 结构发现，便于再 fetch |
|
| 诊断 | 查看脱敏配置并测试 Grok 连接 |
|
| 配置 | 持久化并切换当前进程的 Grok 主模型 |
|
所有工具还统一返回 status、error、error_detail 和 partial。web_search 的 query 是唯一必填参数。规划工具是可选能力，不是搜索前置步骤；所有 thought 参数均为可选。Claude Code 侧工具名可能带 mcp__grok-search__ 前缀。
层 | 位置 | 作用 |
层 A | Claude 等调用方：英文思考、中文对用户、证据标准、何时 search/fetch/map | |
层 B | MCP 内短英文 | 仅服务 Grok |
层 B 禁止 硬编码 7–16 次检索楼层或单次注入超长领域细则，以免 MCP 超时、弱于原项目可用性。
web_search（Grok）定位 URL / 初答
→ web_fetch（Tavily）读论文或文档全文
→（可选）web_map（Tavily）扩展站内页面再 fetch
→ 客户端按层 A 证据标准综合，用中文回复用户当 extra_sources>0 时，Tavily Search 可提供结构化候选进入 Grok 综合；这是增强，不能 削弱「fetch/map 必 Tavily」叙事。Tavily 补充失败时 Grok 仍可 partial_success；Grok 失败时 Tavily 不能替代最终答案。
Grok 上游由 GROK_API_PROTOCOL 选择：默认 chat → 流式 /chat/completions；response → 流式 /responses（官方推荐，input 消息数组 + 可选 server tools）。使用 Grok 4.5 / multi-agent 做联网研究时建议：
GROK_API_PROTOCOL=response
GROK_PRIMARY_MODEL=grok-4.5
# 或 multi-agent（Chat Completions 不可用，会自动强制 response）:
# GROK_PRIMARY_MODEL=grok-4.20-multi-agent-xhigh
GROK_SERVER_TOOLS=web_search,x_search
GROK_REASONING_EFFORT=xhigh # multi-agent 深度；4.5 可按需设置
GROK_SINGLE_ATTEMPT_TIMEOUT=600
WEB_SEARCH_TOTAL_TIMEOUT=270用户查询以短 JSON 传递；匹配到的领域细则（prompt_domains/*.md）按需追加到 system。关键结论附 Sources/References，便于 get_sources 缓存。
Cherry Studio 建议把 MCP 工具外层超时设置为 300 秒；这是避免客户端过早产生 -32001 的安全上限，不是性能目标。服务端单次 web_search 默认使用 WEB_SEARCH_TOTAL_TIMEOUT=270 的总墙钟预算，并在该预算内主动返回成功、部分成功或结构化错误，为 MCP 序列化、进程调度和客户端传输预留约 30 秒。
Grok 单次读取上限由 GROK_SINGLE_ATTEMPT_TIMEOUT 控制，默认 120 秒；每次真实尝试的实际可用时间会缩短为“单次上限与当前剩余总预算中的较小值”。GROK_MODEL_MAX_ATTEMPTS=5 只表示最多 5 次真实 HTTP 请求，不保证一定执行满：等待 Grok 槽位、Tavily Key 槽位、HTTP 传输、流读取、指数退避和 Retry-After 都消耗同一个总预算；剩余预算不足以容纳合理的新尝试时会提前停止。
同一 MCP 进程默认最多同时执行 2 个 Grok HTTP 请求。Tavily Search、Extract、Map 共用 Key 健康与占用状态，每个 Key 同时最多 1 个真实请求；多个健康 Key 可以各承担一个并发请求。所有槽位在成功、错误、取消、超时和流中断路径中释放，重试也必须重新排队。预算终止诊断会区分 max_attempts_exhausted、non_retryable_error、total_budget_exhausted 和 concurrency_queue_timeout，并报告配置/实际尝试数、耗时、预算与排队时间。
status 只有三种稳定值：
success：工具目标完整完成。合法的空信源列表可以成功，例如 Grok 给出有效答案但没有来源。
partial_success：已返回可用结果，但某个补充组件或非关键步骤失败。例如 Grok 成功、Tavily 补充失败；规划尚未完成；站点映射包含部分无效项。
error：当前工具目标未完成。空答案、空抓取内容、空 URL 映射、配置错误和上游失败都不会伪装成成功。
工具 |
|
|
|
| Grok 返回非空有效答案；来源可以为空。 | Grok 成功但已请求的 Tavily 补充失败。 | Grok 最终失败、流中断、无效/空答案或配置错误；Tavily 成功不能替代 Grok 答案。 |
| 会话存在； | 缓存中只有部分来源可验证。 | 会话不存在/过期或缓存组件失败。 |
| Tavily 返回非空 Markdown。 | 当前单 URL 提取是原子操作，暂无部分成功。 | 配置、认证、限流、服务、参数错误，或上游成功但无正文的 |
| 返回至少一个 URL 且响应完整。 | 返回了 URL，但缺少根 URL 或忽略了无效项。 | Tavily 故障，或上游成功但没有 URL 的 |
| 脱敏配置读取和 Grok 连接测试均成功。 | 配置可返回，但连接/认证/配置测试失败。 | 连脱敏配置对象都无法构造。 |
| 主模型成功写入当前进程和兼容配置。 | 原子写入，暂无部分成功。 | 模型为空或配置持久化失败；仍只修改主模型。 |
规划工具 | 所需阶段已完成并生成可执行计划。 | 会话有效但仍有必需阶段未完成。 | 会话不存在、JSON 参数无效或规划组件失败。 |
规范错误位于 error_detail：
{
"code": "tavily_service_unavailable",
"message": "Tavily 服务暂时不可用",
"service": "tavily",
"retryable": true,
"http_status": 503,
"upstream_code": "upstream_unavailable",
"diagnostics": {
"service_circuit": {"state": "open", "retry_after_seconds": 30}
}
}诊断信息只包含必要的脱敏字段，不包含 Grok/Tavily Key、Authorization 头、可能回显凭据的响应正文、Python traceback 或内部对象表示。结构化错误只结束当前工具调用，stdio MCP 进程仍可发现工具并执行后续调用。
兼容字段映射：
旧字段 | P4 映射 |
| 继续保留字符串形式的旧错误码或旧消息；新调用方应读取 |
|
|
| 保留 P2 Key 状态与服务熔断摘要，并补充重试性、HTTP/上游错误码。 |
| 保留 P3 兼容字段；单模型模式下 |
| 继续保留原工具字段；是否成功统一以 |
典型返回如下。
web_search 完整成功；有效答案没有来源仍是成功：
{"status":"success","session_id":"abc123","content":"有效答案","sources_count":0,"error":null,"error_detail":null,"partial":false}Grok 成功但 Tavily 补充失败：
{"status":"partial_success","session_id":"abc123","content":"有效答案","sources_count":0,"partial":true,"error":null,"error_detail":{"code":"tavily_all_keys_unavailable","message":"所有 Tavily Key 均不可用","service":"tavily","retryable":false,"http_status":401,"upstream_code":"invalid_api_key","diagnostics":{"key_statuses":[{"fingerprint":"tvly…1234","state":"invalid"}]}},"tavily_error":{"code":"tavily_all_keys_unavailable","message":"所有 Tavily Key 均不可用"}}Grok 最终失败时，即使 Tavily 成功也不会伪装为答案：
{"status":"error","session_id":"abc123","content":"","sources_count":0,"error":"grok_primary_failed","error_detail":{"code":"grok_primary_failed","message":"Grok 模型调用失败，已用尽最大尝试次数","service":"grok","retryable":true,"http_status":503,"upstream_code":"upstream_unavailable","diagnostics":{"primary_attempts":5,"fallback_attempts":0,"total_attempts":5,"termination_reason":"max_attempts_exhausted","configured_max_attempts":5,"actual_attempts":5,"elapsed_ms":120000,"budget_ms":270000,"queue_wait_ms":0}},"partial":false}其他工具示例：
{"tool":"get_sources","status":"success","session_id":"abc123","sources":[],"sources_count":0}
{"tool":"web_fetch","status":"success","url":"https://example.com","content":"# Page","provider":"tavily"}
{"tool":"web_map","status":"error","base_url":"https://example.com","results":[],"error_detail":{"code":"tavily_no_urls","message":"Tavily 请求成功，但没有发现可返回的 URL","service":"tavily","retryable":false,"http_status":null,"upstream_code":null,"diagnostics":{"upstream_succeeded":true,"empty_result":true}}}
{"tool":"get_config_info","status":"partial_success","partial":true,"configuration":{"GROK_API_KEY":"未配置"},"connection_test":{"status":"配置错误"},"error_detail":{"code":"grok_configuration_error","message":"GROK_API_KEY 未配置","service":"grok","retryable":false,"http_status":null,"upstream_code":null,"diagnostics":{"configuration":"grok"}}}
{"tool":"switch_model","status":"success","success":true,"previous_model":"grok-4-fast","current_model":"grok-3-mini","message":"主模型已切换"}
{"tool":"plan_intent","status":"partial_success","partial":true,"session_id":"plan123","plan_complete":false,"phases_remaining":["complexity_assessment","query_decomposition"],"error_detail":{"code":"planning_incomplete","message":"搜索计划尚未完成，可继续提交剩余规划阶段","service":"planning","retryable":true,"http_status":null,"upstream_code":null,"diagnostics":{"phases_remaining":["complexity_assessment","query_decomposition"]}}}服务按 GROK_API_PROTOCOL 使用 chat 或 response 单一端点（不自动跨协议切换）。OpenRouter 地址会继续为模型追加兼容的 :online 后缀；失败时只在当前协议端点与当前模型上按规则重试。
每次调用只使用用户配置的当前模型。408、429、5xx、连接失败、连接/读取超时、完整内容产生前或流式传输中的中断，可识别的中转站“上游账号不可用/死号/账号池不可用”，以及 GROK_RETRYABLE_UPSTREAM_CODES 列出的 HTTP 200 内嵌错误，会按带随机抖动的指数退避重试，默认最多执行 5 次真实请求。
重试不会突破 WEB_SEARCH_TOTAL_TIMEOUT，也不会绕过 GROK_MAX_CONCURRENCY。认证、参数、模型不存在和无权限错误会以“因不可重试错误提前停止”结束；只有确实达到配置上限才报告“已用尽最大尝试次数”。总预算或并发排队耗尽使用独立终止原因和结构化诊断。
模型不存在或无权限会立即停止；模型暂时不可用会继续重试当前模型。明确的 400/422 参数错误和 401/403/API Key 认证失败也会立即停止。错误分类同时检查 HTTP 状态、OpenAI 兼容错误对象、错误码、错误类型和正文语义。
流内容会在服务端完整缓冲并校验结束标志。流在产生部分内容后中断时，残缺内容不会作为成功答案返回、缓存或提取来源。最终失败返回 grok_error，包含当前模型、真实尝试次数、最后错误分类、状态码/上游错误码，并保留值为 null/0/false 的旧备用模型兼容字段；不会包含 API Key 或 Authorization 值。
switch_model(model) 保持旧调用形式不变：它更新当前进程使用的模型，并将 primary_model（同时保留兼容的 model 字段）写入本地配置。
可以使用逗号、分号或换行配置多个 Key：
TAVILY_API_KEYS=tvly-key-1,tvly-key-2,tvly-key-3正常请求会在健康 Key 间公平轮询，Search、Extract、Map 共享同一套运行时状态：
healthy：正常参与轮询。
cooldown：临时限流、超时、网络错误或临时服务异常，冷却后重新探测。
quota_exhausted：额度耗尽，使用较长冷却时间。
invalid：Key 无效或被撤销，本进程内不再使用。
Key 的“忙碌”是独立于上述健康状态的瞬时占用信息，不会被误判为冷却、额度耗尽或失效。同一 Key 忙碌时会优先选择其他健康空闲 Key；如果所有健康 Key 都忙碌，则在当前工具预算内等待最早可用槽位。
401/403 会使当前 Key 失效；429 会根据错误码、正文和 Retry-After 区分临时限流与额度耗尽；400/422 直接返回参数错误；404 提示检查 TAVILY_API_URL。多个不同 Key 出现相同 5xx 或网络错误时会触发服务级熔断，冷却后仅允许一次半开探测。
所有 Key 不可用时，web_fetch 和 web_map 返回 status="error"、tavily_all_keys_unavailable 及脱敏状态摘要。web_search 会保留已有 Grok 结果，返回 status="partial_success"，同时设置 partial=true 并保留 tavily_error。该错误只终止当前工具调用，不会退出 MCP 进程。
搜索信源会话只保存在当前 MCP 进程内，最多 256 项并在 1 小时后过期；get_sources 对过期会话返回 session_id_not_found_or_expired。可选规划会话同样最多保留 256 项，并在空闲 1 小时后过期。模型目录的成功结果缓存 5 分钟，之后重新读取 /models；失败不会被缓存为空结果。服务不长期缓存最终答案，也不会默认把完整搜索正文写入磁盘。
确认 uvx 在客户端进程的 PATH 中，并检查仓库地址、命令名 grok-search 和 JSON/TOML 语法。Windows 客户端如果找不到 uvx，可填写其绝对路径。
web_fetch 和 web_map 依赖 Tavily。调用 get_config_info，确认 Tavily 已启用并配置了 TAVILY_API_KEY 或 TAVILY_API_KEYS。
在 uvx 参数开头加入 --native-tls，让 uv 使用系统证书库。完整示例见客户端配置指南。
配置诊断只返回脱敏 Key。不要把真实 Key 写入仓库、Issue、日志截图或客户端共享配置。
-32001: Request timed out把 Cherry Studio 的 MCP 工具超时设置为 300 秒，并确认服务端没有把 WEB_SEARCH_TOTAL_TIMEOUT 配置为 300 秒或更高。默认 270 秒会先返回业务层结构化超时；300 秒只是客户端安全上限。
git clone https://github.com/Timmyzzo/WebSearch-MCP
cd WebSearch-MCP
uv sync --extra dev
uv run ruff check .
uv run pytest
uv run python -m build更多模块说明、测试范围和阶段边界见 开发者指南。
外部项目的代码级对比、许可证边界和采用/拒绝理由见 外部项目实现分析。
Return masked configuration and test Grok API connectivity.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| error_detail | No | |
| configuration | No | |
| connection_test | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose some behavioral traits, such as returning 'masked' configuration and 'testing' API connectivity. However, it does not explicitly state whether the operation is read-only or if the connectivity test has side effects (e.g., network calls), leaving some ambiguity.
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, direct sentence that conveys both functions—returning masked configuration and testing connectivity—without any extraneous words or redundant details.
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 (no parameters) and the presence of an output schema, the description is largely complete. It covers the core purpose, though it could elaborate on what the connectivity test entails or what 'masked' implies, but such details are not essential for a minimal viable 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 tool has zero parameters, and the schema is empty. According to the rubric, the baseline for tools with no parameters is 4, and there is no additional parameter information needed since none exist.
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 function: 'Return masked configuration and test Grok API connectivity.' It uses specific verbs and resources, and by mentioning configuration and Grok API, it distinguishes itself from sibling tools like web_fetch and get_sources, which are unrelated.
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 no guidance on when to use this tool vs alternatives. It does not mention any prerequisites, exclusions, or situations where it would be preferred, leaving the agent to infer its use case solely from the name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve cached sources for a previous web_search session_id.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID returned by web_search. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| sources | Yes | |
| session_id | Yes | |
| error_detail | No | |
| sources_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description needs to disclose behavior. It conveys that the operation is read-only (retrieving cached data) but does not mention edge cases like invalid or expired session IDs, potential staleness of cached sources, or whether it triggers any underlying actions. The word 'cached' adds some context but not enough for a higher score.
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 one concise sentence, front-loaded with the action and resource. No wasted words, and it directly states the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter retrieval tool with an output schema, the description provides sufficient context about input and purpose. It could mention behavior on invalid session or staleness, but those are edge cases, and the overall completeness is adequate.
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 provides 100% coverage with a clear description of session_id. The tool description essentially repeats the schema's 'previous web_search session_id', adding no new meaning. Baseline 3 applies given full schema coverage.
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 a specific verb ('Retrieve') and resource ('cached sources') tied to a previous web_search session_id. This distinguishes it from sibling tools like web_search or web_fetch, which perform live operations.
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 clearly implies usage after a web_search by referencing 'previous web_search session_id'. However, it does not explicitly mention when not to use it or name alternatives, but the context is evident given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally assess search complexity from 1 to 3.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | Complexity level. | |
| thought | No | ||
| confidence | No | ||
| session_id | Yes | Session ID from plan_intent. | |
| is_revision | No | ||
| justification | Yes | ||
| estimated_tool_calls | Yes | ||
| estimated_sub_queries | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that the tool assesses complexity on a 1-3 scale but fails to mention side effects, output format, or whether it modifies state. This is a significant transparency gap for a planning tool with many required parameters.
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, short sentence with no wasted words, which is efficient. However, it is under-specified to the point of being minimally informative, resembling a placeholder rather than a concise yet complete summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, an output schema, and a role in a planning pipeline, this description is incomplete. It neither explains the tool's purpose in the workflow nor what the output represents. The output schema exists but the description fails to connect the tool's behavior to its inputs and outputs.
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 description coverage is only 25%, so the description must compensate for the many undocumented parameters. The description only hints at the 'level' parameter (via the 1-3 scale) and provides no meaning for required fields like estimated_sub_queries, estimated_tool_calls, or justification. This adds almost no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Optionally assess search complexity from 1 to 3' identifies a clear action (assess) and resource (search complexity), but it does not explain what the assessment involves or how it differs from sibling planning tools. The word 'Optionally' adds ambiguity about whether this step is required.
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 given on when to use this tool or when to use alternatives. The description does not mention any context, prerequisites, or comparisons to sibling tools like plan_sub_query or plan_tool_mapping.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally define execution order for a search plan.
| Name | Required | Description | Default |
|---|---|---|---|
| thought | No | ||
| confidence | No | ||
| sequential | Yes | ||
| session_id | Yes | ||
| is_revision | No | ||
| parallel_groups | Yes | ||
| estimated_rounds | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits, but it only states that the tool 'optionally define[s] execution order.' It does not explain side effects, what happens if the tool is not invoked, permission requirements, or how it interacts with other plan tools. This is far below the burden of disclosure for a tool with no 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 a single short sentence, which is concise, but it is under-specified for a tool with 7 parameters. The brevity is not appropriately sized; it sacrifices necessary detail for extreme brevity, making it more under-specification than efficient communication.
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 tool has 7 parameters, 4 required, no annotations, and an output schema, yet the description is just one vague sentence. It fails to explain the context of execution order, how to structure parallel groups or sequential steps, the meaning of estimated_rounds, or what the output represents. This is completely inadequate for the tool's 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?
Schema description coverage is 0%, so the description must explain parameter meanings, but it mentions none. It references 'execution order' which likely relates to 'sequential' and 'parallel_groups' parameters, but without any explanation, it adds no semantic value beyond the raw property 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 states a specific resource ('execution order for a search plan') and an action ('define'), but the verb 'define' is generic and the phrase lacks specificity about what defining execution order entails. It distinguishes from sibling planning tools by focusing on execution order, but does not clearly explain the tool's role relative to them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only says 'Optionally define execution order,' which implies choice but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The optionality is the single weak usage signal, so the score is lower than a clear context would receive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally start or revise a structured search plan.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Optional domain. | |
| thought | No | Optional concise planning note. | |
| confidence | No | Confidence score. | |
| query_type | Yes | Question type. | |
| session_id | No | Existing session to revise, or empty. | |
| ambiguities | No | Comma-separated ambiguities. | |
| is_revision | No | Overwrite the previous intent. | |
| core_question | Yes | Distilled core question. | |
| premise_valid | No | Whether the premise is valid. | |
| time_sensitivity | Yes | How time-sensitive the answer is. | |
| unverified_terms | No | Comma-separated terms to verify. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It only mentions starting or revising a plan, but does not explain what 'revise' entails, side effects, persistence, or any other operational behavior. The description is too vague to be transparent.
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 concise sentence with no redundant content. It is appropriately compact, though it sacrifices some useful context for brevity.
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 11 parameters and a complex search-planning workflow, the description is minimal and does not explain how this tool fits into the overall process, what a 'structured search plan' is, or when it is appropriate to start versus revise. The output schema exists but does not compensate for the missing workflow context.
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 100%, so the schema already thoroughly documents all 11 parameters. The description adds nothing beyond the schema, meeting the baseline expectation.
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+resource: 'start or revise a structured search plan.' It distinguishes from sibling tools like plan_search_term and plan_sub_query, which handle more granular components of the search plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'Optionally' implies the tool is not always needed, but the description provides no explicit guidance on when to use it versus the alternatives (e.g., plan_search_term, plan_execution). There are no stated conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally add one search term to a plan.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| round | Yes | ||
| purpose | Yes | ||
| thought | No | ||
| approach | No | ||
| confidence | No | ||
| session_id | Yes | ||
| is_revision | No | ||
| fallback_plan | No |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full behavioral disclosure burden. It only mentions 'add one search term' without revealing side effects, mutation behavior, idempotency, or interaction with the existing plan state.
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 single sentence is clear, front-loaded, and contains no fluff. It is appropriately concise in form, though it sacrifices information content for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no annotations, and no schema-level descriptions, a one-sentence description is radically incomplete. It omits essential context about how the search term is used, revision behavior, and the overall plan workflow.
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 names only 'search term' without mapping it to any of the 9 parameters. It fails to clarify required fields like session_id, round, or purpose.
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 uses the specific verb 'add' and resource 'one search term to a plan', making the core purpose clear. It does not explicitly differentiate from sibling tools like plan_sub_query or plan_intent, so it stops short of a 5.
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 such as plan_sub_query, plan_tool_mapping, or web_search. There are no prerequisites, exclusions, or contextual cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally add one sub-query to a search plan.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| goal | Yes | ||
| thought | No | ||
| boundary | Yes | ||
| tool_hint | No | ||
| confidence | No | ||
| depends_on | No | ||
| session_id | Yes | ||
| is_revision | No | ||
| expected_output | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention side effects (e.g., modifying the plan), dependencies (e.g., session_id requirements), or any state changes. The single sentence provides no insight into the tool's behavior 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, concise sentence with no fluff or redundant wording. It is front-loaded with the core action. However, it is under-specified, so it doesn't earn a perfect score, but for conciseness alone it is 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 tool's complexity (10 parameters, 5 required) and no annotations, the description is drastically incomplete. It omits critical details like how adding a sub-query affects the plan, required session context, and the role of the 'is_revision' flag. The output schema exists but does not compensate for the absent behavioral and usage context.
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% for 10 parameters, and the description adds no parameter-level meaning. It does not explain the purpose of fields like 'id', 'goal', 'boundary', or 'depends_on', leaving the agent to infer semantics solely from property names. This is a significant failure to compensate for the schema's lack of 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 action ('add one sub-query') and the resource ('to a search plan'), using a specific verb+resource structure. It distinguishes from sibling tools like plan_search_term and plan_tool_mapping by focusing on sub-query addition, though it doesn't elaborate on what a sub-query entails.
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. The word 'Optionally' hints at it being non-mandatory, but there is no mention of prerequisites, context, or exclusions. Sibling tools such as plan_search_term and plan_tool_mapping are not referenced for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Optionally map one sub-query to a web tool.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | ||
| reason | Yes | ||
| thought | No | ||
| confidence | No | ||
| session_id | Yes | ||
| is_revision | No | ||
| params_json | No | ||
| sub_query_id | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| session_id | No | |
| error_detail | No | |
| plan_complete | No | |
| executable_plan | No | |
| completed_phases | No | |
| complexity_level | No | |
| phases_remaining | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Optionally map' implies a non-destructive planning action, but it does not disclose whether the mapping is mutable, reversible, requires session state, or affects other plan elements. The behavioral context is minimal and insufficient for an agent to predict side effects.
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 concise sentence with no redundant words. It efficiently communicates the core action in a front-loaded manner. The word 'Optionally' earns its place by signaling the tool's non-mandatory role. It loses one point because it is too terse to satisfy the needs of a complex 8-parameter tool.
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 (8 parameters, no annotations, rich schema with enums and defaults) and the presence of sibling tools, the description is woefully incomplete. It only states the primary purpose and says nothing about the mapping lifecycle, how 'params_json' is used, or how 'is_revision' affects behavior. The output schema may describe returns, but the description does not contextualize the tool's role in the planning workflow.
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 fails to explain any of the 8 parameters. The schema has an enum for 'tool' and other fields like 'is_revision' and 'params_json', but their meanings are not clarified. The description adds no value beyond the field names, providing no compensation for the lack of 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 'Optionally map one sub-query to a web tool' identifies a specific verb ('map') and resource ('sub-query to a web tool'), making the tool's function clear. It also distinguishes itself from sibling planning tools like 'plan_sub_query' by focusing on the mapping action to a web tool. However, it does not name alternative tools explicitly, so it loses a point for insufficient 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 description gives no guidance on when to use this tool versus alternatives such as 'plan_sub_query' or 'web_search'. The word 'Optionally' hints at some flexibility but does not clarify conditions, prerequisites, or exclusions. There is no explicit when-to-use or when-not-to-use context, leaving the agent uncertain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist the primary Grok model used by subsequent searches.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | Grok model ID to persist. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| message | Yes | |
| partial | No | |
| success | Yes | |
| config_file | No | |
| error_detail | No | |
| current_model | No | |
| previous_model | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose the write behavior. It states the effect — persisting the model for subsequent searches — which communicates that this changes persistent state. However, it doesn't mention reversibility, permissions, or what happens if an invalid model is provided, leaving some gaps.
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 redundancy. It directly states the action and purpose, earning the highest score for conciseness.
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 is a simple setter with one parameter and 100% schema coverage, the one-sentence description is adequate. The existence of an output schema (not shown) also reduces the need to explain return values.
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 already documents the 'model' parameter with a description ('Grok model ID to persist'), so schema coverage is 100%. The description adds minimal extra meaning beyond calling it 'primary', which is not a significant semantic addition.
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 uses the specific verb 'persist' and clearly identifies the resource (primary Grok model) and scope (subsequent searches). It distinguishes itself from sibling search/planning tools by focusing on model persistence.
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 this is for setting the model for future searches, but it doesn't explicitly state when to use this over alternatives or list any exclusions. There is no mention of alternative tools, so the usage guidance is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract a web page as Markdown using Tavily Extract.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Complete HTTP or HTTPS URL to extract. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| error | No | |
| status | No | |
| content | No | |
| partial | No | |
| provider | No | |
| error_detail | No | |
| tavily_error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a useful behavioral detail by stating the output format (Markdown) and mentions the underlying service (Tavily Extract). However, with no annotations, it does not disclose potential limitations, rate limits, or authentication requirements, so it only partially carries the transparency burden.
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, direct sentence that immediately conveys the tool's function with no redundancy or extraneous details. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with complete schema coverage and an output schema, the description covers the essential purpose and output format. It lacks usage guidelines, which slightly reduces completeness but does not make it inadequate.
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 already fully documents the single url parameter with a description and pattern regex. The tool description adds no additional parameter-level semantics, so the baseline of 3 applies due to high schema coverage.
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 extracts a web page as Markdown, using a specific verb ('Extract') and resource ('web page'). This is specific and distinguishes it from sibling tools like web_search and web_map.
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 no explicit guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or recommended contexts, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover a website's URL structure using Tavily Map.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Root HTTP or HTTPS URL to map. | |
| limit | No | Maximum total URLs returned. | |
| timeout | No | Operation timeout in seconds. | |
| max_depth | No | Maximum traversal depth. | |
| max_breadth | No | Maximum links followed per page. | |
| instructions | No | Optional natural-language filter instructions. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| partial | No | |
| results | No | |
| base_url | No | |
| error_detail | No | |
| tavily_error | No | |
| response_time | No | |
| ignored_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral details are provided beyond the basic purpose. There are no annotations to supplement, so the description alone should disclose any side effects, rate limits, or limitations; it does not.
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?
One sentence, direct, no filler. It is front-loaded and concise.
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?
While the schema covers parameter details and an output schema exists, the description lacks guidance on when to use this tool, the meaning of the mapping concept, and how it compares to sibling web tools. This makes it incomplete for a tool with moderate 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 already covers all six parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional parameter information.
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 maps a website's URL structure using Tavily Map, which is a specific action and resource. It does not explicitly differentiate from sibling tools like web_search or web_fetch, but the concept of 'mapping URL structure' is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus alternatives like web_search or web_fetch. No context on typical use cases or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Research the web with Grok and optionally use structured Tavily evidence. Returns unified status/error_detail fields plus a session_id and answer content.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Optional Grok model ID for this request only. | |
| query | Yes | Clear, self-contained search query. | |
| platform | No | Optional platform focus such as GitHub, Reddit, or Twitter. | |
| extra_sources | No | Additional Tavily results to feed into evidence synthesis and cache. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | No | |
| content | Yes | |
| partial | No | |
| grok_error | No | |
| session_id | Yes | |
| error_detail | No | |
| tavily_error | No | |
| sources_count | 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 of disclosing behavior. It does mention the return fields (unified status/error_detail, session_id, answer content) and optional Tavily evidence, which gives some behavioral context. However, it does not disclose important traits like whether this is a read-only operation, rate limits, authentication needs, or how the Grok model interacts with the search. This is minimal disclosure for a tool with no annotation support.
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 exactly two sentences, front-loading the primary purpose and then briefly noting the return format. Every sentence earns its place, and there is no fluff or repetition of schema information. This is an ideal length for a tool description.
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 tool has an output schema, so the description need not explain return values in detail—it even goes a bit beyond by mentioning them. However, the description is incomplete in terms of usage context: it lacks when-to-use guidance, what distinguishes it from sibling tools, and how the optional Tavily evidence and extra_sources parameter affect behavior. Given the tool's moderate complexity, the description is adequate but leaves clear 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?
The input schema already provides descriptions for all 4 parameters, with 100% coverage. The description adds no additional meaning to the parameters themselves, so the baseline score of 3 is appropriate. The schema handles parameter semantics entirely.
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 function: 'Research the web with Grok and optionally use structured Tavily evidence.' This specifies a distinct verb (research) and resource (web with Grok), which is more specific than a generic 'search'. However, it does not explicitly differentiate from sibling tools like web_fetch or get_sources, so it misses the top score.
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 no guidance on when to use this tool versus alternatives. There is no mention of use cases, exclusions, or comparison with sibling tools such as web_fetch or get_sources. The only implied guidance is that it is for 'research,' but that is too vague to be actionable.
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.1get_config_infoget_sourcesplan_complexityplan_executionplan_intentplan_search_termplan_sub_queryplan_tool_mappingswitch_modelweb_fetchweb_mapweb_searchScored across 12 tools
The plan_* tools all contribute to building a structured search plan, but each has a distinct role (e.g., adding a term vs. adding a sub-query vs. mapping to a tool). The only potential confusion is between plan_search_term and plan_sub_query, but the descriptions generally clarify the difference.
All tool names use lowercase snake_case with consistent verb_noun or prefix patterns (plan_*, web_*, get_*, switch_*). No mixed conventions or vague verbs.
12 tools is well within the typical 3-15 range and each tool serves a clear purpose within the web search and planning workflow. The count feels neither bloated nor sparse.
The tool set covers the core lifecycle of planning, executing, and retrieving web search results. Minor gaps exist, such as the lack of a 'view plan' or 'reset plan' tool, but agents can work around these limitations.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Scrape, crawl and search the web for AI agents via MCP.
Search the agentic web. 4,100+ sites, 11 tools incl. check_url + verify_mcp for probe-before-use.
