scaleway-ops-mcp-server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.1
Disambiguation5/5
Every tool has a clearly distinct purpose, organized by domain (iam, s3, audit) and action (create, get, list, update, delete, etc.). Overlaps are explicitly noted in descriptions (e.g., list_policy_rules vs get_policy) and resolved with clear guidance. No two tools appear to do the same thing.
Naming Consistency5/5
All tools follow a consistent `scaleway_<domain>_<verb>_<noun>` pattern. Verbs are uniform within the domain (e.g., create/get/list/update/delete for most resources). Minor variations like `add_group_member` vs `create_application` are consistent across similar operations.
Tool Count4/5
At 117 tools, this is very large for an MCP server. However, each tool is justified by the comprehensive coverage of IAM, S3, and Audit Trail operations. The count is appropriate for the scope (multiple sub-services with full CRUD and configuration). A slight deduction for discoverability challenges, but not excessive given the domain.
Completeness5/5
The tool set provides comprehensive lifecycle coverage for IAM (users, groups, applications, policies, API keys, SSH keys, SAML, SCIM, security settings), S3 (bucket configuration, objects, presigned URLs, object lock), and Audit Trail (events, alerts, exports). There are no obvious dead ends or missing operations within these domains.
Average 4.4/5 across 100 of 117 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 9 of 9 community issues answered or closed in the last 6 months
- 46 commits in the last 12 weeks
- Last stable release on August 20, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly indicates a destructive/removal action ('Remove', 'stops serving'), while the annotations declare destructiveHint: false. This is a direct contradiction, making the description misleading about the tool's behavioral impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action and its consequence without any unnecessary words. It is highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description states the main effect, but the contradiction with destructiveHint creates confusion about whether data/configuration is permanently lost. It also does not mention behavior when the configuration does not exist or whether the operation is reversible, leaving important gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete parameter descriptions (bucket name and optional region with enum). The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action: 'Remove the static-website configuration' and the result: 'the website endpoint stops serving.' This distinguishes it from sibling tools like get_bucket_website and put_bucket_website.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to disable static website hosting on a bucket, but it does not explicitly state when to use it vs. alternatives or mention any conditions. The sibling list provides context, but the description itself offers no direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the annotations: partial update semantics ('Only passed fields change') and API-side validation behavior for invalid fields. It does not contradict the annotations, which already indicate non-read-only, idempotent, non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise, front-loaded sentence with no filler. It loses a point because the phrase 'name/email where the API allows' is slightly ambiguous given the schema exposes first_name/last_name and no email parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core update semantics and validation, and the schema richly documents the tags replacement behavior. However, it lacks any mention of return values, required permissions, or how this differs from the username/password update tools, leaving the tool somewhat incomplete for an agent navigating a large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, but the tags parameter is thoroughly documented in the schema itself. The description adds useful cross-parameter semantics like partial updates and validation, but it mentions 'email' which is not in the schema, and does not clarify first_name/last_name beyond their obvious property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool updates a User's mutable profile fields, naming tags and name/email. It is more specific than a tautology and generally distinguishes from username/password update siblings, though it doesn't explicitly call out first_name/last_name as the exact schema fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context (only passed fields change, invalid fields rejected) but gives no explicit when-to-use vs alternatives, no exclusions, and no reference to sibling tools like scaleway_iam_update_user_username or scaleway_iam_update_user_password. The usage boundary must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the explanation that grace periods are 'post-lock/deletion data-access windows' which clarifies the concept, but does not disclose additional behavioral traits such as pagination, ordering, or any side effects beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical clarification. It is front-loaded with the action and resource, and every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no output schema). The description explains the concept of grace periods and the read-only nature. However, it does not specify what the response contains (e.g., a list of objects with start/end dates) which could aid agent reasoning, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden for parameter documentation. The description does not mention the user_id parameter, its format, or how to obtain it. While the title and context imply the parameter is the user's ID, explicit guidance is absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' (interpreted as list), the resource 'User's grace periods', and explains what grace periods are (post-lock/deletion data-access windows). This distinguishes it from sibling tools like scaleway_iam_list_api_keys or scaleway_iam_get_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through its title and explanation, but does not explicitly state when to use this tool versus alternatives. For example, no mention that for general user details one should use scaleway_iam_get_user, or that grace periods are a specific concept only available via this endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds that the operation restores access and is reversible. This is consistent but adds only modest context beyond the annotations, such as no mention of permission requirements or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) and front-loaded with the primary action. However, it borders on under-specification; a brief note about context (e.g., 'after a user is locked') would improve completeness without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, clear name), the description is largely complete. It states the purpose and relationship to a sibling tool. Missing elements are minor, such as what happens if the user is already unlocked (idempotentHint partially covers this) and authorization requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single 'user_id' parameter. It does not elaborate on the parameter's meaning, format, or how to obtain it beyond implying it's the UUID of the locked user. This is insufficient for a low-coverage scenario.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore a locked User's access') and explicitly distinguishes it from its sibling 'lock_user' by calling it the 'reversible counterpart'. This leaves no ambiguity about what resource is affected and what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a user is locked and you want to restore access, and mentions 'lock_user' as the paired operation. However, it does not explicitly state when NOT to use it (e.g., if the user is already unlocked) or provide any prerequisites, which are minimal but would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, covering safety and idempotency. The description adds useful behavioral context by specifying that the response includes the API-key count. No contradictions. It adds value beyond annotations without being required to repeat them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 11-word sentence that is succinct, front-loaded with the key action, and contains no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 'get' operation with one parameter and a clear return benefit (API-key count), the description is mostly complete. It states the resource, identifier, and a notable return field. However, it does not specify other returned fields or error handling (e.g., 404). Given the simplicity and comprehensive annotations, the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description says 'by id' but this is already implied by the parameter name 'application_id' and format 'uuid'. It adds no additional meaning about what the ID represents or how to obtain it. The description fails to add semantic value beyond the parameter name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'IAM Application', the identifier 'by id', and an additional detail 'including its API-key count'. This distinguishes it from sibling tools like scaleway_iam_list_applications (which returns all) and create/update/delete (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that scaleway_iam_list_applications should be used for listing, or any prerequisites like needing the application_id. The name and title imply the use case, but explicit context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds only the filter capability and organizational scope, but does not disclose pagination behavior, API limits, or how results are structured. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that states the core action and resource. It contains no extraneous words and is immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with one optional parameter and no output schema, the description is minimal. It does not mention pagination, result format, or any prerequisites. The schema adds important filter behavior, but the overall context is barely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the parameter 'name_filter' is fully described in the schema (case-insensitive, applies across pages). The description paraphrases this with 'optionally filtered by name substring', adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'IAM Applications', and scopes to 'this Organization'. It also mentions the optional filter, clearly distinguishing it from sibling tools like scaleway_iam_list_users or scaleway_iam_list_policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly establishes usage by naming the resource (applications) and optional filter, but it does not explicitly state when to use this tool over siblings like scaleway_iam_list_users. There is no 'use this when you need applications' or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds 'certificates registered for SAML SSO validation' but no additional behavioral traits beyond what annotations provide. It does not contradict annotations, but adds little value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no extraneous words. It efficiently communicates the tool's purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and strong annotations, the description is mostly sufficient. It identifies the resource (SAML certificates) and purpose. A minor gap is lack of output structure description (no output schema), but the tool's simplicity mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'saml_id' is well-described with a reference to 'scaleway_iam_get_saml_config's id field'. The tool description adds no further parameter semantics beyond the schema. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List certificates registered for SAML SSO validation' clearly states the action (list) and the resource (certificates for SAML SSO). It effectively distinguishes this list operation from sibling tools like scaleway_iam_get_saml_certificate (single certificate) and add/delete variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like scaleway_iam_list_api_keys or scaleway_iam_get_saml_certificate. The purpose is implied by the name and sibling context, but the description lacks when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's statement 'Read the key/value tag set' adds little beyond confirming it's a read operation. It does not disclose additional behavior such as error conditions, empty tag sets, or output format, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and target. It contains zero fluff or redundant text, making it maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, read-only nature, and full parameter descriptions, the description sufficiently conveys the tool's return value (the key/value tag set) and context. It could explicitly mention the response format (e.g., map or XML) but that is implied by 'tag set'. The lack of an output schema is offset by the clear purpose statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage (100%) for all parameters (bucket, key, region) with clear descriptions. The tool description itself does not add any parameter-specific meaning, so it meets the baseline for schema-described parameters without adding extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the key/value tag set attached to an object, using a specific verb ('Read') and resource. It distinguishes itself from sibling tools like scaleway_s3_get_bucket_tagging (bucket-level) and scaleway_s3_put_object_tags (write) by specifying 'object' and 'tag set'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading object tags, but it does not explicitly mention when to use it versus alternatives like scaleway_s3_get_bucket_tagging or scaleway_s3_put_object_tags. No exclusions or alternative tools are referenced, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the annotations: it confirms the permanent nature, the immediate revocation of permissions, and the confirm requirement. This aligns with destructiveHint=true and readOnlyHint=false without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, each earning its place. The first sentence front-loads the core purpose and permanence, the second adds critical usage details (confirm requirement and immediate effect). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with annotations and schema, the description covers the key behavioral aspects. It could mention side effects like what happens if the policy is in use (addressed implicitly by immediate revocation) or mention error conditions, but overall it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the confirm parameter already has a description in the schema that matches what the tool description restates. The policy_id parameter lacks any description in either the schema or tool description, so no new meaning is added for that parameter. The tool description does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'delete' and explicitly identifies the resource as 'IAM Policy'. It clearly states the permanent nature and the immediate revocation of permissions, which distinguishes it from update, clone, or other policy-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement for confirm=true and implies that this is for permanent deletion, but it does not explicitly state when to use this tool versus alternatives like update_policy or clone_policy. The guidance is adequate but lacks explicit 'when-not-to-use' or prerequisite checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and idempotentHint=false. The description goes beyond by emphasizing the permanent nature of the deletion and explaining the real-world consequence (loss of SSH access). It also highlights the confirm safeguard. This adds meaningful behavioral context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three sentences), front-loaded with the core purpose, and every sentence earns its place. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, destructive), the description covers the permanent action, the confirmation gate, and the risk. It lacks guidance on retrieving the SSH key ID or handling errors, but for a delete tool with strong annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (confirm has a description). The tool description only reiterates that confirm must be true, adding no new information about the ssh_key_id parameter (format, source, or required format). For a low-coverage schema, the description should compensate but does not sufficiently explain the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('PERMANENTLY remove') and clearly identifies the resource ('an SSH key'), distinguishing it from other SSH key tools (list, get, create, update) and from other delete tools in the sibling list. The permanence and confirm requirement add operational clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by stating the confirm requirement and warning about the impact of deleting a key still in use. However, it does not explicitly compare to alternatives (e.g., updating the key or replacing it), leaving the agent to infer when this tool is the right choice over other SSH key operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the agent knows it's a safe read operation. The description transparently discloses a key behavioral trait: the path is unconfirmed and may need correction on first real use, which is critical information beyond the annotations. This adds valuable context about reliability without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loading the core purpose. The additional path caveat is useful but feels slightly verbose for an AI agent; it could be more terse. Still, it earns its place by providing critical behavioral context. No unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (simple read tool with 2 params, no output schema, but path uncertainty), the description adequately covers what it does, its return content (metadata with fingerprint and expiry), and a key caveat. It could include the expected return format or what happens if the path is wrong, but overall it's sufficient for a tool with strong annotations and few parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description carries the full burden for parameter semantics. It mentions 'by id' and references 'saml_id' and 'certificate_id' in the path discussion, but does not explicitly describe what the two required parameter values (uuid strings) represent or how they are used. The description adds minimal meaning beyond the schema's property names, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a single SAML certificate's metadata (fingerprint, expiry) by ID. The verb 'read' and resource 'SAML certificate' are specific and unambiguous, and the mention of 'by id' distinguishes it from the sibling scaleway_iam_list_saml_certificates which lists multiple certificates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by referencing the list tool's path and noting this is for a single item, but it does not explicitly state when to use this vs. alternatives like the list tool or get_saml_config. There's no 'use when' or 'use instead' guidance, leaving the agent to infer it should be used when a specific certificate ID is known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds value by specifying that the response includes the full public_key text and fingerprint, which is not captured in annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words with no wasted content. It is front-loaded with the core action and immediately followed by key return details. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter, the description adequately states the purpose and key return fields (public_key text, fingerprint). However, it does not mention other likely fields (id, name, timestamps) nor does it explain the parameter format. The absence of an output schema increases the need for description completeness; the current description is mostly sufficient given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the only parameter ssh_key_id. The description only says 'by id', which minimally implies the parameter's role but does not explain its format (UUID), origin, or constraints. With no param descriptions in schema, the description should compensate but does not provide sufficient detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the resource 'one SSH key by id'. It further specifies what is included in the returned data (public_key text and fingerprint), clearly differentiating from sibling tools like list_ssh_keys, create_ssh_key, update_ssh_key, or delete_ssh_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for retrieving a single SSH key by ID, but it does not explicitly state when to use it versus list_ssh_keys or other IAM get tools. No when-not or alternative guidance is provided, leaving the agent to infer usage from the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: that preset and managed groups are included, and that name filter is exact (not substring). This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. First sentence states purpose and scope; second provides critical filtering nuances. Every word earns its place. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 optional parameters and no output schema, the description covers filtering nuances but omits pagination details, default ordering, response format, or what happens with no filters (returns all groups). While sufficient for a simple read-only list tool, minor gaps prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so baseline is 3. The description adds that name is an exact match and array filters use ANY logic, which partially repeats schema descriptions. It does not clarify tag exactness (already in schema) or order_by. The added value is marginal, meeting but not exceeding the baseline for high-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('Groups'), and clarifies scope ('in the Organization, including Scaleway's preset groups and any special managed groups'). This clearly identifies the tool's purpose and distinguishes it from sibling tools like list_users or create_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage guidance by detailing filter behavior ('name is an EXACT match', 'Array filters narrow to groups matching ANY of the given ids'). However, it does not explicitly state when to use this tool vs alternatives (e.g., get_group for a single group) or when not to use it. The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and no destructiveness (destructiveHint=false). The description adds value by clarifying the additive nature ('preserved') and the refusal condition for managed groups. It could further disclose behavior when adding already present members (e.g., silent no-op or error) but provides solid context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the core purpose, the second adds critical behavioral nuance (additive vs replace, refusal condition). Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity bulk add tool with 3 parameters and no output schema, the description covers the core behavior and an error case. However, it lacks details on what the success response looks like, whether adding duplicate members is safe (idempotent), and partial failure behavior. It is adequate but leaves operational questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only group_id gets a description in schema). The description does not elaborate on the parameters—it mentions adding 'Users and/or Applications' but does not explain that user_ids and application_ids are arrays of UUIDs, how to acquire them, or that they are optional. With low coverage, the description should compensate but fails to provide meaningful parameter-level guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('multiple Users and/or Applications to a Group') and clearly distinguishes from sibling tools like scaleway_iam_add_group_member (singular) and scaleway_iam_set_group_members (replace) by stating 'at once' and 'additive, not a replace.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that this tool is additive and not a replace, guiding the agent to use set_group_members for replacement. It also notes that the tool refuses non-editable groups, which informs when not to use it. However, it does not mention the singular variant scaleway_iam_add_group_member as an alternative for adding a single member at a time, leaving some usage gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, so the description's job is lighter. It adds value by specifying the permanence, the required confirm flag, and the immediate effect on IdP provisioning. It also honestly notes an unverified path caveat. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with key information front-loaded ("PERMANENTLY revoke"). It includes necessary warnings and a caveat without redundancy. Slightly verbose on the path uncertainty note, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with required confirm, the description covers the essential operational context: permanence, prerequisite, immediate impact, and path uncertainty. The sibling tools list includes related SCIM operations, providing sufficient context. No output schema, but return values are likely straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'confirm' has a description). The description reiterates that confirm must be true but does not explain the semantics of scim_id or token_id beyond what their names and UUID format imply. Given low coverage, the description should provide more parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name, title, and description clearly communicate that this tool permanently revokes a SCIM token. The description uses strong verbs ("PERMANENTLY revoke") and uniquely identifies the resource type, distinguishing it from sibling delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (to revoke a SCIM token) and includes a critical prerequisite (confirm=true). It warns that IdP provisioning breaks immediately, providing context on consequences. However, it does not explicitly guide against use when rotation is intended, nor does it mention creating a new token as the recovery alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds specific behavioral context by detailing the response contents (member lists, special-group flags), which goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core purpose and key response details without any extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and clear annotations, the description is nearly complete. It describes the response content (members, flags) but lacks details on pagination or limits. Without an output schema, this is sufficient but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description for group_id provides sufficient context. The tool description does not add new parameter-specific meaning, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and specifies the resource 'one Group's full details', including member lists and special-group flags. This distinguishes it from sibling tools like list_groups (which returns summaries), create_group, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when full details of a specific group are needed) but does not explicitly state when not to use it or suggest alternatives like list_groups for summaries. The context is adequate but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds minimal behavioral context beyond confirming it's a read-only listing. It mentions the required permissions, which is useful, but doesn't describe pagination, rate limits, or other operational traits. Given annotations handle the safety profile, the description's additional value is limited but not absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, lists key return fields, and caps with permission requirements. Every sentence serves a purpose with no fluff. This is an exemplary model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no nested objects), the description is nearly complete. It covers purpose, return fields, permissions, and scope. The only missing element is pagination behavior (e.g., limit, cursor), but for a simple listing this is acceptable. No sibling tool overlaps in a confusing way.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (1 parameter fully described). The description adds no additional parameter meaning—it doesn't elaborate on filter behavior, case sensitivity, or pattern. Baseline 3 is appropriate because the schema already documents the parameter sufficiently, and the description doesn't enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists human users of the organization, specifies the IAM page reference, and enumerates the returned fields (id, email, status, type, locked, MFA flags). This is a specific verb+resource+scope combination, and among the sibling tools, it's the only user-focused listing tool, making it unambiguously distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the required permission ('Needs IAMUserReadOnly/IAMUserManager'), which serves as a usage prerequisite. While it doesn't explicitly mention when not to use it or provide alternatives, the context is clear: it's a simple listing tool. No sibling tool directly threatens ambiguity, but explicit when-to-use guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful nuance: it requires confirm=true (emphasizing safety), clarifies that the operation is reversible in the sense tags can be re-applied, and notes the current set is lost. This goes beyond annotation data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and every word adds value. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with full annotations and complete schema coverage, the description covers the essential behavior: what it removes, the confirm requirement, and the reversibility nuance. It doesn't mention error conditions or return values, but these are not critical given the tool's simplicity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented in the schema. The description only reiterates the confirm requirement, which is already in the schema (const: true). It adds no additional semantics beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove ALL tags from a bucket' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_bucket_tagging (retrieve) and put_bucket_tagging (set). The scope (ALL tags) is explicit and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the requirement (confirm=true) and the effect (remove all tags), but it does not explicitly mention when to use this tool versus alternatives like put_bucket_tagging. The context implies it's for clearing all tags, but no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the permanence emphasis ('PERMANENTLY') which goes beyond the generic destructive flag, and 'Requires confirm=true' highlights the safety gate. No contradiction with annotations; the schema further clarifies versioning nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences deliver the essential message with zero fluff: what it does, the permanence, and the confirmation requirement. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-object deletion tool with 100% schema coverage and rich annotations (destructive, idempotent, readOnly), the description plus schema is largely sufficient. It lacks explicit success/failure behavior, but the tool's simplicity and annotation coverage mitigate that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all four parameters (key, bucket, region, confirm). The description adds no parameter-level detail beyond the schema; 'Requires confirm=true' merely restates the confirm constraint already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb+resource ('PERMANENTLY delete one object') and clearly distinguishes from the sibling tool scaleway_s3_delete_objects by specifying 'single object'. The title reinforces scope with 'Delete a single object from Scaleway Object Storage'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'delete one object' implies this tool is for single-object deletion, but there is no explicit when/when-not guidance or mention of alternatives like scaleway_s3_delete_objects for bulk deletion. Usage context is only implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds a valuable behavioral detail: the tool throws NoSuchCORSConfiguration when no rules are set, which helps agents handle errors. This goes beyond annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise—two short sentences—with no redundant words. It front-loads the action and error behavior without any filler, fully earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 2 parameters and no output schema, the description adequately covers purpose and error behavior. The annotations provide safety context, and the schema handles parameters. The description is complete for its complexity, though it could optionally mention that region defaults are handled in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both 'bucket' and 'region' are well-documented in the schema. The description does not add any extra information about parameters, which is acceptable given the schema clarity. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read a bucket's CORS rules') with a specific resource (bucket CORS) and directly differentiates from sibling put_bucket_cors and delete_bucket_cors tools. The verb 'Read' precisely conveys the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (read CORS rules) but does not explicitly mention when to use this tool versus alternatives, such as put_bucket_cors or delete_bucket_cors. No exclusions or contextual guidance is provided beyond the obvious name and action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive. The description adds the specific error behavior 'Errors with NoSuchLifecycleConfiguration if none are set,' which is valuable. But it doesn't address return format, permissions, or other behavioral details, so it's only modestly beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action, and every clause earns its place. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For this simple read tool with two parameters and no output schema, the description covers the core purpose and a key error condition. It lacks output structure detail, but that's not required given the nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with bucket and region already described in the input schema. The tool description adds no additional parameter-level detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Read' identifies exactly the action on the specific resource 'bucket's lifecycle rules.' Distinguishes from sibling tools by naming the lifecycle-specific resource and adding the NoSuchLifecycleConfiguration error detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the operation as a read, which implies when to use it (to inspect lifecycle rules) and contrasts with sibling put/delete lifecycle tools. However, it doesn't explicitly name alternatives or state when not to use it, so it misses the top bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a modifier (readOnlyHint=false) and non-destructive creation (destructiveHint=false). The description adds significant behavioral context: it clarifies that the creation produces an identity with zero permissions, and it discloses the return value (application id). This goes beyond what annotations convey, though it omits details like rate limits or eventual consistency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the purpose and type, second states the critical limitation and next steps. It is front-loaded and efficient. It could be slightly more structured (e.g., explicit return value mention), but it conveys all essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by explaining the return value and the next steps. It covers the core purpose, scope, and workflow. It does not mention prerequisites like authentication or permissions, nor error cases, but these are often implicit. The sibling tools list provides additional context for chaining operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have detailed descriptions in the schema). The tool-level description does not add new semantic information about the parameters themselves; it only mentions the return value. The schema already provides naming conventions and constraints, so the description meets the baseline but adds minimal additional param value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies 'Create a new IAM Application (a non-human identity) in this Organization.' It distinguishes this tool from user creation or other identity tools among siblings by explicitly stating it is for non-human identities. It also clarifies that it only creates the identity without permissions, setting clear boundaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that the application has no permissions until a policy is attached, and names the specific follow-up tool (scaleway_iam_create_policy). It provides clear next-step guidance. However, it does not explicitly mention when not to use this tool or alternative approaches (e.g., using groups), which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and not destructive. The description adds valuable behavioral context: it is a compact view that omits the public key text, and it requires specific permissions. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences, each delivering essential information: purpose + context, behavioral trait + alternative, permission requirement. No wasted words, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional parameters, and the description covers purpose, behavioral limitation, and permission. However, there is no output schema, and the description does not mention what fields are returned (e.g., id, name, creation date). It only says 'compact view' without specifying the return structure, leaving an incomplete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add any meaning beyond what the schema already provides for the two parameters (`name` and `project_id`). It mentions 'Project' in the main text but does not elaborate on parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists SSH public keys registered in a Project, with a specific verb and resource. It distinguishes itself from the sibling `scaleway_iam_get_ssh_key` by noting it is a compact view that omits the public key text, and explicitly directs users to that tool for full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear alternative (`scaleway_iam_get_ssh_key`) for when the full key is needed, and states the required permission (`SSHKeysReadOnly/FullAccess`). It implies usage context (listing keys for a project) but does not explicitly list exclusions or scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=false, destructiveHint=false, idempotentHint=true, indicating a safe, idempotent mutation. The description adds value by revealing that the tool explicitly refuses special/managed groups and only modifies passed fields (partial update semantics). This is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, each serving a purpose: the first states what fields change and the partial-update behavior, the second warns about restrictions. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the action, scope, and special-case restrictions. While it doesn't describe return values (acceptable given no output schema), it could be improved by mentioning prerequisites like group existence or authentication requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only group_id has a description). The description adds no parameter-specific details beyond the schema's field names and types. For a 4-parameter tool, this is insufficient – the description should explain constraints like description maxLength or tag semantics to help the agent construct valid calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Change' and 'Refuses') to state the tool modifies an IAM group's name/description/tags. It clearly distinguishes this update operation from sibling tools like 'scaleway_iam_update_application' or 'scaleway_iam_update_user' by targeting the 'Group' resource explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Only passed fields change', implying a partial update pattern, and warns that Scaleway-managed/special groups are refused tool-side. However, no explicit alternative tool is named for modifying those restricted groups, and there is no guidance on when to use this versus other update tools like 'scaleway_iam_update_policy'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by stating the password is supplied by the caller, takes effect immediately, and warns about account-takeover power. It also mentions that session invalidation is unverified. These details are not in the annotations (destructiveHint: true, idempotentHint: true, etc.) and add valuable behavioral context. No contradiction with annotations is present; the idempotentHint is technically consistent with setting the same password.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the action. It is informative without being overly verbose. Each sentence adds value: action, security implication, parameter guidance, and uncertainty. Minor wordiness (e.g., 'ADMIN-SET password reset:') is acceptable given the sensitivity. The structure is logical and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (security-sensitive mutation, no output schema), the description covers essential aspects: what it does, how it works, security implications, and uncertainty about session invalidation. It does not explain error handling or response, but the lack of output schema reduces the need. The description is sufficiently complete for an AI agent to understand the tool's behavior and risks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 67% of parameters with descriptions. The tool description repeats the password length constraint, adds 'live-probed', and reinforces the confirm requirement. It also provides security guidance about password generation. However, it does not add new semantic meaning for the user_id parameter beyond the schema. The description adds moderate value over the schema, but not enough to raise the score above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is an admin-set password reset for a Scaleway IAM user, using specific verbs ('set') and resource ('Scaleway IAM User's password'). The title adds 'admin reset' for differentiation. Among sibling tools like scaleway_iam_update_user and scaleway_iam_lock_user, this tool's purpose is distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it is an admin-set password reset, warns about 'account-takeover-grade power', requires confirm=true, and advises on generating and delivering passwords securely. It also notes the uncertainty about session invalidation. While it does not explicitly list alternatives or when not to use, the unique nature of password reset and the clear security context make the guidelines effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations (which only mark openWorldHint=true and destructiveHint=false). It explicitly states the operation is non-destructive (fully reversible), idempotent in effect despite no idempotentHint, and discloses the uniqueness lag behavior. This is valuable for decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense, focused sentences. It front-loads the core action (create empty group) and packs essential guidance (reversibility, no permissions, naming constraints, uniqueness pitfall) without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema, the description covers the core mechanics (empty group, reversible, naming constraints) and a known edge case (uniqueness lag). It does not describe the return value or group ID structure, but given the low complexity (3 obvious params), the coverage is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for documenting parameters. It mentions the 'name' requirement (required, unique, max 64 chars) but does not describe 'tags' or 'description' parameters. Baseline 3 is appropriate because the description adds some but not full compensation for zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new, empty IAM Group, which is distinct from the many sibling tools. It explicitly says the group is empty with no permissions until members or policies are added, making the purpose precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to start building a group from scratch) and warns about a uniqueness lag when re-creating deleted group names. However, it does not explicitly contrast with alternative approaches like using scaleway_iam_update_group or scaleway_iam_create_application for similar identity creation tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already mark destructiveHint=true, the description adds meaningful context by stating the operation is 'PERMANENTLY' and 'Irreversible' and that 'anything using this key stops authenticating immediately.' This goes beyond the raw annotation and informs the agent of real-world side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, front-loaded sentences: the action, the required confirm flag, and the irreversible consequence. Every sentence earns its place, with no redundant or filler language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, fully schema-documented, two-parameter destructive tool with no output schema, the description provides the essential semantics: what is deleted, the required confirmation, and the immediate effect. Together with the annotations and schema, the agent has sufficient context to invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the schema already documents access_key as the key identifier (not secret_key) and confirm as a required true constant. The description re-emphasizes these but adds no new semantic detail beyond the schema, so it meets the baseline for a fully covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'PERMANENTLY revoke an API key by its access_key,' which uses a specific verb and resource and clearly distinguishes this from sibling tools like scaleway_iam_create_api_key or scaleway_iam_update_api_key. It also conveys the destructive nature of the operation, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool is for permanently revoking an API key and requires confirm=true, giving a clear invocation condition. However, it does not explicitly name alternatives or exclusions among the many IAM sibling tools, so the guidance is contextually clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false, making the safe, read-only nature of the tool fully transparent. The description adds value beyond annotations by detailing the exact fields returned (password-renewal enforcement, grace period, lockout threshold, max expiration durations). It does not contradict annotations, so no issue there.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 16 words. It front-loads the purpose ('Read org-wide auth policy') and then lists specific fields. Every word is meaningful; there is no fluff, repetition, or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless, read-only tool with no output schema and a description that enumerates the return fields, the description is nearly complete. The only gap is that it does not explicitly state the return format or whether pagination applies (though with no parameters it's likely a single result). Given the tool's low complexity, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (0 parameters, 0 required), meaning the schema provides complete information. The description does not need to add param-level details. However, it compensates by clearly stating what the return payload covers, which helps the agent understand what data will be retrieved even with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Read org-wide auth policy' and then enumerates the specific security settings returned (password-renewal enforcement, grace period duration, login-attempt lockout threshold, max session/API-key-expiration durations). This clearly distinguishes it from sibling tools like scaleway_iam_get_saml_config (which focuses on SAML) or scaleway_iam_get_user (which focuses on a single user). The verb 'read' and resource 'org-wide auth policy' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for reading organization-level security settings. However, it provides no explicit guidance on when to use this vs. alternatives like scaleway_iam_get_saml_config or scaleway_iam_get_user. It does not mention prerequisites (e.g., required permissions) or exclusions. Since there is only one read tool for security settings, the need for differentiation is low, but the description misses the opportunity to guide an agent on when this call is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds value by specifying the scope ('in this Organization') and the optional filter, which are behavioral traits not captured by annotations. No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the verb 'List', and contains no filler or redundant information. Every word contributes to clarity, making it highly efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema, no nested objects), the description is largely complete. It covers the core behavior and filter. A minor gap is the lack of mention of pagination or return format, but for a list operation, the behavior is predictable. The description is sufficient for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter application_id has a clear description). The tool description adds the organization scope and restates the filter concept, providing marginal additional context. Since the schema already explains the parameter well, the description adds limited new semantic value, earning a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (IAM Policies), and the scope (in this Organization). It also mentions the optional filter by application, which distinguishes it from sibling tools like scaleway_iam_get_policy and scaleway_iam_list_policy_rules. The verb+resource pattern is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells the agent when to use this tool: when you need to list policies, optionally filtered by application. It does not explicitly state exclusions or alternatives (e.g., 'use scaleway_iam_get_policy for a single policy'), but the context of siblings and the clear filter parameter provide sufficient guidance for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond annotations: the org-wide blast radius, potential to lock everyone out, risks to console-based recovery, and the need for pre-verification. It also warns that the PATCH call was not live-verified. This far exceeds the annotation signals (destructiveHint=true, idempotentHint=true) that merely hint at high impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the core purpose but becomes verbose with warnings and procedural notes. Sentences like 'PATCH call itself was not live-verified (deliberately - see docs/gotchas.md)' add important context but could be trimmed or moved to a separate note to improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with high impact, the description covers risks, prerequisites, and fallback measures. However, it does not describe the expected output or response format (no output schema exists). The absence of success/error indicators is a minor gap, but the safety-critical information is well addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for each parameter (confirm, entity_id, single_sign_on_url). The description adds no additional semantic meaning beyond re-stating the confirm requirement, which is already explicit in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Change the registered identity provider's entity_id/SSO URL') using a specific verb ('change') and resource ('entity_id/SSO URL'). It is easily distinguishable from sibling tools like scaleway_iam_enable_saml and scaleway_iam_disable_saml.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: verify IdP configuration before calling, keep a non-SAML login method as fallback, and require confirm=true. It also contrasts with the enable operation (PATCH vs POST). However, it does not explicitly state when to avoid using this tool or list alternative tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the copy is server-side, which clarifies no local data transfer occurs, and explicitly constrains source/destination to the same region. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core operation, and contains no filler. It efficiently states what the tool does, the key benefit, and the main constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description is adequately complete for tool selection and invocation. It covers purpose, mechanism, and the critical same-region requirement. It could mention overwrite behavior or permissions, but these are not essential given the existing metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters already described in the input schema. The description reinforces the same-region constraint and destination semantics but does not add substantial meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the specific action: a server-side copy of one object to a new bucket/key. It distinguishes this from sibling tools like scaleway_s3_put_object, scaleway_s3_get_object, and scaleway_s3_delete_object by stating the operation happens without downloading and re-uploading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use this for server-side copying within the same region. It does not explicitly name alternative tools or state when not to use it, but the same-region constraint and 'without downloading and re-uploading' help the agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds useful behavioral detail: 'ALL CORS rules' are removed, and browsers will regain no cross-origin access (default-deny). This is meaningful context for an agent deciding whether to invoke the tool, and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence that states the operation and its most important consequence. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple configuration-deletion tool with only two well-documented parameters, the description covers the key context: complete removal and the resulting security behavior. It does not address edge cases such as deleting CORS on a bucket without existing rules, but this is a relative minor gap for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both bucket and region in the input schema. The tool description itself adds no parameter-level detail, so it neither complements nor harms the schema's already-sufficient parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Remove ALL CORS rules') on a specific resource ('a bucket'), making the tool's function clear. It also distinguishes this from related S3 operations like get_bucket_cors and put_bucket_cors by emphasizing complete removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear behavioral context: it removes all CORS rules and leaves bucket access in a default-deny state for browsers. It does not explicitly name alternatives like get_bucket_cors or put_bucket_cors, but the use case is evident from the wording and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides key behavioral nuance beyond the annotations: the empty config on fresh buckets (HTTP 200, not AWS-style error), and that the setting is real/toggleable rather than inert metadata. It also corrects an earlier inaccuracy, demonstrating a deliberate focus on accurate runtime behavior. This complements the readOnlyHint/idempotent annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph and contains valuable information, but the history/self-correction sentence ('An earlier version...') is meta-commentary that doesn't help invoke the tool. Front-loaded purpose statement is good, but overall the description is more verbose than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations handle parameter documentation and safety semantics well. The description adds crucial runtime context for an edge case (empty config) and states there is no error on fresh buckets. It does not fully describe the structure of a non-empty configured response, but for a simple read operation with no output schema, the provided information is still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters (bucket with description and region with enum/description). The description doesn't add parameter-specific semantics, but that is okay because the schema does the heavy lifting; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource: 'Read the bucket's S3 default-encryption configuration.' It also distinguishes itself from related S3 config tools by noting the Scaleway-specific behavior, which sets this read operation apart from both AWS and sibling tools like put/delete_bucket_encryption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains that a fresh bucket returns an empty config and that this is a real toggleable setting, which helps the agent know what to expect. It also references put_bucket_encryption/delete_bucket_encryption as the operations that alter the setting, providing useful context for when to use this read. It doesn't explicitly say 'use this instead of X' for all alternative tools, but the use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is established. The description adds useful behavioral context beyond annotations by disclosing that the tool returns an error when the bucket has no policy, which is important for agent expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the operation, the target resource, and a relevant error condition. There is no filler, redundancy, or repetition of schema field names.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read operation with full schema coverage and strong read-only annotations, the description provides enough context: it identifies the resource type, says it reads the policy JSON, and covers the no-policy failure mode. No output schema exists, but 'policy JSON' is sufficient for an agent to infer the return value at a functional level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters: bucket includes a name and example, and region includes an enum plus default behavior. The description adds no parameter-level detail beyond contextualizing that the policy is on an Object Storage bucket, so it stays at the baseline for well-schema-documented tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a specific resource ('Bucket Policy JSON attached to an Object Storage bucket'), clearly distinguishing it from the many sibling tools like get_bucket_tagging, get_bucket_cors, or put_bucket_policy. It also adds a meaningful edge-case signal by stating that an error is raised when the bucket has no policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as a read/fetch operation for an existing bucket policy, which implies the appropriate context for use. It does not explicitly name alternatives or exclusions, but the tool name and sibling set (put_bucket_policy, delete_bucket_policy) make the intended usage reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the specific error behavior (NoSuchTagSet) which is useful behavioral context beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. It front-loads the purpose and adds the key error condition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with good annotations and full schema coverage, the description is complete. It covers the purpose, the error case, and the annotations handle the safety profile. No output schema exists, but the description doesn't need to explain return values for a simple tag read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (bucket and region) are already documented in the schema. The description doesn't add additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a bucket's tags (key/value pairs), which is a specific verb+resource combination. It distinguishes from sibling tools like scaleway_s3_put_bucket_tagging and scaleway_s3_delete_bucket_tagging by focusing on the read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading tags, and the error condition (NoSuchTagSet) provides context for when the tool might be used to check if tags exist. However, it doesn't explicitly state when to use this over alternatives or mention any prerequisites, though the sibling tools make the distinction clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by naming the exact error response when no website configuration is set, which is not derivable from the annotations or schema. This gives the agent useful expectation-setting beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The first sentence leads with the verb and resource, and the second provides a crucial edge-case behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with good annotations and schema coverage, the description is essentially complete. It explains the action and the main error case. It does not detail the returned fields, but the resource name ('static-website configuration') makes the expected return obvious enough for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented with names and descriptions. The tool description adds no additional parameter-level meaning, which matches the baseline score for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and clearly identifies the resource ('a bucket's static-website configuration'). This distinguishes it from sibling getters like get_bucket_cors, get_bucket_tagging, and get_bucket_versioning, which target different bucket configurations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case: retrieve the static-website configuration for a bucket. It also provides a meaningful error condition (NoSuchWebsiteConfiguration) that helps the agent decide whether the tool is appropriate when no configuration may exist. It does not explicitly name alternatives, but the sibling tools make context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explicitly states that existing rules not in the provided list are removed and explains the effect on browser cross-origin access. This is important because annotations only indicate it's a write operation (readOnlyHint: false). There is no contradiction with the destructiveHint: false annotation, as removing rules is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the purpose, the second explains the critical full-replace behavior and its effect. No waste, front-loaded, and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity with a nested rules array, but the schema is rich with descriptions. The description covers the key semantic of full-replace and the effect on access. No output schema is needed for a setter. The description is complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions for all parameters including the nested rules object. The description itself adds no additional parameter guidance, but the schema already provides sufficient meaning. Baseline 3 is appropriate since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set a bucket's CORS rules' with a specific verb and resource. It also explains the critical FULL-REPLACE semantics, distinguishing it from get/delete siblings. This is specific, unambiguous, and directly addresses the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool via the full-replace semantics: it is for replacing the entire CORS rule set. It does not explicitly contrast with get/delete alternatives, but this is easily inferred from the purpose and sibling tool names. The guidance is clear enough for an agent to choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the overwrite behavior and single-part limitation, which are not captured by the annotations alone. It also points to additional constraints (size, encoding) in the content field, adding context beyond the readOnly/idempotent/destructive flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, action-first, and zero fluff. It states the primary purpose, then a key constraint, then an efficient pointer to further details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description covers purpose, scoping, and key constraints via pointer. It does not mention return values or error handling, but the rich schema and annotations compensate, making it sufficiently complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter has detailed semantics (e.g., content size cap, base64 encoding, region default). The description only references the content field, so it adds no new parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Upload (or overwrite) a single object' with a specific verb and resource. It distinguishes from sibling tools like copy/delete/list by emphasizing 'single-part only' and pointing to the content field for size/encoding constraints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly excludes multipart with 'Single-part only' and directs users to the 'content' field for the size ceiling and encoding, which in the schema explains that larger files should go through the console or scw CLI. The alternative guidance is available but not in the main description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about cursor-based pagination with no total_count, default 24-hour window, and compacted per-kind behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively compact given the complexity (8 parameters, pagination, multi-stream behavior). The first sentence front-loads the core purpose and result format. However, it could be slightly tighter—the permission caveat and error resolution might be better placed in a separate note rather than the main flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high parameter count (8), full schema coverage, and lack of output schema, the description provides adequate context for invocation: it explains the pagination memory model, default time window, and behavioral options (full_detail toggle). The sibling context shows this is part of a large audit family, and the description distinguishes well from related audit tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond what the schema already documents—the schema already details defaults, constraints, and filtering behavior for all 8 parameters. The description's mention of defaults (24 hours) and pagination caveats references schema fields but doesn't add new per-parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all three Audit Trail event streams in one chronological feed, with each event tagged by kind (api, auth, or system). This specific verb+resource combination ('list combined events') distinctively maps to the tool's name and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (timeline investigation across streams) and when to use alternatives (per-stream tools: scaleway_audit_list_events, _list_authentication_events, _list_system_events for single stream needs). Also explains permission requirement (AuditTrailReadOnly) and how to resolve permission failures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, non-destructive read operation. The description adds useful context about the behavior: the pagination cap (max_pages), the potential for a 'truncated' indication, and the fact that it filters by Organization scope (not user/workspace). However, it doesn't describe the output format or any edge cases (e.g., when no export jobs exist). With the annotations covering the core safety traits, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first clearly states the tool's purpose, the second connects it to the console UI, and the third provides crucial authorization guidance. It's nearly concise and well-structured, though the third sentence is a bit dense and could be slightly tighter. Still, every sentence adds value with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters with 100% schema coverage, annotations covering safety, and no output schema, the description provides a decent picture. It covers the core purpose, scope (Organization-level), key return fields, and a critical authorization edge case. However, it lacks a description of the return format or how to interpret the response (e.g., what 'last run' and 'last status' look like). For a listing tool, this is still reasonably complete, but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, meaning each parameter is already documented in the input schema. The description adds some contextual value by explaining the 'max_pages' parameter's safety cap and the 'truncated' response field, but it doesn't elaborate on the 'name' filter's exact match requirement beyond what's in the schema. Overall, the description adds marginal value on top of an already well-documented schema, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the Organization's Audit Trail export jobs, specifies the purpose (shipping audit events to Object Storage), and includes details like S3 destination config, last run, and last status. It also distinguishes this tool from other audit tools like query tools and from the other export job tools (create, delete), making its purpose distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it (viewing the Organization's export jobs, like the console's Audit Trail > Exports page) and crucially provides an exclusion scenario: it notes that a read-only credential (AuditTrailReadOnly) may not be sufficient, and if the call fails with permissions_denied, to grant the write permission set. This is excellent guidance, preventing authorization confusion and directing the agent to a specific sibling tool (scaleway_iam_set_policy_rules) for remediation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as destructive, but the description adds context: the session is invalidated immediately, the holder is signed out, and the severity matches API key revocation. This goes beyond the generic destructive flag and explains the real-world impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, and every clause adds value. No fluff or redundancy beyond a useful severity comparison.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter destructive tool with no output schema, the description covers the core purpose and effect. It does not mention idempotency or reversibility, but annotations already convey destructiveness and non-idempotency. The only gap is lack of jti explanation, which is partially mitigated by the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only confirm has a description). The description repeats that confirm must be true but adds no new meaning for jti, leaving the parameter ambiguous. It does not explain what jti is or how to obtain it, failing to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Immediately invalidate one active browser/console session.' It specifies the resource (a JWT session) and distinguishes it from API keys, which separates it from sibling tools like delete_api_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (revoking interactive sessions) and contrasts with revoking API keys, but it does not explicitly name alternatives or provide 'when-not-to-use' guidance. The requirement for confirm=true is mentioned, providing a usage constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveHint=true and readOnlyHint=false, but the description adds rich behavioral context: the operation is permanent, requires confirmation, has an OWNER protection guard, reveals API scoping to guest-users only, and discloses that the happy path is untested. This goes well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at four sentences with the core action front-loaded. Each sentence adds value (permanence, confirm requirement, two guards, testing caveat). The 'Live-probed' sentence is slightly verbose but still earns its place by indicating reliability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers all critical aspects: the irreversible nature, the mandatory confirm parameter, two explicit failure modes (owner refusal and API scoping rejection), and testing transparency. It does not describe the success response format, but that is acceptable given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (confirm has a description, user_id does not). The description mentions 'Requires confirm=true,' which reinforces the schema's const=true for confirm but adds no new meaning. It offers no additional context for the user_id parameter beyond what the schema already provides (uuid, required). The description does not compensate for the missing schema description on user_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'PERMANENTLY remove a User from this Organization,' using a specific verb (remove) and resource (User) with an explicit scope (Organization). Among sibling tools, there are other IAM user actions like lock, unlock, update, delete_mfa_otp, etc., but no other delete user tool, so this is well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the required confirm=true prerequisite and details two guards (refuses to delete the OWNER, API endpoint guest-scoping). It implicitly tells the agent when deletion will fail, though it does not mention alternative tools like lock_user for temporary disablement or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false. The description goes beyond by labeling the action as 'SECURITY-WEAKENING,' explaining the confirm=true requirement to prevent accidental use, and detailing why enrollment is excluded (half-configured states, live-verified endpoint). This adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, followed by warnings and use-case guidance. It is compact with no wasted words, though the last sentence contains internal notes ('flow states unprobed, endpoint shape live-verified 2026-08-18') that may be slightly cryptic for an LLM.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, security impact, required confirmation, legitimate use case, and what is not included. With no output schema and low schema coverage, it provides adequate context for a two-parameter destructive tool. Missing: a brief mention of user_id's format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only confirm has a description). The description reinforces confirm's const=true requirement, which adds value. However, it does not describe user_id (UUID) beyond calling it a 'person,' so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Remove the person's TOTP MFA factor,' which clearly specifies the verb (remove) and resource (TOTP MFA factor). It distinguishes itself from sibling tools by explicitly stating that enrollment is not a tool here, and no other sibling deals with MFA OTP.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Expected legitimate use: lost authenticator recovery,' providing clear context for when to use the tool. It also explicitly warns against using it for enrollment ('Creating/enrolling a new OTP is deliberately NOT a tool here') and explains why, giving strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds empirical confirmation that the API never populates the rules array, which is a behavioral trait beyond what annotations provide. This saves the agent from discovering this limitation through trial and error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all front-loaded with essential information. No wasted words: purpose, list of returned fields, caveat about rules, and cross-reference to the sibling tool. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the main points: what it returns, what it does not return, and an alternative. It could slightly improve by mentioning the output format (e.g., 'returns a single policy object'), but it is already largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no description for policy_id). The description only says 'by id', which redundantly restates the parameter name. It does not explain what a policy_id is, how to obtain it, or any constraints beyond the schema's UUID format. With zero coverage, the description should compensate but fails to add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Get one IAM Policy's metadata') and specifies the resource and returned fields. It explicitly distinguishes itself from siblings by noting that it does not return the rules array and directs to scaleway_iam_list_policy_rules for that, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Does NOT return the actual rules array... Call scaleway_iam_list_policy_rules for the real rules.' This tells the agent exactly when to use this tool (when only metadata is needed) and when to use an alternative (to get rules). No additional context is needed for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by noting the specific error condition when SAML has never been enabled, which goes beyond annotation data and helps the agent handle that case correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states purpose and key fields; the second clarifies the error behavior. No wasted words, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description partially compensates by listing return fields and explaining the error case. However, it does not specify the response structure or additional details like HTTP status codes, leaving minor gaps for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description adds meaning by listing the output fields (status, entity IDs, ACS URL), which helps an agent understand what data to expect, exceeding the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the Organization's SAML SSO configuration, lists specific fields (status, entity IDs, ACS URL), and distinguishes it from sibling tools like enable/update/disable SAML by being the read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It lacks guidance on exclusions or alternative tools, but the error behavior note ('Returns an error if SAML has never been enabled...') provides implicit context about expected state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it is 'live-verified', actually changes the console state to 'Disabled', and is 'not a no-op on inert metadata'. This directly addresses the common concern of whether a delete-style operation truly changes state. The annotation set is thin, and this extra detail helps the agent set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences. The first states the core action; the second adds high-value real-world verification. No filler, no repetition of schema/property names. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter tool, the schema documents those parameters well, and the description plus annotations are enough to know what the operation does and that it is a real state change. No output schema exists, so return values are not required to be explained. The description is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage: bucket is a required string, and region has a clear enum plus a stated default. The description does not add further parameter explanations, but because schema coverage is 100%, this is acceptable and does not lower the score. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove the bucket's default-encryption configuration,' clearly distinguishing this from sibling tools like get/put_bucket_encryption. It also states the observable outcome (reverting the console's 'Encryption type' to 'Disabled'), which makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the context: use this tool to delete/disable a bucket's default encryption configuration. It does not explicitly name alternatives or exclusion cases, but the action is specific enough that no reasonable alternative is suggested by the sibling list. It stops short of full when-to-use/when-not-to-use guidance, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds significant value by explaining the immediate impact on principals ('Any principal relying only on this policy loses access to the bucket immediately') and the confirm requirement, which goes beyond what annotations state. This helps the agent anticipate consequences, so above baseline but not over-the-top.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, both front-loaded with the core action and the most critical detail (confirm=true). It wastes no words and earns every sentence, making it highly scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with no output schema, the description covers what matters: the action, the required confirm flag, and the consequence of immediate access loss. Combined with annotations, the agent has all necessary behavioral and safety info. It is complete given the low complexity and rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter (bucket, region, confirm) already having descriptions. The description mentions 'Requires confirm=true' which mirrors the schema's const constraint, adding no new semantic info. Baseline 3 is appropriate since the schema already handles parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Remove a bucket's Bucket Policy entirely,' specifying the exact action and resource. It distinguishes from siblings like get_bucket_policy and put_bucket_policy by focusing on removal. It also adds a key consequence (immediate access loss) that aids selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to delete a policy) and explicitly requires confirm=true, which is a critical usage condition. However, it does not mention alternatives or when not to use it, though the sibling list makes the context clear. It falls short of an explicit 'when-not' or naming alternatives, so it gets a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond these by explaining how visibility is derived (from ACL grants, with the AllUsers group check) and noting that it returns raw grants as well. This contextualizes the read behavior and output, which is useful for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no fluff. It front-loads the core action ('Read a bucket's visibility'), then provides the derivation logic and return content. Every sentence earns its place, making it easy for an agent to quickly grasp the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, read-only operation), the description is fully complete. It explains the visibility derivation, the return of raw grants, and the safe read nature (reinforced by annotations). There is no missing information that would hinder selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: bucket has 'Bucket name.' and region has 'Region to operate in. Defaults to the server's configured region (fr-par).' The description adds no additional parameter-specific information beyond what the schema already provides. Since schema coverage is high, the baseline score of 3 applies, and the description doesn't enhance it further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read a bucket's visibility, derived from its ACL grants'. It specifies the exact resource (bucket visibility) and the verb (Read), and differentiates itself from sibling tools like scaleway_s3_set_bucket_visibility by focusing on reading vs. setting. The derivation logic ('public' if anonymous AllUsers group holds any grant) adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for reading visibility, as opposed to the sibling scaleway_s3_set_bucket_visibility for setting it. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions (e.g., 'if you need to change visibility, use the set tool'). The context is clear but lacks explicit alternative guidance, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: bucket listing in Scaleway is per-region, unlike AWS's account-wide namespace. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. The parenthetical about region-scoping earns its place by highlighting an important difference from AWS, making it genuinely useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, single-parameter, read-only listing tool with rich annotations and a complete schema. The description supplies the critical region-scoping behavior and nothing important is missing for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter, region, including its enum values and default. The description reinforces the 'one region' idea but does not add parameter syntax or format details beyond the schema, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List), the resource (Object Storage buckets), and the regional scope. It is distinct from siblings like scaleway_s3_list_objects, which targets objects rather than buckets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining that buckets are region-scoped on Scaleway, so the agent knows a region must be considered. It does not explicitly name alternatives or say when not to use this tool, but the guidance is still effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the description's main job is to add operational context. It does this by disclosing pagination behavior and the continuation-token flow, plus the folder-like delimiter grouping. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the main action and object first and only essential operational details (pagination) afterward. Every clause earns its place and no schema details are needlessly repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with rich inline parameter descriptions, this is contextually complete: it states the scope, optional filtering, delimiter grouping, and pagination contract. The absent output schema is mitigated by references to returned continuation tokens and common_prefixes in parameter docs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents all six parameters including defaults, max, enum, and continuation semantics. The description reinforces prefix/delimiter/pagination but adds little meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List object keys in a bucket,' a specific verb+resource statement that clearly distinguishes this from sibling S3 operations like listing buckets, getting an object, or deleting objects. It adds relevant scope modifiers (prefix, delimiter, pagination) without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly communicates when to use the tool: to enumerate keys in a bucket, optionally narrowed by prefix or grouped by delimiter. It does not explicitly name alternatives or exclusions, but the context is clear enough for a list-objects task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial detail that tags not in the provided list are removed. This elaborates on the destructive behavior beyond what the annotation flag alone conveys. It also clarifies idempotence by stating the list becomes the complete tag set, though it doesn't explicitly mention idempotency. Overall, it adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence (about 24 words) that front-loads the action and resource, then adds the critical full-replace nuance. No redundant phrases or fluff—every word earns its place. It is ideal for quick parsing by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 100% schema coverage and complete annotations, the description covers the essential semantics (full replace) and leaves no gaps about what the tool does. No output schema exists, and the tool's behavior is fully captured by the description and annotations. It is complete for its context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reinforces the 'tags' parameter's semantics by stating 'the provided list becomes the complete tag set', which aligns with the schema's 'COMPLETE tag set to apply'. However, it adds no new information beyond the schema descriptions for the other parameters (bucket, region). It doesn't compensate beyond the schema, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Set a bucket's tags' and explicitly defines FULL-REPLACE semantics, clearly distinguishing this from sibling tools like get_bucket_tagging and delete_bucket_tagging. The title and description both convey the exact action and resource, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly mention alternatives like 'use get to read or delete to remove all', the description makes it clear this tool is for replacing the entire tag set. The full-replace semantics implies when to use it (when you want to set the complete tag set) and implicitly warns against using it for partial updates. This is nearly explicit enough without naming siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations by revealing immediate backfill behavior, non-deletion of objects by delete_export_job, and the need for bucket cleanup. It also includes a live-verified date and troubleshooting for permissions_denied, providing strong operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, each carrying distinct, high-value information including purpose, prerequisites, side effects, and permissions. Slightly long but every sentence is necessary; front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 8 parameters and no output schema, the description comprehensively covers preconditions, side effects, monitoring, and permission requirements. It also references related tools for bucket creation and job deletion, giving a complete operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions; the description mostly reiterates bucket and confirm semantics already present in the schema. It adds no new parameter-level details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates an export job for Audit Trail events to an S3-compatible Object Storage bucket. The verb 'create' and resource 'export job' are specific, and it differentiates from sibling delete/list export job tools by describing the shipping destination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites (bucket must exist and be writable), a required confirm=true, and post-creation monitoring via scaleway_audit_list_export_jobs. It also mentions the permission boundary (read-only covers only query tools) and a remediation step, making it clear when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations that mark it as read-only and non-destructive, the description discloses return characteristics (last handful, no filters/pagination) and a specific permission requirement. It also hints at error behavior by noting what happens if permissions are missing. Minor omission: no mention of rate limits or result size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose+constraints, usage hint, permission+error recourse. No fluff, no repetition. Appropriate length for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers what the tool does and returns at a high level ('snapshot of most recent Audit Trail events'). It explains the no-filter/no-pagination behavior. While it doesn't detail the exact structure of returned events, for a 'quick check' tool this is sufficient, especially since sibling tools likely have richer output documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add new per-parameter semantics beyond what the schema already provides. The schema already describes region (with default), project_id as optional filter, and full_detail as boolean. The description's permission note applies globally, not to specific parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resource: 'Get the snapshot of most recent Audit Trail events'. It clearly states constraints: 'the last handful of api events, no filters, no pagination'. This distinctively separates it from sibling tools like scaleway_audit_list_events which are paginated queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use: 'Handy as a cheap anything happening lately? check before running a full paginated query'. Provides prerequisite: 'Requires the AuditTrailReadOnly permission set on THIS server's own credential' and a fallback action referencing sibling tool scaleway_iam_set_policy_rules. This contextualizes usage well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds value by stating that membership grants permissions immediately, existing members are preserved, and the tool refuses non-editable groups. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each conveying distinct information: the core action, immediate effect, preservation of existing members, and refusal conditions. No filler words; front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple member addition tool with no output schema, the description covers the action, immediate effect, preservation, and refusal. The sibling tools are distinct enough. Minor gap: no mention of error handling or result status, but the description is sufficient for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that both user_id and application_id can be provided simultaneously ('both may be given at once - it's not either/or'), which is not explicit in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds one User and/or one Application to a Group in a single call. It distinguishes from siblings by noting existing members are preserved and that it refuses non-editable groups, which differentiates it from set_group_members and remove_group_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use this tool: for adding a single user/application while preserving existing members. It also mentions refusal conditions (non-editable groups). However, it does not explicitly contrast with related tools like add_group_members (plural) or set_group_members, leaving some inference needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description goes beyond these by detailing client-side validation that rejects private keys, the consequence of granting broad SSH access, and the caution against speculative calls. No contradiction with annotations; the description adds significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence conveying the core action and the most critical constraint (no private keys), and the second providing the broader impact and a warning. Every word is purposeful; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, what input constraints it enforces, and the high-level behavioral impact. It does not specify the return value (no output schema required), but provides enough context for an agent to understand the tool's seriousness and scope. The warning against speculative use fills a gap that annotations do not address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already explained in the input schema. The description only reiterates that public_key must be a public key, which is already stated in the schema. No additional parameter-level meaning is added beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Register' and the resource 'PUBLIC SSH key', explicitly distinguishing it from private key operations and from sibling tools like list/update/delete SSH keys. It also specifies the scope of access granted, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual guidance by warning 'don't call speculatively' and explaining that the action grants SSH access to any instance/service trusting keys from this Project. It does not explicitly list alternatives (e.g., listing existing keys before creating), but the warning and context are clear enough to inform appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that a real email is sent, that the semantics are unverified, and that the `type` field default was inferred. This adds critical behavioral context about side effects and uncertainty, which annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, then adds necessary warnings and caveats. While three paragraphs are slightly verbose, each sentence contributes to transparency or usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the return value or expected response (e.g., user ID, confirmation). No output schema exists, so the description should have covered what the agent receives on success. It also does not address idempotency implications (e.g., multiple calls with the same email will send multiple emails). The unverified warning honestly admits gaps, but completeness is still moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 75% of parameters with descriptions. The description adds nuance: the constraint 'Requires confirm=true' reinforces the schema's const, and the note on the `type` default being 'inferred, unverified' provides extra context beyond the schema's default and description. Tags remain undescribed, but overall the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a human User by email,' specifying the verb and resource. This distinguishes it from sibling tools like scaleway_iam_create_application or scaleway_iam_create_api_key, which create different IAM resources. The title reinforces the dual action of creating and inviting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns 'never call speculatively' and states 'Requires confirm=true,' providing clear usage constraints. However, it does not directly compare this tool to alternatives (e.g., creating an application for non-human users), though the purpose inherently differentiates it. The warning about real email delivery is a strong guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description exceeds the destructiveHint annotation by detailing the exact scope of destruction: deletion of all owned API keys, policy detachment, and immediate, irreversible authentication loss. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler. The first sentence front-loads the primary action and consequences. Every sentence earns its place by providing essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, irreversible tool with no output schema, the description fully covers what the tool does, its cascading effects, the required confirmation flag, and real-world implications. The agent has enough information to understand the operation and its risks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (only confirm has a description). The description mentions 'Requires confirm=true' but adds nothing beyond the schema's own description for confirm. The application_id parameter receives no explanation about its format or how to obtain it, leaving the agent without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes an IAM Application and enumerates the cascading effects (deletes API keys, detaches policies). It distinguishes itself from other IAM deletion tools like delete_api_key or delete_policy by targeting the application resource specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires confirm=true and warns about irreversible credential failure. It does not, however, contrast this destructive deletion with alternative actions like updating or disabling the application, which are available among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description adds that the action is permanent, requires explicit confirmation, details the deprovisioning behavior, and includes a technical note about the endpoint implementation (fetches config first, uses top-level DELETE). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the key point ('PERMANENTLY disable SCIM'), and each sentence adds important information: confirm requirement, immediate effect, deprovisioning risk, and technical implementation detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, required parameter, behavioral consequences, and even a technical note for correctness. It is nearly complete for an agent to decide and invoke safely. The only minor gap is the lack of mention of the return value or confirmation response, but that is not critical given the destructive nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions 'Requires confirm=true', which reinforces the schema's 'const: true' description but adds no new syntax or format details. The parameter semantics are adequately covered but not enriched beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'PERMANENTLY disable SCIM', clearly stating the action (disable) and resource (SCIM provisioning for the Organization). It distinguishes itself from siblings like scaleway_iam_enable_scim and scaleway_iam_get_scim_config by its destructive nature and the confirm requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires 'confirm=true', warns that provisioning stops immediately, and highlights the critical deprovisioning risk: 'if the IdP was the mechanism offboarding relies on to remove departed Users, that stops working silently until re-enabled.' This provides strong context on when to use and the consequences, though it does not explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations which already mark the tool as read-only and non-destructive, the description explicitly states that the secret_key is never included in the list and is only visible at creation. This is critical for an agent to understand the tool's output limitations and avoid expecting secrets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core action and immediately deliver the most important behavioral note (secret key visibility). No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema) and strong annotations, the description covers the essential use case. It could be slightly improved by mentioning whether pagination is used, but the readOnlyHint and openWorldHint mitigate this. The description is adequate for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a clear description for the single parameter (application_id) with 100% coverage. The tool description only restates the optional filter, adding no new semantic value. Baseline 3 is appropriate since the schema handles the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: list API keys in the organization. It distinguishes itself from sibling tools like list_users or list_policies by specifying the resource (API keys) and scope (Organization). The parenthetical about the secret key adds unique behavioral context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool (to list API keys) and the optional filtering by application. While it doesn't explicitly list alternatives, the purpose is self-explanatory given the sibling tool names (e.g., list_applications, list_users). A slight improvement would be to mention that for deeper filtering or search, other tools exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds context about returning 'permission sets + scope' but doesn't disclose details about pagination limits, whether the returned list is complete or chunked, or what happens if the policy_id doesn't exist. Baseline 3 is appropriate given good annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence defines purpose and key details, the second provides usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with 1 parameter, no output schema, and no nested objects. The description covers the core purpose, scoping guidance, and what the output contains. It could mention whether the tool returns empty vs non-empty results differently, but overall it's complete for a straightforward read-only list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that policy_id is required and effectively explains the return semantics (permission sets + scope as project_ids or organization_id), which adds value beyond the schema's uuid format definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets actual rules (permission sets + scope) attached to a Policy. The verb 'list' and resource 'policy rules' are specific and distinct from siblings like scaleway_iam_get_policy or scaleway_iam_set_policy_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool ('see what a policy really grants') and contrasts it with scaleway_iam_get_policy, telling the agent not to use that alternative for this purpose. This is exemplary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and no destructiveHint, so the tool is clearly safe to call. The description adds value by warning that the token secret is never included—a critical detail for agents expecting the full token value. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that fully convey purpose and a critical behavioral caveat. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter, no output schema, and excellent annotations. The description is largely complete, but it does not describe the output format (e.g., list of tokens with fields like id, name, status) or pagination behavior, which could be useful for agents. Still, given the low complexity, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage and clearly documents the scim_id parameter with its format (uuid) and a cross-reference to scaleway_iam_get_scim_config's id field. The description does not repeat parameter details, which is acceptable given complete schema coverage. A slight deduction because the description could mention that scim_id is required and comes from another action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists SCIM provisioning tokens, specifying the exact resource (SCIM tokens) and the verb (list). It distinguishes itself from related tools like scaleway_iam_create_scim_token or scaleway_iam_delete_scim_token by mentioning the token secret is never included, which is a key behavioral distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly indicates when not to expect the token secret (only visible at creation via another tool). However, it does not explicitly state when to use this tool versus other IAM list tools (like list_api_keys), but the unique resource type (SCIM tokens) and the schema dependency on scim_id from get_scim_config make it clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing the immediate loss of permissions, the need for confirm=true, and the refusal to operate on Scaleway-managed or non-editable groups. These are critical behavior details not implied by destructiveHint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three focused sentences: the action, the mandatory confirmation, and the high-impact consequences and constraints. Every sentence carries essential information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and lack of output schema, the description covers the most critical risks: permission loss, confirmation requirement, and limitations on editable groups. It could be slightly more complete by specifying whether one of user_id/application_id is mandatory or both are allowed together, but overall it is sufficient for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds slight clarity by noting 'one User and/or one Application,' but it does not explain the exact relationship between user_id and application_id (e.g., whether exactly one must be provided) or add value beyond the schema's existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Remove one User and/or one Application from a Group,' which is a specific verb+resource statement that clearly distinguishes this from sibling tools like add_group_member or set_group_members. The title also reinforces the single-member removal scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool (removing a single member) and highlights the requirement for confirm=true. It also provides cautionary guidance about checking whether the member relies solely on this group's permissions. However, it does not explicitly name alternative tools or state when not to use it (e.g., use set_group_members to replace all members).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint: false and idempotentHint: true, so the description does not contradict them. The description adds clarity by explicitly stating that the key material is immutable, which is critical behavioral context not in annotations. It does not cover rate limits or authorization requirements, but the annotations already signal safe mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, clear and direct. No filler. Front-loaded with the primary action, followed by important limitation. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 2 required params, the description is adequate. It explains the operation, the one constraint (key material immutability), and the alternative action. It misses potential side effects or confirmation of success, but given the simplicity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description clarifies that 'name' is the new name and 'ssh_key_id' identifies the key. It adds value by explaining what the parameters are for, beyond the schema's basic types. However, it does not specify minimum length implications or provide examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Change an SSH key's name.' It specifies the verb (change) and the resource (SSH key name), and distinguishes from the sibling tool scaleway_iam_create_ssh_key and scaleway_iam_delete_ssh_key by explicitly stating that key material cannot be modified here and must be recreated separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (to change the name) and what not to do (cannot change public_key/fingerprint), directing the agent to delete and recreate for key rotation. It does not, however, mention prerequisites or alternative tools by name among siblings (e.g., scaleway_iam_get_ssh_key to fetch details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as non-readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral context: the confirm parameter is a safeguard ('Requires confirm=true') and changing username without proper notification will prevent the user from signing in next time. This disclosure of side effects on user login ability goes beyond the structured annotations. The 'Live-probed on bogus ids only (404 shape)' comment adds transparency about how the tool validates the user_id (by making a live existence check and returning 404 for invalid IDs). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences that are front-loaded and each provide distinct value: first sentence states purpose, second sentence gives critical usage condition and consequence, third sentence adds testing behavior detail. No unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple mutation with 3 required parameters and no output schema, the description covers the main behavioral aspects: purpose, required parameter condition, side effects, and validation behavior. It does not explicitly describe what the API returns (success/error), but since no output schema is provided, this is not a major gap. The description is sufficient for the agent to understand when and how to call the tool and what to communicate to the user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (user_id lacks description; new_username and confirm have basic descriptions). The description adds value by explaining why confirm is required (to force user notification) and the consequence of not setting it correctly. The 'new_username' parameter is adequately described in the schema. The description does not add detail for user_id, but UUID format is standard. Overall, the description enriches the meaning of the confirm parameter beyond the schema's 'Must be explicitly true' by linking it to the login impact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state this tool changes the username (login identity) of a Scaleway IAM user. The description explicitly says 'Change what the person types to LOG IN', which is a specific verb+resource combination. It differentiates itself from sibling tools like scaleway_iam_update_user (general update) and scaleway_iam_update_user_password (password change) by focusing uniquely on the username.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: 'Requires confirm=true - they must be told, or they cannot sign in next time.' This warns the agent that setting confirm to true is not just a formality but that the user must be informed to avoid lockout. It implies when to avoid using (if user cannot be notified) but does not explicitly name alternative tools or scenarios when not to use it. The guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only and destructive, and the description adds meaningful context: credentials are not exposed, the URL is time-limited, and put exports a write capability outside the MCP boundary requiring confirmation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core function, followed by use cases and a safety caveat. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema descriptions and annotations, the description covers purpose, usage context, and the key safety caveat. It does not describe the return value shape, but the URL output is implied and no output schema exists, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 7 parameters. The description adds some cross-parameter context (operation='put' requires confirm=true), but this is also stated in the schema, so the added semantic value is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Generate') and resource ('presigned URL for one object'), clearly states GET/PUT access and time-limitation, and distinguishes itself from sibling inline-transfer tools by mentioning 'content too large for scaleway_s3_get_object/put_object's inline transfer.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool: handing a download/upload link outside MCP or for content too large for inline transfer. It also names the alternative tools and gives operational guidance that operation='put' requires confirm=true.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation block already declares readOnlyHint=true, destructiveHint=false, idempotentHint=true, which tells the agent this is a safe read operation. The description adds behavioral context beyond annotations: it explains the rules are preconfigured (cannot be created/deleted), the permission escalation needed, and that the tool corresponds to the console's Audit Trail > Alerts page. There is no contradiction with the annotations. However, the description does not detail the output format or pagination behavior beyond what the schema hints (max_pages).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loads the core purpose. Every sentence adds information: the first defines what the tool does and its context, the second clarifies the nature of the rules, the third covers permissions. No fluff. Slight improvement would be to merge the permission context more concisely, but overall it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, the description does not need to explain return format. The annotations (readOnlyHint, destructiveHint, idempotentHint) are strong, and the description covers purpose, usage, permissions, and sibling distinction. It is slightly incomplete on output details (e.g., field names in response), but for a list tool with solid annotations, this is acceptable. Could be more complete about pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that 'region' defaults to the server's configured region and that 'status' filter applies to the list. It also hints at pagination via max_pages. However, the description does not elaborate on the meaning of each parameter beyond what the schema already says; it complements but does not significantly expand.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists Scaleway's preconfigured Audit Trail alert rules for the Organization, including their status. It explicitly distinguishes itself by noting these are preconfigured by Scaleway and cannot be created or deleted, which differentiates it from sibling tools like scaleway_audit_list_custom_alert_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: for Scaleway-defined alert rules only, and mentions that creation/deletion is not allowed (only enable/disable). It also explains the permission requirements beyond minimal read access, and even suggests a corrective action (using scaleway_iam_set_policy_rules) if a permission error occurs. This offers clear context for when and how to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond what annotations provide (destructiveHint=true). It details the permanent nature, the need for confirm=true, the immediate loss of policy access for former members, and the tool-side check that prevents deletion of special groups. This fully compensates for the lack of behavioral detail in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at under 30 words but packs critical information: permanent deletion, confirm requirement, irreversibility, policy impact, and protection for special groups. Every sentence serves a distinct purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 simple parameters, no output schema, and high schema coverage, the description is complete. It covers the deletion behavior, required confirmation, downstream effects, and guardrails. Adds exactly what an agent needs to understand the tool's impact beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for both group_id and confirm parameters. The description adds context about the confirm parameter being required for safety but doesn't elaborate on group_id beyond what the schema provides. Baseline 3 is appropriate since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'PERMANENTLY delete a Group' and emphasizes irreversibility, which is a very specific verb+resource combination. It distinguishes itself from sibling tools like scaleway_iam_create_group or scaleway_iam_update_group by highlighting the permanent destruction aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the required 'confirm=true' parameter for safety, and warns about irreversible consequences including policy access loss. It also states it refuses Scaleway-managed groups (all_users/all_applications) tool-side. However, it doesn't explicitly name an alternative tool for safer deletion or mention when NOT to use it aside from protected groups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by specifying what fields the response includes: 'status, type, locked, MFA flags'. This is a useful elaboration beyond the raw annotations, letting the agent know the breadth of data returned. No description of rate limits or auth is given, but for a simple read operation the annotations suffice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence: 'Read one human User by id - full profile incl. status, type, locked, MFA flags.' Every word adds value – the verb, the target, the uniqueness ('one'), and the specific fields. No wasted text, perfectly scoped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with rich annotations, the description is complete. It covers what the tool does, what data it returns, and the required input. It doesn't explain return format, but no output schema exists and the behavior (returning a user object) is straightforward. The sibling list of users provides the ID workflow, which is implicitly referenced via schema description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with a single required parameter 'user_id' that already includes a description: 'User ID from list_users.' The description adds no further parameter details, but the schema already links it to list_users for discovery. Since schema coverage is perfect and the description reinforces the parameter's role, this is slightly above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb-resource pair 'Read one human User by id' and immediately clarifies scope: 'full profile incl. status, type, locked, MFA flags'. This distinguishes it from sibling tools like scaleway_iam_list_users (which lists users) and scaleway_iam_update_user (which modifies). A single, focused tool for getting a detailed user profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to use when you need a complete profile of a single IAM user, identified by user_id. The sibling context includes list_users for obtaining that ID, so an agent can infer the workflow. There are no explicit exclusions or mentions of when not to use it, but the purpose is clear enough that an agent would choose this over a list or mutation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds valuable behavioral context: the bucket is private by default, and the Object Lock create-time flag is silently ignored on Scaleway, requiring a specific post-creation sequence. This discloses a non-obvious platform behavior that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loaded with the core action. Every sentence earns its place: the first states what the tool does, the second directs follow-up configuration, and the third warns about the Object Lock limitation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter creation tool with no output schema, the description is complete. It covers the default state, post-creation configuration path, and a critical platform-specific caveat, giving an agent everything needed to invoke the tool and proceed correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (bucket and region), including an example and enum values, so the description adds little parameter-level meaning. The 'private by default' note is behavioral rather than parameter-specific, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Create a new, empty Object Storage bucket') and clearly states the default visibility ('private by default'). It distinguishes from sibling tools by explicitly directing configuration tasks to the scaleway_s3_*_bucket_* config tools, making the creation-focused purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool and what to do afterwards, naming the config tools for post-creation setup and scaleway_s3_enable_object_lock for Object Lock. It does not explicitly state when not to use the tool, but the follow-up guidance effectively differentiates this creation step from configuration and object-lock enabling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds critical context beyond that: the deletion is permanent, the bucket must already be empty, confirm=true is mandatory, and the operation fails if objects exist. This significantly clarifies behavior and safety constraints, going well beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys all critical information: permanence, the empty-bucket requirement, the confirm flag, and the failure mode. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with rich annotations and a fully descriptive schema, the description covers the essential behavioral aspects (permanence, prerequisites, failure condition). No output schema is needed for a delete operation. The description is complete and helps the agent invoke the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a descriptive comment. The description's mention of 'confirm=true' reinforces the confirm parameter but does not add new semantic meaning beyond the schema. With full schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'PERMANENTLY delete an empty Object Storage bucket.' The verb 'delete' is specific, the resource is identified, and the term 'empty' distinguishes this from tools that delete objects within a bucket. It also differentiates from sibling tools like scaleway_s3_delete_object, scaleway_s3_delete_bucket_tagging, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the bucket must be empty, and confirm=true is required. It states a failure condition ('Fails if the bucket still contains objects'), which implicitly guides the user to empty the bucket first. However, it does not explicitly name alternatives like scaleway_s3_delete_objects or suggest a safe deletion workflow, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it reveals that versioning can be frozen at Enabled when Object Lock is enabled, which is a critical constraint the agent must know. It also provides a live-verification date, enhancing trust. This goes beyond the readOnlyHint and idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded: the first sentence states the purpose and return values, the second provides a critical caveat. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This simple read tool is fully covered: both parameters have schema descriptions, annotations cover safety, and the description explains the return values and a special case (Object Lock). No output schema exists, but the return values are defined in text. The description is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, both parameters are already well-documented in the schema. The description does not add new parameter semantics beyond referring to 'bucket's versioning state', so it meets the baseline but adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read a bucket's versioning state' and enumerates the possible return values ('' , 'Enabled', 'Suspended'). This distinguishes it from sibling tools like set_bucket_versioning (write) and get_object_lock (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for use (reading versioning state) but does not explicitly mention alternatives or when-not-to-use scenarios. Since the getter/setter pair is implied by the tool name, this is clear context without exclusions, but it lacks explicit alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read, but the description adds crucial behavioral context: ObjectLockConfigurationNotFoundError means NOT enabled, and there is no disabled state—the config simply does not exist until enabled. This explains an edge case that the schema and annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and every sentence adds value—especially the error-semantics note. No wasted words or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only configuration check with one required parameter, the description fully covers the essential behavior and error semantics. No output schema is present, but the tool's simplicity and the explanation of the not-enabled condition make it sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both bucket and region (100% coverage), so the description need not add parameter details. It does not add meaning beyond the schema, but the schema already does the heavy lifting, justifying the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads whether Object Lock (WORM protection) is enabled on a bucket, using a specific verb and resource. It also distinguishes from the sibling tool scaleway_s3_enable_object_lock by focusing on the read aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to check if Object Lock is enabled, with important semantics about the error meaning not-enabled. It does not explicitly name alternatives or exclusions, but the read-vs-write contrast is implied through the sibling tool list and the description's wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so the description does not need to repeat those. The description adds valuable behavioral context beyond the annotations: it verifies that the setting is real and visible in the console, confirming it takes effect immediately. This goes beyond what structured metadata provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first states purpose, second adds verification detail. No fluff, front-loaded with the key action. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple set operation with few parameters and no output schema. Annotations cover safety and idempotency. The description provides the action, the specific algorithm, and verification in the console. It is complete for an agent to use correctly without further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (bucket and region have descriptions; algorithm has a const but no description). The description reiterates AES256 but adds no additional info for bucket or region. The schema already covers the essentials, so the description provides minimal added value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set the bucket's S3 default-encryption configuration (AES256)'. This is specific with verb + resource + configuration detail. It distinguishes from sibling tools like get_bucket_encryption and delete_bucket_encryption by naming the 'set' operation and the encryption algorithm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to set default encryption) but does not explicitly mention alternatives or when not to use it. However, the context from sibling tools (get/delete encryption) and the tool's name is clear enough for an agent to infer appropriate usage. The live-verification note adds confidence in using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation is atomic and full-replace (disables rules not listed), requires confirm=true, and has specific permission needs beyond read-only. The annotations (destructiveHint=true, idempotentHint=true) are consistent and the description adds valuable context about the 501 error and non-retry advice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but every sentence is useful and well-structured. It front-loads the core purpose and then provides context, alternative, requirements, and a caveat. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive full-replace, permission requirements, API caveat, alternative), the description covers all needed aspects: purpose, when to use, prerequisites, error handling, and fallback. The absence of an output schema is acceptable since the tool is a mutation and the description mentions the error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are already clear. The description reiterates the full-replace semantics for enabled_custom_alert_rule_ids and the confirm requirement, but does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (replace) and resource (the complete set of enabled custom alert rules), and explicitly distinguishes from the sibling tool scaleway_audit_set_custom_alert_rules_enabled by noting the difference between full-replace and additive semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: prefer the additive sibling unless full-replace is needed, requires confirm=true, and details permission requirements with a specific fallback (scaleway_iam_set_policy_rules). It also includes a caveat about a 501 error and advises not to retry, directing to an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotent, not read-only, not destructive), the description reveals that it only modifies listed rules, requires more than AuditTrailReadOnly, and includes a critical caveat that the API currently returns a 501 error despite documentation. This adds substantial behavioral context not available from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the primary purpose front-loaded, followed by differentiation, prerequisites, permissions, and a caveat. Every sentence serves a purpose, though the caveat paragraph is lengthy. It is slightly verbose but justified by the nuanced context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and a currently non-functional API, the description covers behavior, side effects, permissions, failure handling, and provides a fallback alternative. It is remarkably complete for the agent to make informed decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters (region, enabled, rule_ids). The tool description reinforces the behavior but does not add new parameter-level details beyond what the schema already provides. Given high coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Enable or disable specific custom alert rules by ID') and differentiates itself from the sibling tool 'scaleway_audit_replace_enabled_custom_alert_rules' by emphasizing that it touches only the listed rules, leaving others unchanged.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 (for toggling specific rules), when to use the alternative (to rewrite the whole set), how to obtain rule IDs, required permissions, and how to handle permission errors. It also warns about the current API unavailability and advises against retrying on HTTP 501, directing to a working alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the org-wide blast radius, lockout risk, requirement for confirm=true, and the unverified field shape (best-effort guess). This adds substantial behavioral context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but informative, with warnings and caveats that are necessary for a high-risk tool. It front-loads the purpose but could be more succinct and better structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-risk mutation tool with no output schema, the description covers purpose, risks, prerequisites, and parameter caveats, providing enough context for the agent to invoke it safely. No return value is specified, but that is not required without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with descriptions (100% coverage). The description adds a caveat that the 'certificate' field name is a best-effort guess, which is valuable for the agent to know. It also reiterates confirm=true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Register a new signing certificate for SAML SSO' with a specific verb and resource, clearly distinguishing this from sibling tools like enable_saml, update_saml, and delete_saml_certificate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context on when to use: when adding a new signing certificate, and includes preconditions like verifying IdP config and keeping a non-SAML fallback. It does not explicitly mention alternatives or when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-idempotency (idempotentHint=false). The description adds context about the interplay with S3 bucket policies and the necessity to pre-fetch permission sets. It does not detail response format, error conditions, or required IAM permissions, but the annotations cover the basic behavior adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no fluff. Front-loaded with the core purpose, then branching into specific usage guidance and relationship to sibling tools. Each sentence adds distinct value, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain return values or error handling. It does cover prerequisites (call list_permission_sets), inter-tool dependencies (S3 bucket policy), and parameter conventions. For a create operation with clear annotations, this is mostly complete but missing the output shape slightly reduces the score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (3/6 parameters lack schema descriptions). The description compensates by explaining the naming convention for `name`, the rule structure for `rules` (one rule per scope_type, mutual exclusivity of project_ids/organization_id), and mentions the principal parameters (user_id, group_id, application_id). However, the `description` parameter is not addressed, and schema descriptions for `user_id`/`group_id` are absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an IAM Policy' and specifies the resource, action, and scope. It distinguishes itself from the bucket-level sibling scaleway_s3_put_bucket_policy by explaining the project-wide vs. bucket-specific split. This is a specific verb-resource pairing that differentiates well among the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use this tool ('project-wide half') vs. Bucket Policy for object storage, and warns that both are required. It instructs to call scaleway_iam_list_permission_sets first to obtain exact names and scope types. This provides clear context and exclusions for proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond annotations: the token is returned only once (irretrievable later), requires confirm=true for safety, grants IdP administrative power over users, and includes a FIELD SHAPE UNVERIFIED warning about the description parameter. Annotations show readOnlyHint=false and destructiveHint=false, which align with the description's mutation warning, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, with critical warnings front-loaded. The FIELD SHAPE UNVERIFIED note is slightly redundant with the docs reference, but still valuable. Minor markdown-like formatting (bold) could improve scannability but is not required.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 required parameters with full schema coverage and no output schema, the description covers the essential creation workflow, one-time return behavior, and safety confirm requirement. The FIELD SHAPE UNVERIFIED caveat acknowledges limitations. Slight gap: doesn't mention what happens on success (e.g., response structure) or error cases, but the schema's const on confirm provides sufficient guardrails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant context beyond schema descriptions. It explains the 'confirm' parameter's purpose (acknowledging IdP power), clarifies scim_id comes from scaleway_iam_get_scim_config's id field, and gives an example for description ('e.g. the IdP's name'). The FIELD SHAPE UNVERIFIED caveat also qualifies the description parameter's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a new SCIM token, which is a specific resource creation action. It distinguishes from sibling tools like scaleway_iam_list_scim_tokens (list) and scaleway_iam_delete_scim_token (delete), though it could more explicitly contrast with enable/disable SCIM operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly warns that the token is returned only once and must be captured immediately and configured in the IdP. It states the confirm=true requirement and explains why ('grants the IdP power to create/modify/deactivate Users'). The FIELD SHAPE UNVERIFIED caveat also sets proper expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), description reveals that the deletion is permanent, SSO breaks immediately if the active certificate is removed, and advises checking other certificates first. Also flags that the path is unconfirmed, directing to get_saml_certificate for details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler. First states action and key requirement, second warns of SSO impact and suggests a mitigation, third acknowledges uncertainty and points to another resource. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 3 required params and no output schema, the description covers: permanent nature, confirm requirement, critical side effect (SSO breakage), and cross-references to list and get tools. Could briefly mention what happens if the certificate doesn't exist, but effectively equips an agent to use the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only confirm described). The description mentions the confirm requirement and implies certificate_id via context, but doesn't explain saml_id or the exact relationship between parameters. The parameter names are fairly self-explanatory, but the description could add more clarity on what 'saml_id' refers to (the SAML configuration ID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool permanently removes one SAML certificate with a specific verb ('remove') and resource ('SAML certificate'). Distinguishes from siblings like list, get, add by explicitly focusing on deletion and warning about SSO consequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (delete a certificate) and when-not (if it's actively validating SSO, check list tool first). Also specifies the confirm=true prerequisite, giving clear guidance on safe invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Read' which is consistent with annotations (readOnlyHint, destructiveHint false, idempotentHint true). It adds no additional behavioral context beyond annotations, but there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words, clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the specific metadata returned (jti, audience, expiry, IP, user agent), providing clarity on what the user gets despite lacking an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the jti parameter, and the description reinforces its role as the identifier sourced from list_jwts, making its meaning unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a single JWT session's metadata by its id, listing the exact fields (jti, audience, expiry, IP, user agent), and distinguishes from list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions the id comes from scaleway_iam_list_jwts, implying usage after listing, but does not explicitly contrast with other tools or provide explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral context: the tool returns an error if SCIM was never enabled, and that this is the expected default state. This clarifies a non-obvious behavior beyond the annotations, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (30 words) with no filler. The first sentence front-loads the core purpose and returned fields. The second sentence adds essential error behavior. Every word earns its place; there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the key return fields (id, created_at) and the error behavior. For a simple config read operation with annotations present, this is nearly complete. A minor gap is that the full return shape is not guaranteed, but the stated fields are likely sufficient for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter information since none exist. Schema coverage is 100% (no parameters to describe), and the description adds value by explaining the config fields returned (id, created_at).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read the Organization's SCIM config (id, created_at)', specifying the exact verb (Read) and resource (SCIM config). It distinguishes from siblings like scaleway_iam_enable_scim (write) and scaleway_iam_list_scim_tokens (list) by focusing on reading the config itself and noting the error condition for unconfigured state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Returns an error if SCIM was never enabled - that is the expected default state'. This tells the agent when the tool is appropriate (reading existing config) and normalizes the error scenario. While it does not explicitly list alternatives, the sibling tool set includes enable/disable and list tokens, making the usage context sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses a live-probe result showing that API-key credentials get 403 even with full IAMManager, and speculates that the surface is scoped to own JWTs. It also states it reports errors verbatim. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, but every sentence adds value: purpose, differentiation, live-probe results, and caveats. It is front-loaded with the core purpose and then provides critical usage context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, differentiation, and behavioral limitations well. However, with no output schema, it does not describe the response format (e.g., fields of a JWT object, pagination). Given the low complexity (1 input param), the lack of output details is a minor gap. Still, the error handling description is a plus.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema's description of the audience_id parameter (which already says it's the User ID from scaleway_iam_list_users). The description mentions 'for one User' but that's already implied by the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists active JWT sessions (browser/console logins) for one user. It explicitly distinguishes this from API keys, which is a direct sibling tool (scaleway_iam_list_api_keys), making the purpose unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: for interactive-login session tokens, not API keys. It also warns that the tool may only be callable from a human's own session context, not from an API-key-based server, and reports the 403 error verbatim. This is excellent usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructive and write behavior. The description adds critical detail: 'anyone currently a member but NOT in either list is REMOVED, losing this group’s grants immediately' and 'Refuses Scaleway-managed/special groups', providing transparency beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the core operation, consequences, requirements, and limitations without any extraneous information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the key behavioral aspects: full replace, immediate removal, confirm flag, safety restrictions. It does not detail error scenarios or idempotency (covered by annotations), but remains complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions are adequate. The description adds extra semantic value by explaining the cumulative effect of the arrays ('the given user_ids/application_ids become the COMPLETE member list') and practical usage ('Pass empty arrays to remove everyone'), justifying a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'FULL-REPLACE a Group's membership' and clarifies that the provided arrays become the complete member list, distinguishing it from incremental add/remove sibling tools like scaleway_iam_add_group_member and scaleway_iam_remove_group_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (full replacement vs incremental changes) through terms like 'FULL-REPLACE' and 'COMPLETE member list', and provides practical guidance: 'Requires confirm=true', 'Pass empty arrays to remove everyone', and 'Refuses Scaleway-managed/special groups'. No explicit alternatives are named, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, lowering the bar. The description adds meaningful context: 'PERMANENTLY delete', 'immediate and irreversible' in the confirm param, and the reassuring guarantee 'never wipes a bucket recursively'. It does not discuss error/partial-failure behavior, but the safety-critical aspects are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence where every segment earns its place: permanence, batch limit, key-explicitness, confirm requirement, and anti-recursion safety. It is appropriately front-loaded and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive batch delete with 4 parameters and no output schema, the description covers the key operational constraints: key-count limit, no wildcard, confirm requirement, and the irreversibility. A small gap is the lack of guidance on partial failure behavior, but the main usage and safety context is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema descriptions are rich: keys mentions S3's hard cap, credits the no-wildcard form, points to list_objects, region states its default, and confirm explains irreversibility. The tool description itself adds no extra parameter detail, but the schema does the heavy lifting well beyond simple type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'PERMANENTLY delete up to 1000 explicitly-named objects in one call' — a specific verb+resource+scope. It clearly differentiates from the sibling scaleway_s3_delete_object (singular) by emphasizing the batch limit of 1000 and explicit-key scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-not conditions ('No prefix/wildcard form - never wipes a bucket recursively') and names the alternative workflow ('list scaleway_s3_list_objects first if you need to delete everything under a prefix'). This exactly satisfies the 'explicit when/when-not/alternatives' ideal, even if the singular sibling is not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint), it discloses that expiration permanently deletes objects, requires confirm=true regardless of rule content, and specifies storage-class applicability. This adds substantial operational context that is not present in the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence is information-dense: purpose, replacement semantics, destructive warning, and storage notes. There is no fluff or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the key non-obvious behaviors (replace, delete, confirm, storage classes) and distinguishes from sibling lifecycle tools. It could mention edge cases or prerequisites, but it is sufficient for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 75% of parameter descriptions; the description adds meaning for 'rules' (full-replace) and 'confirm' (must be true), and clarifies storage_class enums. It supplements the schema rather than repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource ('Set a bucket's lifecycle rules') and immediately clarifies the full-replace semantics, distinguishing this from get/delete lifecycle siblings. The title's '(full replace)' is reinforced in the description, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context about the full-replace and destructive behavior, which tells the agent when to use it (complete overwrite) and that confirm=true is required. It lacks explicit alternatives, but the sibling tools (get/delete lifecycle) are obvious and the full-replace nature implies it is for setting a complete rule set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond annotations: 'FULL-REPLACE', the requirement of confirm=true because 'this publishes an HTTP website endpoint', the endpoint naming pattern, and the dependence on visibility for anonymous access. This goes beyond readOnly/destructive/idempotent hints, telling the agent what happens in the real world. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences with the core function first, then the confirmation requirement, then the operational context. Every sentence adds relevant information without boilerplate, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter mutation tools with no output schema, the description covers the core purpose; full-replace side effect, publication risk, confirm requirement, endpoint naming, and a dependency on bucket visibility. It could optionally mention how to verify with the get_bucket_website sibling, but the provided context is sufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. The description adds semantic value by explaining that confirm=true is required because the operation publishes an HTTP endpoint, and characterizes index_document/error_document roles ('index document, optional error document'). This is baseline-plus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Configure the bucket for static-website serving (index document, optional error document).' It clearly distinguishes this PUT operation from sibling tools like scaleway_s3_get_bucket_website and scaleway_s3_delete_bucket_website by naming the configuration action and adding the FULL-REPLACE warning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear situational context: the tool publishes an HTTP website endpoint, requires confirm=true for that reason, and notes that anonymous access depends on bucket visibility with an explicit cross-reference to scaleway_s3_set_bucket_visibility. It does not explicitly contrast with when to use get/delete website variants, but the usage intent is well understood.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly stating that the operation replaces the entire tag set rather than merging, which is critical behavioral context for a destructive operation. The annotations already mark destructiveHint and readOnlyHint, so the description adds useful semantic nuance without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and followed by a critical caveat. Every sentence earns its place; there is no filler or redundant restatement of the title beyond the necessary 'replace' framing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive mutation behavior, no output schema, and a nested tags object, the description plus schema provides sufficient guidance: replace semantics, how to preserve existing tags, and complete parameter documentation. It does not explain error conditions or permissions, but annotations and schema cover the most critical operational context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the tags field description adds important meaning beyond the type definition: it clarifies that the value is a complete tag set and that calling this tool replaces, not merges. The key and bucket fields also include concrete examples, and region documents its default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Replace an object's entire tag set' with the specific verb 'replace' and the resource (object tags). The emphatic 'This REPLACES, it does not merge' distinguishes it from a merging behavior and aligns with the tool's name and the sibling get_object_tags use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The schema's tags field explicitly advises calling scaleway_s3_get_object_tags first if existing tags must be kept, providing direct guidance for a common alternative. It also references the same replace-not-merge semantics as scaleway_s3_put_bucket_policy, giving the agent a comparable pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds: 'PERMANENTLY delete', 'Stops future exports; objects already written to the destination bucket are NOT deleted by this call.' This goes beyond the annotation by clarifying the exact side effects and what persists. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each essential. Front-loaded with the action word 'PERMANENTLY delete'. No wasted words; permissions and side effects are efficiently explained.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with clear parameters and annotations, the description covers: action, prerequisite (confirm), behavioral nuance (bucket objects untouched), and error recovery (permissions fix). No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds context: region defaults to server's region, confirm must be true, export_job_id sourced from list_export_jobs. The confirm description repeats schema text but ties it together. Good value-add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'PERMANENTLY delete an export job by ID,' using a specific verb and resource. It clearly distinguishes this delete operation from sibling Audit tools like list_export_jobs and create_export_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the prerequisite 'Requires confirm=true' and the permission requirement ('Needs more than AuditTrailReadOnly...'), including a fix for permission errors. While it doesn't explicitly state when to use (e.g., 'when you no longer need the job'), the purpose is self-evident and the guidelines cover critical success factors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the permission requirement, default time window, and important pagination semantics: cursor-based with no total_count, max_pages as a safety cap, and response indicating truncation with a continuation token. It also predicts a common failure mode (permissions_denied) and suggests a remedy using another tool. This is rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then efficiently covers permission and pagination in a few dense sentences. Every sentence adds value and no redundancies exist with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description adequately covers purpose, permission, defaults, pagination behavior, and response indicators (truncation, continuation token). It also hints at returned fields with 'who did what, when, from where, against what' and mentions the full_detail toggle. This is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all 7 parameters with 100% description coverage, establishing a baseline of 3. The description adds meaning by explaining the real-world impact of max_pages (safety cap, not completeness guarantee) and that method_name_contains is client-side, which isn't fully captured in the schema. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'Audit Trail events' with scope 'across this Organization'. It distinguishes from sibling audit event tools by noting 'the same data as the console's Audit Trail > Events page', clarifying it is the general event stream. This provides a clear, specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (general audit trail listing) and gives a critical prerequisite: requires AuditTrailReadOnly permission on the server's credential, with troubleshooting advice. It also notes defaults (last 24 hours) and pagination behavior, giving clear context. However, it doesn't explicitly contrast with sibling tools like list_authentication_events or list_system_events, though the scope is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: it lists the catalog, requires specific permissions (AuditTrailReadOnly), explains the consequence of missing permissions, and suggests how to fix it. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then usage guidance, then permission details. Every sentence is informative with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema). The description covers purpose, usage, permissions, and output content (service and method names). It is fully complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (region parameter fully described in schema). The description does not add additional parameter semantics beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'products/services integrated with Audit Trail', and specifies it returns service and method names. It also explicitly connects this tool to the filters of sibling scaleway_audit_list_* tools, distinguishing it from others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to call: 'Call this when a filter value is rejected or to discover valid values before querying.' Also provides detailed instructions on permission requirements and how to resolve permissions_denied errors by granting AuditTrailReadOnly via scaleway_iam_set_policy_rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint and idempotentHint annotations by explaining that each permission set has a scope_type ('organization' or 'projects') and that combining different scope_types causes a 400/invalid_arguments error. This details the data model and failure mode without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact three-sentence paragraph that efficiently covers the tool's purpose, a critical domain constraint, and usage guidance. Each sentence earns its place with no redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional filter and no output schema, the description is self-contained: it explains what is listed, the important scope_type constraint, and the recommended workflow with scaleway_iam_create_policy. It also gives the exact error message, making it sufficiently complete for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, name_filter, is already fully described in the schema with examples like 'ObjectStorage' or 'IAM', achieving 100% schema description coverage. The tool description adds no additional parameter-level meaning, so it remains at the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List every permission set Scaleway IAM policies can grant' with concrete examples like ObjectStorageReadOnly and IAMPolicyManager. This clearly identifies the tool's function and distinguishes it from sibling IAM tools like scaleway_iam_list_policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Call this BEFORE scaleway_iam_create_policy to confirm exact names and scope_types'. It also warns that mixing scope_types in a single rule fails with a specific error and advises using separate rules, providing actionable context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses the critical non-rotation guarantee, that the access_key/secret_key pair never changes, and that only passed fields are modified while omitted fields remain unchanged. It also adds operational context about the consequences of delete+recreate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, covering the core behavior, usage guidance, and patch semantics in three focused sentences with no filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter update tool with strong annotations and a fully descriptive schema, the description covers purpose, usage, and behavioral nuances thoroughly. No output schema is needed for tool selection/invocation, and no critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already documents each parameter with formats, examples, and 'omit to leave unchanged' notes. The description's patch-semantics statement largely reinforces schema details rather than adding new parameter-level meaning, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it changes an existing API key's description, expiry, or default_project_id, and explicitly clarifies that it does NOT rotate the secret. This clearly distinguishes it from sibling tools such as create_api_key, delete_api_key, and update_application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool instead of delete+recreate for metadata-only changes, provides concrete examples like extending an expiry or fixing a stale description, and explains why delete+recreate would be harmful. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false (write operation), destructiveHint=false (non-destructive), and idempotentHint=true (safe to repeat). The description aligns and adds detail: it explicitly states the mutation scope (which fields change), assures safety of renaming, and explains the patch-like behavior (only passed fields change). While no output schema exists, the description covers the return implications adequately for this use case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with no wasted sentences. It front-loads the purpose, immediately clarifies what's excluded, then provides the safety rationale and patch behavior in three concise sentences. Every sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this tool has 4 parameters (1 required), 50% schema coverage, no output schema, and no nested objects, the description is remarkably complete. It covers the mutation scope, safety, tag format constraints and replacement semantics, and patch behavior. There is no missing information that would prevent correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (tags and name have descriptions, policy_id and description do not). The description adds significant value beyond the schema: it clarifies the tags replacement behavior ('pass the complete set'), validates the tag key format with examples and a regex constraint, and warns about API rejection of colons. The name parameter's schema description points to another tool's description, but the tool description confirms the naming convention is covered elsewhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('rename/re-describe/re-tag') and clearly identifies the resource ('existing IAM Policy'). It explicitly distinguishes what the tool does from what it does NOT touch (rules, application_id, principal/permission fields), making it easy to differentiate from siblings like scaleway_iam_set_policy_rules or scaleway_iam_clone_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 (only for name/description/tags changes) and what not to expect (no permission or principal changes). It also gives a safety note that renaming is always safe since nothing references a policy by name, and clarifies that only passed fields are changed while omitted fields remain as-is.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explaining the dangerous consequence: 'objects that would have expired keep living (rule removal stops pending deletions - dangerous in the opposite direction of putting rules).' This is critical behavioral context that annotations (destructiveHint: true) do not provide. It also mentions the confirm=true requirement, which is a safety mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and every word earns its place. It includes the critical safety warning without fluff. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive, requires confirmation, has a dangerous side effect), the description is complete. It covers the action, the safety requirement, and the behavioral consequence. The schema covers parameters, and annotations cover destructive nature. No output schema is needed for a delete operation. The description is fully sufficient for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions (100% coverage). The description adds value by explaining the confirm parameter's purpose (safety confirmation) and the dangerous consequence of removal. It doesn't add detail on bucket or region, but those are self-explanatory from the schema. The description's emphasis on confirm=true is a meaningful addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove ALL lifecycle rules' with a specific resource (bucket lifecycle). It distinguishes from siblings like get_bucket_lifecycle and put_bucket_lifecycle by emphasizing the removal of all rules, not just a single rule or configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you want to remove all lifecycle rules from a bucket. It doesn't explicitly mention alternatives, but the sibling tools (get/put lifecycle) are obvious alternatives, and the description's focus on 'ALL' and the confirm requirement provides clear context. It lacks explicit 'when not to use' guidance, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though readOnlyHint and idempotentHint already communicate safety, the description adds important behavioral detail: content is returned as UTF-8 text when possible, otherwise base64, a 5 MB decoded-size cap, and the fail-fast behavior for oversized objects. This goes well beyond annotation values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences cover the core purpose, return encoding behavior, size limit, and fallback tool. Every sentence earns its place with no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description tells the agent what to expect: content, included metadata, encoding property, and base64/text handling. It also covers the main failure mode and a concrete workaround, making the tool well-specified for reliable selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already explains bucket, key, and region clearly. The description does not add extra parameter-level semantics, but it does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Download a single object's content and metadata.' It unambiguously distinguishes this from sibling tools like scaleway_s3_put_object, scaleway_s3_head_object, and scaleway_s3_generate_presigned_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: it explains that larger objects fail fast and directs the agent to 'use scaleway_s3_generate_presigned_url instead.' This is a clear, named alternative with a concrete threshold.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds behavioral context by explaining that the body is not transferred and enumerating the metadata returned (content-type, size, etag, last-modified, user metadata), which is valuable given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the primary action in the first sentence and cost guidance in the second. All words are informative; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, return value (metadata fields), and the cost tradeoff vs. the main alternative. Given no output schema and a simple HEAD operation, this is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters (bucket, key, region with defaults and enum), so the description need not repeat them. The tool description adds nothing beyond the schema for parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') with a clear resource ('object metadata') and explicitly states that it does not transfer the body, distinguishing it from the sibling tool scaleway_s3_get_object. The title reinforces this by stating 'Get object metadata without downloading its content'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly compares to scaleway_s3_get_object: 'Cheaper than scaleway_s3_get_object when you don't need the content.' This gives a concrete when-to-use condition and names the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses crucial behavioral consequences: enabling creates delete markers instead of deleting data, suspension retains existing versions, and the versioning state can never return to 'never-enabled.' It also exposes a failure condition (InvalidBucketState with Object Lock). This is rich, non-obvious behavioral information that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. The first sentence states the core function, and the following sentences add necessary caveats about data retention, irreversibility, and Object Lock. No sentence is wasted or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing operation with no output schema, this description is complete enough for reliable invocation. It explains the irreversible state transition, the confirm parameter, retention behavior, and a key failure case. An agent has enough context to decide when to call this tool and how to construct the call safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, and the description adds meaningful semantics for status by explaining what 'Enabled' and 'Suspended' mean operationally. It also reinforces the confirm=true requirement for suspension. Bucket and region are already documented in the schema, so the description appropriately focuses on the more nuanced parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action: 'Set versioning to Enabled or Suspended.' It clearly identifies the resource (bucket versioning) and the two valid target states. It distinguishes itself from the sibling get_bucket_versioning tool and from other S3 configuration setters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: enabling keeps all object versions, suspending requires confirm=true, and suspension is not disabling. It also warns that suspending fails when Object Lock is enabled. However, it does not explicitly point to get_bucket_versioning as an alternative for checking current state, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, non-destructive, idempotent tool. The description adds key behavioral context: public-read grants anonymous internet READ on all objects and confirm=true is required for that branch; private restores owner-only access. This goes beyond the structured annotations, though it doesn't touch on reversal side effects or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: first sentence states the core behavior and parameter relationship, second sentence provides alternative-tool guidance. Every clause contributes, no unnecessary redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no output schema and relatively few parameters, the description covers the entire invocation context: the meaning of each visibility value, the confirm requirement, the effect on object access, and the relationship to sibling tool. An agent can use this tool correctly without needing additional implicit information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the schema documents bucket, region, and confirm. The description adds crucial semantics for the visibility enum and for the confirm flag, explaining exactly what each visibility value does. It adds meaning beyond the schema despite not explaining every parameter in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Set bucket visibility via canned ACL') and clearly distinguishes between the two visibility values, public-read and private. It also mentions the alternative bucket-policy tool, eliminating ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It repeatedly states that this is the 'coarse on/off switch' and that Bucket Policies provide finer-grained control, explicitly naming scaleway_s3_put_bucket_policy. This gives the agent a clear rule for when to choose this tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint: false, destructiveHint: false, idempotentHint: true. The description adds critical behavioral context: idempotent partial update behavior, all-or-nothing failure (HTTP 404 on unknown ID), and explicit permissions requirements beyond AuditTrailReadOnly. The 'Live-verified' timestamp adds credibility. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with the core purpose, then provides behavioral contrast, troubleshooting, and permissions context. Every sentence adds value. Slightly dense with technical details but remains efficient for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, the description covers all key dimensions: purpose, differentiation from sibling, parameter semantics, error behavior, permissions requirements, and data source. The agent has enough context to invoke correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 explaining the enabled parameter semantics ('true: enable exactly these rules... false: disable exactly these rules') and the rule_ids source (from list_alert_rules), going beyond the schema's basic description. The region default value is also clarified. No output schema needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states the tool enables/disables specific preconfigured alert rules by ID, clearly distinguishing from the sibling scaleway_audit_replace_enabled_alert_rules. The verb 'Enable or disable' combined with 'Touches ONLY the listed rules' makes the specific resource and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs scaleway_audit_replace_enabled_alert_rules, provides where to get rule IDs (scaleway_audit_list_alert_rules), and gives detailed troubleshooting for permissions errors with a specific sibling tool reference (scaleway_iam_set_policy_rules).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and not read-only, which is consistent with the description. The description goes beyond annotations by revealing that the tool internally fetches the SAML config ID before performing the delete, explaining lockout risks for users without passwords, and confirming the working endpoint via live probe. This provides critical behavioral transparency for a dangerous operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise given the complex behavioral information it covers, including the endpoint probe detail. However, the live-probe sentence is lengthy and could be slightly restructured for readability. Every sentence is earned, but clarity could be improved with minor rephrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter, no output schema, and is a high-risk destructive operation. The description covers the prerequisite (`confirm=true`), consequences (permanent removal, lockout risk), implementation detail (fetches config ID), and endpoint behavior. This fully addresses the complexity and risk level, leaving no gaps for an AI agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 explicitly linking `confirm=true` to the permanent removal action and mandatory safety step, which reinforces the schema's const=true constraint but does not add entirely new semantics. Slightly above baseline due to the strong safety emphasis.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently removes the organization's SAML SSO configuration, which uses a specific verb and resource. It also distinguishes from sibling tools like scaleway_iam_enable_saml and scaleway_iam_update_saml by focusing on disabling, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires `confirm=true`, warns of permanent destruction, and explains the fallback and lockout consequences. It also includes a live-probe finding about the correct endpoint, which prevents incorrect usage (e.g., using the org-nested path that returns 405). This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavioral details beyond annotations: requires confirm parameter, has no request fields, enabling alone grants no provisioning access (must create token separately). Annotations correctly reflect destructiveHint=false and readOnlyHint=false, and the description adds rich context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear front-loading of the main purpose, a critical requirement (confirm=true), and a behavioral caveat (no request fields, needs separate token). One sentence is slightly verbose ('live-probed 2026-08-18: this endpoint takes no request fields') but still relevant. Concise enough with very little waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter, no output schema, and good annotations, the description is fully complete. It explains what SCIM provisioning means, the single behavioral requirement (confirm), and the necessary post-step (create token). No important gaps remain for an agent to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the confirm parameter's purpose ('requires confirm=true') and the broader context that enabling alone doesn't grant access. However, it doesn't describe other parameters beyond what the schema already documents, but with only one parameter and high coverage, the added context is meaningful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool enables SCIM provisioning for an Organization, explaining SCIM's purpose (external IdP managing users). It stands apart from siblings like scaleway_iam_disable_scim, scaleway_iam_create_scim_token, and scaleway_iam_get_scim_config by explicitly stating it enables SCIM and listing related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not and prerequisite guidance: requires confirm=true, states enabling alone doesn't grant provisioning access, and directly names a sibling tool (scaleway_iam_create_scim_token) to use for token creation and IdP configuration. Also includes a future-dated note about no request fields, which helps an agent understand the expected behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-idempotent (`idempotentHint: false`) and non-destructive (`destructiveHint: false`) behavior. The description adds critical behavioral context beyond annotations: the tool requires write permissions beyond AuditTrailReadOnly with an explicit resolution path via `scaleway_iam_set_policy_rules`, it cannot modify the query in place, and it includes a frank caveat about a known API 501 error with instructions to not retry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and mechanism in the first sentence, then progressively covers behavioral constraints, permissions, and the important caveat. It is efficient but slightly verbose in the caveat section; a more concise version could separate the core from the live-verified note. Still, every sentence earns its place by providing actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, multiple siblings in the audit family), the description is remarkably complete. It explains the rule logic, mutation constraints, required permissions (with resolution), and a known deployment limitation with clear alternative. No gaps remain that an agent would need to guess about.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. However, the description adds valuable semantic context: it explains the relationship between `occurrences` and `evaluation_window` (defining the triggering condition), it clarifies that the CEL query field surface is undocumented by Scaleway, and it notes the region default. This enriches the schema's bare definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a custom Audit Trail alert rule, specifying the exact mechanism (CEL expression evaluated against incoming audit events, firing when matching events exceed occurrences within evaluation_window). It also distinguishes this from the preconfigured alert rules tool (`scaleway_audit_list_alert_rules`), which is a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 (to create a custom rule with a new query), provides an alternative (`scaleway_audit_update_custom_alert_rule` for metadata-only edits), clarifies when NOT to use it (changing the query requires creating a new rule and deleting the old one), mentions prerequisites (write permissions via `scaleway_iam_set_policy_rules`), and even includes a live-verified caveat about the 501 error with guidance to not retry and use the alternative `scaleway_audit_list_alert_rules` instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive. The description goes beyond annotations by disclosing: separate endpoint from its sibling, actual event types returned, cursor-based pagination with no total_count, and a default 24-hour window. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Everything earns its place: first sentence defines scope and event types, second differentiates from sibling, third explains permissions, fourth notes default window, fifth covers pagination. No filler, every sentence is independently useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and 6 parameters, the description completely covers: purpose, event types, permission requirements, failure mitigation, time default, pagination behavior, and sibling differentiation. The 100% schema coverage with good param descriptions complements the main text perfectly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context for pagination ('Safety cap on pagination (100 items/page)') and the full_detail parameter ('drop user_agent and per-resource detail blobs'), which provide meaningful semantics beyond the schema descriptions. Only minor gap: could explain recorded_after/recorded_before more explicitly in terms of event timestamps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists authentication events (logins, API-key/token auth, MFA outcomes) and explicitly differentiates from the sibling scaleway_audit_list_events by specifying it covers authentication activity only, not API/resource activity. The verb 'list' is appropriate for a read-only endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Excellent guidance: explicitly names the sibling tool (scaleway_audit_list_events) for differentiation, identifies required permissions (AuditTrailReadOnly), explains a common failure mode (permissions_denied), and provides a step-by-step remediation path (grant via scaleway_iam_set_policy_rules at organization scope). Also notes default time window (24 hours).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint. The description adds critical behavioral insight: a caveat that the API returns 501 in practice, explains permission sensitivity beyond the annotation hints, and advises on error handling. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs: first concisely states purpose and sibling distinction; second covers caveat and resolution. Every sentence adds unique value with zero waste. Front-loaded with actionable info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what fields the return will include (query, evaluation window, threshold, severity, status). Covers permissions, error handling, and real-world viability. Highly complete for a list tool with strong annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description adds minimal extra parameter detail but the schema already covers defaults, filters, and pagination cap well. A slight bonus as the description contextualizes the region and status within the organizational scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists an Organization's custom Audit Trail alert rules with specific fields (query, evaluation window, occurrence threshold, severity, status). It distinguishes from scaleway_audit_list_alert_rules (preconfigured rules). Verb + resource + scope is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (listing custom rules) vs. the sibling scaleway_audit_list_alert_rules (preconfigured). Provides a real-world caveat that the API endpoint is non-functional (HTTP 501) and advises not to retry, directing to the working alternative. Also explains permission requirements and a fix if authorization fails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations (readOnlyHint, idempotentHint, destructiveHint false) by disclosing permission requirements, default time window (24 hours vs API's 1-hour default), cursor-based pagination with no total_count, and a specific error scenario (permissions_denied). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. Information is front-loaded: purpose, sibling differentiation, permissions, defaults, pagination. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of audit trail event streams and the 6-parameter schema (fully described), the description covers all critical aspects: what the tool does, how it differs from siblings, permission requirements, default behavior, pagination mechanics. No output schema exists, but the description adequately manages expectations about cursor-based pagination. Complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 6 parameters have descriptions), so baseline is 3. The description adds value by explaining the combined default time window (24 hours, pinned explicitly), the pagination caveat for max_pages, and the default ordering. This contextualizes the parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists system events (actions by Scaleway's own systems), explicitly naming the two sibling tools (scaleway_audit_list_events and scaleway_audit_list_authentication_events) and distinguishing by event source. Verb 'List' and resource 'system events' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: describes the tool as the third event stream for system actions vs API activity vs authentication. Includes a troubleshooting note about the required AuditTrailReadOnly permission and directs to scaleway_iam_set_policy_rules to grant it. Also explains default time window and pagination behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations. It reveals a critical gotcha about the Scaleway CLONE endpoint ignoring the request body and returning an unattached policy, and explains that the tool works around this by following up with a PATCH to restore principal and tags. This expected behavior is not captured by the annotations (which only indicate non-readonly, non-destructive, not idempotent, and open world), so the description provides essential behavioral context. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded core purpose, followed by key usage details, a major gotcha, and a follow-up accuracy note. Every sentence adds value, and there is no fluff. It is appropriately verbose for the complexity of the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 1 parameter, zero output schema, and the complex behavioral nuance (APi workaround), the description is remarkably complete. It explains what the tool does, why this behavior is non-obvious, and notes potential misleading response fields (nb_rules/nb_permission_sets) with a suggestion to verify via scaleway_iam_list_policy_rules. No additional information seems needed for an AI agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single required parameter policy_id. The description does not explicitly explain what policy_id is, but the tool name and context make it clear that it's the ID of the policy to clone. A brief note on the parameter's format (UUID) is present in the schema, and the description's deep context about behavior adds value. Could be improved by explicitly stating that policy_id is the source policy's UUID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones an IAM policy with verb 'Clone' and resource 'an existing IAM Policy'. It specifies exactly what is copied (rules, principal, tags) and how the name is handled, distinguishing it from other sibling tools like scaleway_iam_create_policy and scaleway_iam_update_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (to get a true clone that matches the source) and warns about the underlying API's buggy behavior. It also provides a clear alternative for renaming (scaleway_iam_update_policy) and mentions that renaming is always safe since nothing references a Policy by name, giving excellent usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds critical context beyond this: 'ORG-WIDE BLAST RADIUS: this changes how EVERYONE in the Organization signs in' and explains the severe consequence of misconfiguration (lockout with no console recovery). It also discloses the transitional 'missing_certificate' state preventing immediate exposure. This fully compensates for any missing annotation details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences of core purpose followed by critical warnings and next steps. Every sentence adds essential context: what it does, the blast radius, prerequisites, required parameter, and post-call status. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (org-wide change, destructive, no output schema), the description covers: purpose, prerequisites, parameter intent, risk/deadly consequence, fallback recommendation, required confirmation, and follow-up steps. It is fully complete for an agent to invoke safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 semantic meaning by explaining what entity_id and single_sign_on_url are used for (registering the IdP) and that confirm must be true to acknowledge the org-wide impact. However, it does not elaborate on format constraints beyond what the schema (minLength, uri format) provides, placing it slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Enable SAML SSO, registering the identity provider's entity_id and SSO URL'. The verb (Enable), resource (SAML SSO for the Organization), and specific registration details are explicit. It distinguishes itself from siblings like scaleway_iam_disable_saml, scaleway_iam_update_saml, and scaleway_iam_add_saml_certificate by describing the initial setup and next steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit when and when-not guidance: 'Verify the IdP-side configuration is correct BEFORE calling this, and keep at least one non-SAML login method (password) available on your own account as a fallback.' It also states the requirement 'confirm=true'. The mention of the starting status 'missing_certificate' and the need to later use scaleway_iam_add_saml_certificate provides clear context for when this tool should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which indicate destructive and open-world), the description discloses critical behavioral traits: irreversibility, permanent versioning freeze, rejection of disable attempts, and the non-functional alternative at bucket creation. It does not contradict any annotations; in fact, it enriches them with specific consequences and verification details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense with high-value information, each sentence serving a purpose: defining the action, warning irreversibility, stating prerequisites and workarounds, and noting deletion behavior. It is front-loaded with the core action and consequence, with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an irreversible operation with four parameters and no output schema, the description covers all necessary context: prerequisites, fallback behavior, alternative methods (and why they fail), and post-condition deletion behavior. This is sufficient for an agent to make an informed decision and execute correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all four parameters described), so baseline is 3. The description adds value by explaining the rationale for enable_versioning_if_needed (avoids InvalidBucketState) and ties the confirm parameter implicitly to the one-way door concept. While not exhaustive, it meaningfully supplements the schema with contextual reasoning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Enable Object Lock (WORM: object versions can never be deleted before their retention expires)'. It uses a specific verb and resource, and distinguishes from sibling tools like scaleway_s3_get_object_lock by emphasizing the enabling action and its one-way nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: notes the prerequisite of versioning being enabled, the parameter to handle it automatically, and explicitly states that creating a bucket with object lock at creation time is not possible on Scaleway and this tool is the only working path. Also clarifies that an empty locked bucket can still be deleted, helping agents decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds valuable behavioral details: the operation is atomic, an unknown rule ID rejects the whole request (no partial application), and it requires confirm=true. It also explains the permission requirements beyond what annotations provide. No contradiction between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action and key distinction. It includes a live-verified date, error behavior, and permission troubleshooting—all in a few sentences without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and annotations, the description covers the purpose, usage guidelines, parameter semantics, error behavior, and permissions thoroughly. It provides a complete picture for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, yet the description adds crucial semantic context: e.g., 'after this call, exactly the listed rules are enabled and every other preconfigured rule is disabled - including ones you did not mention.' This clarifies the meaning of the enabled_alert_rule_ids array and the confirm parameter's role in preventing accidental misuse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Atomically replace the COMPLETE set of enabled preconfigured alert rules'. It uses specific verb 'replace' and resource description, and differentiates itself from the sibling tool 'scaleway_audit_set_alert_rules_enabled' by highlighting the full-replace vs additive semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: 'Prefer scaleway_audit_set_alert_rules_enabled (additive) unless you genuinely want full-replace semantics, e.g. syncing to a declared state.' It also mentions the requirement for confirm=true and the needed permissions, giving clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond what annotations provide: it reveals that secret_key is returned only once and cannot be recovered, that the key is immediately active, and that each call mints a real credential. Annotations only show readOnlyHint=false and idempotentHint=false, which are vague; the description compensates fully with specific, actionable warnings about irreversibility and active credential creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with the core purpose, immediately follows with the critical one-time retrieval warning, then provides usage guidelines and parameter context. Every sentence adds unique value—no repetition or fluff. The warning about capturing the secret_key is front-loaded, which is appropriate for a high-stakes behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description is complete: it explains what the response contains (access_key + secret_key pair) and the critical post-call requirement (capture immediately). It covers all 4 parameters with actionable guidance, addresses idempotency concerns, and provides usage context relative to other IAM tools. The description leaves no significant gaps for an AI agent to make a mistake.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds significant value beyond the schema: for expires_at, it explains the trade-off between omitting it (durable operational credential) vs. setting a short expiry (throwaway key). For default_project_id, it clarifies that this is required specifically for S3-compatible API calls. For description, it notes this is the only way to identify keys later in the console. These semantic enrichments are crucial for correct parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates an API key (access_key + secret_key pair) for an Application, which is a specific verb+resource combination. It distinguishes itself from siblings like scaleway_iam_list_api_keys (listing) and scaleway_iam_update_api_key/scaleway_iam_delete_api_key (management of existing keys) by emphasizing creation and the critical one-time retrieval behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 and critical caveats: it instructs the caller to capture the secret_key immediately (e.g., write to env file or secret manager), warns against calling it speculatively since each call creates an immediately-active credential, and contrasts durable operational credentials (omit expires_at or use long expiry) with throwaway/bootstrap keys (should have short expiry). This effectively tells the AI agent how and when to use it responsibly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide key traits (idempotent, non-destructive, not read-only), and the description adds significant beyond-annotation context: it explains exactly why renaming is safe (downstream references use application_id, not name), confirms partial updates semantics ('Only the fields you pass are changed; omitted fields are left as-is'), and does not contradict any annotation. This is excellent transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph of 4 sentences, front-loaded with the core action and then progressively adding critical context. Every sentence earns its place: first the purpose, then why renaming is safe, then a note on partial updates. No filler, no repetition of what the schema or title already convey.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and moderate schema coverage, the description is fully complete for this update tool. It covers safety implications (no downstream breakage), partial update semantics, tag replace semantics (including vocabulary and validation), and name safety rationale. With the annotations confirming idempotence and no destructiveness, there are no obvious gaps for an agent to get stuck on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the description compensates thoroughly. For the tags parameter, the description provides a locked vocabulary ('env={prod|dev|local|ci|shared}', 'access={ro|rw|admin|full}', etc.), warns about colons being rejected, and clarifies REPLACE semantics ('pass the complete set you want, not just the ones you're adding'), which is critical because replace vs. merge is ambiguous from the schema alone. For name and description, cross-references to other tools' conventions and length mentions further clarify. This goes far beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource combination ('Rename/re-describe/re-tag an existing IAM Application') and clearly lists all changeable fields (name, description, tags). It also explicitly states what is fixed ('Only the id is fixed'), which distinguishes this update tool from the sibling create/delete application tools. No ambiguity remains about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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, including a critical safety detail: renaming is safe because nothing references an application by name ('Bucket Policies and API keys reference application_id, never the name'), so agents can confidently rename without fear of breaking live credentials. It also states that only passed fields are changed and omitted fields are left as-is, which is valuable operational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description details the blast radius in both directions: tightening can lock out users, loosening weakens security. It also discloses the partial update mechanism ('Only the fields you pass are changed') and even mentions live-verified behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with no filler. It front-loads the core purpose ('Change org-wide auth policy'), then layers critical warnings and usage notes in a logical sequence. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description fully covers tool behavior: purpose, scope, partial update semantics, confirm requirement, blast radius, and references to external docs. For a security-impacting mutation tool, this is comprehensive and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds rich meaning: it explains the confirm parameter requirement, ties specific fields (login_attempts_before_locked, enforce_password_renewal) to the described effects, and clarifies that an empty call leaves values untouched. This goes well beyond the schema's bare definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Change org-wide auth policy,' which is a specific verb ('Change') and resource ('org-wide auth policy'). This clearly distinguishes it from sibling tools like scaleway_iam_update_user or scaleway_iam_enable_saml, which operate on different scopes or resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool by highlighting the org-wide impact and the partial update behavior. It contrasts with 'SAML/SCIM's enable endpoints' and references docs/gotchas.md for alternatives, providing clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![scaleway-ops-mcp-server MCP server](https://glama.ai/mcp/servers/gkrost/scaleway-ops-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/gkrost/scaleway-ops-mcp-server)

Score Badge

Copy to your README.md:

[![scaleway-ops-mcp-server MCP server](https://glama.ai/mcp/servers/gkrost/scaleway-ops-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/gkrost/scaleway-ops-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gkrost/scaleway-ops-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server