set_active_mesh

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

With no annotations provided, the description carries the full burden and does so unusually well: it discloses that it writes to a SHARED meshbook config file, that it verifies scope with the server before writing, and what the failure blast radius is (all commands returning token_out_of_scope, CLI included). It omits return shape, but that is covered by the output schema.

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 actionable content is front-loaded in two sentences, but roughly two-thirds of the text is historical incident post-mortem (dates, 'one out-of-scope call from an MCP session', 'Wren mapped the cross-poisoning from Liza25 (report B5)'). That material does not help an agent invoke the tool and dilutes the spec.

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 mutating, shared-state tool whose output schema exists, the description supplies the side-effect model (persists to shared config), the verification gate, and the consequence of misuse — enough to call it correctly. Preconditions on token scope would round it out.

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% and the single property is an undescribed string, so the description must compensate. It does: mesh_id accepts either a UUID or a name, and name matching is case-insensitive. That is exactly the missing format information, though it gives no examples or ambiguity-resolution rule (name collisions).

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?

First sentence gives a specific verb+resource ('Set the active mesh') plus the accepted identifier forms (UUID or name, case-insensitive). It does not explicitly name or contrast with the nearest sibling (list_my_meshes / whoami), so it stops short of a 5.

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?

Usage is implied by the shared-config and token-scope context, but the description never states when to call this versus alternatives or what preconditions hold (e.g., must the token already be scoped to the target mesh?). The guidance has to be inferred from the incident narrative.

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