SearchPipe

searchpipe_search

Run an AI-powered web search for a query: multi-engine retrieval → page fetching → LLM reranking → optional AI answer.

Uses the same commercial pipeline and accepts the same parameters as the HTTP POST /search endpoint: authentication → rate limiting → input moderation → credit charge → search → output moderation + AI-generated marker → refund on failure → usage logging. Credits are charged per call.

search_depth: "basic" (default, 1 credit) / "advanced" (2 credits) / "fast" (0.5 credit — skips all LLM steps: results keep engine order with engine-provided relevance scores, no answer is generated). include_domains / exclude_domains: restrict or exclude domains ("example.com" matches the domain and any subdomain; "*.example.com" matches subdomains only; "example.com/docs" also requires the URL path to start with /docs; exclude wins over include). time_range: recency window "day" / "week" / "month" / "year"; start_date / end_date: ISO YYYY-MM-DD bounds (results without a known publish date are not filtered). topic: "general" (default) or "news" (always adds a dedicated news channel to retrieval). country: ISO 3166-1 alpha-2 region bias (e.g. "US"); language: upstream market language (e.g. "en", "zh-CN"); combined into the upstream market locale. safe_search: 0 off (default) / 1 moderate / 2 strict. include_images: also run an image search and return an images array alongside results. output_type: "search_results" (default) / "answer" (same as include_answer=true) / "structured" (grounded JSON object per output_schema — requires output_schema; on failure output is null). objective: optional one-line search intent from the calling agent; improves reranking only. stream is REST-only and not available over MCP. api_key: an API key starting with sp-. It may also be provided through the SEARCHPIPE_API_KEY environment variable (the parameter takes precedence). Returns Tavily-style structured results (query / answer / results[] / images[] / output). Returns a tool error on authentication failure, insufficient credits, content violation, invalid parameters (422), or retrieval failure.

Input Schema

Name	Required	Default
`query`	Yes
`topic`	No	general
`api_key`	No
`country`	No
`end_date`	No
`language`	No
`objective`	No
`start_date`	No
`time_range`	No
`max_results`	No
`output_type`	No
`safe_search`	No
`search_depth`	No	basic
`output_schema`	No
`include_answer`	No
`include_images`	No
`exclude_domains`	No
`include_domains`	No
`include_raw_content`	No

Output Schema

Name	Required	Description
`query`	Yes
`usage`	No	Billing and cache info for this request
`answer`	No	LLM-generated answer (optional)
`images`	No	Image results (present when the request set include_images=true)
`output`	No	Structured JSON object conforming to output_schema (output_type='structured' only; null when conversion failed)
`notices`	No	How this response was produced (safe to show to the model)
`results`	Yes
`warnings`	No	Parameter-level issues: a requested feature did not take effect (safe to show the developer; do not feed to the model)
`request_id`	No	Unique request identifier, also returned as the X-Request-Id response header
`ai_generated`	No	Whether the response contains LLM-generated content
`answer_audit`	No	Per-statement audit of the AI answer (advanced depth only)
`response_time`	No	Server processing time for this request, in seconds

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

changedOutput schema / properties / results / items / properties / score / description

Previous value: -"Relevance score 0-1: from the LLM reranker on basic/advanced; the upstream engine score on fast depth (0 when the source provides none)"New value: +"Relevance score: 0-1 from the LLM reranker on basic/advanced; raw, unnormalized upstream engine score on fast depth (0 when the source provides none; not comparable across engines)"

changedOutput schema / properties / usage / anyOf

Previous value: -[
-  {
-    "description": "本次请求的计费与缓存信息（P0 响应信封，history/20261020-api-v1-endpoints.md）。",
-    "properties": {
-      "cached": {
-        "default": false,
-        "description": "True when the response was served from the result cache",
-        "title": "Cached",
-        "type": "boolean"
-      },
-      "credits_charged": {
-        "default": 0,
-        "description": "Credits billed for this request (0 when served from cache, exempt, or refunded)",
-        "title": "Credits Charged",
-        "type": "number"
-      }
-    },
-    "title": "UsageInfo",
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "本次请求的计费与缓存信息（P0 响应信封，history/20261020-api-v1-endpoints.md）。",
+    "properties": {
+      "cached": {
+        "default": false,
+        "description": "True when the response was served from the result cache",
+        "title": "Cached",
+        "type": "boolean"
+      },
+      "credits_charged": {
+        "default": 0,
+        "description": "Credits billed for this request. Cache hits are charged; 0 when exempt or refunded.",
+        "title": "Credits Charged",
+        "type": "number"
+      }
+    },
+    "title": "UsageInfo",
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed19 schema fields changedOct 20, 2026

addedInput schema / properties / country

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / end_date

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / exclude_domains

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / include_domains

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / include_images

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / language

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / objective

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / output_schema

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / output_type

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / safe_search

Added value: +{
+  "default": 0,
+  "type": "integer"
+}

addedInput schema / properties / search_depth

Added value: +{
+  "default": "basic",
+  "type": "string"
+}

addedInput schema / properties / start_date

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / time_range

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / topic

Added value: +{
+  "default": "general",
+  "type": "string"
+}

addedOutput schema / properties / images

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "description": "图片检索结果（P1 控制面 T1）：include_images=true 时随响应返回。",
+        "properties": {
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Short caption/context from the source page, when available",
+            "title": "Description"
+          },
+          "url": {
+            "description": "Image URL",
+            "title": "Url",
+            "type": "string"
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "title": "ImageResult",
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Image results (present when the request set include_images=true)",
+  "title": "Images"
+}

addedOutput schema / properties / notices

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "How this response was produced (safe to show to the model)",
+  "title": "Notices"
+}

addedOutput schema / properties / output

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Structured JSON object conforming to output_schema (output_type='structured' only; null when conversion failed)",
+  "title": "Output"
+}

changedOutput schema / properties / results / items / properties / score / description

Previous value: -"LLM relevance score, 0-1"New value: +"Relevance score 0-1: from the LLM reranker on basic/advanced; the upstream engine score on fast depth (0 when the source provides none)"

addedOutput schema / properties / warnings

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Parameter-level issues: a requested feature did not take effect (safe to show the developer; do not feed to the model)",
+  "title": "Warnings"
+}

Changed5 schema fields changedOct 20, 2026

addedOutput schema / properties / request_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Unique request identifier, also returned as the X-Request-Id response header",
+  "title": "Request Id"
+}

addedOutput schema / properties / response_time

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Server processing time for this request, in seconds",
+  "title": "Response Time"
+}

addedOutput schema / properties / results / items / properties / id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Stable result identifier (first 16 hex chars of the SHA-256 of the URL)",
+  "title": "Id"
+}

addedOutput schema / properties / results / items / properties / published_date

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Publish date when the source provides one (ISO 8601 string), else null",
+  "title": "Published Date"
+}

addedOutput schema / properties / usage

Added value: +{
+  "anyOf": [
+    {
+      "description": "本次请求的计费与缓存信息（P0 响应信封，history/20261020-api-v1-endpoints.md）。",
+      "properties": {
+        "cached": {
+          "default": false,
+          "description": "True when the response was served from the result cache",
+          "title": "Cached",
+          "type": "boolean"
+        },
+        "credits_charged": {
+          "default": 0,
+          "description": "Credits billed for this request (0 when served from cache, exempt, or refunded)",
+          "title": "Credits Charged",
+          "type": "number"
+        }
+      },
+      "title": "UsageInfo",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Billing and cache info for this request"
+}

Changed3 schema fields changedOct 18, 2026

addedOutput schema / properties / results / items / properties / relevance_score

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Relevance Score"
+}

addedOutput schema / properties / results / items / properties / relevance_stage

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Relevance Stage"
+}

addedOutput schema / properties / results / items / properties / relevance_status

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "scored",
+        "missing",
+        "failed"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Relevance Status"
+}

Changed2 schema fields changedOct 16, 2026

addedOutput schema / properties / answer_audit

Added value: +{
+  "anyOf": [
+    {
+      "description": "tier-2 已审计答案：answer 逐陈述审计报告（E 方向 E-2，2026-10-15）。\n\nadditive 契约：仅 search_depth=\"advanced\" 且 include_answer=true 且\nanswer_audit_enabled 开时产出。score = 系统判 supported 的陈述占比\n（分母=有引文被判定的陈述数；全部 uncited 时为 0.0）。",
+      "properties": {
+        "prompt_version": {
+          "description": "Audit judge prompt version",
+          "title": "Prompt Version",
+          "type": "string"
+        },
+        "score": {
+          "description": "Fraction of judged statements that are supported, 0-1",
+          "title": "Score",
+          "type": "number"
+        },
+        "statements": {
+          "items": {
+            "description": "单条陈述的审计结果（E 方向 tier-2，四标签契约与 /verify 同名同义）。",
+            "properties": {
+              "citations": {
+                "items": {
+                  "description": "陈述级引用：该陈述所引结果及其支撑 span（E 方向 tier-2）。",
+                  "properties": {
+                    "quote": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "default": null,
+                      "description": "Supporting span quoted from the cited page (None = no page text)",
+                      "title": "Quote"
+                    },
+                    "span_end": {
+                      "anyOf": [
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "default": null,
+                      "title": "Span End"
+                    },
+                    "span_start": {
+                      "anyOf": [
+                        {
+                          "type": "integer"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "default": null,
+                      "title": "Span Start"
+                    },
+                    "title": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "default": null,
+                      "title": "Title"
+                    },
+                    "url": {
+                      "title": "Url",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "url"
+                  ],
+                  "title": "StatementCitation",
+                  "type": "object"
+                },
+                "title": "Citations",
+                "type": "array"
+              },
+              "confidence": {
+                "default": 0,
+                "description": "Judge confidence 0-1 (0 for uncited)",
+                "title": "Confidence",
+                "type": "number"
+              },
+              "text": {
+                "description": "Answer statement (citation markers stripped)",
+                "title": "Text",
+                "type": "string"
+              },
+              "verdict": {
+                "description": "supported/partial/unsupported/inconclusive (judged) or uncited (no [n] marker, not judged)",
+                "title": "Verdict",
+                "type": "string"
+              }
+            },
+            "required": [
+              "text",
+              "verdict"
+            ],
+            "title": "StatementAudit",
+            "type": "object"
+          },
+          "title": "Statements",
+          "type": "array"
+        },
+        "uncited_count": {
+          "description": "Statements without any [n] citation marker",
+          "title": "Uncited Count",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "score",
+        "uncited_count",
+        "statements",
+        "prompt_version"
+      ],
+      "title": "AnswerAudit",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Per-statement audit of the AI answer (advanced depth only)"
+}

addedOutput schema / properties / results / items / properties / evidence

Added value: +{
+  "anyOf": [
+    {
+      "description": "tier-1 证据级结果（E 方向 E-1）：每条 result 自带的逐字证据。\n\nquote/span 来自 locator.best_supporting_span（query 当 claim，对抓取正文\n确定性选句，span 为 raw_content 中的字符偏移）；抓取失败退回 content\nsnippet 兜底（此时 span 相对 content 字段，0 起算）。纯本地计算，零出站。",
+      "properties": {
+        "fetch_status": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "HTTP status of the page fetch (None = not fetched/timeout)",
+          "title": "Fetch Status"
+        },
+        "fetched_at": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Fetch completion time, ISO-8601 UTC",
+          "title": "Fetched At"
+        },
+        "final_url": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Final URL after redirects",
+          "title": "Final Url"
+        },
+        "quote": {
+          "description": "Verbatim supporting sentence from the page",
+          "title": "Quote",
+          "type": "string"
+        },
+        "redirected": {
+          "default": false,
+          "description": "Whether the fetch followed redirects",
+          "title": "Redirected",
+          "type": "boolean"
+        },
+        "source_tier": {
+          "default": "unknown",
+          "description": "Source authority tier: official/press/academic/preprint/community/unknown",
+          "title": "Source Tier",
+          "type": "string"
+        },
+        "span_end": {
+          "description": "Quote end offset (exclusive)",
+          "title": "Span End",
+          "type": "integer"
+        },
+        "span_start": {
+          "description": "Quote start offset (into raw_content, or content when snippet-fallback)",
+          "title": "Span Start",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "quote",
+        "span_start",
+        "span_end"
+      ],
+      "title": "ResultEvidence",
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Verbatim evidence: supporting quote, span, source tier, fetch metadata"
+}

Changed4 schema fields changedOct 14, 2026

addedOutput schema / properties / results / items / properties / cited_by_count

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "被引数（直连学术路填充）",
+  "title": "Cited By Count"
+}

addedOutput schema / properties / results / items / properties / doi

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "规范化 DOI（直连学术路填充）",
+  "title": "Doi"
+}

addedOutput schema / properties / results / items / properties / source_route

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "召回路由标记: general/science/general_rw/direct:<api>/fanout_web",
+  "title": "Source Route"
+}

addedOutput schema / properties / results / items / properties / year

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "发表年份（直连学术路填充）",
+  "title": "Year"
+}

Changed11 schema fields changedSep 15, 2026
- addedOutput schema / properties / ai_generated / title
```
Added value: +"Ai Generated"
```
- addedOutput schema / properties / answer / title
```
Added value: +"Answer"
```
- addedOutput schema / properties / query / title
```
Added value: +"Query"
```
- addedOutput schema / properties / results / items / properties / content / title
```
Added value: +"Content"
```
- addedOutput schema / properties / results / items / properties / raw_content / title
```
Added value: +"Raw Content"
```
- addedOutput schema / properties / results / items / properties / score / title
```
Added value: +"Score"
```
- addedOutput schema / properties / results / items / properties / title / title
```
Added value: +"Title"
```
- addedOutput schema / properties / results / items / properties / url / title
```
Added value: +"Url"
```
- addedOutput schema / properties / results / items / title
```
Added value: +"SearchResult"
```
- addedOutput schema / properties / results / title
```
Added value: +"Results"
```
- addedOutput schema / title
```
Added value: +"SearchResponse"
```
AddedSep 14, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations the description carries the full burden and largely succeeds: it discloses the authentication → rate limiting → moderation → credit charge → search → refund-on-failure pipeline, per-call credit costs including the 0.5-credit fast mode, and the specific error conditions that produce a tool error. It stops short of declaring idempotency/read-only semantics or result-size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The summary sentence is front-loaded and the rest is dense, scannable parameter documentation with no filler. It is long, justified by 19 parameters and zero schema descriptions, though a few pipeline details (usage logging, output moderation) could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter tool lacking annotations or schema descriptions, the description is nearly self-sufficient: it covers the pipeline, cost model, error modes, and return shape (query/answer/results/images/output). Only the handful of unmentioned parameters keep it from being fully complete.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains search_depth credit tiers, include/exclude domain glob semantics with precedence, exact date formats, topic/country/language meaning, safe_search levels, output_type modes, objective's reranking effect, and the api_key/SEARCHPIPE_API_KEY precedence. A few parameters (max_results, include_raw_content) are left undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Run an AI-powered web search for a query") and even spells out the internal pipeline (retrieval → fetching → reranking → optional answer). The purpose is unambiguous, but it never mentions the sibling tool searchpipe_verify, so it does not actively differentiate itself from alternatives.

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

Usage Guidelines3/5

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

Offers rich intra-tool guidance (when to pick search_depth basic vs advanced vs fast, when output_type "answer"/"structured" applies, credit tradeoffs), which implies usage. However it never states when to use this tool rather than searchpipe_verify, or any conditions under which it should not be used.

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

All SearchPipe tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.