scaleway-ops-mcp-server

Server Quality Checklist

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

Latest release: v0.1.0
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
- 19 commits in the last 12 weeks
- No stable releases found
- 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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds that invalid fields are rejected with the API's own validation message and that only passed fields change. This provides useful context beyond annotations, though it doesn't detail error handling or side effects for mutation of mutable fields.
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, concise and front-loaded with the core purpose. Every sentence adds value: the first defines the action and scope, the second clarifies partial update semantics and validation behavior.
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 mutable update tool with no output schema, the description adequately covers partial update behavior and validation, but lacks parameter explanations. Given the 0% schema coverage and 4 parameters, it is incomplete without providing parameter meanings.
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% — the description does not explain any parameters, while the schema lists 4 parameters (tags, user_id, last_name, first_name) with types but no descriptions. The description mentions 'tags; name/email' but fails to map to specific parameters, leaving the agent guessing about field names vs schema keys.
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 updates a User's mutable profile fields, specifying tags, name, and email. It identifies the resource (Scaleway IAM User) and action (update), and distinguishes from siblings like create_user, delete_user, lock_user, unlock_user, update_user_password, and update_user_username.
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 partial update behavior ('Only passed fields change'), which helps the agent understand how to use it. However, it does not explicitly state when to use this tool vs alternatives like update_user_username or update_user_password, nor does it mention prerequisites like needing the user_id.
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true. The description adds emphasis on permanence but does not add significant behavioral context beyond what annotations and schema provide. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that front-load the key action and constraint. It is efficient with no wasted words, though it could include a brief alternative mention for completeness. Still, conciseness is strong.
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 the tool's simplicity and rich schema/annotations, the description is minimally complete. It covers the core action and mandatory confirm parameter but omits edge cases (e.g., idempotency for missing objects, permissions, return behavior). It relies heavily on the schema and 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 detailed descriptions for all 4 parameters. The description adds no new parameter semantics; it only repeats that confirm must be true, which is already in the schema. Baseline 3 applies as the 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 title and description clearly state the tool deletes a single object from Scaleway Object Storage. The description emphasizes 'PERMANENTLY delete one object', distinguishing it from the sibling scaleway_s3_delete_objects (plural) and other S3 tools like get/put/list.
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 only one guideline: 'Requires confirm=true.' It does not explicitly state when to use this tool versus alternatives (e.g., batch delete via scaleway_s3_delete_objects). The usage context is implicit from the name and title, but no comparative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the behavioral detail about returning an error for missing policies, which is useful. However, it does not disclose whether the returned policy is always a JSON string, what format it is in, or any rate-limiting or authentication details. With strong annotations, the bar is higher, and more context would improve the score.
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 resource, and provides an important behavioral note. Every sentence adds value with no filler. It is appropriately sized for a simple read 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 the low complexity (2 parameters, no output schema, no nested objects), the description is fairly complete. The error condition clarifies behavior. However, it could mention that the response format is typically a JSON policy string or reference schema, but with no output schema, the description handles the core need well. It is slightly incomplete by not stating the return type explicitly, but overall adequate.
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 additional meaning beyond the schema—it only mentions the bucket policy, not parameters. The schema already describes 'bucket' and 'region' adequately, so the description does not compensate or enhance understanding 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 it reads the current Bucket Policy JSON attached to an Object Storage bucket. It uses the specific verb 'Read' and resource 'bucket policy', and it distinguishes itself from sibling tools like scaleway_s3_put_bucket_policy and scaleway_s3_delete_bucket_policy by focusing on reading rather than writing or deleting.
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 when you need to read the bucket policy, but it does not explicitly say when to use this versus alternatives. It includes an error condition ('Returns an error if the bucket has no policy'), which hints at when not to use it (if no policy exists), but lacks explicit when/when-not guidance or mention of sibling tools.
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 are minimal (readOnlyHint=false, destructiveHint=false). The description adds that the website endpoint stops serving, which is a useful behavioral consequence. However, it does not disclose prerequisites (e.g., bucket must exist), idempotency implications, or error conditions, partially compensating for annotation gaps but leaving some transparency missing.
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 of 12 words. It efficiently states the action ('Remove the static-website configuration') and the effect ('the website endpoint stops serving') with no redundant or unnecessary 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?
For a simple two-parameter deletion tool without an output schema, the description covers the primary purpose and consequence. However, it omits details about reversibility, error responses (e.g., if the configuration doesn't exist), and relationship to other S3 configuration operations. It is adequate but not fully complete for an agent to handle edge cases.
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' have descriptions in the input schema. The tool description adds no additional parameter guidance beyond what the schema already provides, meeting the baseline but offering 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 title and description both use 'Delete' and 'Remove the static-website configuration', clearly specifying the action and resource. The effect 'the website endpoint stops serving' adds concrete context, distinguishing it from sibling tools like scaleway_s3_get_bucket_website and scaleway_s3_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 usage for removing static website configuration, but does not explicitly guide when to use this tool versus alternative tools such as scaleway_s3_put_bucket_website (to set) or scaleway_s3_get_bucket_website (to inspect). No exclusion criteria or when-not-to-use advice is provided, so the agent must infer from context alone.
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. The description adds valuable behavioral context beyond these: it specifies that the tool returns an error (NoSuchTagSet) if the bucket has no tags. This is not covered by annotations and is important for agent error handling. No contradiction with annotations 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 two sentences (28 words) with zero wasted content. The verb 'Read' is front-loaded, and the entire description fits in a single line, making it highly efficient for quick agent scanning.
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 simple read operation with no output schema, the description covers the purpose and one key error condition. However, it does not describe the return value format (e.g., list of tags with key and value fields), which would help the agent process the response. Given the lack of output schema, the description could be more complete, but it is minimally adequate.
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?
Both parameters (bucket, region) have full descriptions in the input schema (100% coverage). The description does not add any additional meaning or usage details for the parameters, 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 'Read a bucket's tags (key/value pairs)', providing a specific verb and resource. It also mentions the error case NoSuchTagSet. The tool name itself distinguishes it from sibling tools like scaleway_s3_put_bucket_tagging and scaleway_s3_get_object_tags, and the description reinforces the read-only nature.
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 such as scaleway_s3_put_bucket_tagging, scaleway_s3_delete_bucket_tagging, or scaleway_s3_get_object_tags. It does not state that this is the read operation for bucket-level tags, nor does it mention any preconditions or context. The error mention (NoSuchTagSet) gives a slight hint but insufficient for an agent to decide between related tools.
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 are mostly neutral (readOnlyHint: false, destructiveHint: false) but provide no safety guidance. The description adds value by disclosing that the tool makes a 'real change' (not a no-op on inert metadata), which is a behavioral trait. However, it does not mention whether this operation requires authentication, been destructive to existing data, or have any side effects. Given the neutral annotations, credit for the real-change insight, but lacking broader 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, front-loaded with the primary purpose ('Remove the bucket's default-encryption configuration.'). The second sentence adds a useful behavior verification note. No wasted words; every sentence serves a 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?
Given two simple string parameters with complete schema documentation, no output schema, and annotations that mostly just indicate it is not read-only or idempotent, the description adequately covers what the tool does and its effect. The live-verification timestamp adds credibility. Could be improved by noting if returning an error on non-existent encryption or any prerequisite (like bucket existence), but overall sufficient for a straightforward delete 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%, so the schema already documents the two parameters (bucket: required; region: optional). The description adds no new meaning beyond what the schema provides (bucket name and region defaults are explained in the schema). Baseline of 3 is appropriate as the 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 the verb (Remove), the resource (bucket's default-encryption configuration), and the specific effect (reverts the console's 'Encryption type' back to 'Disabled'). This distinguishes it from sibling tools like scaleway_s3_put_bucket_encryption and scaleway_s3_get_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to disable bucket encryption, and disambiguates from no-op behavior via the live-verification note. However, it does not explicitly state when NOT to use this tool (e.g., when you want to modify rather than delete encryption) or list alternatives (like put_bucket_encryption with different settings).
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 safety and side effects. The description adds value by disclosing that the tool errors with NoSuchCORSConfiguration if no rules are set, which is a useful behavioral trait 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?
The description is two sentences, front-loaded with the primary action ('Read a bucket's CORS rules') followed by a key behavioral note. Every word earns its place; 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?
For a simple read tool with 2 fully-documented parameters and comprehensive annotations, the description covers the essential purpose and a notable error case. It does not describe the output format (no output schema), but given the simplicity and existing structured data, the description is sufficiently complete for an agent to call this 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 'bucket' and 'region' already described in the schema. The tool description does not add any additional meaning or context for these parameters, so it meets the baseline but does not exceed 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 uses a specific verb ('Read') and resource ('a bucket's CORS rules'), clearly distinguishing this from sibling tools like scaleway_s3_put_bucket_cors or scaleway_s3_get_bucket_lifecycle. It also adds an error condition detail, 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 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 over alternatives such as put_bucket_cors or delete_bucket_cors. It does not mention prerequisites, context, or exclusions, leaving the agent to infer usage solely from the name and annotations.
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, indicating a safe read operation. The description adds the specific error condition 'NoSuchLifecycleConfiguration' when no rules exist, which is valuable behavioral context beyond the annotations. 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?
The description is extremely concise with two sentences, each adding value: the first states the action, the second warns about the error case. No superfluous text, and the key information is front-loaded.
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 lacks an output schema, so the description should compensate by explaining the structure of lifecycle rules (e.g., an array of rules with filters, transitions). It only says 'Read a bucket's lifecycle rules' without describing the return format, leaving the agent uninformed about what to expect. This is a significant gap for 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 both parameters ('bucket', 'region') adequately described in the input schema. The description does not add any additional meaning or usage details beyond what the schema provides, so it meets 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 clearly states the action: 'Read a bucket's lifecycle rules.' It also specifies the error condition for absent rules, which differentiates it from sibling tools like put/delete lifecycle. The verb+resource combination 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading lifecycle rules, but it does not provide explicit guidance on when to use this tool versus other S3 read tools (e.g., get_bucket_policy, get_bucket_tagging). No alternatives or exclusions are mentioned, leaving the agent without clear differentiation among sibling S3 read tools.
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only operation. The description adds context about credential security and time-limitation, but does not contradict annotations. It lacks detail on behavior like error handling or side effects, but suffices given the 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 extremely concise with two sentences. The first sentence immediately states the core action and its benefit, the second gives when to use it. Zero 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?
Given the absence of an output schema, the description does not explain the returned URL format or how to handle responses. It adequately describes purpose and usage but leaves out details on what the agent should expect from the call, which is a moderate gap 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.
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 significant parameter-level detail beyond what is already in the schema (e.g., operation enum, expires_in_seconds constraints). It mentions GET vs PUT and time-limited nature, but those are already clear from 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 clearly states the tool generates a time-limited presigned URL for a single object, specifying GET or PUT access. It explicitly distinguishes itself from scaleway_s3_get_object/put_object by noting it is intended for external sharing or large content, providing strong differentiation from 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: it is useful for handing download/upload links outside MCP or for content too large for inline transfer via sibling tools. While it does not list explicit when-not-to-use scenarios, the context is clear and provides viable alternatives.
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, clearly indicating a safe read operation. The description adds value by disclosing the specific error behavior: 'Errors with NoSuchWebsiteConfiguration if none is set.' This is a key behavioral detail 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 exceptionally concise with two sentences, zero waste. The first sentence is front-loaded with the core purpose, and the second sentence adds a critical behavioral note. Every word 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 simple read-only tool with two parameters, no output schema, and comprehensive annotations, the description is complete. It communicates the operation, resource, and expected error condition. No additional information is needed 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% (both 'bucket' and 'region' have descriptions). The description adds no additional meaning about the parameters beyond what the schema already provides. Baseline 3 is appropriate as the 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 it reads a bucket's static-website configuration, distinguishing it from sibling tools like scaleway_s3_get_bucket_policy and scaleway_s3_get_bucket_tagging. The verb 'Read' and resource 'bucket's static-website configuration' 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. While the name and context with siblings imply its purpose, there is no mention of prerequisites, when not to use it, or comparison to other get-configuration tools. The error condition is noted but does not constitute usage 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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by confirming the setting is live-verified and affects the console's 'Encryption type' display. It does not contradict annotations; in fact, it reinforces idempotency by stating it's a real setting. However, it doesn't disclose whether previous encryption settings are overwritten or if any side effects occur.
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 long, front-loading the core action and adding a verification note. The second sentence is informative but slightly longer than necessary; it could be more concise. However, it contains no fluff or repetitive information.
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 3 params (1 required), no output schema, and moderate complexity, the description is fairly complete. It explains the effect (encryption config set) and the algorithm. It does not explain the return value (likely empty or standard response), but that is acceptable without an output schema. The context is adequate for an AI 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 description coverage is 67% (2 of 3 parameters have descriptions). The description adds value by specifying the algorithm is 'AES256' (matching the schema's const), but does not add meaning beyond what's in the schema for 'bucket' and 'region'. The 'algorithm' parameter's const/default are already clear from 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 clearly states the action ('Set'), the resource ('bucket's S3 default-encryption configuration'), and the specific algorithm used ('AES256'). It also adds a note that this is a real, effective setting, distinguishing it from any potential filler. Among sibling tools like scaleway_s3_get_bucket_encryption and scaleway_s3_delete_bucket_encryption, the purpose is 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 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 (to enable default encryption on a bucket), but does not explicitly state when NOT to use it, nor does it mention prerequisites (e.g., IAM permissions, bucket existence). There is no guidance on alternatives or related tools (like scaleway_s3_get_bucket_encryption to check current config).
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?
The description explicitly mentions the destructive behavior ('Removes ALL grants... loses access immediately') and the 'confirm' requirement, which adds value beyond the annotations' destructiveHint: true and the schema's const: true for confirm. 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?
Two concise sentences that are front-loaded with the core action, then the key requirement and consequence. 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?
Given the destructive nature, the description covers the core behavior and confirm requirement. Without an output schema, it could optionally mention the successful response or error states, but the close fit with annotations makes it nearly complete for an experienced user.
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, the baseline is 3. The description adds no param details beyond the schema, but the warning about access loss reinforces the confirm parameter's gravity.
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 'Remove' and resource 'bucket's Bucket Policy', and distinguishes it from sibling tools like scaleway_s3_put_bucket_policy and scaleway_s3_get_bucket_policy, which are about setting or getting the policy.
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 need for 'confirm=true' and warns about immediate loss of access, giving context for when to use it, but does not explicitly state when not to use it or compare it against alternatives like nullifying the policy via put_bucket_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 clearly stating 'FULL-REPLACE semantics' and that 'tags not in the list are removed'. This adds valuable behavioral context beyond the annotations (which indicate idempotentHint=true and destructiveHint=false). The description is consistent with annotations; 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?
Two sentences succinctly convey the purpose and a critical behavioral nuance. Every word is purposeful. The title adds '(full replace)' for additional clarity. No wasted or redundant text.
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 tagging operation with good annotations and full schema coverage, the description is largely sufficient. It covers the core action and the key behavioral trait (full-replace). It does not mention return values (no output schema) or error conditions, but these are minor gaps given the tool's simplicity and the presence of idempotentHint=true.
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 individual parameter details beyond the schema, which already adequately describes the 'tags' parameter as 'The COMPLETE tag set to apply'. The description reinforces the full-replace concept but does not add new semantic value per 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 explicitly states 'Set a bucket's tags' with a specific verb and resource. It distinguishes itself from sibling tools like 'scaleway_s3_delete_bucket_tagging' and 'scaleway_s3_get_bucket_tagging' by clarifying the FULL-REPLACE semantics, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to use delete_bucket_tagging instead). It implies usage for setting tags but lacks context on prerequisites or exclusions. The full-replace semantics is mentioned but not framed as a 'when to use' directive.
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?
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?
Adds key behavioral context beyond annotations: 'PERMANENTLY delete', 'immediate and irreversible', and the emptiness constraint. Annotations already flag destructiveHint=true, so no contradiction. The description reinforces the severity without repeating structured data.
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?
One concise sentence front-loaded with 'PERMANENTLY delete'. Every word serves a purpose with no extraneous content. The bold emphasis on 'PERMANENTLY' aids agent attention.
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 single-action tool, the description covers the core behavioral contract: irreversible deletion, emptiness prerequisite, and confirm requirement. No output schema exists, but return values are not critical for a delete operation. Slight gap: doesn't mention that the bucket name becomes available for reuse, but that is noted in the confirm parameter description.
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 detailed descriptions for each parameter (bucket, region, confirm). The tool description does not add new semantic info beyond what the schema already provides, 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?
Description clearly states the verb 'delete' and the resource 'Object Storage bucket', with specific conditions (must be empty). Distinguishes from sibling tools like scaleway_s3_delete_object and scaleway_s3_create_bucket.
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?
Explicitly requires confirm=true and states the bucket must be empty. While it doesn't directly mention alternatives, the prerequisite (empty bucket) implies the need to first delete objects, guiding the agent away from premature use.
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 (destructiveHint=true, idempotentHint=true), the description clarifies that while the action destroys the current tag set, it is reversible via re-application. It also mandates the confirm parameter as a deliberate safeguard. 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 concise sentences: the first states action and requirement, the second adds nuance about reversibility. No redundant information; front-loaded with the core 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 delete operation with 3 parameters and no output schema, the description covers the essential aspects: what it does, required parameter, and behavioral nuance. It could mention error cases or that the operation returns nothing, but 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate descriptions for all three parameters. The description reinforces that 'confirm' must be true, but does not add new semantic detail beyond 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 'Remove ALL tags from a bucket' with a specific verb (remove) and resource (bucket). It distinguishes from sibling tools like scaleway_s3_get_bucket_tagging and scaleway_s3_put_bucket_tagging by emphasizing 'ALL' tags, making the action 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 explicitly requires 'confirm=true', providing a clear precondition. It mentions reversibility in terms of re-applying tags, giving context on the outcome. However, it does not explicitly compare to alternatives (e.g., when to use put_bucket_tagging instead) or state when not to use the 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which clearly indicate a safe, read-only, idempotent operation. The description adds 'key/value tag set attached to an object', confirming it returns tags—consistent with annotations. There is no contradiction, and the behavioral profile is well-covered by annotations, so a score of 4 reflects that the description aligns without adding much beyond 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 10-word sentence: 'Read the key/value tag set attached to an object.' This is maximally concise, front-loaded with the action, and contains no extraneous words or repetition. Every word serves a purpose, earning the top score.
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 3 parameters (2 required), full schema coverage, and comprehensive annotations (readOnly, idempotent, etc.), the description is largely complete. It explains the return type (key/value tags) and the resource (object). However, it does not specify the output format or mention that the tool could return an empty set if no tags exist. With no output schema, a slight addition about return behavior would improve completeness.
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 covers 100% of parameters with descriptions (e.g., 'Object key (the full path within the bucket)', 'Bucket name'), so the schema already explains both required parameters and the optional region. The description adds minimal parameter-level meaning beyond the schema, but since coverage is high, a baseline of 3 applies; the score of 4 acknowledges that the schema is already excellent, leaving little for the description to 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 clearly states 'Read the key/value tag set attached to an object', specifying both the verb (read) and the resource (tag set on an object). This distinguishes it from sibling tools like 'scaleway_s3_put_object_tags' (write) or 'scaleway_s3_get_bucket_tagging' (different resource level), making the 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 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, nor does it mention prerequisites or exclusions. For example, it doesn't clarify whether the bucket must exist, whether the object must have tags, or when to use this vs. 'scaleway_s3_list_objects' to see tags. There is implicit context from the tool name and siblings, but 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 value beyond the annotations: it states 'FULL-REPLACE' (indicating overwrite behavior), explains the need for confirm=true due to publication of a public endpoint, and mentions the dependency on visibility settings. The annotations already indicate openWorldHint=true and idempotentHint=true, and the description reinforces these without contradiction. It provides useful behavioral context that the 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, front-loaded with the primary purpose. Every sentence contributes essential information: what it does, that it's a full replace, the confirm requirement, the endpoint naming, and a cross-reference to a related tool. There is no redundancy or unnecessary text.
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 tool's purpose, required confirm flag, endpoint naming, and a dependency on visibility. It does not explicitly mention that the configuration is a full replace (overwrites existing), but 'FULL-REPLACE' implies that. There is no output schema, so no return value expectations are needed. The description is sufficient for a typical use case, but could be slightly more complete by noting that the bucket must already exist or that the operation is idempotent.
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 reiterates the purpose of index_document and error_document ('index document, optional error document') and emphasizes the confirm parameter's role. However, it does not add significant new details beyond what the schema descriptions already provide (e.g., bucket name, region, default values). The description adds marginal extra meaning for the confirm parameter but not enough to raise the 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 verb ('Configure'), the resource ('bucket for static-website serving'), and the specific elements ('index document, optional error document'). It explicitly says 'FULL-REPLACE', distinguishing it from sibling tools like get_bucket_website (read) and delete_bucket_website (remove). The purpose is unambiguous and specific.
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: 'Requires confirm=true because this publishes an HTTP website endpoint for the bucket.' It also explains the endpoint naming convention and directs users to check the console for the exact URL. Additionally, it mentions a dependency on bucket visibility via a sibling tool. While it does not list when not to use this tool or provide alternatives, it gives sufficient context for appropriate use.
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 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds value by listing the specific metadata fields returned (jti, audience, expiry, IP, user agent), which is beyond what annotations convey. It does not contradict any 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, well-structured sentence that front-loads the verb 'Read' and immediately conveys the tool's purpose. Every word adds value, with no redundancy 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 read tool with one parameter, rich annotations, and no output schema, the description is complete. It specifies the operation, the input (id), and the output fields. The parameter description in the schema complements the tool description. No gaps remain.
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 a clear description for the 'jti' parameter. The description adds meaning by stating the tool reads metadata by id and lists the fields returned, which is not present in the schema (no output schema). This helps the agent understand what information will be retrieved using the 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 explicitly states the verb 'Read' and the resource 'JWT session's metadata', listing the specific fields (jti, audience, expiry, IP, user agent). It clearly distinguishes from siblings like scaleway_iam_list_jwts (list all) and scaleway_iam_delete_jwt (delete) by specifying this is a read operation for a single session by id.
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 context by stating the tool reads by id and the parameter description notes the id comes from scaleway_iam_list_jwts. While it does not explicitly state when not to use or list alternatives, the simplicity of the tool and presence of sibling tools make the intended use clear. Slight improvement would be to explicitly mention that this is for retrieving metadata after listing.
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false — covering safety. The description adds critical behavioral context beyond annotations: the tool returns an HTTP 200 in empty config cases (not an error, unlike AWS), the config is a real toggleable setting (not inert), and the description documents that a previous version of the doc was wrong and has been corrected after live verification. This is exemplary transparency about the tool's actual behavior and its edge cases.
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 ('Read the bucket's S3 default-encryption configuration') in the first sentence, which is ideal. The remaining sentences add important behavioral nuance. It's on the longer side for a read tool but each sentence earns its place — however, the parenthetical about AWS comparison could be tightened slightly to reduce verbosity while maintaining the differentiation 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?
The tool is simple (2 params, read-only, no output schema) so completeness requirements are lower. The description covers the key behavioral nuance (empty vs error) and confirms the setting is real. It doesn't specify what the response format looks like or what fields to expect in a non-empty response, but since there's no output schema, a mention of the structure (e.g., 'returns an encryption configuration object with algorithm and key fields') would make it score 5.
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 descriptions in the schema). The description adds no additional parameter semantics — it doesn't clarify the format of 'bucket' (ARN vs name) or the scope of 'region' beyond what's in the schema. With full schema coverage, baseline 3 is appropriate; the description doesn't add new meaning to parameters but also doesn't contradict.
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 bucket's S3 default-encryption configuration' — a specific verb ('read') coupled with a precise resource ('bucket S3 default-encryption configuration'). It also immediately distinguishes this tool from similar S3 bucket read tools by highlighting the behavior difference vs AWS, and its sibling context includes other S3 config readers, so this positioning helps the agent differentiate.
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 doesn't explicitly say 'when to use this vs alternatives', but it strongly implies when: use this when you need to inspect the current encryption state, not when you need to set/modify it (that's put_bucket_encryption/delete_bucket_encryption siblings). It provides context that the encryption setting is real and toggleable, guiding agents away from treating it as inert metadata. However, explicit guidance on when NOT to use it or mention of alternatives beyond the named siblings would push this to 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?
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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying exactly what metadata is returned and confirming no body transfer occurs. 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 sentences that are highly informative and to the point, with no fluff. First sentence defines action and output, second provides cost rationale relative to sibling. Every word contributes.
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 is complete for a simple, safe, read-only operation: it explains what metadata is returned, confirms no body transfer, and provides selection guidance. No output schema exists, but the listed metadata fields suffice. Slight gap: no mention of the region parameter's default behavior, though schema covers it.
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 parameters are fully documented in the schema itself. The description does not add additional parameter details beyond the schema, which is acceptable given high 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 the tool fetches object metadata without downloading content, with specific metadata fields listed (content-type, size, etag, etc.). It distinguishes itself from scaleway_s3_get_object by noting this is cheaper when content is not needed.
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 advises using this over scaleway_s3_get_object when you don't need the content, providing a clear when-to-use scenario. The sibling list includes both tools, and the description directly compares them.
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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, read-only operation. The description adds valuable behavioral context beyond annotations by stating lists are region-specific, which is a key non-obvious behavior for an agent to understand. There is 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 that packs essential information: the verb (list), resource (buckets), scoping (one region), and a clarifying contrast with AWS. There is zero waste; 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?
Given the tool's simplicity (1 optional parameter, no output schema, simple list operation), the description is largely complete. It explains the region-scoping quirk, which is the most critical missing piece from the schema. However, it doesn't mention that the output will be a list of bucket names/structure, but with no output schema and annotations covering safety, this is a minor gap for such a straightforward 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% – the single optional parameter 'region' is well-documented in the schema with its default value. The description adds meaning beyond the schema by explaining that scoping to a region is required due to Scaleway's architecture, which justifies the presence and role of the parameter. A score of 4 reflects that the description adds useful context beyond the schema's 100% 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 very clearly states the tool lists Object Storage buckets and crucially adds that buckets are region-scoped on Scaleway, unlike AWS's account-wide namespace. This specific verb and scope definitively distinguishes it from any sibling tool, especially the many IAM and audit tools.
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 tool should be used to list buckets in a specific region, and the parenthetical contrast with AWS provides important context for users familiar with other providers. There are no alternatives among the siblings for listing buckets (scaleway_s3_list_objects lists objects within a bucket), but explicit 'when not to use' guidance is missing, so it doesn't reach 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 indicate this is not a read-only operation (readOnlyHint: false), is open-world (openWorldHint: true), and is idempotent (idempotentHint: true). The description goes beyond annotations by spelling out the destructive side-effect: existing rules not in the list are removed (full-replace). It also explains the consequence – loosening or restricting cross-origin access – which adds important risk context. 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 tightly packed sentences. Front-loaded with the core action, immediately follows with the critical full-replace semantics in all caps, then closes with the security implication. No filler, no repetition of what's in the schema.
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 3 parameters, 100% schema coverage, no output schema, and clear annotations (idempotent, not destructive), the description covers the essential behavioral nuance (full-replace) and consequence. No need to detail return values since output schema is absent. However, it could mention that sending an empty array would effectively clear all rules (though delete_bucket_cors exists). Still, completeness is high for the tool's complexity.
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 schema already documents all three parameters well (bucket name, region, rules array). The description clarifies that the 'rules' parameter is the COMPLETE set (not an incremental addition), which is a critical semantic distinction beyond the schema's 'The COMPLETE CORS rule set to apply.' This prevents the agent from mistakenly believing it can just append a rule.
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 'Set' and the resource 'Scaleway bucket CORS rules'. It immediately clarifies the full-replace semantics, which distinguishes it from any partial-update or append alternative. The title also includes 'full replace' as a deliberate qualifier.
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 explains the full-replace behavior – the provided list becomes the complete rule set and existing rules not in the list are removed. It also mentions the effect: 'loosens or restricts browser cross-origin access'. While it doesn't explicitly tell when not to use it or name an alternative (like delete_bucket_cors to remove all rules), the behavioral note is strong enough for an agent to decide.
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 reveals critical behavioral traits beyond what annotations provide: 'creation triggers an IMMEDIATE backfill, not just a future cadence' with specific examples of the objects written. It also clarifies that delete_export_job does not clean up those objects, and that the bucket must be emptied manually before deletion. The permission requirements are explicitly stated. 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 a single paragraph with multiple sentences, each serving a distinct purpose: purpose, prerequisite, behavioral caveat, permission guidance. It is reasonably concise given the amount of information packed in, but could be slightly more structured (e.g., bullet points for the caveats). 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?
Given the tool's complexity (7 parameters, no output schema, S3 integration), the description covers prerequisites, behavior, permissions, side effects, and related tools. It mentions checking job status via list_export_jobs but does not explicitly state what the create endpoint returns (e.g., job ID). This is a minor gap 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.
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 adds some context for the bucket parameter (must exist, create it first) and mentions the prefix example, but this is already partially covered in the schema's parameter descriptions. The description does not add significant new meaning beyond what the schema provides for each 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 opens with a specific verb+resource: 'Create an export job shipping Audit Trail events to an Object Storage bucket (S3 destination).' This clearly distinguishes the tool from sibling audit tools like scaleway_audit_list_export_jobs and scaleway_audit_delete_export_job, and also references the prerequisite bucket creation tool (scaleway_s3_create_bucket).
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 prerequisites ('The bucket must already exist and be writable - create it first'), when to use alternatives ('check last_run_at / last_status via scaleway_audit_list_export_jobs afterwards'), and error recovery ('if the call fails with permissions_denied, grant the Audit Trail write permission set via scaleway_iam_set_policy_rules'). It also warns about the side effect of the backfill not being undone by delete_export_job.
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description correctly states the operation is server-side and not re-uploading, which adds context beyond the idempotentHint=true annotation. However, it does not elaborate on idempotency behavior (e.g., overwriting if destination exists) or permissions/ACL requirements. The description aligns with annotations (no contradiction), and the annotation set already conveys safety hints (non-destructive, idempotent).
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 terse sentences: the first defines the core operation with technical advantage, the second enforces a critical constraint. No filler words. Every sentence adds unique, necessary information for an agent to use the tool correctly.
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 schema covers all parameters, annotations provide idempotency and non-destructive hints, and there is no output schema, the description sufficiently frames the copy operation. It could optionally mention that copy works for any object size (since server-side) or that it can serve as a rename, but these are minor additions. The description does not leave critical 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, and the tool description adds context that all parameters relate to a region-constrained copy. The description explicitly confirms that source and destination must be in the same region, echoing the region parameter's note. No ambiguity remains about what each parameter does or how they relate to the operation.
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 a server-side copy operation for Scaleway S3 objects, specifying the verb 'copy', the resource 'object', and the technical behavior (no download/re-upload). It distinguishes itself from sibling tools like scaleway_s3_put_object or scaleway_s3_get_object by focusing on copying between buckets/keys.
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 notes that source and destination must be in the same region and that cross-region copy is out of scope. It implicitly rules out direct upload/download. However, it does not explicitly contrast with sibling S3 tools like scaleway_s3_put_object (which uploads) or scaleway_s3_delete_object (which removes), nor does it mention when to use this tool for renames vs. copying across buckets.
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 significant behavioral context beyond the annotations: it specifies permanence ('PERMANENTLY delete'), a batch limit (1000), a mandatory confirmation flag ('Requires confirm=true'), and clarifies it does not support recursive deletion. Annotations already set destructiveHint=true and idempotentHint=true, and the description aligns with and enriches these traits.
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 three concise clauses: purpose, requirement, and limitation. Every word adds value, and the key action ('PERMANENTLY delete') is front-loaded. No extraneous information.
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 batch delete tool with no output schema, the description covers all essential aspects: what it does (batch delete), how many (up to 1000), safety requirement (confirm=true), and what it does not do (no recursive). The sibling context and parameter descriptions fill remaining gaps, making this complete for agent 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 tool description itself does not describe parameters beyond noting the confirm requirement, which is already in the schema. However, the input schema has 100% coverage with detailed descriptions for all four parameters (e.g., keys: 'Explicit list of keys to delete...'). Per the rubric, when schema coverage is high, a 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 states 'PERMANENTLY delete up to 1000 explicitly-named objects in one call,' which is a specific verb (delete) and resource (objects). The title 'Batch-delete' and the explicit mention of 'No prefix/wildcard form' clearly distinguish this from the sibling 'scaleway_s3_delete_object' (singular delete) and from any recursive bucket deletion tool.
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 'Requires confirm=true' as a usage requirement and states 'No prefix/wildcard form - never wipes a bucket recursively' as an exclusion. It implies batch use for multiple known keys, but does not explicitly mention when to prefer this over the singular delete tool. The parameter description for 'keys' gives additional guidance about listing first, but that is part of the schema.
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 value beyond the annotations by explaining that the response can be an empty string, 'Enabled', or 'Suspended', and includes the important exception about Object Lock. However, it doesn't mention whether the tool requires specific IAM permissions or what happens if the bucket does not exist. Given the rich annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description is still quite transparent about the read-only behavior.
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 with two sentences that efficiently communicate the purpose, the return values, and an important edge case. Every sentence contributes meaningful information 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 with only two parameters, no output schema, and excellent annotations. The description fully covers the behavior: it lists possible outputs, notes the Object Lock interaction, and is self-contained. There is no need for additional details on return structure or error handling given the tool's simplicity.
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 parameter semantics beyond what the schema provides, but it does not need to since the schema fully documents both parameters. No extra context is provided about what region defaults to or how bucket names are validated, but the schema already includes descriptions and constraints.
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 bucket's versioning state, listing the three possible values and immediately distinguishing this from any write or configuration tool. It stands out among siblings like scaleway_s3_set_bucket_versioning and scaleway_s3_enable_object_lock by focusing solely on a read operation for versioning state.
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 usage context by noting when this tool should be used (to check versioning state) and includes a critical caveat about Object Lock freezing versioning. It implicitly advises against using this tool when you need to set versioning, pointing users to a different sibling (scaleway_s3_set_bucket_versioning). The live-verified date adds trustworthiness.
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=false, so the description carries a lighter load. The description adds valuable behavior context by explaining how visibility is derived from ACL grants and that it returns raw grants, which is beyond the annotations. 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?
The description is two sentences: the first explains what the tool does and how, the second notes an additional return detail. Zero waste, perfectly front-loaded and 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 is a simple read operation with strong annotations (readOnlyHint, idempotentHint), two well-understood params, no output schema required, and the description covers the derivation and returns, the information provided is fully sufficient for agent 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?
Schema description coverage is 100%, so both parameters are documented in the schema. The description does not repeat parameter syntax but provides context about the bucket and region parameters indirectly. This adds moderate value beyond the schema, so a 4 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?
Description uses specific verb 'Read a bucket's visibility', names the resource ('bucket visibility'), and clarifies how visibility is derived from ACL grants. This clearly distinguishes it from siblings like scaleway_s3_get_bucket_policy or scaleway_s3_get_bucket_lifecycle.
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?
Description implicitly states this tool is for reading bucket visibility, not setting it (which would be scaleway_s3_set_bucket_visibility). It explains the ACL-based derivation and provides return details ('Returns the raw grants too'). No explicit when-not-to-use guide, but the context of siblings and the read-only nature make it clear.
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=true, idempotentHint=true, destructiveHint=false. The description adds value by clarifying the error behavior (absence of config means disabled, not error), which is beyond what annotations provide. 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?
Two concise sentences that cover the tool's purpose and key behavioral nuance. 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 simple read operation with no output schema, the description adequately covers the main behavior and error interpretation. No gaps given the tool's complexity and available 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 documentation coverage is 100% and both parameters (bucket, region) are described in the schema. The description does not add any extra parameter details, so baseline score 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 whether Object Lock (WORM protection) is enabled on the bucket, with a specific verb 'Read' and resource 'bucket object-lock configuration'. This distinguishes it from sibling tools like scaleway_s3_enable_object_lock or scaleway_s3_get_bucket_lifecycle.
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 how to interpret results: 'ObjectLockConfigurationNotFoundError means NOT enabled - there is no disabled state'. This provides clear usage guidance on error handling, though it does not explicitly state when to use vs. alternatives or when not to 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?
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.
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral information beyond the annotations: pagination mechanics (continuation token), delimiter semantics (grouping into common_prefixes and excluding matching keys from objects), and the S3 hard cap of 1000. 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 two sentences, front-loaded with the core purpose, and every sentence adds value. 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?
Given no output schema, the description covers pagination (next_continuation_token) and delimiter behavior. It could be more explicit about the response structure (e.g., objects array, common_prefixes, is_truncated), but it is sufficient for a filtered-list 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?
With 100% schema description coverage, the baseline is 3. The description adds value by explaining the pagination flow and the effect of the delimiter, which enhances understanding beyond the schema descriptions. It does not repeat schema 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 clearly states the verb 'list', the resource 'object keys in a bucket', and optional scoping by prefix and delimiter. It distinguishes itself from sibling tools, such as scaleway_s3_list_buckets, by specifying that it lists objects within a bucket.
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 on when to use the tool (listing objects with optional prefix and delimiter) and mentions pagination. It lacks explicit exclusions or alternatives, but the context is sufficient for understanding the tool's purpose.
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 (destructiveHint: true) and idempotent (idempotentHint: true). The description reinforces this by stating it 'Replaces' and 'does not merge,' and goes well beyond by warning about the specific gotcha that using ARNs instead of bare names fails, the Version=2023-04-17 requirement for application_id principals, and that s3:HeadObject is invalid. These behavioral nuances (error-prone values, companion IAM policy need) provide critical transparency beyond structured 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 field is three sentences: first sentence states the action, second sentence links to the IAM companion for broader context, third sentence provides a concrete safety recommendation. Every sentence serves a distinct purpose with no redundancy. The heavy parameter documentation is correctly placed in the schema, keeping the description lean and 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?
For a PUT operation with no output schema, the description covers the core action, safety net, and companion tool need. The schema handles detailed syntax rules and gotchas. The combination is complete enough for correct invocation. A minor gap: the description doesn't mention that the tool returns no meaningful body (only success/error), but this is implicit for a PUT. Slightly more explicit return information would earn a 5.
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 the input schema already contains an extremely detailed description for policy_json (including gotchas, format, merging workflow, known invalid actions/resources, version requirement). The main Description field adds only the safety net tip about granting the owner access. While helpful, this adds minimal parameter semantics beyond 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 opens with 'Replace a bucket's entire Bucket Policy with the given JSON document,' which is a specific verb ('Replace') and resource ('bucket's entire Bucket Policy'). It explicitly distinguishes from sibling IAM policy tools by calling this the 'bucket-scoped half of access control' and referencing scaleway_iam_create_policy. Among siblings like scaleway_s3_get_bucket_policy or scaleway_s3_delete_bucket_policy, this tool's purpose is unmistakable and 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 clear when-to-use context: setting a full bucket policy. It explicitly contrasts with the get-merge-put workflow by stating 'To add a statement without losing existing grants, call scaleway_s3_get_bucket_policy first...' and redirects to scaleway_iam_create_policy for the IAM companion requirement. The safety net recommendation ('include a statement granting the bucket owner's own user_id full access') gives proactive guidance to prevent lockout. This is comprehensive alternatives and exclusion advice.
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: it explains the effect of enabling (keeps all object versions, delete markers instead of removal), the effect of suspending (stops versioning for new writes, retains existing), and irreversible state consequences. However, it does not explicitly mention idempotency or non-destructive nature already hinted by annotations, so a 4 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 3 sentences, each sentence adds critical value: first sentence states basic function, second explains core behaviors, third warns about irreversible constraints. No filler or repetition of schema fields. Information is front-loaded effectively.
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 moderate complexity (4 params, some conditional logic), the description provides adequate guidance for safe invocation. It covers state transitions, requirements, and constraints. It doesn't document return values, but no output schema exists, so that's acceptable. A small gap: it doesn't mention whether the operation is synchronous or if there are propagation delays.
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 description adds meaning beyond the input schema: it clarifies the behavior of the 'confirm' parameter (required for Suspended) and explains the 'status' enum values' effects (Enabled keeps versions, Suspended stops new versioning). The schema already covers 75% of parameters, and the description compensates well for the remaining 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 the tool's function: 'Set versioning to Enabled or Suspended'. It distinguishes the tool from siblings by focusing specifically on bucket versioning operations, and it explicitly contrasts with related tools like scaleway_s3_get_bucket_versioning and scaleway_s3_enable_object_lock.
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 strong usage guidance: it explains when to use Enabled vs Suspended, specifies the requirement for confirm=true when suspending, and warns about irreversible state transitions ('VERSIONING CAN NEVER GO BACK TO never-enabled'). It also includes a conditional failure condition for Object Lock integration, helping the agent avoid invalid states.
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the tool is clearly destructive. However, the description adds valuable behavioral context beyond annotations: it clarifies the immediate effect ('whoever holds that session is signed out right away'), the required confirm flag, and the parallel to API key revocation. There is no contradiction with annotations, and the extra context is substantial.
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 zero filler. Every word adds value: the tool's effect, the required parameter, the severity comparison. It is front-loaded with the core action and then elaborates efficiently.
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 (2 parameters, no output schema, destructive action), the description provides complete guidance: what it does, what it requires, what the outcome is, and how it compares to related actions. An agent can safely decide to invoke this tool with no additional documentation 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 50% – the confirm parameter has a description, but jti does not. The description explicitly mentions that confirm is required, and that the effect is 'immediate' and 'same severity as revoking an API key', adding meaningful semantic context for the confirm parameter. While jti is not individually described, the description as a whole explains what the tool targets (a session), compensating somewhat. The baseline of 3 is elevated to 4 because the description adds clear value 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 immediate, specific verbs ('Immediately invalidate', 'revoke') with a clear resource ('one active browser/console session', 'interactive login'). It clearly distinguishes this from API key revocation by explicitly contrasting the type of credential being revoked, effectively differentiating it from sibling IAM revocation 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?
The description explicitly states the tool requires 'confirm=true' and compares the severity to revoking an API key, providing clear context on when this is the appropriate tool (for interactive sessions) versus alternatives. The 'immediately invalidate ... same severity as revoking an API key' guides the agent to understand the weight of this action.
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.
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the creation aspect is clear. The description adds important caveats: the bucket is private by default, Object Lock at creation is silently ignored on Scaleway, and references configuration tools for subsequent setup. The one missing detail is whether the operation is idempotent or what happens if a bucket with the same name exists, but the context of 'create' and 'S3' implies non-idempotent.
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 efficient sentences with no fluff. The first sentence states the core action and default visibility. The second sentence immediately points to configuration tools for further setup. The third sentence provides a critical caveat about Object Lock and the correct workflow. Every sentence adds value and is front-loaded with the essential information.
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 simple 2-parameter input schema (bucket name and region), no output schema, and rich annotation context, the description is complete. It covers default visibility, post-creation configuration workflow, and a platform-specific nuance about Object Lock. There is no meaningful gap for this tool's purpose.
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%, covering bucket and region. The description adds no extra parameter-level detail, but this is acceptable because the schema already documents the bucket naming (minLength: 3) and region default. The region description in schema includes a concrete example ('fr-par'). The description's mention of 'private by default' and 'Scaleway' adds platform-specific context that aids 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 'Create a new, empty Object Storage bucket, private by default.' This provides a specific verb (create), resource (Object Storage bucket), and key attribute (empty, private by default). It also differentiates from sibling tools like scaleway_s3_get_bucket_tagging or scaleway_s3_set_bucket_versioning by explicitly mentioning configuration tools and their naming pattern.
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 not to configure settings at creation: 'Configure it afterwards with the scaleway_s3_*_bucket_* config tools.' It also warns that 'Object Lock cannot be enabled at creation on Scaleway' and provides the correct workflow: 'enable versioning then scaleway_s3_enable_object_lock afterwards.' 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, destructiveHint=false, but description clarifies the destructive behavioral effect (removing all CORS rules, thus disabling cross-origin access). It adds the 'default-deny' consequence which annotations don't provide, giving full transparency.
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 only 13 words, zero fluff. It front-loads the action and consequence efficiently.
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 simple tool (2 params, high schema coverage, no output schema), the description is complete. It explains what happens, the behavioral outcome, and when to use it, with no gaps.
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 'bucket' and 'region' parameters are documented in the schema. The description does not add extra meaning beyond what the schema already says, but that is acceptable given high schema coverage, hence 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 uses a specific verb 'Remove' and resource 'ALL CORS rules from a bucket'. It clearly distinguishes this tool from related sibling tools like scaleway_s3_get_bucket_cors and scaleway_s3_put_bucket_cors.
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 that after removal, browsers regain no cross-origin access (default-deny), which tells the agent exactly when to use this tool (when CORS restrictions should be removed) and implies the consequence of the action.
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, idempotentHint, etc. The description adds non-obvious behaviors: truncation to MAX_OUTPUT_CHARS, encoding decision (text vs base64), and the server-wide truncation policy. 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 the main purpose. Each sentence adds necessary context: purpose, encoding behavior, truncation and alternative. 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?
Given the tool's simplicity (3 params, no output schema, safe annotations), the description covers everything needed: what it does, encoding, truncation, and the alternative for large objects. No gaps.
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 documents all parameters. The description does not add further meaning beyond the schema, e.g., not explaining the region default. Baseline 3 is appropriate when schema is complete.
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 'Download a single object's content and metadata', which is a specific verb-object pair. It distinguishes from siblings like scaleway_s3_generate_presigned_url by mentioning truncation and providing an alternative for large objects.
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 the agent when to use this tool vs. the alternative: 'for large objects, use scaleway_s3_generate_presigned_url instead'. Also implies this is for small objects due to truncation, and 'single object' clarifies scope.
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 details behavioral traits beyond annotations: it can overwrite existing objects ('Upload (or overwrite)'), has a non-obvious binary encoding requirement ('base64-encode first'), and states idempotency (overwrite) aligning with the idempotentHint annotation. The size cap and single-part limitation add useful context. However, it does not mention whether bucket permissions are needed or if the operation affects bucket metadata. With idempotentHint=true and destructiveHint=false, the description adds meaningful behavioral 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, front-loaded with the core purpose ('Upload (or overwrite) a single object'), followed by a critical constraint (size ceiling and encoding). Every sentence earns its place with no waste, and the structure prioritizes essential information before details.
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 6 parameters (all well-documented in schema), the rich annotations (idempotent, not read-only, not destructive), and no output schema, the description is fully complete. It explains the single-part constraint, size limit, and encoding requirement—all critical for usage. No gaps are evident for this tool's complexity and provided schema/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 description coverage is 100%, so the schema already documents all parameters well. The description adds value by explaining the 'content' field's size ceiling and encoding requirement, and by reaffirming the default region. It goes beyond the schema by highlighting the max size limit and encoding setup, which are critical for correct usage. A 4 is appropriate because it enhances understanding without being redundant.
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 'Upload (or overwrite) a single object' with a specific verb ('Upload') and resource ('object to Scaleway Object Storage'). It distinguishes itself from other S3 tools like scaleway_s3_delete_object and scaleway_s3_copy_object. The mention of 'single-part only' and the reference to sibling tools suitable for larger uploads further differentiates its scope.
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 ('single-part only') and when not to: it mentions a size ceiling (MAX_PUT_OBJECT_BYTES, default 5 MB) and that 'multipart/large-file upload is out of scope; use the console or scw CLI for anything larger.' This provides clear boundaries and alternatives, helping the agent make appropriate decisions.
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?
The description provides extensive behavioral context beyond annotations: irreversibility (Scaleway rejects disable at XML-schema level), versioning frozen to Enabled, live-verification dates (2026-08-18), and that empty locked buckets can still be deleted. Annotations include destructiveHint=true, which is consistent, and the description adds concrete details.
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: purpose first, then irreversibility, then prerequisites and workaround. All sentences are informative. Minor redundancy (title already says ONE-WAY) but overall 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?
For an irreversible mutation tool with a prerequisite, the description covers all necessary context: what the tool does, the one-way nature, prerequisites, workaround for creation, confirmation requirements, and the fact that empty buckets can still be deleted. No output schema exists, but the return value is implicit (success/failure).
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?
Input schema coverage is 100%, so the baseline is 3. The description adds value by explaining the real-world implications of the 'confirm' parameter (one-way door) and the 'enable_versioning_if_needed' parameter (auto-enable vs. instructive failure), which goes beyond the schema 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 that this tool enables Object Lock (WORM) on a Scaleway bucket, making it irreversible. It specifies the exact behavior and distinguishes itself from sibling tools (e.g., scaleway_s3_get_object_lock, scaleway_s3_create_bucket) by being the only working method to enable object lock on Scaleway, as creating with the flag is silently ignored.
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 the prerequisite (versioning must be enabled) and offers the enable_versioning_if_needed parameter. It notes that creating a bucket with object lock at creation is not possible on Scaleway, positioning this tool as the sole working path. It also implies when not to use (if reversibility is needed) by highlighting irreversibility.
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 and idempotentHint=true, but the description adds crucial context beyond annotations: it explains that rules with 'expiration' permanently DELETE matching objects (not just transition), that this is a full replace (not a merge), and that confirm=true is required even if no destructive rules are present. This goes well beyond the annotation surface and prevents major errors.
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?
At three sentences, the description is efficient and front-loaded with critical warnings. The first sentence states purpose, the second delivers the most important behavioral notes (full-replace, destruction, confirm requirement), and the third adds storage class context. It's slightly verbose for a 4-param tool but earns its space by preventing mistakes. Could be trimmed slightly without loss.
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 destructive nature, 4 parameters (3 required), schema coverage of 75%, and no output schema, the description provides complete guidance for correct usage. It covers full-replace semantics, destructive potential with explicit deletion warning, confirm requirement, storage class targets, and scope (Scaleway storage classes). The sibling set is large, but the description effectively isolates this tool from other S3 configuration tools. No gaps exist 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 description coverage is 75%, covering 3 of 4 parameters. The description adds value by explaining the overall replace semantics and linking to schema fields like 'expiration_days'. However, it doesn't walk through each parameter individually. Since schema already documents 'rules', 'bucket', 'region', and 'confirm' reasonably well, the description compensates by contextualizing the rule structure (e.g., storage class options) and the mandatory confirm flag. A score of 4 reflects strong synergy with 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 clearly states the verb ('Set'), resource ('bucket's lifecycle rules'), and critical behavioral qualifiers ('FULL-REPLACE', 'DESTRUCTIVE'). It distinguishes this tool from siblings like 'scaleway_s3_get_bucket_lifecycle' (read) and 'scaleway_s3_delete_bucket_lifecycle' (remove all rules), which are the only other lifecycle-related tools. The description explicitly flags the destructive nature and full-replace semantics, 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 on when to use this tool vs alternatives. It notes that rules with expiration are destructive and require 'confirm=true regardless of rule content'. It also specifies that rules apply to Scaleway storage classes and transitions target specific classes (ONEZONE_IA, GLACIER), helping the agent avoid misuse. The sibling list includes complementary tools like get/delete lifecycle, making the boundary clear.
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 and readOnlyHint=false. The description goes beyond this by explicitly stating 'PERMANENTLY revoke', 'Irreversible', and the immediate authentication impact. It also flags the required confirmation step. This adds valuable context 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?
Two short, front-loaded sentences. No wasted words. Every sentence adds unique value: the first states the action and input, the second states the requirement and consequence.
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 a simple delete operation with 2 parameters, 100% schema coverage, no output schema, and clear annotations, the description is fully complete. It covers the essential behavioral context (destructiveness, confirmation requirement, immediate effect) that an agent needs.
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 value by explaining the purpose of confirm ('Must be explicitly true. Deletion is immediate...'), but it does not detail the access_key parameter format beyond what the schema provides (e.g., the 'SCWXXXXXXXXXXXXXXXXX' example is in the schema, not the description). A small deduction for not reiterating the format.
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 verb ('PERMANENTLY revoke') paired with a specific resource ('an API key by its access_key'). It is clearly distinct from siblings like scaleway_iam_list_api_keys, scaleway_iam_create_api_key, scaleway_iam_update_api_key, and other delete tools (e.g., scaleway_iam_delete_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?
The description explicitly says 'Requires confirm=true' and emphasizes that the action is 'Irreversible - anything using this key stops authenticating immediately.' This gives clear when-to-use guidance and warns against accidental use. It is properly differentiated from list/create/update API key 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?
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?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description explains the destructive nature (overwrites complete array, not merge), atomicity, and the safety rationale. It warns about the IAMPolicyManager lockout scenario, adding context about credential risk that annotations do not cover. 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 purpose and safety proposition. Every sentence earns its place: purpose, danger of alternative, prerequisite action. No redundancy or 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 complexity and sensitivity of IAM policy rules modification, the description covers the core behavior, atomic safety, lockout risk, prerequisite call, and the intended use case (add/remove permission sets). It is complete enough for an agent to correctly select and invoke the tool, especially with the sibling context and 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?
With schema coverage at 50% (policy_id lacks a description), the description compensates by thoroughly explaining the rules parameter's behavior and usage workflow (call list first, pass entire array). It does not add meaning for policy_id but heavily enriches the main parameter's semantics beyond the 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 immediately states the verb 'Overwrite' and resource 'COMPLETE rules array on an existing Policy', explicitly distinguishing itself from the delete+recreate pattern. It clearly specifies the atomic nature and safety, differentiating from sibling operations like scaleway_iam_list_policy_rules (read-only) or scaleway_iam_delete_policy (whole policy deletion).
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 guidance: 'the safe way to add or remove a permission set on a live policy' and 'Prefer this over delete+recreate' with a detailed explanation of the lockout danger. It also instructs to call scaleway_iam_list_policy_rules first, providing a clear prerequisite workflow.
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 set destructiveHint=true and idempotentHint=false, establishing this as a non-idempotent destructive operation. The description goes well beyond the annotations by proactively disclosing the inverse safety risk: removing rules stops pending deletions, causing objects to survive that would have been deleted. It also reveals the safety mechanism 'requires confirm=true', which the schema also documents. There is 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 compact at two sentences, immediately front-loading the all-removal scope in the first sentence. Every clause earns its place: the scope, the confirm requirement, the behavioral consequence, and the contrast to putting rules. There is zero 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's complexity (3 parameters, all schematically covered, no output schema, clear sibling alternatives), the description is complete. It explains the operation's effect, its dangerous directionality, and the mandatory safety parameter. No output schema exists, but the side effect of removing rules is adequately described. No behavioral dimensions remain unaddressed.
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 schema already fully documents all three parameters. The description adds value by semantically linking the 'confirm' parameter to its requirement and purpose as a safety gate. However, it does not elaborate on 'bucket' or 'region' beyond what the schema provides. A score of 4 is appropriate because the description enhances the meaning of the most consequential 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 a specific verb-resource combination ('Remove ALL lifecycle rules') and distinguishes the scope ('ALL') effectively. It distinctly separates this tool from its sibling scaleway_s3_get_bucket_lifecycle (which reads) and scaleway_s3_put_bucket_lifecycle (which creates/updates). The description precisely identifies the operation as a wholesale removal rather than a targeted rule deletion.
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 a critical prerequisite ('Requires confirm=true') and provides exceptional when-not-to-use guidance by explaining the dangerous consequence of removal: 'objects that would have expired keep living (rule removal stops pending deletions - dangerous in the opposite direction of putting rules).' This directly helps an agent decide whether to call this tool versus modifying or reading lifecycle 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?
The description clearly states the destructive nature (replace instead of merge), which aligns with and adds context beyond the annotations (destructiveHint: true). It explicitly calls out the non-merge behavior, which is critical for an agent to understand the operation's effect.
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 at one line, with the critical behavioral warning front-loaded in all caps ('This REPLACES, it does not merge - see the 'tags' field.') and cross-references. Every word 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 tool's limited parameter count (4), high schema coverage, and lack of output schema, the description covers all essential behavioral requirements: what the tool does, its destructive nature, prerequisites (getting existing tags first), and analogous sibling behavior (scaleway_s3_put_bucket_policy). It is complete for an agent to safely and effectively invoke 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 the schema already documents all parameters extensively. The description adds meaningful emphasis on the 'tags' parameter's replace-not-merge behavior and cross-references scaleway_s3_get_object_tags and scaleway_s3_put_bucket_policy for analogous semantics, providing valuable context 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 provides a specific verb ('Replace') and resource ('an object's entire tag set'), explicitly contrasting with merging behavior. This clearly distinguishes it from sibling tools like scaleway_s3_get_object_tags.
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 this operation replaces, not merges, and directs the user to call scaleway_s3_get_object_tags first if existing tags need to be preserved. 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?
Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description aligns with these: it reveals that setting public-read grants anonymous read access to all objects (a significant behavioral detail), that confirm=true is required, and that private restores owner access. 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?
The description is two sentences long, front-loading the core purpose and then efficiently adding the most critical behavioral notes (confirm requirement, sibling tool mention). Every sentence adds value 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?
Despite having no output schema, the description combined with annotations covers: what the tool does, when to use it vs. alternatives, parameter meanings, required confirm flag, and behavioral impact. The sibling list is large but the description explicitly disambiguates from the most relevant alternative (bucket policy tool). Complete for this tool's complexity.
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 covers 75% of parameters with descriptions. The description adds semantic value by clarifying what the two enum values actually do ('public-read' grants anonymous internet read, 'private' restores owner-only access) and by explaining the confirm parameter's required=True constraint when visibility=public-read. The region parameter's default is mentioned in schema but not description; still, the added value is strong.
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 visibility via canned ACL), the resource (bucket), and the specific settings (public-read/private). It explicitly calls out the sibling tool scaleway_s3_put_bucket_policy as the finer-grained alternative, which helps disambiguate from similar S3 tools 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 usage context: it describes when to use the tool (set visibility via canned ACL), includes a warning about the confirm=true requirement for public-read, and names the more granular alternative (scaleway_s3_put_bucket_policy). This enables the agent to make informed decisions.
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?
The description adds significant context beyond the annotations. While annotations confirm it is not read-only (`readOnlyHint: false`) and not destructive (`destructiveHint: false`), the description clarifies the 'patch' semantics: 'Only the fields you pass are changed; omitted fields are left as-is.' This is crucial for safe invocation and is not deducible from the schema or annotations alone. The exception for `expires_at` ('there is no way to clear an existing expiry back to 'never'') is a perfect example of transparent behavioral disclosure.
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 highly efficient. The opening sentence front-loads the verb, resource, and key behavioral constraint ('WITHOUT rotating its secret'). The second sentence provides the 'why' and 'when'. The final sentence clarifies the idempotent/patch-like behavior. Every sentence serves a distinct purpose with no waste, and the structure is logical for a decision-making 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?
Given the tool's moderate complexity (4 params, no nested objects, no output schema), the description is complete. It covers purpose, critical behavioral nuance (idempotency via patching), safety warning (secret not rotated), and a specific parameter caveat (unchangeable expiry). The agent has all the information needed to invoke this tool safely and correctly without any external reference.
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 description coverage is 100%, the tool description adds immense value. For the `expires_at` parameter, it explicitly warns that 'there is no way to clear an existing expiry back to 'never', only to set a new one', which is a critical caveat not present in the schema. The description's opening sentence also groups the purpose of all mutable parameters, reinforcing that they are all metadata-only changes. This elevates the param docs from merely descriptive to prescriptive.
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 verb ('Change') and clearly specifies the resource ('an existing API key's description, expiry, or default_project_id'). It immediately distinguishes itself from sibling tools like `scaleway_iam_delete_api_key` and `scaleway_iam_create_api_key` by emphasizing that it does NOT rotate the secret. This makes the tool's specific purpose within the IAM API key lifecycle 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?
The description provides excellent usage guidance. It explicitly states when to use this tool ('instead of delete+recreate for a metadata-only change') and gives concrete examples ('extending an expiry before it lapses, or fixing a stale description'). It also explains the negative consequence of the alternative ('delete+recreate would mint a new secret and break anything already deployed'), which is critical decision-making information for an 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 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/logic-arts-official/scaleway-ops-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/logic-arts-official/scaleway-ops-mcp-server)

Score Badge

Copy to your README.md:

[![scaleway-ops-mcp-server MCP server](https://glama.ai/mcp/servers/logic-arts-official/scaleway-ops-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/logic-arts-official/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/logic-arts-official/scaleway-ops-mcp-server'

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