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

Annotations indicate readOnlyHint=false and destructiveHint=true, so the description correctly implies a mutating action. It adds transparency by clarifying that the secret value is not exposed in replies, logs, or errors, which is a security-critical behavior not evident from annotations. It also discloses the default expiry of 6 months and the rationale (standing secret = standing capability), and mentions the returned keyId for revocation. The description slightly exceeds what annotations provide, though it doesn't detail the exact lease shape or all error conditions, but for a sensitive operation, this is strong.

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 long but each sentence carries substantive information: the core action, the canonical use case, the secret's handling, default expiry, and revocation path. It is front-loaded with the action and purpose, and while longer than ideal, the detail is necessary for a security-sensitive tool. There is some redundancy (repeating the 6-month default rationale), but overall it is structured well, with the most critical safety information (the secret not being exposed) stated early.

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 complexity of the tool (5 parameters, one required, security-sensitive, no output schema), the description is quite complete. It explains the use case, the authentication flow, the secret's handling, default expiry, and revocation. The lack of an output schema is compensated by describing the reply's contents (connection name and lease shape) and its exclusions (secret value). It doesn't cover potential errors or authentication prerequisites (like having a connection), but given the sibling context and schema descriptions, the essential info is present. A slight gap is not specifying how to set up the initial Microsoft connection, but that's covered by sibling tools like connections_accounts.

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 description coverage is 100%, so the schema already documents all five parameters with descriptions. The tool description adds context for appId (specifically for signing, the app with the Artifact Signing Certificate Profile Signer role) and for lifetimeMonths (explaining why default is 6 months). However, it doesn't add extra semantics for instance, displayName, or instanceName beyond what the schema provides. Since coverage is complete, a baseline of 3 is appropriate, with the added context on appId providing slight additional value, but not enough to push to 4.

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 tool's purpose: mint a client secret for an app registration and vault it, with a specific verb ('mint', 'vault') and resource ('app registration'). It distinguishes itself from siblings like connections_lease_credential by emphasizing the one-step server-side process and the fact that the secret is vaulted without exposing the value. The context of Azure Artifact Signing provides a concrete use case, making the purpose unambiguous.

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 describes when to use this tool (when a machine needs to authenticate as an app without human credential handling) and when not to (e.g., mentions revoking with graph_remove_application_password for early expiry). It also names the alternative tool for revocation, providing clear guidance on lifecycle management. The use case of Azure Artifact Signing is detailed, including environment variable usage, which helps an agent decide if this is the right tool.

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