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

It adds significant behavioral detail beyond the destructiveHint annotation: there is no dry-run, confirm must be true, the stored credential is overwritten in place, the org-enumerability check happens before any IAM write, and invalid accounts return an error with nothing changed. It also discloses that the minted key is written to the vault server-side and describes the reply shape.

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 dense but every sentence earns its place: operation, diagnostic guidance, preconditions, and return contract are all included without filler. The core destructive behavior is front-loaded in the first sentence and the alert-level confirm requirement appears 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?

For a destructive, cross-account minting tool with no output schema, the description covers prerequisites, the cross-account path, validation-before-write behavior, the no-dry-run requirement, and the exact response contract. Nothing an agent needs to safely invoke it is missing.

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?

Although the input schema already covers 100% of parameters, the description enriches them materially: instanceName must be an EXACT existing dead instance and never invents a new one, targetAccountId must be enumerable by fromRootInstance via Organizations ListAccounts, and confirm acts as the sole safety gate with no dry-run. These meanings go beyond the schema's individual 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 names a specific action and resource: 'mints a fresh scoped IAM operator credential THERE and overwrites the stored credential for that EXACT instance' in a MEMBER (plane) account. It clearly carves out this tool from the sibling connections_mint_org_operator by targeting member accounts rather than org accounts.

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 says to diagnose first with aws_sweep across instances or the vault_operator_role_census instrument, and it specifies two preconditions (confirm must be true and targetAccountId must be org-enumerable) before any IAM write. It does not spell out the exact alternative-selection rule versus connections_mint_org_operator beyond 'MEMBER (plane) account' and 'Same contract', but the context is clear.

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