Skip to main content
Glama

Update form

update_form
Destructive

Update a form of the current team: title / description / isActive / flagImg / landingImage / theme / report / openGraph / language / systemText. flagImg is the quiz cover, landingImage the landing-page cover (sets the image only, does not toggle the landing page); both take a media id from finalize_image_upload, a media URL, or "" to clear. report and openGraph (the social share card on the answer link) merge by sub-key — only what you pass is replaced, "" clears an openGraph sub-key; in the outcome_quiz scene outcomes are matched by code so existing images survive, and removing an outcome still referenced by question votes is rejected. systemText is replaced wholesale ({} clears it). language is changeable only while the form has no language versions; scene never. Questions go through add_question / update_question / delete_question / move_question, dimensionAnalysis alone through set_dimension_analysis.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesThe form ID to update
themeNoNew visual theme for the answer page. Only this sub-key of personalized is changed; settings are kept. Optional visual theme matching the quiz topic/mood. Default light. Pick the one that best fits the quiz: light (clean neutral bright; default — formal/general quizzes); corporate (professional blue+gray; B2B, career, business assessments); dark (modern sleek dark; tech, night, cool personality quizzes); cupcake (soft pink cute rounded; fun, food, kids, lighthearted); pastel (gentle pastel artsy; lifestyle, aesthetics, soft mood); valentine (pink romantic hearts; love, relationships, holidays); synthwave (neon purple/pink retro; gaming, trends, bold personality); luxury (dark + gold premium; finance, luxury brands, high-end); forest (deep green nature; environment, health, outdoors); coffee (warm brown cozy; food & drink, cafe, lifestyle); autumn (warm orange/brown seasonal; autumn, cozy, harvest); halloween (purple+orange spooky; Halloween, horror, festive fun); night (deep calm blue; astronomy, mindfulness, calm tech); cyberpunk (high-contrast neon yellow; tech, esports, gaming).
titleNoNew title
reportNoReport configuration, merged by sub-key into form.report: passing overallAnalysis fields (title/formula/levels/summaryTemplate/suggestionsTemplate/hideOverallScore) replaces overallAnalysis; passing dimensionAnalysis replaces the dimension list (codes are kept by code or by name, omitted title / radar settings are preserved; an empty dimensions array clears it; a dimension still referenced by a question's dimensionScores or by report.formula cannot be removed); in the outcome_quiz scene passing outcomes replaces the outcome list (matched by code, existing images kept; cannot be emptied, and removing an outcome still referenced by question votes is rejected); unspecified parts are kept. Common usage: either set custom question codes in create_form and pass report.formula / dimensionAnalysis in the same call, or call create_form first to get the auto-generated field codes, then update_form to fill in report.formula and/or dimensionAnalysis (which reference question codes).
flagImgNoQuiz cover image: a media ID returned by finalize_image_upload, or a media URL. Pass an empty string to clear the cover.
isActiveNoWhether to enable response collection
languageNoChange the form's language. Only allowed while the form has no translation links and is not referenced by other language versions; otherwise rejected.
openGraphNoSocial share card (Open Graph) settings: the title / description / image shown when the answer link is shared to social media or chat apps. In update_form each sub-key is merged independently (only the keys you pass change; pass an empty string to clear one). SEO keywords are generated automatically and cannot be set here.
systemTextNoAnswer-page system text overrides as a key→text map. Replaces the whole map (pass {} to clear); empty values are dropped and fall back to the language default.
descriptionNoNew description; pass an empty string to clear. Allows description-scope rich text (including <img src>). This field also accepts an inline image: put an <img src="..."> in it, where src is a direct image URL that renders in <img src> (a page URL that merely contains an image does not work). Use finalize_image_upload to host an image yourself, or a direct URL the user supplied. Never invent an image URL — omit the image instead of risking a broken one.
landingImageNoLanding page cover image: a media ID returned by finalize_image_upload, or a media URL. Pass an empty string to clear it. Note: this only sets the image and does NOT toggle the landing page on/off; the landing image is shown only when the landing page is enabled.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoForm id
sceneNoknowledge_quiz / scored_quiz / outcome_quiz
themeNoAnswer-page theme name
titleNoForm title after the update
flagImgNoMedia id of the quiz cover
isActiveNoWhether the form is open for submissions
languageNoPrimary language
hasReportNoWhether this call replaced the report configuration
openGraphNoSocial share card
updatedAtNoISO datetime
systemTextNoOverridden system copy
descriptionNoForm description
landingImageNoMedia id of the landing-page cover

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / report / description
      Previous value: -"Report configuration, merged by sub-key into form.report: passing overallAnalysis fields (title/formula/levels/summaryTemplate/suggestionsTemplate/hideOverallScore) replaces overallAnalysis; passing dimensionAnalysis replaces it (an empty dimensions array clears it); in the outcome_quiz scene passing outcomes replaces the outcome list (matched by code, existing images kept; cannot be emptied, and removing an outcome still referenced by question votes is rejected); unspecified parts are kept. Common usage: either set custom question codes in create_form and pass report.formula / dimensionAnalysis in the same call, or call create_form first to get the auto-generated field codes, then update_form to fill in report.formula and/or dimensionAnalysis (which reference question codes)."New value: +"Report configuration, merged by sub-key into form.report: passing overallAnalysis fields (title/formula/levels/summaryTemplate/suggestionsTemplate/hideOverallScore) replaces overallAnalysis; passing dimensionAnalysis replaces the dimension list (codes are kept by code or by name, omitted title / radar settings are preserved; an empty dimensions array clears it; a dimension still referenced by a question's dimensionScores or by report.formula cannot be removed); in the outcome_quiz scene passing outcomes replaces the outcome list (matched by code, existing images kept; cannot be emptied, and removing an outcome still referenced by question votes is rejected); unspecified parts are kept. Common usage: either set custom question codes in create_form and pass report.formula / dimensionAnalysis in the same call, or call create_form first to get the auto-generated field codes, then update_form to fill in report.formula and/or dimensionAnalysis (which reference question codes)."
    • changedInput schema / properties / report / properties / dimensionAnalysis / description
      Previous value: -"Multi-dimension analysis (radar chart + per-dimension breakdown). Each dimension gets a server-generated code returned in structuredContent. In the knowledge_quiz scene set fieldCodes per dimension; in the scored_quiz scene set a formula. Dimensions reference question codes: if you set custom question codes you can configure dimensions in the same create_form call; otherwise create the questions first, then get_form to read the auto-generated codes."New value: +"Multi-dimension analysis (radar chart + per-dimension breakdown). Each dimension has a stable code (pass dimensions[].code or let the server generate one; returned in structuredContent). In the knowledge_quiz scene set fieldCodes per dimension. In the scored_quiz scene every dimension needs a formula over question codes (e.g. `{{q1}} + {{q2}}`); a question may override its score for one dimension via choices[i].dimensionScores, otherwise the formula uses its plain choice score. If you set custom question codes you can configure everything in one create_form call; otherwise create the questions first, then get_form to read the auto-generated codes."
    • addedInput schema / properties / report / properties / dimensionAnalysis / properties / dimensions / items / properties / code
      Added value: +{
      +  "description": "Optional stable identifier for the dimension (same rules as question codes: starts with a letter or underscore, letters/digits/underscores only). Set it when questions reference the dimension via choices[i].dimensionScores in the same create_form call. When updating, pass the existing code to keep it; if omitted, a dimension with the same name keeps its current code, otherwise one is generated.",
      +  "maxLength": 64,
      +  "type": "string"
      +}
    • changedInput schema / properties / report / properties / dimensionAnalysis / properties / dimensions / items / properties / fieldCodes / description
      Previous value: -"Required in the knowledge_quiz scene: the question codes this dimension covers (dimension score = sum of these field scores). Each code must exist in the form. Ignored in the scored_quiz scene."New value: +"Required in the knowledge_quiz scene: the question codes this dimension covers (dimension score = sum of these field scores). Each code must exist in the form. Ignored in the scored_quiz scene, where the formula decides which questions count."
    • changedInput schema / properties / report / properties / dimensionAnalysis / properties / dimensions / items / properties / formula / description
      Previous value: -"Required in the scored_quiz scene: the dimension score formula. Question codes must be wrapped in `{{code}}` (e.g. `{{q1}} + {{q2}}` when you set custom question codes, or `{{__field_abc}} + {{__field_def}}` for auto-generated ones); bare codes are rejected. Supported operators: + - * / ( ). Ignored in the knowledge_quiz scene."New value: +"Required in the scored_quiz scene: the dimension score formula, usually the sum of the questions in this dimension. Question codes must be wrapped in `{{code}}` (e.g. `{{q1}} + {{q2}}` when you set custom question codes, or `{{__field_abc}} + {{__field_def}}` for auto-generated ones); bare codes are rejected. Inside a dimension formula `{{q}}` is the question's score for THIS dimension: its choices[i].dimensionScores override when set, otherwise the plain choice score. A dimension formula cannot reference other dimensions (only report.formula can). Supported operators: + - * / ( ). Ignored in the knowledge_quiz scene."
    • changedInput schema / properties / report / properties / dimensionAnalysis / properties / dimensions / items / properties / standardScore / description
      Previous value: -"Standard score (the radar-chart standard line; in the scored_quiz scene it also acts as the dimension full mark). Default 0."New value: +"Standard score (the radar-chart standard line; in the scored_quiz scene it also acts as the dimension full mark). When omitted in the scored_quiz scene it defaults to the attainable maximum: the formula evaluated with every referenced question at its highest score for this dimension (choices[i].dimensionScores override, else the choice score); 0 when that cannot be estimated, e.g. the formula uses NumberField / date questions. knowledge_quiz defaults to 0."
    • changedInput schema / properties / report / properties / formula / description
      Previous value: -"Total-score formula for the scored_quiz scene, and the ONLY source of the overall score there — summing question scores is the knowledge_quiz rule, so a scored_quiz without this formula scores null and no level ever matches. Required whenever levels are set. Question codes must be wrapped in `{{code}}` (e.g. `{{q1}} + {{q2}}` for custom question codes, or `{{__field_abc}} + {{__field_def}}` for auto-generated ones); bare codes are rejected. Supported operators: + - * / ( ); every referenced code must exist in the current form. Setting dimension formulas does NOT cover this — the overall formula is separate."New value: +"Total-score formula for the scored_quiz scene, and the ONLY source of the overall score there — summing question scores is the knowledge_quiz rule, so a scored_quiz without this formula scores null and no level ever matches. Required whenever levels are set. Question codes must be wrapped in `{{code}}` (e.g. `{{q1}} + {{q2}}` for custom question codes, or `{{__field_abc}} + {{__field_def}}` for auto-generated ones); bare codes are rejected. It may also reference dimension codes the same way (e.g. `{{dim_d}} * 2 + {{dim_i}}`): dimensions are computed first, so the overall score can be a weighted sum of dimension scores; a dimension referenced here cannot be removed later. Supported operators: + - * / ( ); every referenced code must exist in the current form (questions and dimensions). Setting dimension formulas does NOT cover this — the overall formula is separate."
    • changedInput schema / properties / report / properties / levels / items / properties / cta / properties / newWindow / description
      Previous value: -"Open the link in a new window, default false"New value: +"Deprecated and ignored: the CTA link always opens in a new window."
    • changedInput schema / properties / report / properties / outcomes / items / properties / cta / properties / newWindow / description
      Previous value: -"Open the link in a new window, default false"New value: +"Deprecated and ignored: the CTA link always opens in a new window."
  2. Changed1 schema field changed
    • changedInput schema / properties / report / properties / hideOverallScore / description
      Previous value: -"Hide the overall score on the result page (the score ring / number / percentile), keeping the level name, level description and summary. Scored scenes only (ignored for outcome). Default false."New value: +"Hide scores on the result page: the overall score (score ring / number / percentile) AND every dimension score (score / max score / progress bar / score rate) are hidden together, keeping level names, level descriptions, the level ladder, dimension levels and the summary. Note the summary template still renders its score variable if you left one in. Scored scenes only (ignored for outcome). Default false."
  3. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this mutates and can destroy data. The description adds genuine behavioral value beyond those flags: report and openGraph merge by sub-key (only what is passed is replaced), systemText is replaced wholesale with {} clearing it, outcomes in the outcome_quiz scene are matched by code so existing images survive, and removing an outcome still referenced by question votes is rejected. It also notes landingImage only sets the image and does not toggle the landing page. No contradiction with 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.

Conciseness3/5

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

The description is a single dense paragraph of roughly 250 words. There is zero fluff and every sentence carries information, but for a tool with 11 parameters and complex merge semantics, a structured format (short intro, then per-behavior bullets) would aid scannability. The key facts are front-loaded in the first sentence, but the remaining run-on sentences compress several distinct behaviors (media handling, merge semantics, outcome matching, systemText replacement, language restriction, sibling routing) into one block, which an agent must parse carefully.

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 (11 parameters, nested objects, output schema present) and the 100% schema description coverage, the description provides a complete high-level map: it covers merge semantics, media sourcing, the clear-with-empty-string convention, the language restriction, scene immutability, and routes all out-of-scope operations to named siblings. Return values and detailed parameter rules live in the output schema and input schema respectively, so nothing an agent needs to call this tool correctly 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 description coverage is 100%, so the schema itself documents every parameter exhaustively (baseline 3). The description adds a compact high-level synthesis: it groups the updatable fields, clarifies the flagImg vs landingImage roles (quiz cover vs landing-page cover, the latter not toggling the page), states both accept a media id from finalize_image_upload, a media URL, or '' to clear, and summarizes the cross-cutting merge vs replace behavior that the schema only documents per-parameter. This is genuine incremental value over the schema, though the schema carries most of the 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 states a specific verb and resource ('Update a form of the current team') and enumerates exactly which fields are in scope: title / description / isActive / flagImg / landingImage / theme / report / openGraph / language / systemText. It actively distinguishes itself from siblings by routing questions to add_question/update_question and dimensionAnalysis to set_dimension_analysis, so an agent can tell it apart from create_form, update_form_settings, and set_dimension_analysis without opening any schema.

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 and when-not-to-use guidance. It names the sibling tools for adjacent operations ('Questions go through add_question / update_question / delete_question / move_question, dimensionAnalysis alone through set_dimension_analysis') and spells out conditional usage rules: language is changeable only while no language versions exist, and scene is never changeable. It also documents the merge-by-sub-key semantics for report and openGraph, so the agent knows how to construct partial updates. Nothing is left to inference.

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