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

Goes well beyond the readOnly/idempotent/openWorld annotations: it explains that state is judged as a single whole, that URLs are not browsed, that no image/audio/file uploads are accepted, and that questions are answered independently with no cross-contamination. Most valuably it de-mystifies the `confidence` field ('how concentrated the distribution is, not how likely the answer is to be correct') and the single noul probability's meaning.

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 core purpose, then organized under 'How to design the call' and 'Reading the result' with dense, non-redundant bullets. Length is justified given the tool's genuine complexity; no sentence is 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?

Covers call design, question-type selection, batching trade-offs, output keying, and confidence interpretation. With an output schema already present, the return-format explanation is bonus rather than necessity, and nothing an agent needs to invoke this 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, but the description adds real semantic value on top: it separates the roles of `state` (text and facts) from `instructions` (the judgment, in the question's own words) and explains backtick dotted-path references like `account.plan`. It does not add much beyond the schema for `criteria` limits or `model`.

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: send a shared state plus one or more questions to Jev and receive typed judgments rather than prose. It names `jev_batch` as the alternative for per-record judging, but does not differentiate itself from the `jev_choice`/`jev_score`/`jev_noul` siblings, which appear to be the single-question counterparts of the same operation.

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 describes when one call is sufficient versus when a second call is warranted ('make a second call only when an answer decides what to fetch or ask next'), and directs multi-record work to `jev_batch`. It also gives selection guidance among question types (choice for a category, score for an ordered scale, noul for yes/no) and warns to use separate noul questions when multiple labels can apply.

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/idempotent/openWorld annotations: it discloses the cost model (each item costs what a jev_ask call with those questions costs), concurrency and rate-limit pacing, partial-failure behavior, and the early-stop conditions (rejected key, un-waitable rate limit, consecutive failures, time budget). That is the operational context an agent needs before a 100-item call.

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 purpose sentence, then clearly headed sections (How it runs / How to design the call / Reading the result). Dense but every sentence carries actionable information about costs, ids, or failure handling.

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 nested, 100-item-max batch tool with an output schema, the description covers cost, concurrency, id mapping, error/retry semantics, and partial completion. Nothing an agent needs to invoke this 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 already 100%, so the schema documents items/questions/model in detail. The description still adds cross-cutting semantics the schema can't easily convey: the all-or-nothing id rule, positional labelling from "0" when ids are omitted, and that every item is judged against all questions independently. It largely restates rather than extends schema-level detail, so not 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?

States a specific verb+resource with concrete instantiations ('a queue of tickets, a page of comments, rows of records') and explicitly frames the batch-vs-single distinction. It names the sibling jev_ask and says when to prefer it, so an agent can route between them 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?

Explicitly says to use jev_ask for a single item, prescribes id assignment for result mapping, and gives concrete retry guidance (resend not_sent items and retryable errors after retry_after_ms). When-to-use, when-not-to-use, and recovery are all 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 already declare the safe, idempotent, read-only profile, so the bar is lower, yet the description still adds real behavioral context: a choice returns exactly one option, and `confidence` reflects distribution concentration rather than correctness probability. It does not discuss latency, cost, or failure modes, but the semantic caveat about confidence is the high-value disclosure here.

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 core purpose, then usage rules, then return semantics; no filler sentences. It is slightly dense and runs long, but every clause carries actionable instruction rather than restating the name.

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-param boolean-choice primitive with full schema coverage and an output schema, this covers purpose, alternatives, option-authoring, and the confidence-handling workflow end to end. Nothing an agent needs to invoke 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, and the description goes beyond the schema by explaining how to author `instructions` (write the judgment in full, id not sent to model) and how to phrase option descriptions with boundaries. This is genuine guidance layered on top of already-complete field docs.

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

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

States a precise verb and resource — 'Ask one question whose answer is exactly one of a set of options you define' — and immediately bounds it against the two nearest siblings by excluding degrees (jev_score) and yes/no (jev_noul). An agent can tell this apart from jev_ask/jev_batch without opening a 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 positive cases ('a category, a route, or a selection from a closed list'), explicit exclusions ('not for a degree and not for a yes/no'), and routes the multi-label case to separate noul questions via `jev_ask`. It also prescribes when to add an 'other'/'none' option and what to do with low confidence.

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, idempotentHint and non-destructiveness, but the description adds substantive behavior the annotations cannot: the 0-1 output scale and how to read it, the warning that there is no separate confidence field (a confident no is near 0), the fact that an array of records is blended into one answer, and that URLs are not browsed and no media uploads are accepted.

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 core action in one sentence, then usage, then return interpretation. Three paragraphs with little waste, though the closing paragraph on reading low values is slightly discursive for the space it occupies.

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?

An output schema exists so return structure need not be described, yet the description still supplies the interpretive meaning of the returned number. Combined with the state-handling and input-modality caveats, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains when criteria.true/false may be omitted because instructions already define both outcomes, and stresses naming the condition precisely in instructions rather than relying on question_id.

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

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

The opening sentence states a specific verb and resource ('ask one yes/no question and get its probability') and the binary framing inherently separates it from jev_choice and jev_score, while the state description explicitly routes per-record judgments to jev_batch. An agent can identify this as the binary-probability primitive without opening a sibling 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 a concrete selection condition ('use when the condition either holds or does not, and the probability is more useful than a category') and names jev_batch as the alternative for per-record judging. It stops short of an explicit when-not statement or a direct contrast with jev_choice/jev_score.

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 (readOnly, idempotent, non-destructive), and the description adds substantial non-obvious semantics: the score is a probability-weighted mean, not a percentage or category id; fractional scores are interpolations between levels; and two distributions can yield the same score, so probabilities must be read when the difference matters. That is real behavioral context an agent cannot get from the 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?

Front-loaded with the core action, then scale semantics, then return-value caveats. Every paragraph earns its place, though the closing distribution example is slightly verbose for the value it adds.

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 judgment primitive with an output schema and full annotation coverage, the description fills the remaining gaps: how to construct criteria, what the numeric score means, and what else comes back. 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: criteria must be ordered lowest-first, each level must be self-contained (with the reason — fractional scores fall between levels), and a three-level scale yields 0-2. These constraints materially affect correct invocation.

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 first sentence gives a specific verb (ask) and the exact output shape (a position on an ordered scale the caller defines), which separates it cleanly from a categorical sibling like jev_choice. It does not name the sibling it is not, so differentiation is left to inference from the scale wording.

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?

"Use for degree, severity, or intensity" gives clear positive selection criteria, and the schema adds the routing rule to jev_batch for per-record judging. There is no explicit when-not-to-use statement or named alternative (e.g. jev_choice) in the description body.

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