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

Annotations already carry readOnlyHint=false/destructiveHint=false, so the description's job was to add real behavioral context—and it overdelivers. It discloses that SUPERADMIN invocations mutate the user record and PERSIST, that the same call is session-scoped for other roles, that reset is mandatory to avoid lingering state, and that OWNER/ADMIN/STAFF can only reach descendants within 3 hierarchy levels. This transforms a 'switch context' tool from potentially surprising to fully predictable. No annotation contradiction detected.

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?

Purpose first, effect scope second, then role-specific behavior in priority order, then the cleanup mandate, then the discovery pointer. Every sentence carries distinct, non-redundant information and the most safety-critical facts (persistence, reset) are front-loaded. Dense but not bloated.

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-parameter, no-output-schema state mutation tool, nothing needed by a caller is missing: the action, the side effects, the role conditions, the depth limit, the cleanup requirement, and the way to obtain valid IDs. The lack of an output schema is acceptable since a switch tool's return value is near-irrelevant next to the behavioral caveats the description already exhaustively covers.

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%—the tenant_id param already restates session scoping, persistence warning, role limits, and the list_tenants pointer. With that coverage the baseline is 3. The description earns one additional point by supplying the 'max 3 levels deep' subtree constraint, which is absent from the schema and which materially affects whether a call will succeed.

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 tenant for this session') and immediately defines the blast radius ('All subsequent queries... will use the specified tenant's data'). It separates the tool from siblings by naming nevent_reset_tenant and nevent_list_tenants and by clarifying exactly which tenant-refining behavior it introduces—a session-wide context change rather than a one-off query param.

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 and when-done guidance: 'Always call nevent_reset_tenant when cross-tenant work is done' and 'Use nevent_list_tenants to discover available tenant IDs.' Role-based conditions (SUPERADMIN vs OWNER/ADMIN/STAFF) read like a decision rule, so the agent knows not only when to call it but what to do before and after. This is the gold standard.

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