rotate_token_admin

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

With no annotations provided, the description carries full burden and delivers rich detail: explains the Managed-vs-unmanaged behavioral split, describes token delivery mechanisms (push-message + grace window vs return-in-response), notes `restart_required:true` for unmanaged, and discloses that audit logs record BOTH rotator and target for attribution. It also enumerates full error taxonomy. Only minor gap: doesn't disclose whether operation is destructive/irreversible in explicit terms, though hard-cut grace=0 implies it.

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?

Well-structured with clear semantic sections (When to use, Behavior, Returns, Errors) using bolded labels. Each sentence earns its place, front-loaded with the core action. The error taxonomy and return shapes are compactly enumerated without fluff. Zero filler words.

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 4-parameter, no-output-schema, no-annotation tool, the description is thoroughly complete: covers purpose, when/how to use, behavioral nuances, exact return shapes for each branch (managed-with-grace, managed-with-zero-grace, unmanaged), and all error conditions. Nothing meaningful is left unspecified for the agent to guess.

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 baseline is 3. The description adds value by explaining the distinction between rotator and target (self-rotation uses rotate_token), clarifying grace_seconds semantics (clamped, forced hard-cut at 0, ignored by unmanaged), and noting agent_token can come from multiple sources. It adds meaning beyond the field descriptions.

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 clearly states the action ('Admin-initiated rotation of another agent's token') with a specific verb and resource, and names the phase (v2.1 Phase 4b.2). It distinguishes from siblings by explicitly naming rotate_token (self-service) and revoke_token (revocation), and differentiating against the target_agent_name schema constraint.

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?

Provides explicit when-to-use scenarios ('operator-driven incident response, scheduled rotation across the fleet, or onboarding a Managed agent'), states the prerequisite capability (`rotate_others`), and names explicit alternatives for different cases (rotate_token for self-service, revoke_token for revocation without re-issuance). This is model-level guidance.

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