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

Annotations only give the generic readOnly/destructive/openWorld flags, so the description carries the real burden and does add value: it discloses that no Decision-model call is made (cost/latency implication) and that 'it saves nothing' (no persistence), which is the single most important behavioral fact for an agent. What it omits is error behavior — e.g. what happens if the knob has no alternative — and the shape of the returned plan.

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 short sentences, front-loaded with the core action and followed by the cost and persistence caveats; no filler. Slightly reduced by product jargon ('Jev variant', 'decision model's saved answer') that an unfamiliar agent must infer from the title.

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 three-parameter, non-persisting compute tool with full schema coverage, the description covers what it does, what it costs, what it returns, and that nothing is stored. Minor gaps remain around failure modes and whether title_id must match the plan the picks came from.

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 meaning: 'Pass the plan's current picks' effectively promotes the optional nested picks object to a practical requirement and clarifies its provenance, while 'ONE knob' constrains knob_id to a single identifier. That is meaningful guidance beyond the schema strings.

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 action on a specific resource: pick another option for ONE knob of a plan, using the decision model's cached answer. The scope word 'ONE' and the '(free)' qualifier make the intent concrete. It does not name tuning_preview or tuning_surprise as the contrasting siblings in the description text, so differentiation is only implied.

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?

'Pass the plan's current picks; returns the new plan' tells the agent the calling context, and 'without a new Decision-model call (free)' implies it is the cheap alternative to a fresh decision-model run. However, it never says when to choose this over tuning_surprise or tuning_preview, nor what preconditions the plan must satisfy. Usage is inferable rather than stated.

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