# Zai Web Search

> 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.

- Skill: `axect/zai-web-search` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add axect/zai-web-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/axect/zai-web-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Axect (https://skillmd.com/u/axect)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/axect/zai-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.