| name | zai-web-search |
| description | Search the live web via z.ai web_search_prime (GLM Coding Plan MCP server). Use when the user wants current information, recent trends, news, blog posts, docs, or any web resource that academic-database search (reference-search) does not cover. Triggers on web search, ์น ๊ฒ์, search the web, ์ต๊ทผ ๋ํฅ, ์ต์ ํธ๋ ๋, latest trends, find online, ์ธํฐ๋ท์์ ์ฐพ์, what's new, current state of X, search z.ai, GLM web search. |
zai-web-search
Live web search through z.ai's web_search_prime MCP server, included with the GLM Coding Plan subscription (no separate API recharge needed โ see references/protocol_notes.md for why this matters and why the script uses MCP and not the REST API).
The single Python script handles the MCP streamable-HTTP handshake, SSE parsing, and the multiply-escaped JSON response so you can just call it.
Division of labor with reference-search
These two skills are complementary, not competing:
| Skill | Sources | Best for | Output shape |
|---|
reference-search | InspireHEP / OpenAlex / Semantic Scholar APIs | Academic papers, metadata, BibTeX, abstracts, citation context, baselines | Markdown-ready citations with quoted match sentences |
zai-web-search (this) | Live web via z.ai search-prime | Recent trends, news, blogs, docs, non-academic resources, "what is the field doing right now" | title / link / snippet per result |
Default routing:
- "Find papers on X", "baseline citation for Y", "section needs references" โ
reference-search
- "Latest trends in X", "what is the community doing about Y", "search the web for Z", anything outside academic DBs โ
zai-web-search
- A claim that needs both a primary source (academic) and current context (web) โ run both and merge.
Trigger conditions
Invoke this skill when the user says any of:
- "search the web for X", "์น ๊ฒ์", "์ธํฐ๋ท์์ ์ฐพ์๋ด"
- "latest / recent trends in X", "์ต๊ทผ ๋ํฅ", "์ต์ ํธ๋ ๋", "what's new in X"
- "current state of X", "how is the field approaching Y"
- a web-lookup need that is clearly not an academic-DB query (news, blogs, docs, repos, product pages)
- explicit "z.ai search" / "GLM web search" / "use the web"
Prerequisites
The key is the single source of truth โ pi's own credential store, not a duplicate:
test -f ~/.pi/agent/auth.json
python3 -c "import json;print(json.load(open('/home/axect/.pi/agent/auth.json'))['zai-coding-cn']['key'])" >/dev/null
If either fails, tell the user:
The z.ai key is not configured in ~/.pi/agent/auth.json under zai-coding-cn.key. This key ships with the GLM Coding Plan login โ it is the same key pi already uses for the default model. Re-login via pi if it is missing.
Do not create a second credential file. Do not ask the user to paste the key into a skill config. auth.json is the SoT.
Script usage
python3 scripts/web_search.py "<query>" [--limit 8] [--domain example.com] [--json] [--auth PATH]
Arguments:
query (positional or --query / -q): the search query. MCP recommends โค70 chars; the script hard-rejects >200.--limit / -n (default 8): max results.--domain : restrict to a domain (e.g. arxiv.org, nature.com). Optional. Results are also checked locally because the upstream filter may return off-domain items.--json : machine-readable output for piping into another script. Default is human-readable [i] title / link / snippet.--auth (default ~/.pi/agent/auth.json): override the credential path (rarely needed).
Resolve the script path relative to this SKILL.md (skill dir + scripts/web_search.py).
Examples
# human-readable, top 6 results
python3 scripts/web_search.py "autoregressive sampler Ising correlation failure" -n 6
# restrict to arXiv, JSON for downstream processing
python3 scripts/web_search.py "flow sampler critical slowing down" --domain arxiv.org --json
# pipe into a quick relevance filter
python3 scripts/web_search.py "..." --json | python3 -c "import sys,json; ..."
How to use the results
- The script prints title / link / snippet. Snippets are short summaries from the search engine, not the page content โ do not treat them as quotes from the source.
- For anything you plan to cite, open the link and verify the claim against the real page before quoting. Web-search snippets are for discovery and triage, not citation.
- When a result looks like an arXiv/paper link and you need BibTeX or abstract text, hand off to
reference-search or bibtex-gen with the arXiv ID / DOI.
Error handling
| Exit code | Meaning | Action |
|---|
| 0 | success | use the printed results |
| 1 | bad argument (query empty / too long) | fix the call |
| 2 | auth.json missing or no zai-coding-cn.key | user must (re-)configure pi login |
| 3 | auth rejected (HTTP 401 / MCP -401) | key invalid or expired โ re-login via pi |
| 4 | search-side error (429, 5xx, MCP error) | surface the message; retry once after a short wait for transient 429 |
| 5 | network or parse failure | transient HTTP/TLS failures are retried twice; then show stderr and check connectivity |
| 64 | usage error | show --help |
Do not auto-retry on auth errors (exit 2/3). For 429, a single retry after 20โ60s is reasonable; persistent 429 means either rate-limit or (for the REST endpoint) insufficient balance โ but the MCP endpoint used here is covered by the Coding Plan, so persistent 429 on MCP is a rate-limit, not a billing issue.
Limits and honest use
- Snippets are short and may truncate; do not over-claim what a page says from the snippet alone.
- The upstream domain filter is not always strict;
--domain therefore applies a client-side hostname check (the requested domain and its subdomains are accepted).
- Web search can return stale or SEO-heavy results โ cross-check claims that matter.
- This is a discovery tool. Pair with
reference-search for citation-grade literature and with direct page reads (curl / a reader tool) when you need to quote.
References
references/protocol_notes.md โ why MCP-not-REST, the streamable-HTTP handshake, SSE + multiply-escaped JSON parsing, and the gotchas that made this skill necessary.
