Skip to main content
Glama

Update AI environment

update_ai_environment
Destructive

Update the organisation's AI environment settings. Organisation admins only. Only the fields present in the call change; pass an empty string to clear staging_cluster_id or any demo domain field. Setting staging_cluster_id is the switch that turns on PR preview environments and AI workspaces: the cluster must belong to the organisation and not be a sandbox, and once set the platform provisions the cluster's preview DNS zone and installs external-dns on it automatically so demo preview hostnames resolve. demo_base_domain (with the optional demo_ingress_class_name and demo_tls_secret_name) overrides the platform zone with an organisation-owned wildcard domain the admin points at the staging cluster themselves. Returns the saved settings.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "update_ai_environment"
  }
}

Input Schema

NameRequiredDescriptionDefault
demo_ttl_hoursNoDefault hours a PR demo lives before the reaper deletes it (1-720).
dns_root_domainNoThe organisation's own custom root domain its delegated DNS zones (and so its platform-zone preview URLs) hang off - a bare domain dedicated to this organisation, unique across organisations, whose NS records must already point at the Ankra nameservers (the ones serving the platform default). Empty string returns to the platform default (dns_root_domain_default). Zones already provisioned keep their root; a change is refused while cluster DNS zones or manual DNS records still live under the old root, and otherwise the organisation zone is torn down and re-created under the new domain automatically.
demo_base_domainNoOrganisation-owned bare DNS zone (like previews.example.com) public demo URLs hang off; the admin points its wildcard DNS at the staging cluster. Empty string clears it, falling back to the staging cluster's platform-provisioned zone.
demo_ttl_role_capsNoPer-role demo TTL caps in hours, keyed by 'admin', 'operator', or 'member' (values 1-720). Only the provided roles change.
staging_cluster_idNoUUID of the cluster to stage AI workspaces and PR demos on. Empty string clears the staging cluster (which disables PR demos and workspaces). Discover ids with list_clusters.
workspace_ttl_hoursNoHours an ephemeral AI workspace pod lives before the reaper deletes it (1-168).
demo_tls_secret_nameNoKubernetes TLS secret name backing https on demo_base_domain hosts; the secret must exist in each demo namespace (for example via a secret replicator). Empty string clears it, serving previews over http.
demo_ingress_class_nameNoIngressClass demo Ingresses use when demo_base_domain is set (for example traefik or nginx). Empty string clears it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing real side effects: setting staging_cluster_id auto-provisions a preview DNS zone and installs external-dns, demo_base_domain delegates DNS control to the admin, and dns_root_domain changes are refused while zones or manual records remain under the old root. It also states that unchanged fields are preserved and that the tool returns saved settings — exactly the operational context an agent needs before a destructive mutation.

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?

Front-loaded with purpose and the admin restriction, then dense but purposeful sentences on each behavior. Some of the DNS-root sentence is long and run-on, but essentially every clause carries operational information rather than 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 an 8-parameter, zero-required, destructive mutation tool with a nested object, the description covers permissions, partial-update semantics, clearing behavior, provisioning side effects, refusal conditions, and the return value ('Returns the saved settings'). With full schema coverage and no output schema, nothing material is missing.

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 nonetheless adds cross-parameter meaning, explaining that staging_cluster_id is the master switch for PR previews and workspaces and must reference an org-owned non-sandbox cluster, and that demo_base_domain overrides the platform zone. It doesn't re-explain the TTL fields, which the schema already covers.

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?

Opens with a specific verb and resource ('Update the organisation's AI environment settings'), which cleanly contrasts with the obvious read counterpart get_ai_environment. It does not name any sibling explicitly, but the scope is unambiguous enough that an agent knows what it changes.

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?

Gives a hard prerequisite ('Organisation admins only') and partial-update semantics, plus how to disable features via empty strings. It stops short of stating when to use this versus the overlapping demo-related sibling update_application_demo_config, or when to prefer get_ai_environment first, so usage is implied rather than routed.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.