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

Annotations already provide readOnly, idempotent, and non-destructive hints, so the description adds genuinely useful behavioral context beyond them: Jev prefills the state once, extra questions add almost no latency, paths are read server-side and keyed by path, and only answers enter the agent's context. These are non-obvious behaviors that materially affect invocation decisions.

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

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

The description is dense but every sentence earns its place: batching benefit, performance trade-off, question independence caveat, the paths alternative, context containment, and file-naming guidance. Core purpose is front-loaded and the rest builds on it without repetition or 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 tool with five parameters and an existing output schema, the description covers the essential selection and invocation context: when to prefer batching, how paths differ from state, the independence limitation, and how to phrase file references. The output schema handles return-value details, so nothing critical is missing for correct use.

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 high at 80%, so the schema carries most parameter meaning, but the description adds real value: it explains the semantic difference between 'state' and 'paths', notes that the server reads paths and treats them as one state keyed by path, and gives the concrete guidance to name files with their path in backticks. This goes beyond the structured schema descriptions.

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

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

The description uses a specific verb ('Ask') and resource ('several independent questions about the same state'), and immediately distinguishes the tool from repeated single-question calls by emphasizing ONE request and a single forward pass. It clearly conveys what the tool does and how it differs from the surrounding single-question sibling tools.

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 'Prefer this over repeated single-question calls' and gives concrete conditions for when to use 'paths' instead of 'state'. It also states that questions cannot see each other's answers, which tells the agent to avoid this tool when questions are dependent, even though it doesn't name an alternative explicitly.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by clarifying that a probability near 0.5 means equal likelihood, not 'medium' confidence, and by advising one check per label for multiple applicable labels. This goes beyond the annotation coverage, though it does not mention output format or error behavior, which the output schema likely covers.

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 with no filler. It front-loads the core purpose, then adds a critical interpretation nuance and a usage tip. Every sentence earns its place.

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 an output schema present, return-value details are covered elsewhere. The description includes the key behavioral clarification about probability interpretation and the multi-label usage note. For a read-only tool with robust annotations and schema coverage, this is sufficient, though it doesn't mention the verdict thresholds or the exact structure of state/question beyond the 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 parameters (state, question, yes_means, no_means, no_at_or_below, yes_at_or_above) are all documented in the schema. The description adds a note about verdict interpretation but does not elaborate on individual parameter usage beyond what the schema provides. Baseline 3 is appropriate since the schema carries the load.

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 function: 'Ask a yes/no question' and 'Returns the probability that the answer is yes, from 0 to 1, plus a verdict.' This is a specific verb and resource, distinct from the sibling tools (jev_classify, jev_score, etc.) by its focus on binary judgments. However, it does not explicitly contrast itself with alternatives, so it doesn't fully earn 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?

The description provides one usage note: 'Use one check per label when several labels may apply at once.' This gives situational guidance but does not explain when to choose this tool over siblings or when not to use it. The guidance is implied rather than explicit, so it falls short of a higher 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?

The description adds meaningful behavioral context beyond the annotations: it returns per-option probabilities, a confidence value, and a recommended action gated on confidence. It also states the constraint that Jev cannot invent a new option and the limit of 255 options. These details complement the readOnly/idempotent hints without contradicting them.

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, front-loaded with the core purpose, then the return value, then usage guidance and constraint. Every sentence adds information; there is no fluff 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?

For a tool with 6 parameters and nested objects, the description covers purpose, usage, key constraints, and output. It relies on the schema for parameter details and thresholds, which is appropriate. It does not mention the add_none behavior or the exact return structure, but those are covered in the schema and output schema, so the description is sufficiently complete.

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 every parameter is well-described. The description adds only marginal information about parameters: it reinforces the options constraint and mentions the 255 limit (which is not in the schema). It does not detail each parameter, but the schema already does, so the description meets the baseline without adding significant value.

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 action: picking exactly one option from a user-defined set, and clarifies it cannot invent new options. It distinguishes from open-ended tools by specifying 'Use when the answer is one of a fixed set.' This clearly differentiates it from siblings like jev_ask or jev_score.

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 clear condition for use: 'Use when the answer is one of a fixed set.' This implies when not to use (open-ended questions) and notes the requirement that options must be supplied. However, it does not explicitly name alternative tools or provide a when-not list, so it stops short of a full 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/idempotentHint annotations, the description discloses the tool's heuristic failure mode — 'it can pick wrong but never invent a value' — which is exactly the behavioral trait an agent needs to calibrate trust in extracted answers. It also adds the single-read performance guarantee and the null-when-unanswered return semantics, all context the annotations do not provide.

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

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

About five dense sentences with purpose front-loaded in the first clause and no filler. The batching sentence repeats guidance already present in the schema's questions description, and the return-value sentence is partly redundant with the output schema, but the overall length is well within what the tool's complexity justifies.

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 heuristic, confidence-gated nature of the tool and a rich supporting schema (100% param coverage, output schema, four safety annotations), the description covers the non-obvious essentials: candidate collection, the pick-wrong honesty caveat, batching behavior, and null semantics. Nothing needed to invoke it correctly is missing, though an explicit when-not-to-use note would have pushed this to a 5.

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 documents all seven parameters, including defaults (0.8, 0.5, 0.3, 0.7), the path/text exclusivity rule, and the 'line' kind fallback. The description adds only marginal parameter context — 'confidence-gated action' links the act_above/review_above thresholds to output behavior — which earns the baseline 3 but nothing more.

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 names a specific verb and resource — 'Get short values out of a file (a port, a version, a URL, a date, a quoted setting) without reading the file' — with concrete examples that make the tool's scope immediately obvious. It does not explicitly contrast a sibling tool, so it stops short of full 5-level differentiation, but the extraction-vs-classify/score/search/check operation is clear enough to distinguish within the jev_ family.

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

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

The description gives operational context — use this when you need short values from a file rather than reading the whole thing — and adds genuine how-to guidance: 'Pass every value you need from the file in one call: the file is read once for all of them.' However, it never states when-not-to-use or names an alternative sibling, leaving selection guidance implied rather than explicit.

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 annotations (read-only, idempotent), it discloses how the tool works: reading in windows of up to 254 lines with neighbours so line judgments have context, returning ranked line numbers plus a probability, and reading the file once per call. This gives an agent accurate expectations of cost, output, and processing behavior.

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?

Six short sentences, front-loaded with purpose, followed by output, behavior, and usage guidance. Every sentence earns its place, and there is no filler or repetition of structured data.

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 a rich 100% schema coverage, an output schema present, and a description that explains output, algorithm, and the relevant sibling alternative, an agent has enough to call the tool correctly. Return-shape details are covered by the 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 baseline applies; the description does not add parameter-level details beyond the schema. The batching advice for questions mirrors what the schema already documents, so the description adds no additional parameter semantics.

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 names a specific action and resource: finding lines of a large file that answer a question, and specifies the return scope (ranked line numbers plus an overall probability). It clearly distinguishes itself from the sibling jev_search by noting the file-level vs directory-level use case.

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_search across a whole directory, establishing the main alternative. It also gives when-to-use context ('without reading the file yourself') and batching guidance ('pass every question... one call'), so an agent knows how to invoke it efficiently.

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 indicate this is a read-only, idempotent, non-destructive operation. The description adds beyond that by explaining that with an OpenRouter key, it sends a minimal request and reports the model version, which is a behavioral nuance not captured by the annotations. No contradictions.

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 serving a distinct purpose: stating the main function, explaining why usage is appropriate, and detailing behavior with an OpenRouter key. It is front-loaded with the core purpose and free of filler.

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

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

Given the simplicity (no params, clear output), the description is complete. It explains the tool's purpose, the use case, and the behavior variation with OpenRouter. The output schema exists to detail the return structure, so the description doesn't need to describe it in text.

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 0 parameters, and the schema documentation coverage is 100%. The description doesn't need to add parameter details because there are none. It does explain what the tool returns (model list with release dates or model version), which adds value 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 states a clear purpose: to list the models available to the API key, including release dates. It distinguishes itself from siblings like jev_classify or jev_score, which perform different actions, by focusing on model discovery and key verification.

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 when to use the tool: to confirm the key works and to find a model id before assuming one exists. It also explains the difference between using an OpenRouter key and a direct key, providing clear context for when this tool is needed.

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 annotations (readOnlyHint=true etc.), the description discloses substantial behavioral detail: server-side fetching with https-only and no private addresses, markdown/HTML/PDF/Office conversion, verbatim line returns, withholding of lines from pages that try to steer agents, and the 'answers from the best page, not every page' behavior. It also notes that questions cannot see each other's answers. This goes far beyond what annotations provide.

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

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

The description is dense and well-structured: first sentence explains the core mechanism and constraints, second sentence covers the main use case boundary and the caveat about per-page summarization. Every sentence earns its place; no filler or repetition of schema trivia.

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?

The output schema exists, so return values need not be described. The description covers the tool's input expectations (search result URLs and full questions), processing behavior (fetch, rank, extract), constraints (https, private addresses), and edge cases (agent-steering pages, best-page-only answers). For a tool with this complexity and a full output schema, the description is complete.

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 meaning by clarifying that 'urls' are web search result pages and that 'questions' should be batched to save cost, which directly informs parameter usage. However, it does not explicitly expand on the probability threshold parameters beyond what the schema already says, so a 4 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 precisely states the tool's function: after a web search, pass every result URL and questions, and the server fetches pages itself, ranks them per question, and returns the best page's answering lines verbatim. It clearly distinguishes itself from WebFetch by explaining when fetching is not needed, which differentiates it from sibling tools.

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 tells the agent when to use this tool (after a web search, with all result URLs and full questions) and when not to use it ('to summarise each result separately... WebFetch each with a prompt instead'). This direct alternative routing is the gold standard for usage guidance.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), lowering the bar. The description adds genuinely useful behavioral context beyond those annotations: the result is probabilistic, 'can land between levels' (non-integer outcomes), and includes distribution, confidence, and a recommended action. This frames how the tool behaves semantically.

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 dense sentences with zero filler. The purpose and return behavior are front-loaded, and the usage guidance (the differentiator from siblings) comes second. Every clause earns its place, and nothing repeats what the schema or annotations already provide.

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?

The tool has an output schema, so return values need no explanation. The description covers purpose, usage scope, and behavioral output adequately. The threshold parameters (act_above, review_above) are left to the schema, which documents them fully. Only minor enhancement would be naming the alternative sibling explicitly, which the usage guidance dimension already captures.

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 schema already documents that levels must be 'ordered, lowest first' and that question is 'the only instruction Jev sees.' The description adds only marginal signal: 'along an ordered scale you define' reinforces the levels parameter's semantics that the schema already states. It does not materially extend parameter meaning 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 states a specific verb and resource ('Rate the state along an ordered scale you define') and distinguishes itself from category-picking tools. The sentence 'Use for degree or severity, not for picking a category' explicitly separates it from siblings like jev_classify, leaving no ambiguity about what operation this tool performs.

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 or severity, not for picking a category' provides an explicit when-to-use and when-not-to-use rule. It clearly signals a category-picking alternative exists among the siblings, though it stops short of naming the specific tool (jev_classify) that should be selected instead.

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 annotations (readOnly, idempotent, non-destructive), the description reveals what the tool actually does: asks fixed yes/no signals, counts invisible Unicode characters, returns a three-way verdict with probabilities, and clarifies that a clean verdict only lowers risk rather than proving safety. This is substantial behavioral 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?

Three concise sentences front-load the main action, then describe the signals, output, and a key limitation. Every sentence contributes meaningful information and there is 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?

Given the output schema exists and annotations cover safety/idempotence, the description provides what an agent needs: input types, screening mechanism, verdict values, and a caution about interpreting a clean result. No critical behavioral gap remains.

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 documents path, text, no_at_or_below, and yes_at_or_below thoroughly. The description adds context about the screening behavior but does not add any parameter-specific meaning, 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?

The description uses a specific verb ('Check') and names concrete targets ('web page, issue, email, or file') and a clear goal ('for prompt injection'), and it states the timing ('BEFORE reading it into your context'). It does not explicitly distinguish this tool from its siblings such as jev_check or jev_triage, so it stops 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?

The description gives clear when-to-use guidance: apply it to content you did not write and before pulling it into context. It does not mention when not to use it or name alternative tools, so there are no explicit exclusions or sibling trade-offs.

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 mark the tool read-only and non-destructive, and the description adds meaningful behavioral detail: ripgrep honors .gitignore/.ignore, skips hidden/binary/credential files, optional regex filtering, neighboring-line ranking, and the no-pattern fallback to every non-empty line. This goes well beyond the structured hints without contradicting them.

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

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

The description is dense but well organized: purpose first, then mechanism, return value, and practical tips. Every sentence adds operational information, and 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 9-parameter tool with an output schema and strong annotations, the description covers the important caveats (gitignore handling, credential-file skipping, no-pattern behavior, one-pass batching) that an agent needs before calling. The schema handles the remaining parameter details.

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 adds value by explaining how 'pattern' should be used broadly, what happens without it, and why 'questions' should be batched. It does not comment on every parameter, but the schema already documents those.

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 finds lines across a directory that answer a question and ranks them by meaning, with a specific return shape (path, line number, text). It distinguishes from grep but does not explicitly differentiate from sibling Jev tools such as jev_locate or jev_ask.

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 usage guidance: use a broad regex pattern to narrow candidates cheaply, set include or use a small dir when no pattern is given, and batch all questions into one call since candidates are read once. It does not explicitly state when to prefer a sibling tool, so it stops short of full when/when-not 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?

The description discloses multiple behaviors beyond the annotations: files are read server-side so contents never enter context, each item is an independent request with failures reported in place, and nothing is truncated (oversized files fail rather than being cut). These add significant value beyond the readOnlyHint and idempotentHint annotations, giving the agent a clear picture of failure modes and data handling.

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, dense paragraph that front-loads the core purpose and key differentiators. Every sentence earns its place: it covers the batch nature, file reading, use case, query vs questions, failure isolation, and truncation policy without fluff. It is concise yet complete, ideal for an agent scanning for the essentials.

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

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

Given the tool's complexity (7 parameters, nested question structure) and the presence of an output schema and comprehensive annotations, the description covers all critical operational aspects: the batch workflow, server-side file reading, independent failure handling, and the no-truncation guarantee. An agent can confidently invoke it for triage without needing additional clarification.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds semantic meaning by explaining the conceptual difference between 'query' (single relevance check) and 'questions' (typed judgments), the file-path mechanism for avoiding context pollution, and the per-item independence. This goes beyond mere parameter listings, enriching the agent's understanding of how to compose calls.

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: 'Ask the same question set about many items in one call and get one result per item, in input order.' It specifies the verb (Ask), resource (many items), and the key differentiator (batch processing with server-side file reading). This distinguishes it from single-item siblings like jev_ask or jev_classify, which handle one item at a time.

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

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

It provides explicit guidance on when to use: 'Use it to decide which of many files, documents, or candidates deserve a closer look before opening any.' This clearly indicates the batch triage scenario. However, it does not name specific alternatives or state when not to use it (e.g., when you have few items), so it lacks explicit exclusions. Still, the use case is clear enough for an agent to decide.

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