Update a Scaleway Audit Trail custom alert rule

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

The description goes well beyond the annotations to disclose critical behavioral traits. It specifies that the API is mutable (contradicting no hint since readOnlyHint is false), details that name/description are the only mutable fields, and that other fields are immutable. It explains exact permission requirements: 'Needs more than AuditTrailReadOnly' and how to fix permissions_denied with a specific IAM tool. Crucially, it includes a live-verified caveat (dated 2026-08-18) that the endpoint currently returns HTTP 501 'unknown method' and advises not to retry. This is a model of behavioral transparency, and no annotation contradiction exists.

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 well-structured and efficient. It leads with the core purpose in a single sentence, then uses a straightforward 'however' structure to explain immutability and permission needs. The caveat is clearly flagged with a date and live-verified status. Each sentence adds unique value without redundancy; the entire text is front-loaded with essential information. It is dense but never confusing, and every piece earns its place.

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—a custom alert rule update with immutability constraints, specific permissions, and a current API breakage—the description is remarkably complete. It covers the update's scope, the immutable fields, the permission setup with a fallback tool reference, and a documented caveat with a clear alternative. No output schema exists, but the description sufficiently explains what the tool does and doesn't do. The caveat addresses a critical real-world failure mode, making the description contextually complete for effective agent use.

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 100%, so baseline is 3. The description adds value by clarifying that only name and description are updatable metadata, which contextualizes the parameters. It doesn't add syntax details beyond the schema for each parameter, but it does explain the real-world constraint that custom_alert_rule_id comes from another tool (scaleway_audit_list_custom_alert_rules), which is helpful. It also notes that name and description can be omitted to leave unchanged. A 4 is warranted for adding actionable integration context.

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 explicitly states 'Update a custom alert rule's metadata (name/description) in place,' which is a specific verb+resource combination. It clearly distinguishes this from related sibling tools like scaleway_audit_create_custom_alert_rule and scaleway_audit_delete_custom_alert_rule by specifying that only metadata fields (name/description) can be updated, not the query or other core logic. This level of detail sets it apart from any other tool in the sibling list.

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 provides explicit guidance on when to use this tool versus alternatives. It states that to change logic (e.g., query, evaluation window), users must 'create-new + delete-old,' referencing the create and delete counterparts. It also names a working alternative for current API limitations: 'the preconfigured rules via scaleway_audit_list_alert_rules are the working alternative today.' This includes specific conditions for non-use and clear directions to other tools.

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