Enable SAML SSO for the Organization

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.

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.

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.

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.

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.

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.