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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses calibrated probabilities, that the response covers ALL options so near-ties are visible, and the exact JSON return shape including choice, confidence, probabilities, runner_up, model, latency_ms, and usage.

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 well structured: a lead sentence, a use-case paragraph, an Args block, and a Returns block. Every sentence contributes useful information, and the most decision-relevant constraints are front-loaded.

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 no annotations, the description is nearly self-contained: it covers purpose, parameters, output, constraints, and exclusions. It does not mention error/validation behavior, such as what happens with fewer than 2 options or malformed option values, which is a minor gap for a tool that otherwise documents its contract well.

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 0%, but the description compensates for all three parameters: `question` is clarified with a concrete example, `options` is constrained to a mapping of short unique ids to one-line descriptions with a 2-100 count bound, and `context` is marked optional and advised to be short. This adds substantial meaning beyond the raw 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 precise operation: ask Jev to pick one of 2-100 mutually exclusive options with calibrated probabilities, and names typical decision uses like triage, routing, classification, prioritization, and tie-breaking. It is clearly scoped, but it does not explicitly differentiate itself from the sibling `classify` and `score` tools, whose purposes overlap with 'classification' and 'prioritization'.

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 when-to-use context ('fast, cheap structured decisions') and clear when-not-to-use guidance ('NOT for open-ended generation or multi-step reasoning'), including an alternative ('use an LLM for those'). However, it does not address how `choice` relates to the sibling tools `classify` and `score`, leaving some selection ambiguity.

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 carries the full burden of behavioral disclosure. It explains that the tool runs 'choice' once per item, automatically appends the item to the question, aggregates results, and returns a detailed JSON structure including confidence, probabilities, summary counts, latency, and usage. It does not discuss error behavior or potential costs, but it gives a strong operational picture.

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 well-structured with a concise summary sentence, use cases, an Args section, and a Returns section. Every part earns its place: the summary explains what the tool does, Args documents each parameter, and Returns tells the agent exactly what to expect. There is no redundant 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?

The tool is moderately complex with four parameters and a structured return value. The description covers parameters, constraints, execution behavior, and the complete return shape. It could be slightly more complete by explaining what 'Jev' is or clarifying error modes, but nothing essential is missing for an agent to invoke the tool correctly.

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 0%, so the description must compensate fully. It does: items are '1-100 non-empty strings,' options are a 'Mapping of short unique id -> one-line category description' with '2-100 options,' question has a default and is auto-appended with the item, and context is optional. This adds meaningful constraints and semantics beyond the plain JSON 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 immediately states the core action: 'Batch-classify up to 100 items against ONE shared set of categories using Jev.' It also explains that it wraps the 'choice' question type and aggregates results, which differentiates it from the single-item sibling tool 'choice'. Concrete examples like routing support tickets and labeling log lines further clarify the intended resource and function.

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 for when to use the tool, such as 'routing support tickets, labeling log lines, triaging inbox items' and says it is 'Much cheaper and faster than an LLM for mechanical labeling.' It does not explicitly state when not to use it or contrast it directly with sibling alternatives, but the batch-vs-single distinction is implied through the 'choice question type once per item' phrasing.

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 are provided, so the description carries the full burden of behavioral disclosure. It does disclose the output format (JSON string with specific fields), the threshold semantics (>= 0.5 leans yes), and performance characteristics ('fast, cheap'), which is useful. However, it omits details like error behavior, rate limits, or authentication requirements. While these are not critical for a simple query tool, the description is not exhaustive, warranting a score of 3.

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 compact and well-structured: it leads with the core purpose, then usage examples, a clear exclusion, and a concise Args/Returns breakdown. Every sentence adds value, and there is no redundancy or filler. The structure is front-loaded and easy to scan for a quick decision.

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 simplicity (2 params, output schema present), the description covers all essential aspects: what it does, when to use it, what parameters mean, and what to expect in the return value. The output is described structurally, and the tool's scope is well-defined. There is no missing information that would prevent an agent from invoking it correctly.

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 0%, so the description is the sole source of parameter meaning. It clearly defines 'question' as a yes/no question with an example, and 'context' as optional background facts with a length guideline ('Keep it short'). This compensates for the lack of schema documentation, though it could go further (e.g., explaining how context affects output). Still, it provides meaningful semantics beyond the bare schema field names.

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 ('Ask Jev a yes/no question'), defines the input (yes/no question) and output (0-1 degree with threshold), and gives concrete examples. It clearly communicates the tool's core function and distinguishes it from general LLM use by explicitly stating it is for binary checks only. Even without naming siblings, the purpose is unambiguous.

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 states when to use this tool ('fast, cheap binary checks') with real examples, and when not to use it ('NOT for questions that need multi-step reasoning') with a clear alternative ('use an LLM'). This provides strong usage guidance that helps an agent select this tool over alternatives.

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 carries the full burden and does a good job: it explains the fractional 0-based index semantics, confidence, per-level probabilities, and the full JSON return shape. It could add side-effect or read-only clarity, but for a grading tool the described behavior is unusually well disclosed.

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 well organized with an introductory sentence followed by Args and Returns sections. It is reasonably tight, though a few phrases like 'Ask Jev' and 'The official score question type' add flavor without much technical value. Overall, every major section 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?

The description covers all three parameters, return values, constraints, and an example. Since an output schema exists, the detailed return enumeration is a bonus. The main missing piece is explicit guidance on choosing this over sibling tools, but the tool is otherwise complete enough to call correctly.

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 0%, so the description must compensate, and it does: 'question' is explained with an example, 'levels' is constrained to 2-8 unique ordered scale points low-to-high, and 'context' is marked optional with usage guidance. This adds meaning well beyond the bare 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 action and resource: 'Ask Jev (TypeSafe System One) to grade something on an ORDERED scale of 2-8 levels.' It clearly identifies the 'official score question type' and gives concrete examples like risk/severity/quality rubrics. This makes it easy to distinguish from siblings such as classify or choice because the ordered-scale scoring semantics are 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?

The description gives clear context for when to use the tool: grading on an ordered scale, with examples and a concrete question phrasing. It does not explicitly mention alternatives or when not to use it, but the contrast with classification-style tasks is strongly implied by the ordered-levels emphasis.

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 fully discloses the behavior: the key is verified against the live API, saved to ~/.config/jev-mcp/key with permissions 0600, never echoed back, and env var takes precedence. This is exactly the behavioral context an agent needs to anticipate side effects.

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 compact and front-loaded with the core purpose, followed by usage conditions, parameter meaning, and return format. Every sentence adds substantive detail without redundancy.

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 single-parameter onboarding tool, the description covers when to use it, how the key is handled, where it is stored, permissions, precedence, and the return value. Nothing critical is missing for correct invocation.

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 provides no description for api_key (0% coverage), so the description must compensate. It does so by stating that api_key is the TypeSafe API key and telling the user where to obtain one, which fully clarifies the parameter's meaning.

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 specifies a precise action: verify a TypeSafe API key with a live call and store it locally. It clearly identifies the tool as one-time onboarding, which distinguishes it from the unrelated sibling tools (noul, choice, score, classify).

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 an explicit trigger condition: 'Use when TYPESAFE_API_KEY is not set in the server environment.' It also explains precedence behavior with an existing env var, so an agent knows when this tool is appropriate and when it is unnecessary.

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