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

Goes well beyond the annotations (which only say non-readonly, non-idempotent, non-destructive). It discloses that the switch takes effect on the next call with no reconnect, that other sessions on the same key are unaffected, that the key's default workspace is preserved, that in-flight calls run against the previous workspace, and that locked keys are refused.

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?

The core action is front-loaded and each sentence carries information (scoping, effect timing, key behavior, sequencing, locked keys). It is dense and fairly long, but the length is justified by the intricacy of session/client scope semantics rather than padding.

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?

With no output schema and minimal annotations, the description carries the full burden and does so: it covers effect timing, scope, side effects on other sessions, error conditions (locked keys), and even mentions the response's scope field. An agent has everything needed to invoke it correctly.

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 description coverage is 100%, with both slug and workspace_id fully documented including mutual exclusivity and slug resolution. The description reinforces the 'exactly one' requirement, which is mildly useful, but adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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 (switch the workspace this MCP session works in) and scopes it precisely to the session. The name alone could be ambiguous against siblings like workspace_current or workspace_list, but the description immediately clarifies what it changes and at what scope.

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 routes the agent to workspace.list to obtain ids, states the exactly-one-of constraint, and gives concrete when-not guidance: workspace_locked keys refuse to switch, so use a key belonging to the target workspace instead. It also warns not to parallelize calls across a switch.

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