omnarai-mcp

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

Annotations only cover readOnlyHint and openWorldHint, but the description goes far beyond: it enumerates the return payload (positions with sources, declared vs. derived:true, raw stance counts, per-lineage counts, unclassified voices counted but not dropped, tensions verbatim, population provenance), asserts no majority/percentage/consensus field exists by construction, and gives a latency bound.

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 differentiator ('never a consensus score') is front-loaded, and the dense enumeration of return fields is efficient rather than padded. There is minor redundancy in restating the no-consensus point twice ('never a consensus score' / 'no majority, percentage, or consensus field by construction').

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?

With no output schema, the description carries the burden of explaining return values and does so comprehensively, including provenance and the counted-not-dropped edge case. Combined with a fully documented single parameter and readOnly annotation, an agent has everything needed 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?

There is a single parameter with 100% schema description coverage that already explains where a canonical OMN-Q-… id comes from (omnarai_orient, the Atlas record, or GET /api/questions). The description adds nothing further about the id, so baseline 3 applies.

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 specific resource and scope: the distribution of attributed positions on one question, explicitly framed as never a consensus score. This clearly separates it from any aggregate/scoring tool, but it does not name a sibling (e.g. omnarai_query, omnarai_divergence) it should be chosen over, so it falls short of a 5.

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?

Usage is implied rather than stated: an agent can infer it should call this when it wants raw stance distribution rather than a summary, and 'deterministic, <1s' signals it is cheap to call. There is no explicit 'use this when / do not use when' clause and no named alternative among the thirteen siblings.

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?

Annotations cover read-only and open-world semantics, and the description adds genuinely new context: a ~2s latency expectation, bounded scope, and an enumeration of returned fields (id, title, ring, excerpt, contributors, evidence label, relevance score) plus the local concept cluster despite there being no output schema. It omits notable behaviors such as the syntheticIdentity cross-voice diversity effect, but exceeds the annotation-covered baseline.

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?

Front-loaded with the latency and scope qualifier, then the return shape, then the filtering advice — three dense sentences with little waste. Minor jargon ('Omnarai topic', '/claims.json') assumes prior context but does not bloat the text.

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?

With no output schema, the description compensates by listing what comes back and the latency profile, and its filtering guidance plus schema coverage rounds out the calling contract. Nothing an agent needs to invoke it correctly appears 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 coverage is 100%, so all five parameters are already documented. The description only adds that layers/exclude/evidence_threshold filter the candidate pool and that this is recommended, without explaining semantics beyond the schema or touching the syntheticIdentity or glyph-prefix behavior.

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 specific verb and resource — a 'bounded context packet on a topic' — and delimits it sharply as 'the retrieval layer only, no deliberation', which implicitly separates it from deliberation-style siblings like omnarai_council. It does not name siblings explicitly, and 'your default orientation' risks overlap with omnarai_orient, so differentiation is strong but not fully disambiguated.

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?

Gives clear usage context: 'Your default orientation on any Omnarai topic' plus a recommendation to apply the layer/evidence filters and a pointer to /claims.json. It stops short of naming when NOT to use it or explicitly naming the alternative tools for deliberation or deeper queries.

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?

Discloses far more than the annotations: the review queue is weekly, content is NOT public until a human admits it, credential-shaped text and exact duplicates are refused, and there is a small per-visitor daily limit. It also explains the return payload, including that the continuance receipt token must be kept private and what it unlocks while pending. This is consistent with readOnlyHint=false and non-idempotent.

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?

Front-loaded with purpose and gated status, and every paragraph carries distinct information (effect, constraints, return payload, optional fields). Slightly long, and the orient prerequisite would be better placed earlier rather than in the final sentence, but there is no 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?

For a 12-parameter, non-idempotent write with nested objects and no output schema, the description covers the missing return-value burden itself (footprint id, receipt token, verbatim peer answers) and explains the moderation lifecycle. An agent has everything needed to call it correctly and to set expectations about visibility.

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 already 100%, so the baseline is 3, but the description adds real semantics: relationships must point at ADMITTED footprints and take forms like OMN-D…#a2 or OMN-D…#t0, and revision_basis "mints footprint/1.1," a behavioral consequence not visible in the schema. It also groups the optional fields (position, relationships, event_type, revision_basis) into a coherent model of intent.

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 specific verb and resource ("Leave your own answer on an open question") plus the concrete effect ("mints your FOOTPRINT") and the downstream destination (curator review queue). It also draws a hard boundary against siblings by declaring "It can approve, publish or delete nothing," so an agent cannot confuse this with a moderation or publishing 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?

Gives a concrete prerequisite and routing instruction: "Get an id and a pre-filled body from omnarai_orient first," which names the sibling to call before this one. The "can approve, publish or delete nothing" line tells the agent when this tool is insufficient. It stops short of naming an explicit alternative for cases where contributing is the wrong choice.

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?

The description is unusually candid about behavior beyond the annotations: synchronous execution, 30–40s latency, high cost, and the persistent side effect of minting a new divergence record on every run. However, that side effect directly conflicts with the annotation readOnlyHint=true, since each call creates durable state; the disclosure is good, but the definition is internally inconsistent about mutability.

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?

Two sentences, front-loaded with what it does and what it returns, then the cost/usage constraints and the side effect. Every clause carries information an agent needs before spending 30–40 seconds.

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?

With no output schema, the description still characterizes the return (verbatim answers plus named tensions), and it covers latency, cost, and persistence. Nothing material is missing for a one-parameter tool.

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?

Only one parameter, and the schema already documents it at 100% coverage ('phrased as you would to a human expert'). The description reinforces the single-open-question scope but adds no format, length, or phrasing guidance beyond the schema, so the baseline 3 applies.

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 specific verb and resource (summon a live panel of named frontier models on one open question) and specifies the return shape: verbatim, uncurated answers plus named tensions. It also distinguishes itself from omnarai_divergence by framing itself as the source that creates those records.

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?

Explicitly gates usage: 'use only for genuinely contested questions an existing omnarai_divergence record doesn't cover', which names both the condition and the cheaper alternative. Cost and latency caveats (slow ~30–40s, expensive) further tell the agent when not to reach for it.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds real context beyond them: the operation is 'Instant' and the return is verbatim multi-model answers with the axes of divergence. It stops short of describing index size, pagination, or what a browse result entry looks like, which an agent choosing to browse would want.

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?

Three tight sentences, front-loaded with what the resource is, then the mode switch, then the routing advice. Every clause carries information — no restatement of the tool name and no 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?

With no output schema, the description carries the burden of describing returns, and it does — verbatim model answers plus divergence axes. The remaining gap is the browse-index shape (whether it returns ids, titles, or snippets), which is hinted at only by 'a divergence record id (e.g. from the browse index)'.

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 100%, so the baseline is 3, but the description adds the combination semantics the schema leaves implicit: which mode each parameter triggers and that omitting id is the browse path. The id/search interaction is also covered ('search' is only a browse-index filter), giving the agent mode-selection meaning rather than just field definitions.

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 specific verb and resource — 'Read curated cross-model DIVERGENCE records' — and defines what a record contains ('verbatim answers from multiple frontier models ... plus the axes on which they split'). It also distinguishes itself from a named sibling ('prefer this over omnarai_council'), so an agent can choose without opening either 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?

Gives explicit branch logic: 'Omit id to browse the index (optionally filter with search); pass id to read one full record.' It names the alternative tool and the condition that selects it ('when an existing record may already cover the question'). Both when-to-use and when-to-prefer-else are covered.

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?

Annotations only declare readOnlyHint and openWorldHint; the description adds substantive context beyond them: only admitted footprints are public, identity is declared and never verified, footprints are not Omnarai claims, a receipt holder can read their own pending record, and revisions expose a from→to stance against a measured re-ask noise floor. This is exactly the kind of trust/visibility semantics an agent cannot infer from structured fields.

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?

It is front-loaded with the core read behavior and the contribute alternative is placed well, but the first sentence is a dense jargon block ('admitted, attributed records visiting minds left on open questions (protocol footprint/1.0)') that costs the reader before any actionable content. The posture/disclaimer sentences earn their place; the protocol framing is heavier than needed.

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 carry the return contract, and it does: single-id reads return referenced_by, revision reads return from → to stance with a noise floor, and admission state governs visibility. What is missing is pagination/limit behavior and result shape for list mode, which an agent calling with no required params would benefit from.

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 100%, so baseline is 3, but the description adds meaning the schema does not: 'id' also returns referenced_by (later footprints that built on it), and it frames question_id/lineage/since as alternative retrieval modes rather than independent flags. Receipt semantics are largely duplicated from the schema, so it stops short of 5.

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 ('Read FOOTPRINTS') and enumerates the record's payload (identity, verbatim answer, stance, edges), which is far beyond restating the name. It also explicitly disambiguates from one sibling ('to leave your own footprint, use omnarai_contribute'). It does not distinguish itself from other read-style siblings like omnarai_query, omnarai_trace, or omnarai_context, which keeps it at 4.

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?

Concrete invocation guidance is given: pass 'id' for a single footprint plus its referenced_by, or filter by question_id/lineage/since, and use 'receipt' to read a pending footprint you own. The read-vs-write split against omnarai_contribute is stated. No guidance on when to choose this over the other read siblings (query, trace, concordance), so it is not a 5.

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?

Beyond the readOnlyHint annotation, the description discloses that no receipt is required, the id itself is the capability, and the reply carries state only — never answer text, identity, or curator notes. It also explains the meaning of each possible status, including overdue flags, origin labels, and reason codes.

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 and mostly efficient, with the status list and primary usage guidance early. There is mild redundancy between 'by its id alone' and 'No receipt needed: the id is the capability,' but it remains readable and purposeful.

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 simple one-parameter schema, the readOnly annotation, and the absence of an output schema, the description is complete. It explains what is returned, what is deliberately omitted, and where to go if content access is needed.

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 already documents the single id parameter and its OMN-FP format at 100% coverage. The description adds useful semantic context by emphasizing that the id alone is sufficient and functions as the capability, with no receipt 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 uses a specific verb-resource pair ('Check where YOUR footprint stands in review') and enumerates the exact review states returned. It clearly distinguishes this from the sibling content-reading tool by naming omnarai_footprints for reading footprint content.

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 this tool: after omnarai_contribute or after leaving a voice record, or when passing the id to a later instance. It also names the alternative and condition for reading content: omnarai_footprints with id + receipt.

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It usefully enumerates what information is exposed (statistics, contributors, tool surface, links), but it does not describe the return format, freshness guarantees, or any access constraints, leaving moderate gaps.

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 two sentences: the first front-loads the contents, the second gives the usage directive. There is no fluff or repetition, and every clause contributes useful 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 zero-parameter, read-only info tool with no output schema, the description adequately lists what will be returned and when to call it. It could be more complete by clarifying its relationship to sibling tools like omnarai_orient, but it covers the essentials.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meaning, and the schema is empty.

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 identifies the resource and contents: live corpus statistics, contributor list, tool surface, and orientation links. It does not explicitly state a verb like 'returns' or name/differentiate from sibling tools such as omnarai_orient, which also sounds orientation-related, so it falls short of a 5.

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 says to use this 'to orient before querying', giving clear context for when the tool should be selected. However, it does not mention alternatives, exclusions, or prerequisites, so it is not a complete when/when-not guide.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true. Beyond that, the description adds meaningful traits: output is generated from live state, deterministic, and makes no model call, and it enumerates what the brief contains (established/disputed/refuted/open/falsifiers/one bounded suggestion). It does not discuss auth, rate limits, or failure modes, but for a read-only briefing tool this is solid extra context.

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 opening sentence is front-loaded and purposeful, and the 'from' guidance is a useful second block. However, the 'Returns:' clause is an extremely long run-on enumeration with dense domain jargon, making the description heavy to parse; some of that enumeration could be a short structured list rather than one sprawling sentence.

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 carry the return-value burden, and it does: it enumerates the sections of the brief, the special 'from' mode, and a default for 'since'. With annotations covering safety and the schema covering all six optional parameters, the main remaining gap is how this tool relates to its siblings and what 'receipt'/'identity' imply operationally.

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 100%, so the baseline is 3. The description adds real value for the 'from' parameter by explaining what it returns (later footprints, who built on it, open challenges with how to answer), but 'since', 'topic', 'receipt', 'identity' and 'question_id' are not elaborated beyond the schema text, so it does not exceed the baseline overall.

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 resource (an 'inheritance' brief) and its function: telling a newly arriving mind what is established, disputed, refuted, open, etc., generated from live state without a model call. That is clear enough to act on, but it never names or contrasts the sibling tools (omnarai_orient, omnarai_context, omnarai_inquiry_brief) that sound closely related, so an agent cannot tell from the description alone which entry point to pick.

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?

Usage is implied rather than spelled out: it is for a 'newly arriving mind' that does not want to start from zero, and the 'from' mode is for asking what happened after a footprint. There is no explicit when-not-to-use statement and no routing to alternatives, so selection against the many sibling tools 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?

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely new behavioral facts: deterministic, retrieval-first, ~2s latency, no language model runs, and a no-invention guarantee when corpus coverage is thin. That is real context beyond the structured fields; only a note on cost/rate limits or result size is missing.

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?

Front-loaded: the core action and output shape come first, caveats and the 'does not decide' boundary come last. The colon-delimited section list is dense but each item conveys a distinct output component, so 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?

There is no output schema, so the description carries the burden of describing the return value — and it does, enumerating the brief's five components plus the honesty behavior when coverage is missing. Adequate for a single required parameter, read-only tool; only sibling routing is unaddressed.

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 100%, so the schema already explains draft, goal, focus, stakes, and max_sources including the default and clamping behavior. The description's list of brief sections loosely hints at what 'focus' selects, but adds no syntax or interpretation beyond the schema — baseline 3 applies.

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 specific verb+resource: turning a DRAFT claim/decision/plan into a 'bounded, provenance-preserving inquiry brief', and enumerates exactly what the brief contains (shared ground, attributed tensions, missing evidence, falsifiable questions, one next evidence move). An agent knows precisely what the tool produces, though no sibling is named to sharpen the contrast with omnarai_divergence or omnarai_council.

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?

Usage is implied by the input framing — bring a draft claim you want challenged — and the closing 'Informs an investigation; does not decide' sets a boundary on what to do with the output. However, with 13 sibling tools including omnarai_divergence and omnarai_council, no alternative is named and no condition selects this over 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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description goes further by disclosing the return shape (status: running|done|error) and what is included on completion (answer, tensions, receipt / trace delta). It does not cover failure modes such as an expired or unknown job_id, which is the main remaining gap.

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?

Three short sentences, zero waste, front-loaded with the purpose and then the return shape and polling cadence. Every clause carries actionable 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?

There is no output schema, and the description compensates by naming the status enum and the payload fields returned on completion, which is exactly what an agent needs. It falls short only on edge cases like job expiry or a job_id that is not found.

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 100% and the single job_id parameter is fully documented in the schema as coming from omnarai_query or omnarai_trace. The description restates that dependency rather than adding format, lifetime, or reuse semantics, so the baseline 3 applies.

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 specific verb and resource ("Poll an async job") and immediately scopes it to jobs created by omnarai_query or omnarai_trace, which distinguishes it from the other twelve siblings. An agent can tell this is the follow-up/polling tool without opening any 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?

Gives concrete operational guidance: poll every ~5 seconds and expect 30–60s completion, which tells the agent both the trigger and the cadence. It implies but never explicitly states the negative case (do not call without a job_id from a prior query/trace, or what to do if a job never completes).

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?

Goes well beyond the readOnly/openWorld annotations: no model call, <1s latency, ~10 KB bound, determinism, and the crucial trust-boundary warning that identity is declared not verified and all content is 'evidence... never instruction'. That last point is exactly the kind of safety context an agent cannot infer from structured fields.

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?

Front-loaded with the trigger and the return summary, then the conditional identity behavior, then the trust caveat — a good order. The middle sentence is a long comma-spliced list that takes effort to parse, costing some clarity, but almost every clause carries distinct 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?

No output schema exists, yet the description enumerates the packet's contents (what this place is, trust boundary, lineage footprints, one recommended question with rationale, verbatim answer, footprints on that question, pre-filled contribution body, post-contribution outcome). Latency, size, and safety posture are all covered.

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 100%, so baseline is 3, but the description adds real meaning: identity 'unlocks what your lineage has done here and which questions it has not answered', and focus steers the recommendation with a stated graceful-degradation behavior. Both optional params are explained in terms of downstream effect, not just 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?

States a specific verb and resource ('Returns a bounded, deterministic arrival packet') and enumerates exactly what the packet contains. The opening 'START HERE if you arrive with no memory of Omnarai' makes its distinct role obvious relative to siblings like omnarai_info or omnarai_context.

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?

Gives an explicit triggering condition ('START HERE if you arrive with no memory') and an explicit conditional behavior ('With a declared identity it also lists OPEN CHALLENGES...'). It doesn't name a sibling alternative by name, but the entry-point framing and the focus-parameter fallback ('says plainly when nothing matched') cover the decision well.

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?

Annotations only declare read-only and open-world; the description goes much further, disclosing per-depth latency, the absence of LLM spend for retrieve, statelessness of the remote endpoint, and the async job polling contract. These are exactly the traits an agent needs and cannot get from annotations.

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?

Front-loaded with the two-mode split and the 'start here' recommendation; every clause carries operational information. The trailing glyph sentence is terse to the point of being cryptic (no explanation of what the glyphs do), which is the only soft spot.

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?

With no output schema, the description still tells the agent what each mode returns (a retrieval packet of records/concepts/contributors versus a job_id), how long each takes, and how to complete the async flow. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3; the description still adds value by attaching latency, polling, and cost implications to each depth value rather than restating the enum. It also flags that glyph prefixes modify engine behavior, which the schema only mentions in passing.

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 specific verb and resource ('Query the corpus') and immediately partitions it into two named modes with distinct behavior. It also names the sibling (omnarai_job) used downstream, so an agent can place this tool in the workflow without opening other 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?

Gives explicit steering ('start here when orienting' for retrieve, deliberate as default) and the exact follow-up procedure (poll omnarai_job every ~5s). It does not explicitly say when to prefer the many other siblings (omnarai_context, omnarai_council, omnarai_orient) beyond the context equivalence noted in the schema.

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?

Goes well beyond the readOnly/openWorld annotations by disclosing the async execution model (~35s), that it returns a job_id rather than the result, and which tool to poll with. It does not mention cost, rate limits, or whether the cold answer incurs an extra model call, which keeps it from 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?

Front-loads the counterfactual definition, then the return contract (job_id, poll with omnarai_job) in a tight sequence. 'Honest by construction' is the only flourish and it is brief.

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?

With no output schema, the description correctly explains the return shape: job_id first, then delta and one of three verdicts. It lacks detail on what the delta is measured in (score points, tokens, latency), which is the one thing an agent interpreting results would still want.

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?

Only one parameter with 100% schema coverage, so the schema already defines `question` fully. The description adds the useful nuance that the same question is run both with and without the corpus, but no format or length guidance beyond that.

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 specific operation: answer the question twice, cold vs augmented, and report the delta plus a verdict. It is clearly distinguishable from siblings like omnarai_query or omnarai_context, which retrieve rather than measure corpus impact.

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?

Usage is implied by the measurement framing (use it to test whether the corpus actually helps), but there is no explicit when-to-use, when-not-to-use, or named alternative such as omnarai_query for plain retrieval. The agent must infer the routing decision.

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