select_controller

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

With no annotations, the description carries the full burden. It does disclose the key trait — that this sets session-scoped state affecting later calls and that per-call arguments win — which is real behavioral context. It does not say what happens on an unknown name, whether the choice persists across sessions, or whether any prior selection is replaced.

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?

Front-loaded with the purpose and the precedence caveat before any argument detail, and the whole thing is three short lines. The 'Returns: The selected controller' line is mild redundancy since an output schema already exists.

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, so explaining return values is unnecessary, and the description correctly focuses on the session-scoping semantics and the parameter's source. Only failure modes and persistence behavior are left unstated, which are secondary for a simple selector.

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: it identifies the single parameter's valid value domain by pointing at list_controllers rather than merely restating the name. The schema still lacks type/format detail, but the meaning is unambiguous.

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 — 'Choose the controller' — and, crucially, scopes it to 'this session's later tool calls target', which separates it from list_controllers and get_active_controller. It stops short of naming those siblings, so an agent still has to infer the distinction from the verb alone.

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 the value source ('A controller name from list_controllers') and an explicit precedence rule for per-call overrides, which is exactly the kind of routing information an agent needs. It never states when this call is unnecessary or how it interacts with get_active_controller.

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