x_auth_upsert_principal_credentials

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

With no annotations provided, the description fully carries the transparency burden. It discloses the mutating, high-risk nature; the side effects on Vault and Postgres; the expected response shape; common failure conditions; and a safety warning about changing default principal profiles. 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 well-structured with labeled sections (Use when, Do not use, Risk, Required, Environment, Expected response, Common failures, Safety, Example). Every sentence adds meaningful information, and the content is front-loaded with the core purpose. It is appropriately detailed for a complex tool without wasteful prose.

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?

Given the tool's complexity (16 parameters, no annotations, no output schema), the description is remarkably complete. It covers intended use, exclusions, prerequisites, side effects, response shape, failure modes, safety implications, and an example. This provides an agent with nearly all contextual information needed to invoke the 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 schema covers 0% of parameter descriptions, so the description must compensate. It explains the relationship between tenantId, userId/accountId, and the OAuth1/OAuth2 token pairs, and provides a concrete example. However, some schema parameters like label, notes, xUserId, username, and profileKey remain unexplained, so it is not fully comprehensive.

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 opens with 'Store or rotate tenant/user or tenant/account X user credentials,' which precisely names the verb, resource, and scope. It clearly distinguishes this from the sibling x_auth_upsert_app_credentials by explicitly contrasting principal credentials with app-level credentials.

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 provides explicit 'Use when' and 'Do not use when' conditions, and even names the alternative tool for the excluded case. It also lists required permissions/prerequisites (tenantId plus exactly one of userId or accountId) and the required token types, giving unambiguous guidance for when to invoke this tool.

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