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

Annotations only declare write/not-destructive/idempotent; the description adds far more: permission scope (actions.write), plan-gating with a specific error reason, the downgrade semantics where previously saved out-of-plan entries are silently excluded from paid tests, and the return fields. The idempotentHint=true annotation is consistent with 'save the ordered choices' set semantics, and the description's ordering/multi-entry rule reinforces it.

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?

Purpose is front-loaded in sentence one and every subsequent sentence conveys an operative rule rather than filler. It runs long, largely because nine model IDs are spelled out, which is defensible but makes the definition dense enough that a tighter grouping would read faster.

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?

There is no output schema, and the description still names the return payload (enabled_agents and enabled_agent_models). Combined with prerequisites, plan edge cases, downgrade behavior, error reason, and explicit non-goals, an agent has everything needed to decide whether and how to call this.

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% and the model field is an unconstrained string, so the description carries the whole burden and does: it enumerates the valid model IDs per agent (four Claude Code, three Codex, all seven for Pi/OpenCode), establishes that two models of one agent are distinct entries, and states that ordering is significant. This compensates almost completely for 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?

States a specific verb ('Save') plus the exact resource ('ordered agent/model choices for this project's paid Agent Picks tests'), and immediately disambiguates from siblings by noting it neither starts a test nor alters the starter test's fixed models. An agent can distinguish this from devtune_start_action_draft, devtune_set_agent_picks_schedule and the various get_agent_picks_* readers without opening a schema.

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?

Gives explicit preconditions ('Requires an existing setup, Agent Picks access and actions.write'), explicit exclusion boundaries ('Does not start a test or change the starter test's fixed models'), and a plan-qualification rule with the failure mode named (Pi/OpenCode refused with agent_not_in_plan on non-Pro/Enterprise plans). That is when-to-use, when-not-to-use and expected rejection behavior in one block.

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