Ask Jev (batch)

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses rich behavioral traits: independence semantics ('no question can use another's answer'), the meaning of confidence ('says how concentrated the distribution is, not how likely the answer is to be correct'), and input constraints ('a URL here is not a request to browse'; 'accepts no image, audio, or file uploads'). No contradiction with annotations — readOnlyHint aligns with the judgment-returning 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?

The description is long but every section earns its place: three paragraphs cover call design, question-type selection, and result interpretation, with scannable headings. It is front-loaded with the core purpose and the independence rule appears early. For a tool with three question types, nested objects, and confidence semantics, this density is justified; only slight tightening would make it a 5.

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 high-complexity tool, nothing needed for correct invocation is missing: independence rules, second-call conditions, type selection, confidence calibration warnings, and input limitations are all covered. The output schema exists and the description still explains the answer shape ('answers keyed by question id') and the absence of a confidence field on noul. An agent can call this safely and interpret results correctly without further 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 the baseline is 3, but the description adds interplay semantics the schema cannot capture: 'state carries the text and facts; instructions carries the judgment, in the question's own words.' It also adds the dotted-path referencing rule ('account.plan') and maps the type enum to concrete use cases. This exceeds the baseline yet stops short of exhaustive — the schema already documents each parameter well.

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 is explicit and complete: 'Send one shared context and one or more independent questions to Jev (TypeSafe System One) and get typed judgments back — not prose.' It names the verb, resource, batch scope, and output format in one sentence. The batch nature ('one or more independent questions') clearly distinguishes it from the single-type siblings jev_choice, jev_score, and jev_noul.

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 explicit routing and design rules: 'Ask independent questions together in one call... make a second call only when an answer decides what to fetch or ask next.' It also prescribes type selection with an edge case: 'Prefer choice for a category, score for an ordered scale, and noul for a yes/no judgment. Use separate noul questions when several labels can apply at once.' This is when-to-use guidance that leaves nothing to inference.

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