Delete a Scaleway Audit Trail custom alert rule

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

Annotations already provide destructiveHint=true, but the description adds rich behavioral context: it confirms the deletion is 'PERMANENT' and 'irreversible', notes that past events remain in event streams, explicitly details the permission requirement beyond the annotation (needs write permissions, not just read-only), and includes a critical, live-verified caveat about the API returning 501 in fr-par. This goes far beyond what annotations alone convey and even warns against retrying on 501, which is a behavioral trait not inferable from annotations.

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: action statement, requirement, irreversibility note, permission details, and a caveat block. Every sentence adds value. It's slightly longer due to the caveat, but that caveat is vital and earned. The formatting (bold 'CAVEAT', date stamp) aids readability. Minor deduction: the caveat could be slightly condensed without losing clarity, but overall it's efficient.

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 has no output schema and the context is a destructive delete operation, the description is remarkably complete. It covers the action, irreversibility, confirmation requirement, permissions required, error handling (501), a fallback alternative, and a timestamp for the caveat's validity. For a three-parameter tool with high schema coverage, this leaves no significant gaps for an AI agent to make an informed 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 100%, so baseline is 3. The description adds meaning by clarifying the context for custom_alert_rule_id (from scaleway_audit_list_custom_alert_rules) and emphasizing confirm must be true for irreversible deletion. However, the region parameter's default (fr-par) is already in the schema description, and the description doesn't describe the 501 error's relationship to region (it's region-specific but not called out in the description text). Still, the added guidance on confirm and the permission note elevate it above the baseline.

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 'PERMANENTLY delete a custom alert rule by ID,' which uses a specific verb ('delete') and resource ('custom alert rule') and clearly differentiates from sibling tools like scaleway_audit_create_custom_alert_rule or scaleway_audit_list_custom_alert_rules. The focus on irreversibility and permanence makes the action unambiguous.

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 ('delete a custom alert rule by ID'), what it requires ('confirm=true'), and crucially provides an exclusion scenario: the CAVEAT about 501 errors explains when not to use it (deployed API returns 'unknown method') and directs to the working alternative 'preconfigured rules via scaleway_audit_list_alert_rules'. It also details permissions needed (AuditTrailReadOnly insufficient, needs write permission set) and a fallback action ('grant the Audit Trail write permission set') in case of failure, offering comprehensive guidance.

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