Update Scaleway IAM Application

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.

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.

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.

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.

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.

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.