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

Beyond the annotations, the description adds meaningful behavioral context: the effect is immediate, session-wide, and persists only under OAuth authentication, not API key. It also states the membership prerequisite. This is exactly the kind of side-effect and auth detail that annotations alone do not convey.

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 description is three short, purposeful sentences: purpose, prerequisite, and behavioral effect. Every sentence contributes distinct information, and the most important purpose is front-loaded. There is no fluff or redundant 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?

For a simple one-parameter state-switching tool with full schema coverage and an output schema, the description covers everything an agent needs: what resource is affected, the membership precondition, immediate effect on subsequent calls, and the persistence caveat. No critical behavioral or usage gap remains.

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?

The single parameter teamId is fully documented in the schema, including the instruction to take it from list_teams and the membership requirement. The description repeats the membership condition but adds no additional parameter-level meaning beyond what the schema already provides. With 100% schema coverage, the baseline of 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?

The description uses a specific verb and resource — 'Switch the active team for this Bearer token' — and clearly distinguishes this from sibling tools like list_teams or content operations. An agent can immediately understand this is a session-scoped selection action, not a query or content mutation.

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?

The description gives clear context for when the tool is appropriate: it changes the active team for subsequent tool calls, requires membership, and notes auth-dependent persistence. No alternative sibling performs this role, so explicit when-not-to-use guidance is not necessary, but the membership and session-scoping conditions are clearly stated.

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