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

Discloses a significant behavioral trait beyond the annotations: that all subsequent tool calls (posts, media, analytics) operate on the selected workspace, i.e. a session-wide state change. Annotations only carry the generic readOnlyHint=false/destructiveHint=false/openWorldHint=false safety profile, so the state-scoping note is genuinely additive. It stops short of describing reversibility or any confirmation/error behavior, so not a 5.

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-loads purpose, then the side effect, then the parameter format, then the usage rules. Four sentences, each carrying distinct information (what, effect, format, guardrail) with no filler.

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 single-param tool with 100% schema coverage, annotations, and no output schema, the description covers purpose, session-wide side effect, value format, and a consent guardrail. Nothing an agent needs to invoke it correctly is 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 100%, so 3 is the baseline, but the description adds useful format guidance beyond the schema: pass the name 'exactly as shown in list_workspaces' and that the name is preferred because it is unambiguous. That cross-reference to the source-of-truth lister is real added meaning, though the name/id/list-number alternatives largely duplicate the 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 and resource ('Switch the active workspace') and immediately differentiates itself from the sibling list_workspaces by referencing it as the source of valid values. An agent can distinguish this state-changing tool from read-only listers 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 when-to-use ('only when the user has explicitly named the target workspace, or after the user has picked one from list_workspaces') and explicit when-not-to-use ('Never call switch_workspace silently... ask first'). The alternative (list_workspaces) is named and the routing condition is spelled out.

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