Lock a Scaleway IAM User

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

The annotations already provide important context: readOnlyHint=false (write), destructiveHint=true (action has consequences), and idempotentHint=true (can be re-run safely). The description adds significant behavioral context beyond these annotations: it clarifies the action is immediate, it's expected for specific high-stakes scenarios, explicitly notes the console feedback ('shows them as locked'), and honestly flags an unverified detail ('Exact session/token invalidation timing unverified'). This is a model of responsible 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 highly concise at three sentences, front-loading the key purpose and expected use case. The only minor inefficiency is the mention of 'the console shows them as locked' as a parenthetical, which, while valuable, slightly breaks the flow. Every sentence earns its place, adding critical usage and behavioral context.

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 is simple (2 required params, no output schema), the description is complete. It covers what the tool does, why to use it, a critical requirement ('confirm=true'), the behavioral nuance (person vs. service), and an honest caveat about timing. There are no obvious gaps in information needed by an AI agent to make a safe, informed invocation decision.

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 description coverage is 50% (the 'confirm' parameter has a description). The tool description effectively explains the purpose of 'confirm' ('Requires confirm=true') by linking it to the destructive nature of the action, adding value to the schema's description. For 'user_id', the description implies its purpose by naming the target ('Lock a human User'), which, while not explicit, is clear enough given the tool name. A score of 4 is given because the tool name+description clearly conveys the meaning of both parameters, even though only one had a schema description.

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 a strong, specific verb 'Lock' and clearly identifies the resource ('human User', 'a person, not a service'). It explicitly states the expected use cases ('compromise response, offboarding'), which distinguishes it perfectly from sibling tools like 'scaleway_iam_update_user' (which would be used for non-lock changes) or 'scaleway_iam_delete_user' (which is permanent).

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 when to use this tool ('compromise response, offboarding'), flags a required parameter ('Requires confirm=true'), and clearly distinguishes the target ('a person, not a service'), differentiating it from actions on other resources (e.g., API keys, applications). This leaves no ambiguity for the agent.

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