Jev coding-loop router

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

Annotations already carry readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds genuine value beyond these: it discloses the legacy model_tier field is conditional and 'not an instruction to invoke a model', and confirms it 'does not edit files', reinforcing the read-only profile. The model_tier caveat is real added behavioral context, not redundant with annotations.

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?

Four tight sentences with zero filler. The call-timing mandate is front-loaded, followed by output fields, usage preference, the model nuance, and the read-only guarantee—each sentence earns its place with no 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?

An output schema exists to document return values, so the description doesn't need to. For a routing tool of moderate complexity it covers when to call, what it returns, the model-invocation nuance, and the edit behavior. Minor gaps (undocumented params) are already reflected in the parameter_semantics score, so completeness of the routing role itself is solid.

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 57%, partially carrying parameter meaning. The description compensates somewhat by clarifying the model parameter ('Legacy model_tier is conditional') and by signaling the execution-fact param semantics ('prefer prepared tools or gathering context'). However, review_at and auto_accept remain undocumented in both schema and description, so the description doesn't fully close the coverage gap.

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 ('Call before retry/stop/model-tier decisions' on the Jev coding-loop router) and enumerates what it returns (next, risk, focus, handoff/partner_model fields). The scoping to retry/stop/model-tier decisions gives useful distinguishing context versus its sibling jev_* tools, though it doesn't name an alternative explicitly.

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 positions when to call ('before retry/stop/model-tier decisions') and gives when-not guidance ('Prefer prepared tools or gathering context; request a partner generative model only when needed and confidently supported'). It lacks explicit named sibling alternatives, but the conditional model-request instruction is a clear prescriptive boundary.

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