omniseek

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 delivers extensively. It explains that the tool reconstructs from PRIOR work, merges '+'-joined ids for split author profiles, reports ambiguity and alternatives, and includes a 'degraded' flag meaning the graph is missing data and should be retried. It also clarifies what is mechanical fact versus the agent's judgment.

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 dense, front-loaded with purpose and usage modes before detailing disambiguation and output structure. Every sentence earns its place given the 0% schema coverage, no output schema, and the tool's complex graph semantics. The use of bullets and a return-shape block keeps the length navigable.

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 graph-returning tool with no output schema and minimal input schema, the description is remarkably complete: input formats, disambiguation mechanisms, N=1 vs N>1 behavior, bridge collaborators, cooc sub-communities, output fields, failure semantics, retry guidance, and drill-down instruction. An agent has everything needed to invoke and interpret 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%, so the description fully compensates for all four parameters. It defines 'authors' as names, ids, or '+'-joined ids from omniseek_resolve_identity; 'hints'/'papers' as parallel per-author disambiguation lists; and 'source' with concrete guidance like source='s2' for juniors. This adds substantial meaning beyond the bare 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, actionable purpose: '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.' It clearly distinguishes the tool from WebSearch and sibling omniseek_field_skeleton, and positions it as 'one LAYER, not the whole graph.' An agent can immediately tell what resource and relationship this tool operates on.

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 guidance: co-authorship exploration, advisor discovery, and author-group connectivity. It also states explicitly what NOT to use it for: 'For the citation/influence layer use omniseek_field_skeleton; for the others, assemble from the dossier recipe.' It even distinguishes N=1 vs N>1 cases and references omniseek_resolve_identity for ID inputs.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so extensively. It discloses safety gates ('every safety gate lives in the impl, unchanged'), mechanical refusals ('MECHANICALLY REFUSES an admit on hard red-line / incomplete evidence'), reversibility for live actions ('REVERSIBLE overlay row'), and side-effect boundaries ('does NOT apply', 'does NOT admit, only surfaces'). It also clarifies that stage_commit only prepares text and does not apply it, and that wall_probe only surfaces content and never admits. These details go well beyond a simple action description and are highly valuable for an agent.

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 well-structured with each verb on its own line, making it scannable. It front-loads the purpose and then breaks down actions logically. While it is verbose, the complexity of 18 parameters and multiple verbs justifies the length. There is some redundancy (e.g., repeating the fully-qualified name), but overall it is efficient for the information density required.

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, the description is nearly complete. It covers all verbs, required parameters, safety gates, and side effects. It also clarifies the fully-qualified MCP name. The main gap is that it does not explicitly describe the return value for successful calls (though it mentions 'packet' for probe and wall_probe, and an error dict for unknown verbs). Since there is no output schema, this would be helpful but is not critical for correct invocation. Overall, it provides enough context for an agent to use 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%, so the description must compensate, and it does thoroughly. For each verb, it lists the required parameters (e.g., submit requires name, urls, mode, domain, family; optional kind, regions, rationale, draft) and explains their semantics (e.g., mode enum values, draft as a working artifact, baseline_ref required for admit). It also explains how parameters affect behavior (e.g., confirm for retire_live toggles preview vs. write). This gives an agent clear meaning for all 18 parameters, even though they are not individually documented 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 clear, specific statement: 'Use WHEN acting on the source-curation protocol — WRITE a source-lifecycle action'. It names the resource (source-curation protocol) and the action class (write lifecycle actions), and lists all specific verbs (submit, probe, decide, etc.), making it immediately distinguishable from sibling tools like omniseek_curator_view or omniseek_sources, which are read-oriented. The distinction is further reinforced by explicitly saying 'WRITE'.

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 states when to use the tool ('WHEN acting on the source-curation protocol') and provides per-verb guidance on when each action is appropriate. For example, it explains that wall_probe is for client-rendered shells and that apply_live is only for rss-safe subclass, while stage_commit is for non-auto families. It also notes that non-auto families are refused and directs to stage_commit as the alternative, and even clarifies that there is no 'omniseek-eye' server to avoid confusion. This gives an agent explicit routing among verbs and implies when not to use the tool (for reads).

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

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 thoroughly: it states 'Never mutates,' describes what each view returns, explains the error behavior for unknown 'what', and specifies the exact structure of the audit dossier (facts, ratios, safety flags, no verdict key). This is transparent about side effects and outputs.

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 well-organized with bold labels and bullet points, front-loading the key usage directive. Every sentence adds necessary detail, though some redundancy exists (e.g., repeating the server name). It is not excessively verbose but is longer than minimal; still, the structure makes it scannable.

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 (three views, multiple states, integration with another tool), the description is complete: it covers the entry point, output formats, error handling, and the follow-up action via omniseek_curator_act. Without an output schema, it explains what to expect for each view, leaving no critical gap for an agent to call it 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 schema provides no parameter descriptions (0% coverage), so the description must define all parameters. It does so comprehensively: 'what' is explained with its three valid values and their meaning, 'state' is listed with its filter options for the queue view, and 'candidate_id' is tied to the packet view. Unknown values are also handled.

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 WHEN running the source-curation protocol') and names the specific resource (curator state) with three distinct views (queue, packet, audit). It also differentiates from the sibling action tool omniseek_curator_act, making the purpose unmistakable.

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 (during curation protocol), and for each view it explains the scenario (e.g., 'list awaiting_verdict' for queue, 'last-built evidence packet' for packet, 'render KEEP / WATCH / PRUNE' via the act tool for audit). It also notes that unknown values return an error listing valid options, guiding correct use.

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

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 does so thoroughly. It discloses that there is no frontier flag, no polarity judgment, no S2 polarity field, that contexts may be empty, that results can be partial on deadline_hit, and that OpenAlex may contain poisoned titles — all beyond what structured annotations would supply.

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 and well organized into scannable bullets, with the core purpose stated first. Some repetition exists around the no-judgment/cartographer framing, and a few tuning parameters could be explained in less prose, but most sentences carry real operational guidance.

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, the description enumerates the full return shape, explains edge cases (degraded, partial, deadline_hit), names source tradeoffs, flags data hygiene issues, and points to sibling tools for related needs. There is very little an agent would need to call this correctly that 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 compensate for the 8 undocumented parameters. It adds strong meaning for query, seeds, source, and deadline_s, but leaves fresh, n_seeds, max_nodes, and citers_per_seed unexplained, so the agent must infer their purpose from defaults and names.

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

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

The description opens with a specific verb and resource: Map a research field's shape, and immediately defines the deliverable as the field's citation neighborhood. It also distinguishes this from judgment-heavy tools by calling itself a thin graph primitive with NO judgment, and it names a sibling alternative (omniseek_coauthors) for co-authorship.

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 (need citation neighborhood, foundational vs frontier), when to prefer seeds over query, and when to choose source='s2' over openalex. It even tells the agent to fetch a human-curated survey instead for young/hot fields, which is a clear alternative-routing instruction.

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

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 delivers: independent execution, partial failure isolation, the wait_s timeout semantics, the "warming" status with background cache-warming behavior, and the hint mechanism for signature mismatches. It even discloses the serialization behavior for certain venues.

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 first sentence front-loads the purpose, and the dense follow-up sections (fully-qualified name, calls format, wait_s, return envelope) all earn their place given zero schema coverage and no output schema. Minor redundancy — "read-only" appears twice — and the fully-qualified-name preamble is slightly meta, so it doesn't quite earn a 5.

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 (parallel execution, partial failures, timeout races, cache warming) and the absence of annotations, output schema, and parameter descriptions, this description is remarkably complete. It documents both parameters, the full return envelope ({results, elapsed_s, completed, warming, failed, total}), error-hint behavior, and safety constraints.

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 does fully. The ``calls`` parameter is given an exact shape ([{"tool": "omniseek_search", "args": {"query": "..."}}, ...]) plus constraints (max 10, read-only only), and ``wait_s`` is defined as a patience budget with precise return semantics. This adds far more than the bare schema's "array of objects with additionalProperties."

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?

"Run N independent read-only eye tools IN PARALLEL, returning results in one response" names a specific verb, resource, and execution mode. It distinguishes the tool from its single-purpose siblings (omniseek_search, omniseek_read, etc.) by positioning it as the parallel dispatcher rather than an individual eye tool.

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/when-not guidance: "Calls that depend on a prior call's result belong in a SEPARATE gather," "Read-only tools only," and the max-10 bound. It also clarifies the division of labor ("The agent decides WHAT to call... OmniSeek executes them") and warns about the paced-backend serialization quirk for >2 calls.

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

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

With no annotations present, the description carries the full burden, and it thoroughly discloses behavior: read-only and gather-safe, budget clamping with capped:true, fail-open returning error dicts instead of exceptions, structural exclusion of tier J verdicts, non-destructive identity policy, input caps, and vector-missing errors. It also states that content is never inlined and that derived edges carry no timestamps. This is exemplary transparency.

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 is a polymorphic eight-view API with no schema or annotations to lean on, so most sentences earn their place. It is front-loaded with the core query intent, uses clear bullets and capitalization for structure, and avoids filler. A few concepts are restated for emphasis, but the density is justified by the complexity.

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, no annotations, and only a two-property input schema, the description is remarkably complete: it covers all current views, step-by-step usage for find-to-anchor flows, budget semantics, identity policy behavior, cold-start expectations, failure mode, and the frozen ABI. An agent has everything needed to invoke the tool correctly and interpret its constraints.

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 fully compensate for the bare view/args schema. It does: every view name is documented with its args, types, defaults, and semantic meaning, and the self-describing no-view catalog behavior is specified. The policy values are defined as named method-sets rather than numeric thresholds, and budget params are explained. This is exactly the compensation needed.

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 precise usage statement: "Use WHEN you want HOW two entities connect, or what OmniSeek already knows AROUND a paper / author / entity." It names the tool's resource (accumulated evidence graph with typed edges), identifies it as read-only, and differentiates it from sibling tools like omniseek_ruling and the other eye tools. The one-stable-verb (view, args) design is clearly explained, leaving no ambiguity about what the tool does.

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 guidance for each view, names the entry point (view="find"), and states when alternatives apply: writes go to omniseek_ruling, zooming uses other eye tools, and similar does not feed search recall. It even warns about cold-start expectations so an agent does not misinterpret early stats. This is far beyond minimum viable usage guidance.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: it explains ranking by output at the institution in the field, the all-fields default behavior, year_from recency bias, and the lack of PhD-student verification due to OpenAlex limitations. It also discloses the exact return shape.

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 dense, with the primary use case front-loaded before important caveats and return details. The fully-qualified MCP name warning is useful invocation context, and 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?

Given zero schema parameter descriptions and no output schema, this description is unusually complete: it covers what the tool does, when to use it, how parameters change behavior, what the result is, and its limitations. An agent has enough to invoke it 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 must compensate. It explains institution, concept, and year_from with concrete examples and consequences, though limit is left to inference from its schema default. This is a strong recovery from an otherwise bare 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 clear, specific purpose: retrieving the people-roster of a lab, department, or university, optionally scoped to a field. It explicitly frames this as the "who's at this lab" question and distinguishes it from co-authorship, making the tool's identity unambiguous.

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 explicit when-to-use guidance, explains the field-scoping caveat, and names downstream tools (omniseek_coauthors / omniseek_read) for drilling into the roster. It also warns that the roster is a starting point, not a verified membership list, which sets correct expectations.

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

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

With no annotations, the description fully discloses key behaviors: keyless mechanical operation, no synthesis engine, OA semantics per ID type, retracted=None meaning 'not checked' versus notices=[] meaning clean, citation count sources, backend-unreachable behavior, and a clear result/error return shape. This is highly transparent beyond what structured fields 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 densely informative, front-loaded with the core purpose and organized with labeled bullets for each returned signal. Every sentence carries operational or decision-making value, and the return format is clearly laid out.

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

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

Despite no output schema, the description defines the exact result structure, error cases, edge-case semantics for retraction status, and downstream usage. For a single-parameter enrichment tool with no annotations, this is complete enough for an agent to select and invoke it 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 coverage is 0% and there is only one parameter, but the description thoroughly defines it: pass DOIs and/or arXiv ids, gives concrete examples, maps ID sources to specific fields in sibling tool outputs, and explicitly warns against using an OpenAlex W-id. This fully compensates for the bare 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 use case: retrieving ONE paper's open-access full-text PDF, retraction/integrity status, or citation count. It explicitly contrasts these signals with those provided by omniseek_search and field_skeleton, making the tool's scope and distinction from siblings clear.

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 explicit when-to-use guidance ('Use WHEN you need ONE paper's...'), warns against enriching a whole map, and explains which IDs to pass versus which to avoid (not source_id/W-id). It also names sibling signals that do not cleanly provide this data and tells the agent to feed pdf_url to omniseek_read.

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

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

With no annotations, the description carries the full burden. It explains the underlying mechanism (SPECTER embeddings + co-citation), notes that results are ordered by relevance and that the agent should re-judge, and clarifies it uses existing S2 embeddings. It doesn't explicitly state non-destructive behavior or rate limits, but these are reasonably implied for a recommendation 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 every sentence adds distinct value: purpose, mechanism, input details, output format, alternatives, and even server naming. Information is front-loaded, starting with the core use case, and the flow is logical.

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 there is no output schema, the description fully specifies the return structure and ordering. It also covers alternative tools, input constraints, and the MCP server context, leaving nothing an agent needs to call 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?

The schema provides only names and types (0% coverage). The description compensates richly: it specifies acceptable id formats (arXiv, DOI, S2 ids), explains how to pass multiple seeds, and warns against using OpenAlex source_id, which is a common mistake. The limit parameter is not elaborated but its default and obvious purpose make that a minor omission.

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 ('Use WHEN you have a paper and want more like it') and explicitly contrasts with sibling tools (keyword search and citation graph), making the tool's purpose unambiguous and distinct.

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 criteria, what inputs to pass (seed paper ids), a critical pitfall for OpenAlex IDs (metadata.paper_id vs source_id), and names alternatives (omniseek_search, omniseek_field_skeleton) with the conditions that select them.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure—and it delivers. It reveals the auto-routing logic, the arXiv two-tier behavior, the windowing/truncation mechanism, the error categories (walled vs empty vs blocked), and the image/OCR handling. It even discloses that OCR is mechanical and possibly imperfect. No contradictions with annotations (none present).

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 sentence earns its place given the tool's complexity. It is front-loaded with the core purpose and routing, then organized with clear headers (URL BRANCH, DOCUMENT BRANCH, IMAGE HALF) and bullet-style breakdowns. No redundancy or filler; the density is justified by the need to convey nuanced behavior.

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 with no output schema, so the description must fully specify return values—and it does. For the URL branch it lists the exact fields returned, including the added 'reason' on matched:false. For the document branch it details outline, text, media, and caching. It also covers the file-transfer mechanism (scp) and the two ways to handle images. Nothing an agent needs to call it 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 has 0% description coverage, so the description is the sole source of parameter meaning. It explains target (URL or path), start_char and max_chars (windowing and paging), export_media (document branch only), and ocr (image text extraction). It also clarifies their scoped behavior on each branch. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a clear, specific verb+resource: 'Read text from any URL OR document FILE' and immediately distinguishes itself from siblings (omniseek_search, omniseek_transcribe, omniseek_view). The auto-routing between URL and document branches is explicitly defined, so an agent knows exactly what this tool does and how it differs from alternatives.

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

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

The description provides explicit routing rules (file extension vs. URL), tells when to use WebSearch first, when to use omniseek_view for figures, and how to page through truncated results. It also explains when parameters like export_media and ocr are ignored. This is a textbook example of usage guidance with clear alternatives and exclusions.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses that the tool never silently picks, that hint only re-orders and never filters, that likely_same_person never auto-merges, and that degraded means missing-data rather than a confirmed absence. This is far more than a typical tool description provides.

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 deliberately information-dense; every paragraph adds actionable guidance rather than filler. It is front-loaded with the core purpose and distinct identity, then layers details about parameters, disambiguation, merge tokens, and degraded behavior in a logical order.

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 and no annotations, the description is exceptionally complete. It documents the full return shape, explains ambiguous and degraded response fields, provides retry strategies, and ties the output into the broader coauthors workflow. An agent has everything needed 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%, so the description must compensate, and it does. Every parameter is explained with meaningful semantics: hint's re-order-only behavior, source's three modes and 'auto' logic, paper's role in resolving common-name authors, and name as the required person to resolve.

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

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

The description uses a specific verb ('Resolve') and resource ('a PERSON's name to candidate author ids'), and immediately distinguishes itself from sibling tools: 'OmniSeek's other tools keyword-search PAPERS; this resolves an AUTHOR.' It also frames the tool as the 'shared front door for EVERY relationship layer,' making its role unmistakable.

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

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

It clearly says when to use this tool versus alternatives: paper search is for papers, this is for authors, and the result should feed omniseek_coauthors. It also gives concrete conditional guidance: use hint to re-order, use paper to pin common-name juniors, verify ambiguous candidates, and pass source='s2' or paper= when degraded.

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

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

With no annotations, the description fully carries the behavioral burden and does so impressively. It discloses that OmniSeek never makes rulings but stores them declaratively, that pairs normalize to src < dst, that re-creating a pair replaces the prior verdict, and that git history is the audit trail. It also details per-action behavior and error cases.

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 and front-loaded with the use case and core semantics. The fully-qualified MCP name paragraph and the extended separation rationale add useful context but go slightly beyond what is strictly necessary, keeping this from a 5.

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 5-parameter tool with no output schema and no annotations, the description is complete. It covers all actions, return shapes, replacement semantics, error cases, and the relationship to graph policies, so an agent can invoke the tool correctly without additional documentation.

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 the action values ('create', 'list', 'delete'), verdict values ('same' | 'not_same'), the required operands for each action, the optional note, pair normalization, and error conditions like bad verdicts or empty/identical endpoints.

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 trigger ('Use WHEN two graph nodes ARE (or are NOT) the same person/entity...') and a specific operation ('record / list / retract same_as | not_same rulings'). It clearly names the resource (rulings) and explicitly separates itself from omniseek_graph, so an agent can distinguish it from siblings 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?

It gives an explicit when-to-use condition and explains why this write operation is deliberately not part of omniseek_graph, which is strong routing guidance. It does not explicitly compare against sibling tools like omniseek_resolve_identity, so not a perfect 5, but the trigger and separation rationale are clear.

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

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

With no annotations present, the description carries the full burden and delivers extensively: it discloses dedup/merge behavior, cross-lingual semantic recall, ranking mechanics, caching and self-warming, wait_s as a patience budget, staleness semantics, _meta diagnostics, and the fire-then-collect pattern with performance measurements. It even details what happens on unknown staleness values. This is far beyond typical transparency.

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 exceptionally long but well-structured with headers, bullets, and bolded keywords, and it front-loads the core purpose before diving into details. Nearly every sentence adds operational value, though an agent might benefit from a more digestible summary. It earns its length given the tool's complexity, but it is not concise in an absolute sense.

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 9 parameters, three behavioral shapes, and no output schema, the description leaves almost nothing to guess: it documents each shape's return structure, _meta fields, edge cases (empty/errored drills, unknown staleness), and even includes measured performance comparisons. It is as complete as a tool definition can reasonably be.

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 provides only titles and defaults with 0% description coverage, so the description must explain all 9 parameters, and it does: raw, full, debug, limit, query, wait_s, sources, semantic, and staleness are each given operational meaning (e.g., staleness values, limit's role in cache keys, wait_s as patience budget). It fully compensates for the schema's silence.

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 statement: 'Search the curated sources. The default for

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 exhaustive routing guidance: when to use default vs raw, when to name specific sources (walled/slow ones), when to use fire-then-collect vs blocking, and when to pair with WebSearch for open-web breadth. It explicitly warns against misinterpreting an empty broad result and explains the staleness values' trade-offs. No alternative usage is left to inference.

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

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 handles it well. It discloses that the sensor diffs mechanically via a (source, source_id) fingerprint against baseline, that scheduled runs happen automatically in the live service, that unknown actions or missing required args return an error, and that detect_absence only applies to stable sources. These details go well beyond the bare schema.

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 well-structured with action-specific bullets and front-loaded usage guidance. Nearly every sentence adds operational value. There is minor redundancy — 'standing queries with novelty detection' and 'register a standing query that detects NEW results over time' restate the same idea — and the 'no omniseek-eye server' note is tangential, but the organization makes the density acceptable.

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 9-parameter multi-action tool with no annotations and no output schema, the description is remarkably complete. It covers required arguments per action, defaults, scheduling behavior, return summaries, error handling, and edge cases like absence detection scoping. An agent has enough information to select actions, supply parameters, and anticipate 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 for every parameter. It does: action is enumerated with all four values, query is identified as required for create, sources/schedule/notify are explained, notify_if and notify_if_match semantics are detailed, sensor_id is tied to delete/run, and detect_absence is fully described. All 9 parameters receive meaningful explanation beyond the raw 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 purpose: 'MONITOR a query over time and be told only what's NEW — standing queries with novelty detection.' It clearly identifies the tool as a standing-query sensor rather than a one-shot search, distinguishing it from siblings like omniseek_search and omniseek_sources. The action-based breakdown (create/list/delete/run) further clarifies exactly what the tool does.

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 states when to use the tool: when monitoring a query over time and wanting novelty detection. It also gives action-level guidance, such as using action='run' to trigger a sensor manually and action='create' to register one. It does not explicitly name alternative sibling tools or state when not to use it, but the use-case framing is strong enough for an agent to route correctly.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it excels. It explains that a bare call returns a bounded orient (not all facets), that narrowed calls include descriptions, that check_health performs a slow live probe, and it details the distinction between count and backend_count. It also explains the meaning of kind and explicit_only_reason. All behaviors are explicitly documented.

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 well-structured with bullet points and clear sections (BOUNDED ORIENT, per-source facets, Returns, etc.). It is front-loaded with the primary purpose. However, it is verbose, containing extensive detail that could be trimmed for conciseness. Still, each section serves a purpose, and the structure helps an agent parse it. It earns a 4 rather than 5 due to 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 the tool's complexity (5 parameters, no output schema, no annotations), the description is remarkably complete. It covers all routing scenarios, return structures, and caveats (e.g., count overstates coverage). Nothing an agent needs to correctly call and interpret results is missing. It even explains the 'kind' per source and the param_hint mechanism.

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 has zero descriptions for parameters, so the description must compensate. It does so thoroughly: query= is described as token-overlap over multiple fields, domain= as a facet match with did_you_mean on near-miss, region= similarly, verbose=True as full unfiltered list, and check_health=True as a live probe plus system block. Each parameter's effect and return implications are explained in detail.

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 'List all sources — call this to ROUTE before searching,' clearly stating the tool's purpose as a source router. It distinguishes itself from sibling search tools by positioning it as the pre-search routing step. The phrase 'call this to ROUTE' and the mention of returning available_domains/regions for token selection make the tool's role unambiguous.

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 instructs when to use the tool ('call this to ROUTE before searching') and details each parameter's effect: domain= for facet-based routing, query= for token-overlap search, region= for geographic narrowing, verbose=True for full list, and check_health=True for live probing. It also notes when to use the no-arg call versus narrowed calls, providing clear usage guidance and routing logic.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses replace-on-recreate semantics, non-normalization of direction, ambient projection on search, hand-minted id fragmentation, similar_anchors echo, per-action returns, list cap of 200, and error behavior for bad actions or types. This is far beyond typical disclosure.

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 is genuinely complex and the length is justified by actionable detail. It is well organized with clear section headings and front-loaded intent; minor redundancy around omniseek_ruling and graph separation keeps it from a 5.

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 minimal input schema descriptions, the description supplies everything needed to invoke all three actions correctly: endpoint flexibility, type constraints, refused types, memory-vs-graph boundary, action-specific parameters, return shapes, and failure modes. An agent can call this tool without further clarification.

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 defines what each action needs: create requires src, dst, type, note with optional doc; list takes optional about and type; delete takes src, dst, type. It also explains the meaning of note, doc, type, and about with concrete examples and constraints.

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 precise verb-resource pair: 'record / list / retract typed relation statements' for directed, decision-relevant relations. It also distinguishes itself from omniseek_ruling and omniseek_graph, giving an agent a clear identity for this tool.

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 provides explicit when-to-use guidance via the three-part value gate (non-mechanical, decision-relevant, as-of-stamped) and names alternatives: omniseek_ruling for identity types, prose/memory as default, and omniseek_graph for read-only graph access. This removes ambiguity for selection.

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

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 it delivers: it discloses that the service is free/keyless/private/cached forever, that long-item first calls are SLOW, that slices download only the needed region, that diarize is a separate heavier pass, that segments and diarize are mutually exclusive, and that speaker values are cluster indices. These are exactly the non-obvious behavioral traits an agent needs to set expectations.

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 well-structured with thematic paragraphs, inline code formatting, and front-loaded purpose/alternative information. Each section earns its place by enabling correct invocation, though a few sentences (e.g., the Whisper benchmark rationale) are context rather than necessity. It is slightly verbose but not bloated.

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 7-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers all parameters, provides the full return object shape including optional fields and error case, explains interacting flags, and addresses performance characteristics. An agent can invoke this tool correctly with no further 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 description coverage is 0%, so the description must compensate, and it does comprehensively. It explains the url, start/duration formats (seconds or MM:SS/HH:MM:SS), language auto-detection and the benefit of setting it, segments as an extra VAD pass, diarize as superseding segments, and speakers as a pinning mechanism ignored unless diarize=true. Every parameter is given semantic meaning beyond its name and type.

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: 'Transcribe the SPOKEN content of a video / podcast / audio URL via local SenseVoice ASR'. It also differentiates from the sibling omniseek_read by explicitly stating that YouTube already returns captions via omniseek_read and ASR is not needed, so an agent can immediately tell which tool to use 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?

The description is explicit about when to use the tool: bilibili videos, 小宇宙 podcasts, or direct audio-file URLs, and when not to: YouTube, which should use omniseek_read instead. It also provides a clear long-episode pattern (pull chapter timestamps, transcribe only a slice) and warns against whole-item transcription for long episodes. This is concrete, actionable routing guidance.

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

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

With no annotations, the description fully carries behavioral disclosure. It explains it returns image content blocks, can produce contact sheets or manifests, falls back to honest 'nothing to show' notes, applies caps, and avoids any download/scp step. It even notes the bilibili session dependency for video frames.

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 length is justified by the tool's polymorphic behavior and 10 parameters. It is well-organized with clear headings and per-kind parameter groupings, though some rhetorical flourishes and redundant emphasis could be trimmed 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?

Given the complex branching behavior, 10 parameters, and no output schema, the description is remarkably complete. It covers routing, per-kind parameters, return formats, limits, fallback behavior, the required omniseek_read prerequisite, and relationships 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%, and the description compensates strongly by explaining target, kind, sections, names, max_images, render_pages, start, duration, and n with concrete formats and defaults. However, the contact_sheet boolean is only implied through repeated contact-sheet behavior, not explicitly tied to the parameter.

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

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

The description clearly states a specific verb and resource: 'SEE with your own vision' across document figures, image URLs, and video frames. It also distinguishes itself from siblings like omniseek_read and omniseek_transcribe by positioning itself as the visual counterpart and the two-step outline workflow.

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?

Routing rules are explicit: kind='auto' sends document paths/extensions to document figures, video URLs/suffixes to video frames, and everything else to image URLs. It also gives clear when-to-use guidance for render_pages on vector-heavy pages, and recommends pairing with omniseek_transcribe for both visual and audio halves.

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