Set Scaleway Bucket Policy

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

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by revealing that the call REPLACES the entire existing policy rather than merging. It also discloses real risks like lockout, offers a recommended safety net statement, and documents empirically confirmed failure modes such as invalid actions, bare-resource ARN handling, and the required Version value for application_id principals.

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 main description is front-loaded and concise, but the policy_json parameter description is very long and dense. However, nearly every sentence earns its place because it conveys critical, non-obvious Scaleway behavior. A slight reduction in redundancy would improve it, but the structure is logical: safety recommendation, replacement semantics, merge workflow, then specific gotchas and an example.

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, complex policy-write operation with no output schema, the description is remarkably complete. It covers replacement semantics, complementary IAM requirements, how to avoid losing existing grants, potential lockout, invalid actions, ARN-vs-bare-name differences, and the correct Version for application principals. The necessary context for safe invocation is fully present.

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 schema coverage is 100%, the policy_json parameter description adds substantial operational meaning beyond basic types: it clarifies that the value must be a string not an object, explains the replace-not-merge behavior, gives a concrete merge workflow, provides a full example, and documents several platform-specific gotchas. This is far more useful than the raw JSON Schema alone.

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 begins with a specific, unambiguous statement: 'Replace a bucket's entire Bucket Policy with the given JSON document.' This clearly names the resource (bucket policy), the action (replace/PUT), and the overall scope. It also differentiates itself from sibling tools by contrasting with get/delete bucket policy and by referencing scaleway_iam_create_policy as the IAM-side counterpart.

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 explains when this tool is needed and how it relates to alternatives: it is the 'bucket-scoped half of access control,' and it directs the agent to scaleway_iam_create_policy for the complementary IAM side. It also instructs the agent to call scaleway_s3_get_bucket_policy first when merging statements instead of overwriting, and warns that a Bucket Policy alone is not sufficient on Scaleway.

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