Allows reading and normalizing arXiv papers into clean text, enabling academic research workflows.
Integrates with Xiaohongshu as a login-walled source, enabling search through the user's own authenticated browser.
The answer is sitting in minute 47 of a podcast, three replies deep in a comment thread, behind a login, in another language. Your agent gets it anyway.
Self-hosted perception MCP server · one connection
Quick start · Tools · Configure · Contributing
Search gives your agent indexed pages, in one language, in text, and stops there.
OmniSeek gives it the senses to keep going: through languages, logins, comment threads, audio, and pixels, all on your machine.
What each layer gave back, verbatim:
Written down, and in reach. Headlines, official FAQ, top blogs, all one voice: "From 2026, F-1 admission is limited to a 4-year initial period; renewal in a third country remains possible." All quote the same rule. None of them have done it.
Written down, but out of reach. Three first-person threads on 1point3acres, behind your own login: Bangkok, booked to passport in 25 days, interview to approval in 30 minutes; Milan, a month-long fight for a slot, visa issued for 5 years; Tokyo, "silky-smooth". Under the Milan post the author comes back in the comments: "Book any late slot first, then email the consulate to expedite. For one F-1 applicant it worked." One person's experience, not official guidance.
Never written down. A Chinese explainer video on bilibili, transcribed locally: the "4-year cap" in the headlines is the initial period, extensions moved desks rather than vanishing. A rednote video note whose caption is four hashtags, frames and speech read locally: a 212(a)(6)(C) refusal abroad, a misrepresentation finding, can nearly close the F-1 road.
Plain search quoted the rule and stopped. The people who had lived it held the timelines, the workaround, and the risk. OmniSeek also named the sources it held back, each with the exact call to drill it.
It hears (local bilingual ASR, no cloud), sees (images and video frames, in-band), crosses languages (a Chinese query finds English results and vice versa), reads behind login walls (your credentials, your machine, off by default), and remembers (persistent retrieval memory plus a typed, source-traced evidence graph).
Crossing languages draws on the index OmniSeek builds as you use it, so a fresh install starts at a floor. The published claim-verification tests run on exactly that fresh install, which makes their cross-lingual number the coldest case rather than the typical one.
Every source in the catalog, the curated roster of everything OmniSeek can reach, earned its place by beating plain search at one of five jobs (structure, unwalling, transcription, recall, monitoring): citation graphs, regulatory filings, login-walled forums, Chinese-language video. And the catalog is built to grow: a curator pipeline probes, judges, and admits new sources, and retires the ones that decay.
Worked examples, real outputs · A full case study · Every claim above is a test (latest results) · Source health, updated weekly
git clone https://github.com/Battam1111/omniseek.git && cd omniseek
docker compose up -d
docker compose logs omniseek # bearer token printed on first start
curl -s http://127.0.0.1:8765/healthzOn success, it returns:
{"ok":true}Point your MCP client at http://127.0.0.1:8765/mcp with Authorization: Bearer <token>. The token is generated on first start and stored in ~/.omniseek/credentials/omniseek_http.json (with the compose file, that's ./.omniseek/credentials/omniseek_http.json on the host).
Two paths from here. The prebuilt core image (docker pull ghcr.io/battam1111/omniseek, amd64 + arm64) needs no build and carries every core sense; it is Apache-clean and ships without PDF reading, hearing (ASR + video frames), and login-walled sources. Wanting those extras is what triggers a local build: set EXTRAS="[pdf,asr,walled]" and run docker compose build, then up -d (the first build also fetches headless Chromium; later starts are instant). Optional but recommended: set OMNISEEK_CONTACT_EMAIL for a faster lane with Crossref, SEC, and Unpaywall.
python -m venv .venv && . .venv/bin/activate
scripts/bootstrap.sh
python -m omniseek.serve_httpThe bare install is the Core tier: every keyless API and static source, document reading minus PDF, and the lexical memory index. pip install "omniseek[pdf,asr,recall,ocr]" wakes the Research tier (PDF, hearing, cross-lingual vectors, OCR); omniseek[walled] adds the login-walled tier, which stays off until you bring your own accounts; omniseek[all] takes everything. The server prints which senses are online, and which are dormant, at every boot.
On Windows, run bootstrap.sh under Git Bash or WSL; Docker is the simplest path. For an always-on Linux service, see deploy/omniseek.service.
Prefer stdio? The install also ships an omniseek command that speaks MCP over stdio, for clients that launch servers themselves; Dockerfile.stdio wraps the same thing in a container.
OmniSeek binds 127.0.0.1 and requires the bearer token on every request. Do not expose without a reverse proxy (SECURITY.md).
Related MCP server: Augent
One MCP connection; no model, no agent loop inside. Your model thinks, your harness drives the loop, OmniSeek reaches. Start with omniseek_search; explore what's available with omniseek_sources.
Tool | What it does |
| Fan out across the whole catalog, deduplicate, rank. Cross-lingual (semantic + lexical). |
| Normalize any URL or document (web page, PDF, arXiv) into clean text. |
| Read images, document figures, video frames with vision. |
| Transcribe audio/video locally. Bilingual ASR, sliceable by timestamp. |
| Map a research field's citation neighborhood: foundational core vs. frontier. |
| Resolve a person's name to candidate author IDs across databases. |
| Map a researcher's collaboration network by joint-paper count. |
| List who actively publishes at a lab, scoped to a field. |
| Open-access PDF, retraction/integrity status, citation count for a paper. |
| Semantically similar papers (SPECTER embeddings) that keyword search misses. |
| Query the accumulated evidence graph: find, neighborhood, between, since, similar. |
| Standing queries with novelty detection. Only tells you what is new. |
| Record identity judgments (same/not-same) the graph applies at read time. |
| Record directed relations the graph carries forward. |
| Source lifecycle: submit, probe, judge, admit, retire. |
| Read the source-admission queue or a per-source audit dossier. |
| Run multiple tools in parallel, one response. |
| List and route: domains, regions, capabilities, health. |
The login-walled tier has no tool of its own: once you opt in per source, the same omniseek_search(..., sources=["xiaohongshu"], raw=True) runs through your own logged-in browser. See walled sources.
Full reference in tools.md · FAQ
Using Claude Code? skills/omniseek-investigate ships the investigation methodology (sweep, zoom, structure) as a ready-made skill.
OmniSeek is catalog-first: with no config, every benign source is on and login-walled sources are off. Tune in one file, ~/.omniseek/profile.json (example):
Tier | Default |
free (public, no key) | on |
keyed (a free or paid API key you supply) | on once the key is set |
walled (a login you hold) | off; you bring your own browser |
circumvention | off; none in the default pack |
Full reference: configuration · walled sources · legal posture
There is no OmniSeek cloud. No telemetry, no accounts, no relay: a query leaves your machine only as direct requests to the sources you enabled, and OmniSeek adds no other party to that path. Walled-source credentials stay in your own browser, presented only to the site they belong to; OmniSeek never stores, uploads, or even sees your passwords. The retrieval memory and evidence graph it accumulates over months are local files you own: stop running OmniSeek and you keep everything. Not a feature toggle. The architecture.
See CONTRIBUTING.md. The bar for a new source: it must beat plain web search via a mode (structure / unwall / transcribe / recall / monitor). The bar for fixing a decayed source: low, please do. python tests/smoke.py before you push.
By participating you agree to the Code of Conduct.
Your agent seeks what search can't find.
Apache-2.0 · NOTICE · Security · Cite
Use WHEN you want WHO a researcher collaborates with — advisor + closest collaborators by joint-paper count, or how a paper's author group is connected (WebSearch cannot build this). One LAYER, not the whole graph — co-authorship is one edge type; YOU overlay the others (advising, institution cohort, citation, code, social) and judge what each connection MEANS.
Pass author NAMES and/or ids (from omniseek_resolve_identity). A brand-new arXiv paper is not in the graph yet, so this reconstructs from each author's PRIOR work: • N=1 -> that author's frequency-ranked coauthor neighborhood. The advisor + closest collaborators surface by joint-paper count (e.g. Yi R. Fung -> Heng Ji ~51x = her PhD advisor, no advisor field needed — YOU read that signal). • N>1 (e.g. a paper's whole author list) -> additionally the PAIRWISE prior joint-work edges among them (with the actual joint paper titles as evidence) + BRIDGE collaborators (people who co-authored with >=2 of the inputs but are not in the set). This is the "how is this author group actually connected" reconstruction.
Each input may be a NAME, an id, or '+'-joined ids ("id1+id2") for ONE person SPLIT
across ids — their works are MERGED (OpenAlex/S2 routinely split a junior's recent papers;
merging recovers the complete network). Each becomes a node with resolved,
ambiguous + alternatives (juniors often need source="s2", a paper anchor, or an
explicit id — the node note says so when unresolved). The output also carries cooc:
which of the network's top external coauthors co-appear on the same papers, i.e. the
SUB-COMMUNITY structure (an ego's distinct 'research worlds'). Mechanical throughout:
"these two share these N papers" is a fact; advisor-vs-peer, what a cluster MEANS, is YOUR
judgment. For the citation/influence layer use omniseek_field_skeleton; for the others, assemble
from the dossier recipe (github, bluesky, exa, cdp_fulltext, omniseek_read).
hints / papers are parallel lists for per-author disambiguation (an institution
hint, or a known paper that pins a common-name junior).
Returns: {source, n_authors, nodes:[{query, resolved, ambiguous, alternatives, works_seen,
top_coauthors:[{id,name,joint}], degraded?}], edges:[{a,b,joint_count,papers:[{title,year,id}]}],
bridges:[{id,name,shared_by,total_joint}], cooc:[{a,b,n}], degraded?}. (top_coauthors/bridges
carry a representative id you can harvest and pass back to omniseek_coauthors to drill that
person.) A top-level/node degraded means that author's OpenAlex lookup FAILED (rate-limited
/ upstream down): an empty graph is then missing-data to RETRY, not "no collaborators".
| Name | Required | Description | Default |
|---|---|---|---|
| hints | No | ||
| papers | No | ||
| source | No | openalex | |
| authors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and meets it: it discloses that co-authorship is reconstructed from PRIOR work, split IDs are merged, results are mechanical and non-interpretive, sub-community cooc is included, and 'degraded' means upstream lookup failure. This is far beyond a typical description.
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 long and dense, but it is front-loaded with the core use case and uses bullets and a structured return summary. Some repetition exists (the prior-work reconstruction is mentioned twice), yet nearly every sentence carries operational value for a tool with no annotations.
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?
There is no output schema, so the description must explain return values and edge cases. It provides the full return shape, semantics for nodes/edges/bridges/cooc, the degraded flag meaning, and instructs how to harvest ids for further drill-down. For the tool's complexity, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully. It explains author inputs as names, ids, or '+'-joined ids for merged split identities; hints/papers as parallel disambiguation lists; and source via the openalex default and the 's2' alternative for juniors. Each parameter gains operational meaning that the schema lacks.
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 opens with a concrete use case: 'WHO a researcher collaborates with — advisor + closest collaborators by joint-paper count, or how a paper's author group is connected.' This clearly states the verb, resource, and scope. It also distinguishes itself from WebSearch and names the sibling tool for the citation/influence layer, so an agent can tell it apart immediately.
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 explicit 'Use WHEN' conditions, explains the N=1 vs N>1 modes, tells the agent to pull names/ids from omniseek_resolve_identity, and explicitly routes to omniseek_field_skeleton for a different layer. It also tells the agent that an empty graph may be missing data to retry, not a real 'no collaborators' result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN acting on the source-curation protocol — WRITE a source-lifecycle action (submit / probe / decide / admit / retire ...); every safety gate lives in the impl, unchanged. Pick
the action with verb; each verb's REQUIRED args (see the /curator protocol):
• submit (name, urls, mode, domain, family; optional kind, regions, rationale, draft) -> add a CANDIDATE source to the admission backlog. mode ∈ STRUCTURE/UNWALL/TRANSCRIBE/RECALL/MONITOR. draft (foundry-grade) is a WORKING artifact ({"row", "fixture", "probe_summary"}) surfaced in the packet and preferred as stage_commit's ready-to-paste block. • probe (candidate_id) -> run the MECHANICAL evidence-gatherers, persist + return the packet. • wall_probe (candidate_id) -> P2 re-probe: RENDER the candidate in the network-isolated jail (egress only via the SSRF-pin proxy) so a source whose real content the plain-HTTP probe MISSED (client-rendered SPA / anti-bot / soft-login-wall) is measured on its REAL content. Eligible on a parked_p2 candidate OR an awaiting_verdict one YOU judge to be a client-rendered shell (WHEN to spend a render is your call, not an auto-gate). Surfaces content -> lands in awaiting_verdict on the rendered packet (parked_p2 revives, awaiting_verdict re-enriches); nothing -> stays put with the reason. Facts are render-derived (M7): the code never admits, only surfaces. • decide (candidate_id, decision, reasons; baseline_ref required to admit) -> record the admit/watch/reject verdict. MECHANICALLY REFUSES an admit on hard red-line / incomplete evidence / empty baseline_ref / no packet. admit -> owner_review; watch -> watching; reject -> rejected. • apply_live (candidate_id) -> ONE-TAP LIVE ADMIT (rss-safe subclass only): a REVERSIBLE overlay row + live re-register, NO git. Non-auto families are refused (use stage_commit). • rollback_live (name, family) -> full revert of a live-applied overlay row (unregister + drop). • stage_commit (candidate_id) -> ONE-TAP STAGED COMMIT for the NON-auto subclass: prepares the git commit text (does NOT apply); the operator does the git add / commit / deploy by hand. When the candidate has a foundry draft, the draft row IS the ready-to-paste block (+ a provenance line). • retire_live (name; confirm) -> ONE-TAP PRUNE (needs an existing PRUNE verdict): confirm=False previews; confirm=True writes a reversible runtime explicit_only override + stages the git commit. • rollback_retire (name) -> drop the runtime retire override so the source rejoins the fan-out. • source_verdict (name, verdict, rationale; prune_class, coverage_impact) -> record KEEP / WATCH / PRUNE for an EXISTING source. MECHANICALLY REFUSES a PRUNE the source's safety flags forbid.
Unknown verb returns an error dict listing the valid values.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| mode | No | ||
| name | No | ||
| urls | No | ||
| verb | Yes | ||
| draft | No | ||
| domain | No | ||
| family | No | ||
| confirm | No | ||
| reasons | No | ||
| regions | No | ||
| verdict | No | ||
| decision | No | ||
| rationale | No | ||
| prune_class | No | ||
| baseline_ref | No | ||
| candidate_id | No | ||
| coverage_impact | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and handles it well. It discloses side effects (adds candidate, records verdict, writes overlay row), mechanical safety gates ('MECHANICALLY REFUSES an admit on hard red-line', 'MECHANICALLY REFUSES a PRUNE'), reversibility ('REVERSIBLE overlay row', 'rollback_live'), and the fact that unknown verbs return an error dict. It also clarifies that wall_probe only surfaces render-derived facts and never admits, which prevents a dangerous misassumption.
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 long, but it is a multi-verb dispatcher and nearly every line adds necessary invocation detail. The front-loaded opening states the tool's purpose immediately, and the verb-by-verb format is scannable. Some jargon and parentheticals (e.g., SSRF-pin proxy, M7, foundry-grade) add density, but they are meaningful for correct action selection rather than filler.
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?
This is a complex tool: 18 parameters, 10 distinct verbs, conditional requirements, state transitions, and no output schema or annotations. The description covers all verbs, their arguments, side effects, refusal conditions, and error behavior, and even describes return surfaces ('persist + return the packet', 'surfaced in the packet', 'returns an error dict'). Nothing essential for an agent to select and invoke the correct action is missing.
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 no descriptions for any of the 18 parameters, but the description compensates comprehensively by mapping each verb to its required and optional parameters: submit requires name, urls, mode, domain, family; decide requires baseline_ref to admit; retire_live needs confirm; source_verdict takes prune_class and coverage_impact. It also explains parameter semantics such as mode enum values, confirm=False preview behavior, and the draft working-artifact structure. This far exceeds what the bare schema offers.
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 opens with a clear directive: use this tool when acting on the source-curation protocol and performing a WRITE source-lifecycle action. It enumerates the exact verbs (submit, probe, decide, apply_live, etc.), each with a specific resource and effect, which fully disambiguates it from read-only siblings like omniseek_curator_view. This is a specific verb+resource statement, not a tautology.
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 explicitly says when to use the tool ('Use WHEN acting on the source-curation protocol — WRITE a source-lifecycle action') and gives per-verb eligibility conditions, such as wall_probe being eligible on parked_p2 or an awaiting_verdict candidate, and stage_commit being for the non-auto subclass. It does not spell out explicit alternatives like 'use omniseek_curator_view for reads,' but the WRITE qualifier and sibling context make the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN running the source-curation protocol (judge the admission queue or a source audit) — READ curator state: queue | packet | audit. Never mutates. Pick a view with what:
• what="queue" -> the candidate-admission backlog (optionally filtered by state:
new / probed / awaiting_verdict / admitted / watching / rejected / owner_review /
redline_blocked / parked_p2 / error). The judging agent's entry point: list awaiting_verdict,
then view each packet. See the /curator protocol.
• what="packet" -> the last-built evidence packet for candidate_id (a fresh agent picks it up
cold); {"error": ...}/{"state": ...} if none built yet. A foundry-grade draft (the
submitter's WORKING row + fixture + probe summary) is surfaced verbatim under draft.
• what="audit" -> the per-source NEUTRAL audit dossier (P3): facts + LABELED descriptive ratios
the mechanical safety flags per source, NO verdict key. Read this, then render KEEP / WATCH / PRUNE via omniseek_curator_act(verb="source_verdict", ...).
Unknown what returns an error dict listing the valid values.
| Name | Required | Description | Default |
|---|---|---|---|
| what | Yes | ||
| state | No | ||
| candidate_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full behavioral burden and meets it: it explicitly declares 'Never mutates', details the distinct behavior of each 'what' value, states what happens when no packet is built, and specifies that unknown values return an error dict listing valid values.
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 long but earns its length: it covers three distinct views, parameter constraints, error behavior, and protocol sequencing in a scannable bullet format. The most important information is front-loaded and no sentence is wasted.
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 no output schema and no annotations, the description provides richly detailed context for every view, including the draft packet structure, the audit dossier contents, the absence of a verdict key, and the recommended follow-up call to omniseek_curator_act. This is complete enough for an agent to select and invoke the tool correctly.
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 there are no enums, yet the description fully documents all three parameters: 'what' with its three valid values, 'state' with the full allowed list, and 'candidate_id' as the sole selector for the packet view. It also explains how invalid values behave.
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 verb and resource: 'READ curator state: queue | packet | audit' and names the exact protocol context. It also distinguishes itself from the mutating sibling omniseek_curator_act by explicitly saying it never mutates.
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 opening line gives explicit when-to-use guidance: 'Use WHEN running the source-curation protocol (judge the admission queue or a source audit)'. It also names the next-step alternative, omniseek_curator_act, for rendering verdicts after reading the audit view.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map a research field's shape — use WHEN you need its citation neighborhood (foundational core by citations vs frontier by date) to cluster yourself, from a topic or seed papers.
A thin graph primitive, NO judgment: given query (auto-picks top-relevance seeds) or
seeds (OpenAlex work-ids YOU chose as anchors — preferred once you know the field), it
returns the field's complete citation neighborhood: every node with raw metadata, date,
and ONE signal in_degree (how many in-field papers cite it).
YOU are the cartographer — do ALL the intelligence over this raw data:
• SEEDS: if the auto-seeds are off (e.g. a generic survey crept in), re-call with
seeds=[...] you pick from the nodes.
• SOURCE: source="openalex" (default, rich for established fields) or source="s2"
(Semantic Scholar — far better arXiv coverage + accurate citation counts; use it for
recent/bleeding-edge fields where OpenAlex's graph is sparse). s2 nodes also carry
influential (S2 flags the citation link to a seed as substantive, not a drive-by) and
intent (methodology/background/result, when S2 classified it): strong cues for what
to read first, and contexts ([{snippet, intents}]: the RAW citing SENTENCE(s) S2
extracted). READ a snippet to judge a citation's POLARITY yourself (does the citer
SUPPORT, CONTRAST/refute, or merely MENTION the seed): OmniSeek exposes the sentence, YOU
classify; S2 has no polarity field and OmniSeek makes no such judgment. contexts is empty
when S2 never parsed the citing PDF. For a young/hot field the best "graph" is often a
human-curated survey/awesome-list, fetch that yourself instead.
• FOUNDATIONAL vs FRONTIER: high in_degree = the foundational core; recent date
(filter it yourself) + your relevance read = the frontier. There is no frontier flag —
you judge it.
• DATA HYGIENE: OpenAlex occasionally has a poisoned title (e.g. a 14k-citation paper titled
"AI Consciousness" by T.B. Brown IS a corrupted GPT-3 record). You recognize these — no
code does. Use a node's url to verify / omniseek_read to read the real paper.
• Cluster + narrate relevance and sub-fields from titles + concept + your knowledge.
• GAP DETECTION (your seed set's blind spots): each non-seed node carries seed_ref_freq (how many
of YOUR seeds reference it = a foundational ref your reading list is MISSING) and seed_cite_freq
(how many seeds it cites = a frontier citer you are MISSING). Sort non-seed nodes by these to find
what your input lacks. edges (the in-corpus [citer, cited] citation DAG) lets you build the
citation / co-citation / bibliographic-coupling maps yourself (co-authorship: use omniseek_coauthors).
• BUDGET: there is an overall wall-clock cap (deadline_s, ~25s default). On a slow/throttling
S2 the assemble bails early with a PARTIAL map (_meta.deadline_hit: true) rather than
hanging — retry shortly, raise deadline_s, or use source=openalex.
Returns: {seeds, n_nodes, n_edges, edges:[[citer_id, cited_id]], nodes:[{id, title, year, date, cited_by, in_degree, concept, first_author, doi, url, is_seed, seed_ref_freq, seed_cite_freq}]} (sorted by in_degree as a default view only; seed_ref_freq/seed_cite_freq on non-seed nodes). _meta carries seed_titles + seed_note (auto-seed drift check), degraded, deadline_hit, partial.
| Name | Required | Description | Default |
|---|---|---|---|
| fresh | No | ||
| query | No | ||
| seeds | No | ||
| source | No | openalex | |
| n_seeds | No | ||
| max_nodes | No | ||
| deadline_s | No | ||
| citers_per_seed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden of behavioral disclosure, and it delivers extensively: it states the tool makes 'NO judgment,' auto-picks seeds, bails early with a PARTIAL map when the deadline hits rather than hanging, and warns about poisoned OpenAlex titles (the corrupted GPT-3 record example). It also reveals edge cases like 'contexts is empty when S2 never parsed the citing PDF' and its default sort-by-in_degree behavior.
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 purpose is front-loaded in the first sentence and the bolded section headers (SEEDS, SOURCE, BUDGET, etc.) make the long content skimmable. But the description is exceptionally long, with stylistic asides like 'YOU are the cartographer — do ALL the intelligence over this raw data' and emphatic flairs that add tone rather than facts; a tighter edit preserves the same information at roughly two-thirds the length.
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 8 optional params, zero annotations, 0% schema coverage, and no output schema, the description is impressively complete: it spells out the full return structure, deadline/partial-result behavior, data-quality caveats, the gap-detection workflow (seed_ref_freq/seed_cite_freq), and the source-selection decision tree. The only real gaps are three parameters (fresh, max_nodes, citers_per_seed) that go entirely unexplained, though two of those are reasonably inferable from their names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate — and it deeply explains query (auto-picks top-relevance seeds), seeds (OpenAlex work-ids as user-chosen anchors, preferred once you know the field), source (openalex vs s2 tradeoffs including arXiv coverage and influential/intent signals), and deadline_s (~25s default, partial-result behavior). However, fresh, max_nodes, and citers_per_seed receive no semantic explanation, and n_seeds is only implied, leaving several parameters undocumented in both the schema and the description.
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 opening line 'Map a research field's shape' pairs a specific verb with a clear resource, and 'use WHEN you need its citation neighborhood (foundational core by citations vs frontier by date)' states the exact trigger condition. It differentiates from siblings by routing co-authorship needs to omniseek_coauthors and framing its unique niche (citation neighborhood with in_degree signal) against the other omniseek tools.
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 explicit when-to-use ('use WHEN you need its citation neighborhood... to cluster yourself') and when-not-to-use guidance ('For a young/hot field the best graph is often a human-curated survey/awesome-list, fetch that yourself instead'). It also names concrete alternatives (omniseek_read for verification, omniseek_coauthors for co-authorship) and gives source-selection criteria (openalex for established fields vs s2 for recent/arXiv-heavy ones).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run N independent read-only eye tools IN PARALLEL, returning results in one response.
The agent decides WHAT to call (judgment). OmniSeek executes them (mechanical). Each call runs independently; one failure does not affect others. Calls that depend on a prior call's result belong in a SEPARATE gather (the agent reads this batch first, then decides the next batch).
calls: [{"tool": "omniseek_search", "args": {"query": "..."}}, ...]
Bounded: max 10 calls. Read-only tools only.
wait_s: the patience budget. gather returns when all calls finish OR wait_s elapses,
whichever comes first; calls still running are reported with status "warming" (their
background threads keep going and warm the cache — pick them up later with
staleness="cache_only" or a second gather).
Returns: {results: [{index, tool, status, result|error|hint}, ...],
elapsed_s, completed, warming, failed, total}
On an errored call whose failure is a call-signature mismatch (a wrong / missing argument), hint
names the tool's REAL parameters (e.g. "omniseek_read takes: target, start_char, max_chars, ...").
| Name | Required | Description | Default |
|---|---|---|---|
| calls | Yes | ||
| wait_s | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: execution is parallel, failures are independent, calls may continue as background threads after wait_s, warming status is reported, and signature mismatches produce hints. This goes well beyond what the bare schema could convey.
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 longer than average, but the length is justified by the orchestration behavior and return formats. It is front-loaded with the core purpose and uses labeled sections for calls, wait_s, and return value, though a few phrases like 'the agent decides WHAT to call (judgment)' add flavor but not essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no annotations and no output schema, the description covers input format, constraints, timeout semantics, background execution, return shape, and error hints. An agent has enough information to invoke it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema is generic, but the description defines both parameters concretely: calls as a list of {tool, args} objects with a max of 10, and wait_s as a patience budget with a default behavior. The example makes the expected structure unambiguous.
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 leads with a specific, action-oriented statement: 'Run N independent read-only eye tools IN PARALLEL, returning results in one response.' This clearly identifies the tool as a parallel orchestrator for read-only tools, and the example using omniseek_search plus the list of sibling read tools makes it distinguishable from single-call siblings like omniseek_read and omniseek_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditions for use: independent calls, read-only tools only, max 10, and it explicitly says dependent calls belong in a separate gather. It does not name a specific sibling as the alternative for single calls, but the separation guidance and read-only restriction provide enough context to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you want HOW two entities connect, or what OmniSeek already knows AROUND a paper / author / entity; read-only, budgeted projections of its accumulated evidence graph with typed edges (ONE graph).
Everything OmniSeek perceives is a statement with provenance ("X relates to Y, per Z"); the evidence graph accumulates those typed edges in ONE store surfaced through N indexes. It stores FACTS + labeled CANDIDATES, never verdicts: mechanical world edges (tier M: cites, authored, coauthored, affiliated, published_in, about, observed, exact-id same_as) and alignment CANDIDATES (tier A: title-fingerprint / fuzzy-name same_as, name-match authored, string mentions, signal conflicts). Judgment (claims, gaps, identity rulings) is tier J and is STRUCTURALLY excluded from OmniSeek's store — the views project structure, YOU judge it.
ONE STABLE VERB: omniseek_graph(view, args). view names the projection; args is that
view's OWN parameter dict (the views are an open family, their params disjoint per view, so the
ABI is (view, args), not a flat union). THE SCHEMA IS FROZEN: future views and future per-view
parameters change NOTHING in this signature; a no-view call returns the live view catalog (the
surface is self-describing), and content is NEVER inlined (every view returns node ids + labels
edge tuples, so you zoom with the other eye tools).
• view="find", args={"label_query": ..., "kind"?: ...} -> the ENTRY POINT. A node id is minted
by the backend that knows it, so a NAME ("Siva Reddy") is not a node until you resolve it: find
does the mechanical token/substring match over node labels and returns candidate ids + kinds.
Every other view takes an anchor id; find is how you get one.
• view="stats", args={} -> counts by kind / type / tier. The cheap orientation call (also the
cold-start check: see below).
• view="neighborhood", args={"anchor": ..., "depth"?<=2, "types"?, "policy"?, "max_nodes"?} ->
the bounded subgraph around a node.
• view="between", args={"a": ..., "b": ..., "types"?, "policy"?, "max_nodes"?} -> bounded
connection paths between two anchors, the "how do these relate" question. Bidirectional BFS,
<=2 hops per side, up to 8 shortest paths; capped when more existed. No path -> paths:[].
• view="voices", args={"doc_ids": [...], "policy"?: ...} -> collapse a doc set to distinct
upstream VOICES via same_as + authored; the independence counter (mirror collapse, shared-speaker
docs merge, docs with zero evidence land in unresolved and are NEVER counted as a voice).
Input capped at 64 doc ids by explicit error; non-doc: ids come back in skipped.
• view="since", args={"anchor": ..., "date": ..., "types"?, "max_nodes"?} -> the accretion log:
what accreted around an anchor after a date (YYYY-MM-DD or full ISO), STORED edges only,
tier + method shown on every row, NO collapsing (accretion is a fact stream, not an identity
question). Derived edges carry no timestamps and are structurally absent. The sensor consumer.
• view="similar", args={"anchor": , "k"?: ...} -> vector-nearest doc CANDIDATES for an
anchor doc, method align:embed, by RANK (k is a budget, never a score threshold). PROPOSALS
only, never collapsed by any policy; verify, then ratify with omniseek_ruling. Coverage: any doc with
an embedded title, ranked across the UNION of the indexed vec matrix AND the thin-title vec_thin
matrix (P7), so a thin arXiv original and an indexed post rank in ONE space; candidates may be
thin docs. A doc with no vector in either store (un-embedded yet) -> an error naming that.
NON-GOAL: vec_thin does NOT feed search's recall arm (similar + future P5 consumers only).
A no-view call (view="") returns the live view catalog: each view's params + one-line blurb,
DERIVED from the registry, so new views appear here without a client restart.
Identity rulings are WRITTEN via omniseek_ruling (this tool stays read-only, hence gather-safe).
policy (an arg on the collapsing views) = conservative | working | exploratory: NAMED
METHOD-SETS for how far to trust identity (same_as) edges when collapsing, NOT numeric thresholds
(a hand-picked constant is pseudo-precision; the METHOD is the honest epistemic unit, as recall
fuses by rank only):
conservative: collapse on exact-id equality only (DOI / OpenAlex / ORCID / arXiv; default)
working: conservative + agent identity rulings from graph_rulings.json
exploratory: working + title-fingerprint / fuzzy-name alignment CANDIDATES Identity is an EVIDENCE-CARRYING EDGE, never a destructive merge: same_as edges carry tier + method, collapse is reversible, and a not_same_as ruling beats a same_as. OmniSeek never MAKES an identity ruling; it only applies the ones you already recorded.
COLD START (set the expectation or the first stats reads as failure): documents and same-work edges are LIVE FROM DAY ONE (derived over recall's docs — the wall is born pre-populated by construction). Document THIN rows (title + url only, from NON-indexed sources) now accumulate from EVERY search (stats.node_kinds.document_thin), so the perception history is complete, not just the ~40 enumerable sources. Entity kinds (work / person / institution / venue / topic) still fill in as the P2/P3 write taps ship and calls happen; emptiness of those kinds early is CORRECT, not broken.
BUDGETS (the no-silent-caps discipline): depth is clamped to <=2, max_nodes caps the node
count, and any capped result stamps capped: true so a bounded view never reads as
complete. Schema + the view registry live in omniseek.core.recall.graph.
FAIL-OPEN: a graph failure returns an error dict, never an exception — the graph is memory, it must NEVER break search or recall.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| view | 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 of behavioral disclosure, and it meets it thoroughly. It discloses read-only semantics, budget clamping with capped flags, fail-open error behavior, structural exclusion of judgment tier, reversible identity collapsing, and cold-start expectations. This is far beyond what annotations would normally provide.
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 long, but the tool has a generic two-parameter ABI with an open family of views, so extensive enumeration is justified. Structure is strong: the trigger sentence comes first, sections are separated, and each view is named with its arguments and semantics. Some philosophical asides and redundancy could be trimmed, which keeps it from a perfect conciseness score.
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?
There is no output schema and no annotations, so the description is the only source of operational context. It covers all invocation paths, per-view outputs, cap behavior, error dicts, cold-start expectations, the live view catalog, and the relationship to omniseek_ruling. Nothing an agent needs to select and call this tool correctly is missing.
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 is extremely generic (view string plus arbitrary args object) with 0% description coverage, so the description must compensate entirely. It does: it enumerates every view, its exact parameter names, defaults, constraints, return behavior, and error cases. An agent can construct valid calls for find, stats, neighborhood, between, voices, since, and similar without any additional lookup.
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 opening sentence states exactly when to use the tool: to see how two entities connect or what OmniSeek knows around a paper, author, or entity. It explicitly positions the tool as a read-only projection of an accumulated evidence graph with typed edges, which clearly differentiates it from the write-oriented omniseek_ruling and the broader search/read tools.
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 explicit when-to-use conditions ('Use WHEN you want HOW two entities connect...') and specifies that identity rulings are written via omniseek_ruling while this tool stays read-only. It also marks non-goals such as vec_thin not feeding search's recall. However, it does not systematically name all sibling tools as alternatives, so an agent must infer some routing boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you need the people-ROSTER of a lab / department / university (who actively publishes there, optionally scoped to a field) — the "who's at this lab" question, orthogonal to co-authorship ("same lab, never co-authored" is still a tie, and the people-roster of a target lab is exactly the SG/Canada cohort question).
Resolve the institution (+ optional FIELD) -> roster ranked by their output AT that
institution IN that field (so juniors with a few papers surface, not just senior profs).
IMPORTANT: without concept you get the institution's most-prolific people across ALL
fields (e.g. "Hong Kong University of Science and Technology" -> chemistry/materials profs,
not the ML group) — pass concept="machine learning" / "natural language processing" / etc.
to scope to a cohort. year_from (e.g. 2022) biases toward the CURRENT cohort (recent
publishers). The roster is a STARTING POINT you drill (omniseek_coauthors / omniseek_read on
homepages), not a verified lab-member list — OpenAlex has no "PhD student" flag.
Returns: {institution:{id,name}, filters, n, people:[{id, name, works_at_institution_in_field}], note}.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| concept | No | ||
| year_from | No | ||
| institution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so richly: it discloses ranking by output at that institution in that field, the juniors-surface property, the all-fields fallback when concept is omitted, the recency effect of year_from, and the OpenAlex data limitation about no PhD-student flags.
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 front-loaded with the primary use case and packs substantial guidance into two paragraphs plus a return shape. It is slightly redundant with repeated 'people-roster' phrasing and the niche 'SG/Canada cohort question' reference, but no sentence is purely filler.
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?
This tool has no annotations and no output schema, so the description must cover purpose, usage, parameter semantics, behavioral caveats, and return shape. It does all of this: return fields are listed, important failure-of-verification caveats are stated, and sibling drill-in tools are referenced. The only minor gap is the limit parameter, which is already self-explanatory from the schema default.
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 the parameters itself. It does this well for institution, concept, and year_from, with concrete examples like concept='machine learning'. However, the limit parameter is not mentioned in the description, relying entirely on its name/default in 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 opens with a specific verb-resource pair: producing the people-roster of a lab/department/university, and clearly frames the tool as answering the 'who's at this lab' question. It explicitly distinguishes itself from co-authorship tools by noting that same-lab, no-coauthorship is still a tie, so an agent can separate this tool from omniseek_coauthors.
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 states when to use the tool, what optional scoping to provide (concept, year_from), and what not to expect: the roster is a starting point, not a verified lab-member list. It also names the downstream drill-in tools (omniseek_coauthors / omniseek_read), giving clear alternative/next-step guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you need ONE paper's open-access full-text PDF, retraction / integrity status, or citation count — signals omniseek_search / field_skeleton do NOT give cleanly. Keyless, mechanical: YOU decide when + on which papers.
Pass DOIs and/or arXiv ids (e.g. "2306.08543", "10.1145/3292500.3330701"; use a node's
doi from omniseek_field_skeleton, or metadata.paper_id/metadata.doi from an openalex omniseek_search
result — NOT its source_id, the OpenAlex W-id, which is not a DOI/arXiv id). Enrich only the
handful you care about, not a whole map.
For each id:
• is_oa / pdf_url — the open-access full text (arXiv always OA; real DOIs via Unpaywall). Feed
pdf_url to omniseek_read (or read it yourself) to get the WHOLE paper, not just the abstract —
then YOU synthesize. (This thin PDF primitive is why we did NOT add a synthesis engine.) For
FIGURES / architecture diagrams / result plots: download the PDF and Read its pages with your
own VISION — they render in context with captions, so no figure-extraction channel is needed.
• integrity.retracted + integrity.notices (retraction / expression_of_concern / correction /
…) from Crossref's Retraction Watch feed — check before trusting a high-stakes citation.
(retracted=None means "not checked" / backend unreachable; notices=[] means clean. arXiv
ids are checked too: an author withdrawal marker plus the journal DOI, when present, run
through the same Crossref retraction path.)
• citation_count — this paper's citation count (DOI: Crossref is-referenced-by-count; arXiv: S2
citationCount). The single-paper count's home, so you need NOT repurpose omniseek_field_skeleton to
read one node's count. (None when the backend was unreachable.)
Returns: {"results": [{id, kind, doi, is_oa, pdf_url, oa_url, citation_count, integrity:{retracted, notices}}, ...]} (or {id, error} for an unrecognized id).
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool is keyless and mechanical, that it does not synthesize or extract figures, and it explains edge-case semantics such as retracted=None vs notices=[] and backend-unreachable behavior. It also clearly states what the return payload contains, including error entries for unrecognized ids.
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?
Despite being long, the description is tightly organized with front-loaded usage intent, bulleted per-id behaviors, and a compact return schema. Every sentence adds useful information, from identifier guidance to integrity semantics to explicit non-synthesis rationale. The structure makes the detail scannable rather than overwhelming.
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 no output schema and no annotations, the description is complete: it covers valid inputs, per-field output semantics, error handling, backend failures, and downstream tool routing. An agent has everything needed to invoke it correctly and interpret results correctly.
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 only says ids is an array of strings with 0% description coverage, so the description must compensate. It does by specifying accepted identifier forms (DOIs and arXiv ids), giving concrete examples, explaining which fields from sibling tools to use, and explicitly warning against using source_id or OpenAlex W-id. This is far more than the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: enrich a single paper with open-access PDF, integrity status, and citation count. It explicitly contrasts with omniseek_search / field_skeleton, which do not provide these signals cleanly, so an agent can distinguish this tool from its siblings.
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 tells the agent exactly when to use the tool ('Use WHEN you need ONE paper's open-access full-text PDF...') and when not to, such as not using omniseek_field_skeleton to read a single node's count. It also advises enriching only a handful of papers rather than a whole map, and names omniseek_read as the follow-up for reading PDFs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you have a paper and want more like it — semantically-similar papers (SPECTER embeddings) that keyword search and the citation graph miss, including very recent work. Uses Semantic Scholar's recommendation model (SPECTER embeddings + co-citation), so it surfaces conceptually-related work that omniseek_search (keyword) and omniseek_field_skeleton (citations) miss — including very recent papers the citation graph has not caught up to.
Pass seed paper ids (arXiv ids / DOIs / S2 ids — a paper you found via omniseek_search or omniseek_field_skeleton). One seed = "more like this"; several = recommendations from that set. This is OmniSeek's "semantic search": it routes to S2's existing embeddings rather than building any. For an openalex omniseek_search result pass metadata.paper_id (or metadata.doi), NOT source_id — the OpenAlex W-id is a graph id the paper tools do not accept.
Returns: {"seeds", "n", "papers": [{id, title, year, date, cited_by, first_author, doi, url}]} (ordered by S2 relevance; YOU re-judge). Citation neighborhood instead → omniseek_field_skeleton; keyword search → omniseek_search.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the underlying model (SPECTER + co-citation), that it surfaces very recent work outside the citation graph, and that results are ordered by S2 relevance and require re-judgment. It does not mention rate limits or error behavior, so it stops short of a 5.
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 key use case is front-loaded, but the description is repetitive: SPECTER/co-citation, the sibling contrasts, and 'very recent work' are each stated twice. The guidance could be condensed meaningfully without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description supplies a return JSON skeleton, ordering guidance, seed ID formats, and alternative routing. This is complete for normal use; the only clear gap is limit semantics and possible empty/error responses.
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 compensate. It thoroughly explains 'ids': accepted formats, one-vs-many semantics, and the OpenAlex source_id pitfall. However, 'limit' is never described, leaving its effect on 'n' and result count to be inferred only from the schema default.
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 opens with a specific use case: given a paper, get semantically similar papers via SPECTER embeddings. It explicitly contrasts this tool with omniseek_search (keyword) and omniseek_field_skeleton (citations), so an agent can clearly distinguish it from siblings.
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 states exactly when to use it ('Use WHEN you have a paper and want more like it'), what inputs to pass (arXiv IDs/DOIs/S2 IDs), and when to choose alternatives: citation neighborhood -> omniseek_field_skeleton, keyword search -> omniseek_search. It also includes a concrete OpenAlex ID-format warning that prevents a likely error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read text from any URL OR document FILE — OmniSeek's single "read this deep" verb. AUTO-ROUTES.
ROUTING: if target is a local filesystem path OR ends with a document extension
(.pdf / .pptx / .docx / .xlsx / .txt / .md / .csv, case-insensitive, a ?query is tolerated) it
routes to the DOCUMENT reader (below); otherwise it routes to the URL reader. start_char /
max_chars window the body on BOTH branches (see below); export_media / ocr apply only
to the document branch (a URL read has no image-extraction path) and are IGNORED on the URL branch.
URL BRANCH: fetch + normalize ONE URL. Tries each registered adapter until one claims it — a
specific article link (a Reddit post, an arXiv paper, a Bluesky post) as a normalized document.
arXiv is two-tier by design: an /abs/<id> URL returns abstract-level metadata (title / authors
/ abstract, a fast lookup), while an /pdf/<id> URL routes to the PDF extractor and returns the
WHOLE body (e.g. 2203.02155v1 → 68 pages of full text). Pass the URL whose depth you want.
vs the open web: reads ONE specific URL you already have; to FIND open-web pages use WebSearch
first, then omniseek_read to normalize the page (a common pairing).
The normalized body is WINDOWED by start_char / max_chars (default 24000), exactly like the
document branch: a big page (a SEC 10-K/20-F is ~2 MB → ~200k chars, a long article) would otherwise
return one blob that overflows the tool channel and is unreadable. When truncated is true, re-call
with start_char bumped by returned_chars to page through the rest. A small page (< max_chars)
returns whole, truncated=false — unchanged from before.
URL branch returns: {"url", "matched": bool, "document": Document as dict | None,
"total_chars", "returned_chars", "start_char", "truncated"} (the last four only when matched). On
matched:false a reason is added: walled (anti-bot challenge -> retry the source via CDP, e.g.
omniseek_search(sources=[...], raw=True, full=True)) vs empty vs blocked, so you can tell "gated, drill it
another way" from "genuinely nothing there".
DOCUMENT BRANCH (pptx / docx / xlsx / pdf / txt / md / csv): read the FILE into readable, structured text — the document counterpart of omniseek_transcribe (speech). Free, keyless, cached. WHERE THE FILE LIVES:
the operator's machine: scp it to OmniSeek host inbox first — scp "" :omniseek-inbox/ then call with "omniseek-inbox/".
Anywhere on the web: just pass the URL (conference slide decks, a shared docx, a PDF).
WHAT COMES BACK: outline = per slide/sheet/page {label, chars, media} — the MAP of the whole
document, always complete and tiny; text = the readable content ("## Slide 3" / "## Sheet:
budget" / "## Page 5" headers), windowed by start_char/max_chars for big docs (truncated=true +
total_chars tell you to re-call with start_char to continue); media/media_total = the image
inventory per section.
THE IMAGE HALF (be honest about it): a figure deck or scanned doc carries its meaning in IMAGES —
text extraction alone is NOT the document. Two ways to read it: omniseek_view delivers the figures to
your OWN vision in-band (judging the figure is yours); ocr=True here runs OCR over every embedded
image and folds the recognized text-in-pixels (scanned page body, chart labels, palette HEX/RGB
codes) into the body under a '图中文字 (OCR)' section — mechanical text transcription, NOT figure
interpretation, and labeled as possibly imperfect. Use ocr for text-bearing images (scans, labels);
use omniseek_view to SEE the figure.
Document branch returns: {source, format, title, outline, text, total_chars, returned_chars,
start_char, truncated, media_total, media, media_dir, ocr_images?, cached} — or {source, error,
inbox_files?}.
| Name | Required | Description | Default |
|---|---|---|---|
| ocr | No | ||
| target | Yes | ||
| max_chars | No | ||
| start_char | No | ||
| export_media | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden — and it delivers extensively. It discloses auto-routing rules, the windowing/pagination protocol (truncated flag, bump start_char by returned_chars), the arXiv two-tier /abs vs /pdf behavior, the matched:false reason taxonomy (walled/empty/blocked), that export_media/ocr are IGNORED on the URL branch, and the honest caveat that OCR is mechanical transcription, not figure interpretation. This is exemplary behavioral disclosure for a dual-branch tool.
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 long but earned: the tool is genuinely complex with two branches, five parameters, and no output schema. Markdown-style headers (URL BRANCH, DOCUMENT BRANCH, WHERE THE FILE LIVES, WHAT COMES BACK, THE IMAGE HALF) make it scannable. Minor redundancy exists — windowing is explained twice, once per branch — and some phrasing ('unchanged from before', 'be honest about it') adds color without information. Nearly every sentence earns its place, but a few could be tightened.
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 complex auto-routing tool with 5 parameters, no output schema, and no annotations, the description is essentially complete. It documents both return shapes, error/edge cases (matched:false reasons, {source, error, inbox_files?}), the file-ingestion workflow (scp to inbox), caching, and parameter interactions across branches. An agent has everything needed to call this tool correctly and interpret its results.
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 compensate fully — and it does. target's routing semantics (path vs extension vs URL), start_char/max_chars windowing with paging instructions, and the branch-specific behavior of ocr / export_media are all explained in detail. Every one of the 5 parameters gains meaning beyond its schema definition.
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 opens with a clear verb+resource pair: 'Read text from any URL OR document FILE' and identifies itself as OmniSeek's single 'read this deep' verb. It is explicitly differentiated from siblings: omniseek_transcribe is called the 'document counterpart (speech)' and omniseek_view is positioned as the image-seeing tool. The auto-routing between URL and document branches is precisely scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'reads ONE specific URL you already have; to FIND open-web pages use WebSearch first, then omniseek_read to normalize the page (a common pairing)'. It also names alternatives for specific cases — omniseek_view for seeing figures, omniseek_transcribe for speech, and omniseek_search with CDP for walled sources. No ambiguity remains about which sibling to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a PERSON's name to candidate author ids — the shared front door for EVERY relationship layer (you must know WHICH person before you can map their connections).
OmniSeek's other tools keyword-search PAPERS; this resolves an AUTHOR. It NEVER silently
picks — it returns ranked CANDIDATES so YOU disambiguate (the homonym trap: "Zhennan Shen"
is three different people in OpenAlex). hint (e.g. an institution like "HKUST", or a
field) only RE-ORDERS candidates, never filters them. source: "auto" (OpenAlex first,
pulls in Semantic Scholar when the top OpenAlex hit is sparse — i.e. a likely junior /
arXiv-frontier author OpenAlex hasn't indexed), "openalex", or "s2".
paper (an arXiv id / DOI / title of a KNOWN paper by this person) is the reliable way
to pin a COMMON-NAME JUNIOR — it resolves straight from the paper's author list, where a
bare name search fails (e.g. many distinct researchers share a common name like "Wei Zhang";
their paper fixes the exact id).
Use the returned id with omniseek_coauthors. ambiguous: true means two comparable
candidates — confirm with a hint / a paper / a known co-author before trusting either.
likely_same_person (when present) groups same-name same-backend candidates that are likely
ONE person SPLIT across ids, with a ready-to-paste merge_token ("A123+A456") you can hand
straight to omniseek_coauthors as one input; it never auto-merges, just surfaces the candidate merge.
Returns: {query, source, candidates:[{id, source, name, works_count, cited_by,
institution, via_paper?}], ambiguous, note, likely_same_person?:[{source, ids, name,
merge_token, note}], degraded?:{openalex}}. degraded (when present) means the OpenAlex
lookup FAILED (rate-limited / upstream down): an empty/thin result is then missing-data, NOT a
confirmed "not in the graph" — retry, or pass source='s2' / paper=.
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| name | Yes | ||
| paper | No | ||
| source | No | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It states the tool NEVER silently picks, hint only re-orders and never filters, likely_same_person never auto-merges but surfaces a merge_token, and degraded indicates upstream failure rather than confirmed absence. These details go well beyond the minimum and directly prevent misinterpretation.
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 long but appropriately sized for a complex disambiguation tool with four meaningful parameters, no annotations, and no output schema. It front-loads the core purpose and key safety behavior, then logically builds through parameter semantics, disambiguation flags, and failure semantics. Almost every sentence carries operational value.
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?
Since there is no output schema, the description documents the full return shape and explains each important flag (ambiguous, likely_same_person, degraded) with actionable consequences. It also connects the workflow to omniseek_coauthors and gives retry guidance for degraded upstream failures, making the definition self-sufficient.
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 compensate for all parameters. It adds exact meanings for hint (re-order only, never filters, example 'HKUST'), source ('auto', 'openalex', 's2' with fallback behavior), paper (arXiv id/DOI/title, resolves straight from the author list), and the required name (a PERSON's name). This is substantially richer than the bare input 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 leads with a specific verb and resource ('Resolve a PERSON's name to candidate author ids') and immediately distinguishes it from sibling tools: other OmniSeek tools keyword-search PAPERS, while this resolves an AUTHOR. It also states the workflow position as the shared front door for relationship layers, so an agent can clearly tell why this tool exists.
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 explicitly contrasts this tool with paper-searching tools and instructs agents to use the returned id with omniseek_coauthors. It gives concrete selection guidance for the 'paper' parameter (common-name junior authors), explains the source options and their behaviors, and tells the agent how to handle ambiguous results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN two graph nodes ARE (or are NOT) the same person / entity and you want views to collapse them — record / list / retract same_as | not_same_as rulings (the one judgment channel the graph's working policy applies).
OmniSeek never MAKES a ruling; it STORES yours as declarative state and APPLIES it at read time
(the sensors.json precedent: judgment persisted as config OmniSeek executes mechanically). A ruling
says "these two graph nodes ARE / are NOT the same entity"; omniseek_graph's working and
exploratory policies then collapse (or reject) that pair when projecting a view. The pair is
the KEY: it normalizes to src < dst, re-creating a pair REPLACES the prior verdict (declarative
state, not a log; git history is the audit trail).
action picks what to do:
• action="create" (src, dst, verdict="same"|"not_same"; optional note) -> record the ruling.
Returns {created: true, ruling, replaced} (replaced=true if it overwrote a prior verdict for the
pair). A bad verdict / empty or identical endpoints -> {"error": ...}.
• action="list" -> {rulings: [{src, dst, verdict, note, ruled_at}], count}.
• action="delete" (src, dst) -> {deleted: true/false} (false if no ruling existed for the pair).
This is a SEPARATE tool from omniseek_graph (not an omniseek_graph action) because omniseek_graph is batchable in omniseek_gather ONLY because it is read-only; folding a write into it would let the gather whitelist write. Unknown action -> {"error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| dst | No | ||
| src | No | ||
| note | No | ||
| action | Yes | ||
| verdict | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that OmniSeek never makes a ruling itself, only stores user judgment as declarative state and applies it at read time. It also explains pair normalization, replacement semantics, the git-history audit trail, and error conditions, which goes well beyond typical tool descriptions.
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 dense but well organized: trigger, conceptual model, pair-key semantics, action contracts, and sibling separation. Every sentence earns its place, and the most important when-to-use information is front-loaded. The length is justified by the need to document a write tool with no annotations or output schema.
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 mutating tool with no annotations and no output schema, this description is complete. It covers all three actions, expected returns, error cases, overwrite/delete behavior, and the relationship to omniseek_graph. An agent has enough information to invoke all actions correctly and interpret results.
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 compensate, and it does. It defines each action value, the verdict values, the optional note, and the src/dst pair key semantics. It also explains action-specific return fields such as replaced and deleted, making the parameters meaningful without schema help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise trigger condition: use when two graph nodes are or are not the same person/entity and views should collapse them. The description clearly names the resource and operations: record/list/retract same_as or not_same_as rulings. It also distinguishes itself from omniseek_graph, so the agent can tell them apart.
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?
Opens with an explicit 'Use WHEN' condition and closes with a clear separation argument explaining why this is not folded into omniseek_graph due to the read-only batching constraint. This gives concrete routing guidance for choosing this tool over the main graph tool. It does not compare directly to omniseek_resolve_identity, but the trigger condition is specific enough to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the curated sources. The default for "best/latest on X". ONE verb, three shapes.
DISPATCH (deterministic):
• DEFAULT (raw=False): DEDUP + RANK across sources into ONE list. Cross-source duplicates merge
(same paper from arxiv + openalex + … → one entry, the others in metadata.also_in); ordered by
a relevance+recency+engagement blend (metadata._rank) you may re-sort — each doc's named signals
map (e.g. citations / upvotes / stars, each provenance-stamped) + its date are on the doc.
CROSS-LINGUAL + SEMANTIC (default on): also runs VECTOR recall over the local perception-memory
index, so a Chinese query surfaces relevant ENGLISH docs (and vice-versa) and paraphrases match
with no shared words — fused with the lexical + live results by the SAME transparent ranker (the
eye still only retrieves + scores mechanically; you judge). semantic=False forces exact-token
lexical-only (an arXiv id / exact title); semantic=True biases toward the vector recall.
_meta.index reports {lexical, vector, mode}. Empty query ranks by recency (browse mode).
• raw=True + EXACTLY ONE source name (the DRILL idiom, replaces the old omniseek_fetch): fetch that ONE
source UNBOUNDED (with wait_s=None the generous single-source backstop; set wait_s to bound it).
Reach for it BY NAME on a walled/CDP or slow source (xiaohongshu, zhihu, yipinsanfendi,
xiaomuchong, twitter_x, and the explicit_only set): the broad sweep DEADLINE-DROPS these, so only
a named drill waits for them — a broad search that comes back without them is NOT evidence they
have nothing. full=True returns WHOLE content per doc. A cold walled drill self-warms its cache,
so an immediate repeat with the SAME query + SAME limit is sub-second (keep limit identical or the
key differs). On an EMPTY / ERRORED drill the result carries _meta.diagnostic (failed-egress
evidence + the adapter's source-file path) for the /eye-fix loop; a drill with results carries no
_meta (zero noise).
• raw=True otherwise (broad buckets): search many sources in parallel → PER-SOURCE buckets,
uncollapsed (each source's raw take separately, a tight content preview per doc). limit acts
PER SOURCE here. Drill a chosen doc with omniseek_read (whole content), or drop raw for the ranked list.
ROUTING (all shapes): sources=None = all non-explicit_only, deadline-bounded — slow ones drop and are listed in _meta.timed_out. explicit_only sources (browser/CDP + twitter_x) are excluded from the broad sweep → _meta.excluded_count (the size; the full name->reason map is in omniseek_sources) + _meta.excluded_relevant (the query-AWARE subset: walled/slow sources whose facets thematically match THIS query, each with a copy-paste sources=[...] re-run hint). Name them to include their (deeper, login-walled) coverage.
TIME + STALENESS: wait_s = patience budget (None = sensible default; the engine's deadline).
staleness ∈ {"fresh","cached_ok","cache_only"} (default cached_ok): "fresh" bypasses the cache
(live data); "cache_only" is the fire-then-collect PICKUP half (ranked shape) — with NO live work it
reads only what has already SELF-WARMED for the NAMED sources and NEVER re-fires a still-cold walled
source (zero extra CDP / account traffic, poll-safe). Fire-then-collect: FIRE
omniseek_search(query, sources=[walled...], wait_s=12), then COLLECT
omniseek_search(query, sources=[walled...], staleness="cache_only"); use the SAME limit both times
(the cache key includes it; a different limit silently misses). _meta.empty = sources not yet warm.
FIRE-THEN-COLLECT IS NOT JUST FOR WALLED SOURCES: it is the BEST way to run an ORDINARY broad search, and it is both faster AND more complete than waiting. A plain broad call blocks ~16s for ~223 docs. Instead FIRE omniseek_search(query, wait_s=3) -> first results in ~3s, then COLLECT omniseek_search(query, staleness="cache_only") ~20s later -> ~296 docs. Measured over 3 quiesced reps (2026-07-25): 5x faster to first result AND ~33% MORE docs than the blocking call. It wins on both axes because sources the deadline would have cut keep running detached and warm the cache with no deadline over them, so the collect reads MORE than the 16s window could ever hold. The cache plateaus by ~+20s (no gain at +35s), so collecting later buys nothing. Same limit both calls. vs the open web: searches only OmniSeek's curated sources; pair with WebSearch for open-web breadth (orthogonal, often use BOTH).
PER-DOC METADATA is LEAN by default: internal ranking/recall telemetry (recall_rrf / freshness_class /
relevance_hook / merge_basis / ...) is omitted (~25% of a ranked doc); the SIGNAL stays (_rank, also_in,
seen_before / first_seen_at, source-native signals). debug=True keeps the full telemetry (/eye-fix).
Returns (default): {"query", "count", "documents": [...], "_meta": {..., excluded_relevant, "deduped": {in, out}}, routing_hint? (TOP-LEVEL: the strongest excluded vertical/walled matches for THIS query, overlap-ranked, each with its param_hint — name one for its authoritative coverage; present only on a broad sweep with a strong match)}. (raw one-source drill): {"source", "query", "count", "documents": [...], "_meta": {"diagnostic": {...}} # only when empty/errored}. (raw buckets): {"query", "results": {source: [...]}, "total_count", "_meta": {searched, empty, timed_out, errored, excluded_count, excluded_relevant, truncated, progressive:{fast,slow,timed_out}, ...}}. An unknown staleness value is treated as cached_ok and a "note" is added to the return.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| full | No | ||
| debug | No | ||
| limit | No | ||
| query | Yes | ||
| wait_s | No | ||
| sources | No | ||
| semantic | No | ||
| staleness | No | cached_ok |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It thoroughly explains deduplication, ranking signals, cache semantics, staleness modes, deadline drops of slow sources, self-warming of cold walled sources, diagnostic payloads on empty/errored drills, and the side-effect-free cache_only pickup. It even covers edge cases like unknown staleness values and the cache key depending on limit, which is exactly the kind of behavioral nuance an agent needs.
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 long, but it earns most of its length by covering three distinct call shapes, routing rules, and return variants. It is front-loaded with the core purpose and uses bolded headers and bullets to create navigable structure. Some measured-performance detail (e.g., ~16s, ~223 docs, +33% counts) is more than strictly necessary, which keeps it from a perfect conciseness score.
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 no output schema and no annotations, the description is remarkably complete. It documents the full return shape for the default ranked result, the raw one-source drill, and raw buckets, including _meta fields like excluded_relevant, deduped, timed_out, and diagnostic. It also covers the fire-then-collect workflow, staleness edge behavior, and relationship to sibling tools.
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 every parameter must be explained in the prose. The description covers all nine parameters: query, raw, raw's interaction with sources, limit per source and in cache keys, wait_s as patience budget, staleness values and their semantics, semantic toggle behavior, full for whole content, and debug for telemetry. This fully compensates for the absent 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?
Opens with a clear verb and resource: 'Search the curated sources. The default for best/latest on X.' It then distinguishes three explicit shapes (dispatch, raw one-source drill, raw buckets), so an agent can tell exactly what the tool does and how the core action branches. It also differentiates itself from siblings by naming omniseek_read for drilling into a chosen doc and omniseek_sources for the source 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?
Provides explicit routing: use raw=True with exactly one source for walled/CDP/slow sources, use broad buckets for many sources, and drop raw for the ranked list. It also says when NOT to infer absence of results ('a broad search that comes back without them is NOT evidence they have nothing'), explains fire-then-collect as the preferred pattern, and contrasts with WebSearch for open-web breadth. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you want to MONITOR a query over time and be told only what's NEW — standing queries with novelty detection. ONE verb; action picks what to do.
The agent decides WHAT to monitor (judgment); the sensor diffs mechanically (a (source, source_id) fingerprint diff against baseline). Each action's REQUIRED args:
• action="create" (query; optional sources, schedule, notify) -> register a standing query that detects NEW results over time. Sensors run on their schedule automatically in the live service (hourly | daily | weekly; unknown = daily); use action="run" to trigger one manually. Returns the created sensor with its id. notify=True means the scheduler alerts when a scheduled run finds new results; optional notify_if=[keywords] narrows that alert to ONLY new results whose title/content match (notify_if_match="any" default, or "all"), so a broad standing query alerts on the sliver you care about instead of every new item. Optional detect_absence=True ALSO alerts when a tracked STABLE-source item DISAPPEARS (e.g. a page_watch policy page that goes dark / 404s); scoped to stable sources so a churny query sensor is unaffected. • action="list" -> all registered sensors with last-run stats {id, query, sources, schedule, last_run_at, last_new_count, total_runs, baseline_size}. • action="delete" (sensor_id) -> delete a sensor by id. Returns {deleted: true/false}. • action="run" (sensor_id) -> manually trigger one sensor NOW (the manual path beside the automatic scheduler): runs its query, diffs against baseline, updates state, returns a summary with new_count + new_titles. Tests a sensor on demand without waiting for its schedule.
Unknown action, or a missing required arg, returns {"error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| action | Yes | ||
| notify | No | ||
| sources | No | ||
| schedule | No | daily | |
| notify_if | No | ||
| sensor_id | No | ||
| detect_absence | No | ||
| notify_if_match | No | any |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on full behavioral disclosure. It describes automatic scheduling with defaults (hourly | daily | weekly; unknown = daily), manual run behavior, diff against baseline, notification narrowing, absence detection, deletion semantics, and error returns for unknown actions or missing required args.
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?
Despite being long, the text is tightly organized with a front-loaded purpose statement, a clear 'ONE verb' framing, and bullet-per-action structure. Every sentence adds operational detail needed to invoke the tool correctly, so the length is justified.
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 multi-action monitor tool with no output schema, no annotations, and a bare input schema, the description is complete: it covers all actions, required arguments, optional arguments, defaults, return shapes, and error behavior. An agent can determine how to create, list, delete, run, and configure notifications without external information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is solely responsible for explaining the 9 parameters. It does so action by action: required args for create, list, delete, and run, plus optional behaviors for sources, schedule, notify, notify_if, notify_if_match, and detect_absence, and sensor_id usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb-resource pairing: MONITOR a query over time and be told only what's NEW, i.e. standing queries with novelty detection. It also explains that `action` selects the sub-operation, making the tool's role distinct from one-off search or read siblings.
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 explicitly states when to use the tool (when you want to monitor over time and see novelty), and it details each action's use case, including manual triggering vs automatic scheduling. It does not explicitly name alternatives or say when not to use it, so it stops one step short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sources — call this to ROUTE before searching.
BOUNDED ORIENT: a bare (no-arg) call does NOT dump every source's facets. It returns the routing
VOCABULARY (available_domains / available_regions with counts) + the capabilities verb index +
source_names (the bare inventory) + counts, so the orient payload stays small no matter how far
the roster grows (brain_orient's lesson). The per-source FACETS (kind / domains / regions / modes,
needs_credentials, explicit_only, stability, health, ...) plus the prose description arrive when
you NARROW or ask verbose — reach for them on demand:
• domain="jobs" / "papers" / … → only sources whose domains facet contains it, WITH their
full descriptions. domain= is the most RELIABLE router; the no-arg call returns
available_domains (the full closed vocabulary + counts) so you can pick a valid token, and a
near-miss (e.g. "careers") returns did_you_mean instead of a silent empty.
• query="singapore visa" → TOKEN-OVERLAP over name + description + domains + regions +
cross-lingual keywords, ranked best-first (multi-word- and English↔中文-safe), WITH descriptions.
• region="sg" / "ca" / "cn" → only sources whose regions facet contains it (the no-arg call
returns available_regions; a near-miss returns did_you_mean). Region narrowing matters
when the deployment's source pack is geographic.
• verbose=True → the full unfiltered list, WITH every description.
check_health=True does a fresh LIVE probe of every source (slow) AND returns a system block:
the recall-index health (indexed_docs / embedder_available / vec_embed_failures / last_write_age_s)
plus the observation-journal durability head, materialization cursor, pending count, and failures.
and the openalex_usage attribution (which component spent the shared daily budget + remaining).
The no-arg (orient) call also returns capabilities: the non-search VERB index (field_skeleton,
coauthors, transcribe, …) so you discover the whole toolkit here, not only after loading a tool.
Returns: {"count": N, "backend_count": M, "backend_breakdown": {...}, and EITHER
a BARE ORIENT: "source_names": [...] + "note" + available_domains + available_regions + capabilities; OR
a NARROWED (domain/region/query) or verbose call: "sources": [{name, backend, (description when narrowed/verbose), needs_credentials, explicit_only, explicit_only_reason? (present only when excluded; the full catalog of why-strings search's _meta.excluded_count no longer re-ships), param_hint? (the structured query a VERTICAL source wants — a stock code / ticker / author name — present only when the source declares one, so a named call is filled right the first try), stability, access_tier, health, health_as_of, kind?, domains?, regions?, modes?, (healthy, status if check_health)}]. (did_you_mean on a domain/region near-miss; system:{recall, openalex_usage, jobs:[{name, schedule, enabled, last_run, next_run, budget_s, desc}, ...]} when check_health — the background-job fleet.)}
count is the RAW source count; it over-states coverage when many logical sources sit on ONE
upstream. backend_count is the distinct UPSTREAMS (the honest figure) and backend_breakdown
names every upstream backing >1 source, e.g. {"openalex": 42} (40+ affiliation slices of one
corpus + one API budget + one breaker = one backend, not 40 of coverage).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| domain | No | ||
| region | No | ||
| verbose | No | ||
| check_health | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations provided, the description carries the full burden of behavioral disclosure — and it is exceptionally thorough. It reveals that a bare call does NOT dump every facet (bounded orient), that facets arrive on demand, that near-misses return did_you_mean rather than silent empties, that check_health does a slow LIVE probe, and that count over-states coverage while backend_count is the honest figure. These are exactly the non-obvious traits an agent needs.
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 long, but justifiably so for a tool with zero annotations, zero schema descriptions, and no output schema — it must carry the entire contract. It is well-structured and front-loaded: purpose first, then orient behavior, then each narrowing mode, then the return contract. A few phrases are flowery ('brain_orient's lesson', 'the full catalog of why-strings...') and could be trimmed, but nearly every sentence carries unique, non-redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 optional parameters, two distinct return shapes, no output schema, no annotations), the description is remarkably complete. It covers all invocation modes, the full return contract for both bare and narrowed calls, edge cases (did_you_mean, explicit_only_reason presence), performance caveats (check_health slow), capability discovery, and honest counting semantics. Nothing an agent needs to call this tool correctly is missing.
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 fully compensate — and it does. Every one of the 5 parameters (query, domain, region, verbose, check_health) gets rich semantics: domain filters with full descriptions and closed vocabulary, query does token-overlap with cross-lingual support, region filters with did_you_mean, verbose returns the full unfiltered list, and check_health has documented speed costs and a system block. This far exceeds the bare schema titles.
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 opens with a specific verb and resource: 'List all sources — call this to ROUTE before searching.' This states the tool's function precisely and positions it distinctly from the 16 sibling tools as the pre-search discovery/routing tool, not a search or graph tool. The distinction is reinforced throughout with the orient vs. narrowed vs. verbose call modes.
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 explicit when-to-use context: 'call this to ROUTE before searching' and explains each invocation mode (no-arg orient, domain= as 'the most RELIABLE router', query=, region=, verbose, check_health) with concrete guidance. However, it never explicitly names sibling alternatives or states when NOT to use this tool (e.g., 'use omniseek_search when you want actual search results'), so the exclusion is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use WHEN you've concluded a DIRECTED, decision-relevant relation OmniSeek does NOT already store mechanically (X acquired_by Y, paper P refutes claim Q, path R requires gate S) and want the graph to carry it forward — record / list / retract typed relation statements (the general sibling of omniseek_ruling; identity types belong to omniseek_ruling).
OmniSeek never MAKES a statement; it STORES yours as declarative state and PROJECTS it at read time
(the rulings / sensors.json precedent: judgment persisted as config OmniSeek applies mechanically).
A statement is a DIRECTED, typed relation between two graph node ids: "openai --acquired_by-->
someone", "paper X --refutes--> claim Y". It surfaces in omniseek_graph's neighborhood / between / since
under working / exploratory (never conservative — the pure mechanical world) AND, since
the write-side read-back, AMBIENT on any future omniseek_search hit of an endpoint (the
metadata.graph.judgments stamp): recording is NOT write-only — your judgment returns to you when
you next touch the node. The directed triple (src, dst, type) is the KEY, so re-creating it REPLACES
the prior note; direction is YOUR assertion, never normalized.
WHAT EARNS A STATEMENT (the value gate — all three must hold, else it is noise that BURIES the edges carrying a real decision; the graph's value is inverse to its noise density):
NON-MECHANICAL — a relation OmniSeek does NOT already store as a fact. cites / authored / affiliated / coauthored / published_in / about and bare bibliometric counts are the mechanical M/A world; re-asserting them here pollutes the judgment channel, which is for what an API cannot read off: YOUR read.
DECISION-RELEVANT — resurfacing it would change a future call (a positioning, a gate, a disqualifier, a fit verdict, a trajectory read). A true-but-inert edge (both-about-RAG, everyone-at-lab-X-affiliated-with-X) is noise.
AS-OF-STAMPED IF A SNAPSHOT — a point-in-time relation (leads / rising / froze_hiring) drifts while its endpoints stay; put the as-of date in the note, or route it to a sensor, so a future reader never mistakes a stale snapshot for the present.
type is FREE agent vocabulary (mechanically slugged: lowercase, spaces -> underscores,
[a-z0-9_] only, <= 40 chars; views never branch on it). An OPEN family, NOT a menu — coin your
own; some exemplars across domains:
• positioning: attacks_premise_of / near_miss_of / validates_premise_of / does_not_flatten /
anchors / introduces (map a competitive / thesis landscape around a claim node).
• provenance / motive: sourced_from_motivated_party / covers (a source's motive; a walled or
cross-lingual source covering what another missed).
• DECISION-space (the non-academic half, easiest to forget): requires / blocked_by / gated_on (a
blocking precondition), disqualified_by / ruled_out_because (an option-eliminator), good_fit_for
/ misaligned_with / froze_hiring / rising (fit + trajectory), reached ... via (a PATH-SAMPLE: how
someone actually reached an outcome).
Two types are REFUSED with a pointer to omniseek_ruling: same_as / not_same_as — identity is a
pair-keyed, symmetric judgment the collapse machinery consumes, kept to omniseek_ruling's one channel.
MEMORY-vs-GRAPH boundary: prose understanding (a lesson, a conclusion, context, confidence, scope) is
the ATOM — it lives in YOUR own notes / memory, or in this statement's note. The graph statement
is a POINTER, minted only when there is a specific PAIR of wall-addressable nodes whose FUTURE
retrieval must carry the judgment; its note / doc point BACK at the prose rather than
restating it. Default to prose; the edge is an opt-in index. (Everything is both a thought and an
edge; the test is whether two NAMED nodes must carry it forward.)
Endpoints may be ANY node id, even ones no tap minted (claim:..., org:...,
inst:label:openai): a statement may pre-date the wall. Such HAND-MINTED ids FRAGMENT across
sessions (claim:c3_wedge vs claim:c3_exact_wedge silently orphans the edge), so REUSE an
existing id: a create echoes similar_anchors (existing near-match hand-minted ids) so you reuse
one instead of minting a near-duplicate; keep a stable slug for your durable anchors.
action picks what to do:
• action="create" (src, dst, type, note; optional doc) -> record. note is the REQUIRED reasoning;
doc the optional provenance node id (a doc:{source}:{sid} or a note id, strongly encouraged).
Returns {created, statement, replaced, similar_anchors?}. A bad type / empty endpoint / empty note /
a refused identity type -> {"error": ...}.
• action="list" (optional about=node id, optional type) -> {statements, count}, filtered to
statements touching about and/or of type. Capped at 200 with a capped flag.
• action="delete" (src, dst, type) -> {deleted: true/false}.
Like omniseek_ruling this is a SEPARATE tool from omniseek_graph (omniseek_graph stays read-only, hence batchable in omniseek_gather). Unknown action -> {"error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | ||
| dst | No | ||
| src | No | ||
| note | No | ||
| type | No | ||
| about | No | ||
| action | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and meets it: it explains that OmniSeek stores user judgment and projects it at read time, that the directed triple is the key and re-creating replaces the prior note, that type values are slugged, and that unknown actions and refused identity types return errors. It also discloses unusual behavior like read-side ambience on future search hits and hand-minted id fragmentation.
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 long but front-loaded with purpose and usage, and the sectioned structure (value gate, type family, memory boundary, actions) makes it navigable. Some passages are philosophically elaborate and could be tightened, but most sentences earn their place given the tool's complexity and the absence of schema and annotations.
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 seven parameters, no annotations, and no output schema, the description is unusually complete: it includes action-specific return shapes, error cases, the 200-item list cap, replacement semantics, refusal routing to omniseek_ruling, and the read-side projection effect. An agent has enough to call the tool correctly and know what to expect back.
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 compensate, and it does comprehensively. It explains action=create/list/delete with required and optional parameters, note/doc roles, src/dst as any node id, type vocabulary and constraints, about/type filtering for list, and the similar_anchors result. Every parameter in the schema maps to meaningful semantic guidance.
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 names a specific verb family ('record / list / retract typed relation statements') and a specific resource (directed typed relations between graph node ids). It explicitly frames itself as 'the general sibling of omniseek_ruling' and notes that identity types belong to omniseek_ruling, so an agent can distinguish it from the closest sibling without opening the schema.
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 opening 'Use WHEN...' states the exact triggering condition. It gives exclusion guidance — mechanical facts belong to the M/A world, identity judgments belong to omniseek_ruling, prose belongs in notes/memory, and the tool is separate from read-only omniseek_graph. It also says 'Default to prose; the edge is an opt-in index,' making the when-not path explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe the SPOKEN content of a video / podcast / audio URL via local SenseVoice ASR (free, keyless, private, cached forever; chosen over Whisper after a real-audio benchmark — Whisper hallucinates on Chinese podcast intros). For the 干货-in-audio case where the substance is in the audio, not any text: bilibili videos (论文精读 / 方法论 / 读博 / 求职 talks), 小宇宙 podcasts, or any direct audio-file URL. (youtube already returns its captions via omniseek_read — no ASR needed; use that instead.)
THE LONG-EPISODE PATTERN: do NOT transcribe a 2-3h episode whole (30k+ chars nobody reads).
Pull the chapter timestamps from the episode's shownotes (小宇宙 episode pages list them; use
omniseek_search(query, sources=["xiaoyuzhou"], raw=True, full=True) / omniseek_read first), judge WHICH chapter matters, then transcribe just
that slice: start="1:02:30", duration="12:00". Accepts seconds ("3750") or MM:SS / HH:MM:SS.
Slices are also fast to start — on direct/enclosure audio only the slice region is downloaded.
The flat transcript covers [start, start+duration] of the source audio. Pass segments=True to
ALSO get a per-VAD-segment segments: [{start,end,text}] list (seconds) so a no-shownote episode
becomes navigable / time-citable (the flat transcript is unchanged; segments costs an extra VAD +
a batched re-transcribe pass, so request it only when you need the offsets).
Whole-item transcription remains right for short/dense items (a 10-min talk, a keynote clip); it is SLOW on first call for a long item, then cached forever. Reach for it deliberately on ONE item you've judged worth it, never as part of a broad sweep.
language: "" auto-detects; set "zh" / "en" to skip detection and sharpen accuracy when you already know the language.
diarize=True answers WHO said what (interviews / 对谈 / multi-host podcasts): segments become
[{start,end,text,speaker}] with per-turn speaker labels and speakers gives the distinct count.
It routes through a Chinese-focused diarization pipeline (Paraformer-zh + cam++ speaker clustering),
a SEPARATE and heavier pass than the flat SenseVoice path, so request it only when the speaker turns
matter, and expect zh accuracy (English audio is not its target). Cannot combine with plain segments
(diarize supersedes it). speaker values are cam++'s cluster indices (0,1,2,...).
speakers=N pins the diarization to N speakers (the KNOWN head-count: a 1-on-1 interview = 2, a solo talk = 1, a 3-host panel = 3). PASS IT whenever you know the count: cam++'s automatic estimate is unstable on short / noisy slices and will over- or under-split, so pinning N is what makes the turns track reality. Leave it 0 (auto) only when the count is genuinely unknown. Ignored unless diarize=True.
Returns: {url, transcript, chars, audio_seconds, asr_seconds, source, title, cached, start_seconds?, duration_seconds?, segments?, speakers?} — or {url, error, transcript:""} if no audio resolved.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| start | No | ||
| diarize | No | ||
| duration | No | ||
| language | No | ||
| segments | No | ||
| speakers | 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 — and it delivers comprehensively. It discloses the tool's safety/private profile (free, keyless, private, cached forever), performance traits (SLOW first call on long items, fast slice startup with region-only download), cost semantics (segments adds VAD + re-transcribe pass; diarize is a SEPARATE heavier pass), accuracy limitations (Chinese-focused diarization, English not its target), the Whisper hallucination rationale, and the error return shape. Contradicts nothing.
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 long but exceptionally dense — nearly every sentence carries a distinct fact, constraint, or heuristic, and it is front-loaded with the core purpose. It is well-structured with clear section headers (THE LONG-EPISODE PATTERN, return format). Some phrasing could be tightened ('nobody reads', the Whisper benchmark backstory), but the length is largely proportional to the tool's complexity: 7 params, zero schema descriptions, and intricate parameter interactions.
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 context signals — zero annotations, zero schema descriptions, no output schema, 7 parameters with complex interactions — this description is complete. It covers the full return shape (success and error variants), all parameter semantics, performance expectations, known limitations (diarize zh-accuracy), and strategic heuristics (pin speakers=N when known, transcribe only judged slices, never broad sweeps). An agent has everything needed to select and invoke this tool correctly.
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 is the only documentation — and it fully compensates. It explains all 7 parameters: url (source type), language ('' auto-detect, 'zh'/'en' skip detection), start/duration (seconds or MM:SS/HH:MM:SS, with concrete examples '1:02:30' and '12:00'), segments (per-VAD list, extra cost), diarize (speaker labels, cannot combine with plain segments), and speakers (pinning semantics, ignored unless diarize=True). Nothing is left undocumented.
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 opening sentence states a specific verb+resource+method: 'Transcribe the SPOKEN content of a video / podcast / audio URL via local SenseVoice ASR.' It distinguishes itself from siblings by explicitly naming the YouTube case ('youtube already returns its captions via omniseek_read — no ASR needed'), so the agent can tell it apart from omniseek_read and omniseek_search without opening schemas.
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?
Explicit when-to-use guidance is given: the 干货-in-audio case with concrete examples (bilibili 论文精读/方法论/读博/求职 talks, 小宇宙 podcasts, direct audio URLs). Explicit when-not-to-use is also given (YouTube → omniseek_read instead), plus a detailed long-episode pattern that routes through omniseek_search/omniseek_read for shownotes first and instructs never to transcribe a 2-3h episode whole. This is the gold standard for usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SEE with your own vision, IN-BAND — document figures, loose image URLs, or video frames. ONE verb; kind="auto" picks the branch (or force it with kind=document|images|video).
ROUTING (kind="auto"): a document path/extension (.pdf/.pptx/.docx/.xlsx/…, as in omniseek_read) → DOCUMENT figures; a video URL (youtube/bilibili/douyin host or a .mp4/.webm/.mov suffix) → VIDEO frames; otherwise → loose IMAGE URLs (target may be a comma-separated URL list). The images come back as image content you can look at directly (no download/scp dance); OmniSeek only renders the pixels, what they MEAN is yours to read.
WHICH PARAMS BELONG TO WHICH KIND:
• document: sections (comma-separated slide/page numbers to pull, "" = all), names (comma-separated
exact image names from the omniseek_read outline media[].name), max_images (full-res cap; a wider
selection falls back to a contact sheet). THE TWO-STEP: first omniseek_read to get the outline
(which slides/pages hold images), then call this — with NO sections/names you get a CONTACT SHEET
(every image a labeled thumbnail tiled into one montage; triage ~30 for the cost of one), then
pull the few that matter full-res by sections="8,15" or names="s08_02_image.png". Covers
pptx / pdf / docx (the image-bearing formats); text formats return a note.
render_pages="8,15" is the COMPLEMENT (PDF): it renders those WHOLE pages to images, the channel
for a page whose substance is VECTOR figures / dense tables / a layout carrying NO embedded raster
(where sections/names find nothing). This is how you READ a visual page you cannot trust as parsed
text: route to the doc, omniseek_read for the page you want, then render + see it with your own vision.
• images: target = image URLs comma/space/newline separated (paste a walled post's media[] list —
xiaohongshu / zhihu note images, where the 干货 often lives). max_images caps per call.
• video: start / duration (optional slice: "8:30", "90", "1:02:30"; default the whole video, capped
at 30 min), n (frames to sample, default 12, max 24). The VISUAL half of omniseek_transcribe: its
on-screen slides / diagrams / code / charts as ONE labeled contact sheet (a timestamp under each
frame). Pair with omniseek_transcribe on the same slice for BOTH halves. (bilibili frames ride the
same activated playurl session as bilibili audio — the ASR path's visual sibling.)
Returns image content blocks: document = [contact-sheet montage + legend] or [manifest + one block per figure]; images = [manifest + one block per URL that loaded]; video = [contact-sheet + timestamp legend]. Or an error / honest "nothing to show" note.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| kind | No | auto | |
| names | No | ||
| start | No | ||
| target | Yes | ||
| duration | No | ||
| sections | No | ||
| max_images | No | ||
| render_pages | No | ||
| contact_sheet | 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 disclosing behavior. It does so comprehensively: return block shapes per kind, contact sheet fallback behavior, max_images caps, 30-minute video cap, text-format note, bilibili session sharing, and an honest 'nothing to show' error note. No contradictions exist.
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 long but every section earns its place given three modes and ten parameters. It is front-loaded with a one-line summary, then routing, then per-kind parameter details, then return format. Headers and bullet-like lines make it easy to scan despite length.
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 complex multi-mode tool with no output schema and no annotations, the description is remarkably complete. It covers all three input kinds, per-kind parameter behavior, return formats, fallbacks, limits, error handling, and relationships to sibling tools like omniseek_read and omniseek_transcribe. The only minor omission is contact_sheet's explicit role as a boolean flag.
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 compensates by explaining target, kind, sections, names, max_images, render_pages, start/duration, and n in context. However, the contact_sheet boolean parameter is never explicitly defined as a parameter; it is only implied through phrases like 'you get a CONTACT SHEET.' This is a minor but clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear one-line statement of what the tool does: 'SEE with your own vision, IN-BAND — document figures, loose image URLs, or video frames.' It then breaks out three distinct modes (document, images, video) and explicitly contrasts with related tools like omniseek_read and omniseek_transcribe, so an agent can distinguish it from siblings.
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?
Extremely explicit routing rules are given for kind='auto' with file extensions and host names. It describes when to use the two-step process (omniseek_read first), when to use render_pages instead of sections/names, and when to pair with omniseek_transcribe for video. This is far beyond 'use when you need to view visual content.'
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. Dates show when Glama detected each change.
v0.2.0omniseek_coauthorsomniseek_curator_actomniseek_curator_viewomniseek_field_skeletonomniseek_gatheromniseek_graphomniseek_institution_cohortomniseek_paper_enrichomniseek_paper_recommendomniseek_readomniseek_resolve_identityomniseek_rulingomniseek_searchomniseek_sensoromniseek_sourcesomniseek_statementomniseek_transcribeomniseek_viewMost tools have clearly separated domains—search vs read vs transcribe vs view, and coauthors vs field_skeleton vs institution_cohort are distinct workflows. The main ambiguity is that omniseek_graph's similar view partly overlaps omniseek_paper_recommend, and graph views can conceptually subsume some coauthor/citation queries, but the descriptions draw these boundaries clearly enough for correct selection.
All tools share an omniseek_ snake_case prefix, which gives the set a recognizable family identity. However, the naming pattern behind the prefix is mixed: verbs (read, search, view, gather), nouns (sources, graph, sensor, ruling), verb_noun (resolve_identity), and noun_verb (paper_recommend, curator_act) all coexist, so there is no single predictable convention.
18 tools is slightly beyond the typical well-scoped 3–15 range, but the breadth is justified by the server's multiple missions: search, document/audio/visual reading, paper and author analytics, graph memory, monitoring, and source curation. None of the tools feel redundant enough to cut, though the set is undeniably heavy.
The tool surface covers the full research loop: discover and route sources, search, drill/read, transcribe/view, enrich papers, map citation/coauthor/institution relationships, persist rulings and statements into the graph, monitor queries via sensors, and curate sources. Write paths exist for judgments and sensor lifecycle, and read-only graph views are explicitly paired with write tools, leaving no obvious dead end.
An MCP memory server. One memory your agents share — across models, devices and apps.
Search engine for AI agents to find MCP servers, A2A agents, and skills on their own.
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Shared memory for all your AI agents, your whole team and every MCP client — save, search, recall.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Battam1111/omniseek'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
