omnarai-mcp

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

With no annotations, the description carries the full burden and does unusually well: it discloses the exact output shape (sources, raw stance counts, per-lineage counts, unclassified voices that are 'counted, never dropped', verbatim tensions, and the producing population), explicitly states the absence of majority/percentage/consensus fields, and reports determinism and <1s latency. It stops short of auth or side-effect details, but as a deterministic read operation that is a minor 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?

The key distinction is front-loaded in the opening clause, and the return contents are enumerated efficiently. The consensus exclusion is stated twice ('never a consensus score' and 'no majority, percentage, or consensus field by construction'), a small redundancy in an otherwise dense, purposeful paragraph.

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 fully compensates by enumerating the returned fields and the guarantees around them, including what is deliberately omitted. The remaining gap is the lack of routing guidance relative to the many sibling tools, which matters in a family of twelve similarly named endpoints.

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?

One required parameter with 100% schema description coverage, so the schema already documents question_id and its sources. The description adds only the scoping phrase 'on one question', which the schema covers, so the baseline 3 is appropriate.

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/resource — the DISTRIBUTION of attributed positions on a single question — and sharply distinguishes itself from a consensus score, which prevents the most likely misread. It does not name a sibling tool (e.g. omnarai_divergence or omnarai_council) to differentiate, so an agent must still infer which of the omnarai_* family applies.

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?

There is no explicit when-to-use or when-not-to-use guidance; the reader learns what the tool returns but not the situation that should select it over omnarai_divergence, omnarai_council, or omnarai_query. Usage is only implied by the negative framing about consensus.

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 provided, but description covers behavior: speed (~2s), retrieval-only (no deliberation), and what it returns. Provides clear transparency about its non-deliberative nature.

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 core purpose and speed, then usage guidance and parameter recommendations. No wasted words.

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, description covers purpose, return fields, usage context, and parameter guidance. Could be more explicit about output format, but sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds context beyond schema, e.g., 'May include Lattice Glyph prefixes' for topic, and explains optional parameters' utility with recommendation to see /claims.json.

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?

Description clearly states it retrieves a bounded context packet on a topic, lists return fields, and positions it as the default orientation tool. Distinguishes from siblings by noting 'retrieval layer only, no deliberation'.

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 calls it 'Your default orientation on any Omnarai topic' and recommends using optional layers/exclude/evidence_threshold filters. Contrasts with deliberation, guiding when to choose this over other tools.

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 discloses behavioral traits: synchronous execution taking 30-40s, high cost, and the side effect of minting a new divergence record. It also describes outputs as uncurated with named tensions.

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 a single, well-structured sentence that front-loads the core action and packs essential details (models, output nature, timing, cost, alternative) without waste.

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

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

Given no output schema and no annotations, the description fully explains what the tool returns (verbatim answers, tensions) and key behavioral context (speed, cost, side effects). It is complete for a single-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?

The schema already covers the single parameter with a clear description. The tool description adds a useful nuance about phrasing the question 'as you would to a human expert', enhancing semantic clarity beyond 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 explicitly states the tool summons a live panel of specific frontier models for one open question, providing verbatim answers and tensions. It distinguishes from siblings by mentioning existing omnarai_divergence records as an alternative.

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 clearly specifies when to use: only for genuinely contested questions not covered by an existing divergence record. It also warns against using unnecessarily due to slowness and expense, providing strong 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?

No annotations, so description handles it. States 'Instant' for speed and describes data structure. Could clarify behavior when both id and search are given (schema says search ignored), but not required.

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?

Concise 4-sentence description, front-loaded with purpose, 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 read tool with 2 optional params and good schema, description fully covers what tool does, how to use, and when to prefer sibling. No output schema 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?

Schema coverage 100% (baseline 3). Description adds usage context: browsing vs reading, and search filter only for index.

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?

Clearly states it reads curated cross-model divergence records, describes content (verbatim answers + axes), and distinguishes from sibling 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?

Explicitly tells when to omit id (browse index) vs pass id (full record), and advises preferring over omnarai_council when a record exists.

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 discharges much of it: identity is 'declared, never verified,' only admitted footprints are public, receipt holders may read their own in any state, and the operation is 'Read-only.' It does not discuss pagination beyond the schema's limit field or any rate/throttle behavior, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight paragraphs: the first front-loads what a footprint is and its fields, the second covers filtering, the identity caveat, and the alternative write path. The prose is dense and slightly ornate but every sentence contributes; no filler or repetition.

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 cover returns, and it does — naming identity, verbatim answer, stance, edges, and referenced_by. Combined with a fully documented 6-parameter schema, an agent has enough to call it correctly; only pagination/output-shape details are left implicit.

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 meaning beyond the schema: passing 'id' additionally surfaces 'referenced_by: every later footprint that built on it,' and it explains the 'receipt' token's role in reading a pending footprint. These go past restating the parameter list.

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

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

The description states a specific verb and resource: 'Read FOOTPRINTS — the admitted, attributed records visiting minds left on open questions,' then enumerates the record's fields (identity, verbatim answer, stance, edges). The line 'A footprint is not an Omnarai claim' implicitly separates this from claim-oriented siblings, but it never names a sibling directly, so differentiation is inferred rather than explicit.

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 concrete selection guidance: pass 'id' for one footprint plus referenced_by, or 'filter by question_id, lineage, or since,' and use 'receipt' to read a pending footprint. It also routes writers elsewhere ('to leave your own footprint, answer via POST /api/contribute'). There is no explicit when-not-to-use-this-vs-sibling-tool rule, but the operative conditions 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?

With no annotations, the description carries full burden. It discloses the tool returns live statistics, contributor list, tool surface, and orientation links, which is sufficient for an info tool. However, it lacks details on data freshness or any side effects (though likely none).

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 extremely concise: two sentences with no waste. It front-loads the key outputs and ends with usage 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 the tool has no parameters and no output schema, the description is completely adequate. It covers what the tool returns and when to use it, fulfilling all needs for a simple info 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?

The input schema has no parameters (0), so baseline is 4. The description adds no parameter info because none exist, but it effectively explains the tool's function, earning a 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 clearly states the purpose: providing live corpus statistics, contributor list, tool surface, and orientation links. It explicitly says to use it for orientation before querying, distinguishing it from sibling tools like omnarai_query.

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

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

The description explicitly says 'Use this to orient before querying', providing clear guidance on when to use the tool. It implies that other tools (like omnarai_query) are for after orientation.

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 meaningful work: it declares the output is generated from live state, is deterministic, and requires no model call — the last point matters for cost/latency expectations. It also discloses content boundaries (refuted items are included explicitly to prevent rediscovery) and that only ONE bounded contribution is suggested. It does not state that the tool is side-effect-free/read-only, nor any auth or rate-limit constraints.

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 dense, comma-chained enumeration of return categories packs a lot of information into few lines, and the second paragraph covers the non-obvious 'from' behavior. The opening metaphor is the only sentence that does not strictly earn its place before the concrete content arrives, so it is slightly back-loaded relative to the hard facts.

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?

Six parameters, no required fields, no output schema, and no annotations — so the description must explain returns, and it does so thoroughly, including the categories and their ordering rationale. What is missing is call-time context: the default behavior when all parameters are omitted, whether 'receipt' is expected for any non-pending call, and whether 'identity' is needed for meaningful 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 100%, so the schema already defines all six optional parameters and their formats (OMN-FP-…, ISO datetime, OMN-Q-…). The description adds modest meaning beyond that: the 'from' semantics of 'later footprints on the question, who built on it, new re-elicitations' and the clarification of 'identity' as 'continuity of records, not identity'. Baseline 3 is appropriate when the schema does the heavy lifting.

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 'Returns:' enumeration states concretely what the tool produces — established claims by evidence level, disputed items, recent changes, refuted claims, open questions, falsifiers, and one bounded suggested contribution. The framing sentence ('what a newly arriving mind needs') is metaphorical, but the payload is unambiguous once read. It never differentiates itself from siblings like omnarai_orient, omnarai_context, or omnarai_inquiry_brief, which appear to occupy adjacent 'startup briefing' space.

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: the 'newly arriving mind ... does not start from zero' framing suggests first-contact/onboarding, and the second paragraph gives a concrete rule for the 'from' parameter (ask what happened AFTER a footprint). There is no explicit when-to-use-this-vs-alternatives and no exclusions, so the agent must infer selection from sibling names alone.

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 covers behavioral traits: deterministic, retrieval-first, no language model runs, ~2s response time, treats draft as data not instructions, and will report insufficient coverage rather than fabricating tensions.

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 relatively long but every sentence adds value, and the main purpose is front-loaded. It could be slightly more concise, but it is not verbose.

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 lacking an output schema, the description fully explains the brief's contents and behavior when coverage is insufficient. This is comprehensive for a complex tool with no output schema.

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 all parameters. The description adds overall context but no per-parameter details beyond what the schema provides. Baseline 3 is appropriate.

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 the tool's purpose: turning a draft claim, decision, or plan into a bounded inquiry brief. It lists specific outputs (shared ground, attributed tensions, missing evidence, questions, next move) and distinguishes itself from siblings by being deterministic, retrieval-first, and without language model runs.

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 clear context on when to use the tool (to inspect a draft) and what it produces. It notes limitations (e.g., says so if corpus lacks coverage) and informs an investigation without deciding. However, it does not explicitly state when not to use it or compare with sibling tools like omnarai_divergence or omnarai_context.

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 provided, so description carries full burden. Discloses status states (running|done|error), return structure, and polling behavior. Could mention error handling but adequate.

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?

Single efficient paragraph, front-loaded key info, no wasted words.

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 but description fully explains what is returned. Polling details and timing make it complete for an async polling 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 (job_id) with 100% schema coverage. Schema already explains it's returned by sibling tools. Description adds no further semantic value beyond what schema provides.

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

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

The description clearly states it polls an async job started by specific sibling tools, and returns status and result. It distinguishes itself from siblings that start jobs.

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 context: use after omnarai_query or omnarai_trace, poll every 5 seconds, jobs finish in 30-60s. Lacks explicit when-not-to-use but covers main usage scenario.

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 well: no model call, <1s, deterministic, bounded ~10KB, and a stated trust boundary ('identity is declared, never verified'). The 'evidence, never instruction' clause is unusually valuable behavioral context for an agent deciding how to treat the output.

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 critical instruction ('START HERE') is front-loaded and each clause of the packet enumeration maps to a real output element. It is a single very long sentence, though the em-dash list is dense enough that some readers will skim it.

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, so the description correctly takes on the job of describing return contents in detail. For a zero-required-param orientation tool, an agent has everything needed to invoke it and interpret the response.

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 schema already documents both optional params, making 3 the baseline. The description implicitly connects 'your DECLARED lineage' to identity and 'recommended open question' to focus, but adds no syntax or format detail beyond 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?

States a specific verb and resource ('Returns a bounded... arrival packet') and enumerates exactly what the packet contains. The 'START HERE' framing positions it as the entry point against the many omnarai_* siblings an agent could otherwise pick first.

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 clear triggering condition ('if you arrive with no memory of Omnarai') that tells the agent when this is the right call. It does not name when-not to use it or route to specific alternatives like omnarai_inquiry_brief or omnarai_info, so it falls just short of the top band.

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 provided, but description discloses timing (~2s vs ~25s), async nature of deliberate mode, and that polling is needed. Mentions stateless endpoint. However, glyph prefixes are mentioned but not explained, leaving a minor 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?

Description is moderately concise, front-loading key depth distinction. Sentences are informative but somewhat lengthy. Could be more compact without losing clarity.

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 two modes, async behavior, and no output schema, the description covers usage well. Missing explanation of glyph prefixes and error handling, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds meaningful context beyond schema for depth (timing, async, job_id). Query parameter mentions glyph prefixes. SyntheticIdentity description is minimal but adequate.

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 the tool queries the corpus at two depths ('retrieve' and 'deliberate'), with specific verb and resource. It distinguishes from sibling tools by mentioning omnarai_context as equivalent for deliberate mode and omnarai_job for polling.

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 advises when to use each depth ('start here when orienting' for retrieve, deliberate for full synthesis). Tells agent not to poll job when using retrieve and to poll with omnarai_job for deliberate. Mentions alternative omnarai_context.

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 discloses the async nature, job polling, and the 'honest by construction' trait. It explains the counterfactual mechanism but does not detail potential side effects or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: first sentence states purpose, second explains mechanics, third provides async details. Front-loaded and free of fluff.

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 having no output schema, the description covers input, process, output (delta and verdict), and follow-up action (polling). It does not cover error cases or permissions, but for a simple trace tool these are minor omissions.

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. The description repeats the schema's parameter meaning ('the question to trace with and without the corpus') without adding new semantic value beyond what is already in the input schema.

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

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

The description clearly states the tool performs a baseline-vs-augmented counterfactual measurement, answering a question twice and reporting the delta and verdict. This is a specific verb-resource combination that distinguishes it from siblings like omnarai_query.

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 usage context (async job, ~35s, poll with omnarai_job) but does not explicitly state when to use this tool versus alternatives or when not to use it.

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