Set rules on a Scaleway IAM Policy

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

Despite annotations (destructiveHint=true, idempotentHint=true) already indicating danger and idempotency, the description adds critical behavior beyond annotations: the atomic replacement nature, the lockout risk if the credential's own IAM-management permission is dropped, and the irreversibility through this server. This is rich, non-obvious context that annotations cannot convey.

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 well-structured, front-loading the core purpose and then explaining the crucial safety warnings. Each sentence adds value: atomicity, safety, lockout scenario, and the prerequisite call. Slightly long due to repeated warnings, but every point is essential for safe usage.

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 high complexity (destructive, with lockout potential), the description is remarkably complete. It covers the replace semantics, the lockout scenario, the prerequisite to list rules first, and the confirm requirement. The lack of an output schema is fine because the description focuses on input behavior and consequences, which is what matters for such a high-risk operation.

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 coverage is 67%, and the description significantly enhances understanding of all three parameters. The 'rules' parameter is explained as a complete replace, not merge, with a detailed usage pattern (list first, modify, pass back). The 'confirm' parameter is justified as a safety gate against permanent lockout, which is absent from the schema. The 'policy_id' is simple, but the additional context for rules and confirm fully compensates.

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 specific verb ('Overwrite') and clearly identifies the resource ('existing Policy') and the action's scope ('COMPLETE rules array', 'atomic call'). It explicitly distinguishes from alternatives like delete+recreate and warns about the lockout hazard, making its purpose unmistakable.

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?

It provides explicit when-to-use guidance ('the safe way to add or remove a permission set on a live policy'), when-not-to (avoid delete+recreate due to lockout risk), and a direct alternative (scaleway_iam_list_policy_rules to fetch current rules). The description also instructs to call list_policy_rules first, which is essential for correct usage.

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