Skip to main content
Glama

Update widget appearance

update_widget_appearance
Destructive

Set how a website inbox's chat widget looks and behaves: colours, light/dark theme, header style, the screen it opens on, per-language greetings and launcher text, launcher side/icon/offsets (the custom icon needs an image uploaded in the Widget Builder first), the launcher style (bubble, or a minimized text card with a prompt line, a button label per language and an optional https link under it, collapsed to the bubble on mobile unless launcher_card_on_mobile), the launcher_shape (round bubble or labelled pill), the bubble_theme (app, bocadillo, soft_brutal or echo: restyles the launcher, chat panel and text card together), the cards shown over the closed launcher (greeting with a text per language, away, typing, quick replies), the help-center deflection mode, whether "Powered by HellouOne" shows, under the text card too (hiding it needs a plan that allows it), and which sites may embed it. Buttons follow brand_color unless the widget has an action_color of its own. Installed widgets pick the change up on their next page load. Only the fields passed change; get_inbox shows the current values.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "inbox_id": "<inbox_id>"
    },
    "name": "update_widget_appearance"
  }
}

Input Schema

NameRequiredDescriptionDefault
themeNo
inbox_idYes
greetingsNoLanguage code => {title, tagline}; replaces all greetings.
deflectionNo
brand_colorNo
action_colorNo
bubble_themeNoapp is the current look. bocadillo gives every shape one square corner; soft_brutal is ink outlines with hard shadows; echo adds a faint offset copy behind each shape.
header_styleNo
start_screenNo
launcher_iconNohellou is the default mark. The *_animated icons, typing, duo, wave, heart, cursor and face are animated (still for visitors who reduce motion). custom draws the image an administrator uploaded in the Widget Builder first; it cannot be set before that upload.
show_brandingNo
launcher_labelNoLanguage code => launcher text; {} for icon only.
launcher_pulseNo
launcher_shapeNobubble is the round button; pill is icon plus label, 48px tall (always shown, phones included).
launcher_styleNobubble is the round button; card is a minimized text card with a prompt line and a button.
allowed_domainsNoSites allowed to embed the widget, one per line (example.com, *.example.com); null lets any site embed it.
away_card_enabledNoOutside business hours, show when the team is back and where the reply arrives (needs business hours on the inbox). Off by default.
launcher_card_ctaNoLanguage code => card button label (24 characters at most); replaces all languages.
launcher_positionNo
greeting_card_textNoLanguage code => greeting text (120 characters at most); replaces all languages. Empty: the widget's own hello.
launcher_card_textNoLanguage code => card prompt line (60 characters at most); replaces all languages.
typing_card_enabledNoShow who is typing over the closed launcher. Off by default.
greeting_card_enabledNoShow a hello over the closed launcher 8 seconds after the page loads, to visitors with no conversation. Off by default.
launcher_card_link_urlNohttps:// address the card link opens in a new tab (500 characters at most); null removes the link.
launcher_card_on_mobileNofalse (default): on small screens the card collapses to the bubble.
launcher_card_link_labelNoLanguage code => label of the optional link under the card (30 characters at most); replaces all languages. Shown only together with launcher_card_link_url.
quick_replies_card_enabledNoShow an AI agent's question with up to three answers over the closed launcher; an answer opens the chat. Off by default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changed
    • addedInput schema / properties / allowed_domains
      Added value: +{
      +  "description": "Sites allowed to embed the widget, one per line (example.com, *.example.com); null lets any site embed it.",
      +  "maxLength": 2000,
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / away_card_enabled
      Added value: +{
      +  "description": "Outside business hours, show when the team is back and where the reply arrives (needs business hours on the inbox). Off by default.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / bubble_theme
      Added value: +{
      +  "description": "app is the current look. bocadillo gives every shape one square corner; soft_brutal is ink outlines with hard shadows; echo adds a faint offset copy behind each shape.",
      +  "enum": [
      +    "app",
      +    "bocadillo",
      +    "soft_brutal",
      +    "echo"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / greeting_card_enabled
      Added value: +{
      +  "description": "Show a hello over the closed launcher 8 seconds after the page loads, to visitors with no conversation. Off by default.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / greeting_card_text
      Added value: +{
      +  "description": "Language code => greeting text (120 characters at most); replaces all languages. Empty: the widget's own hello.",
      +  "type": "object"
      +}
    • addedInput schema / properties / launcher_card_cta
      Added value: +{
      +  "description": "Language code => card button label (24 characters at most); replaces all languages.",
      +  "type": "object"
      +}
    • addedInput schema / properties / launcher_card_link_label
      Added value: +{
      +  "description": "Language code => label of the optional link under the card (30 characters at most); replaces all languages. Shown only together with launcher_card_link_url.",
      +  "type": "object"
      +}
    • addedInput schema / properties / launcher_card_link_url
      Added value: +{
      +  "description": "https:// address the card link opens in a new tab (500 characters at most); null removes the link.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / launcher_card_on_mobile
      Added value: +{
      +  "description": "false (default): on small screens the card collapses to the bubble.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / launcher_card_text
      Added value: +{
      +  "description": "Language code => card prompt line (60 characters at most); replaces all languages.",
      +  "type": "object"
      +}
    • addedInput schema / properties / launcher_icon / description
      Added value: +"hellou is the default mark. The *_animated icons, typing, duo, wave, heart, cursor and face are animated (still for visitors who reduce motion). custom draws the image an administrator uploaded in the Widget Builder first; it cannot be set before that upload."
    • changedInput schema / properties / launcher_icon / enum
      Previous value: -[
      -  "hellou",
      -  "chat",
      -  "question"
      -]New value: +[
      +  "hellou",
      +  "question",
      +  "headset",
      +  "phone",
      +  "sparkle",
      +  "message",
      +  "typing",
      +  "hellou_animated",
      +  "duo",
      +  "sparkle_animated",
      +  "headset_animated",
      +  "wave",
      +  "heart",
      +  "cursor",
      +  "phone_animated",
      +  "face",
      +  "custom"
      +]
    • addedInput schema / properties / launcher_shape
      Added value: +{
      +  "description": "bubble is the round button; pill is icon plus label, 48px tall (always shown, phones included).",
      +  "enum": [
      +    "bubble",
      +    "pill"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / launcher_style
      Added value: +{
      +  "description": "bubble is the round button; card is a minimized text card with a prompt line and a button.",
      +  "enum": [
      +    "bubble",
      +    "card"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / quick_replies_card_enabled
      Added value: +{
      +  "description": "Show an AI agent's question with up to three answers over the closed launcher; an answer opens the chat. Off by default.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / typing_card_enabled
      Added value: +{
      +  "description": "Show who is typing over the closed launcher. Off by default.",
      +  "type": "boolean"
      +}
  2. First observed

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the write/irreversibility profile is covered. The description adds genuinely new behavior: propagation latency ('Installed widgets pick the change up on their next page load'), plan and upload prerequisites, the action_color override of brand_color, and the launcher_card_on_mobile escape hatch. It never explains the destructive side (that language maps such as greetings and launcher_label are wholesale replacements, which only the schema descriptions mention), so it undersells the risk its own annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire body is a single run-on sentence of roughly 150 words with deeply nested parentheticals, making it hard to scan or parse. The most operationally important facts for an agent — patch-only semantics and the next-page-load propagation delay — are buried at the very end rather than front-loaded. The content itself is largely relevant, but the structure wastes it.

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 27-parameter destructive write with no output schema and only 63% schema coverage, the description is unusually complete: it covers prerequisites, defaults ('Off by default'), propagation timing, and cross-parameter dependencies. Gaps remain on return-value expectations and on how this tool relates to update_inbox, but nothing needed to call it safely is entirely absent.

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 63% schema coverage across 27 parameters, the description earns credit by adding relationships the schema cannot express: bubble_theme restyles launcher, chat panel and text card together; buttons follow brand_color unless action_color is set; the text card collapses to a bubble on mobile unless launcher_card_on_mobile; the card link label only renders alongside launcher_card_link_url. Many remaining fields (launcher_pulse, launcher_position, start_screen, deflection mode) are named without elaboration, so it does not fully compensate 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?

States a specific verb ('Set how ... chat widget looks and behaves') plus the resource (a website inbox's chat widget) and then enumerates the concrete facets: colours, theme, header style, start screen, greetings, launcher style/shape/icon/position, cards, deflection, branding, allowed domains. It is clearly distinguishable from read siblings because it explicitly points to get_inbox for current values.

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?

Gives real usage context: 'Only the fields passed change' establishes patch semantics, and 'get_inbox shows the current values' names the read tool to consult first. It also states prerequisites for two fields (custom launcher icon requires an upload in the Widget Builder; hiding 'Powered by HellouOne' requires a plan that allows it). It does not, however, distinguish this from the sibling update_inbox, which an agent could plausibly confuse with widget settings.

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.

Resources