oauth2_clients_rotate_secret

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does an excellent job: it states the old secret is 'immediately invalidated' (a destructive, irreversible side effect), that the new secret is returned 'once' (a one-time delivery constraint), and instructs to 'store it securely.' It also discloses the authentication limitation. For a security-sensitive mutation tool with zero annotations, this is exemplary behavioral disclosure.

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 sentences, all essential. Each sentence carries distinct weight: what the tool does, the security implication of the response, and the destructive effect on the old secret plus the auth boundary. There is zero filler, no redundancy, and the most critical operational facts are front-loaded. This is appropriately compact for a simple one-parameter security tool.

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 tool with no output schema, the description covers all essential aspects: purpose, return value behavior (new secret shown once), destructive side effect (old invalidated immediately), storage guidance, and authentication requirements. The existence of sibling oauth2_clients_revoke (which revokes rather than rotates) further clarifies the domain boundary. There's nothing material missing for an agent to use this tool correctly.

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 'uuid' is described in the schema as 'OAuth2 app UUID' with 100% coverage. The description doesn't add parameter-level detail beyond what the schema provides, but with only one parameter at full schema coverage, the baseline of 3 is appropriate. The description's reference to 'confidential OAuth2 application' adds some semantic context that helps interpret which UUID is expected, but doesn't dramatically exceed schema value.

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 specific, action-oriented language: 'Rotate the client secret of a confidential OAuth2 application.' It clearly identifies the verb (rotate), the resource (client secret of an OAuth2 app), and the scope (confidential applications specifically). It distinguishes itself from sibling tools like oauth2_clients_revoke and oauth2_clients_create because it addresses secret rotation specifically, which is a distinct operation not covered by any sibling.

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 explicitly states a critical constraint: 'Cannot be called via API key or OAuth2 token.' This gives the agent crucial guidance about when this tool is usable and what auth context is required. While it doesn't name alternative tools explicitly, the requirement for app-level authentication is a clear usage boundary. It also implicitly communicates that this is for confidential (not public) OAuth2 applications, guiding appropriate selection.

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