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

Annotations already declare a non-read-only, non-idempotent, destructive mutation, so the safety profile is carried structurally. The description adds the 'switches' implication that the previous model is replaced and the provider constraint, but says nothing about persistence, whether the agent must be rebooted, or required auth/key state.

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?

A single front-loaded sentence with the constraint and the id source in parentheses; nothing is wasted or repeated.

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 two-parameter mutation with annotations covering safety and no output schema, the definition covers what changes and where ids come from. Only side-effect details (restart requirement, key prerequisites) are missing.

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 50%: agent_id is documented in the schema while model has only a maxLength. The description compensates for the undocumented model parameter by naming get_options as the id source, but gives no format example or provider-matching rule beyond the one clause.

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?

Names a concrete verb (switches) plus the resource and sub-resource (an agent's main model), and constrains the target to models from the same provider. That constraint plus the pointer to get_options distinguishes it clearly from the sibling that only lists options.

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?

Implies usage well: used to change an agent's primary model, with valid ids obtained from get_options and a stated scope limit of the same provider. It does not state prerequisites (for example that a key for the provider may need to be connected via connect_model_key) or when to use a different switch tool such as set_temper.

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