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.