SurveyNinja

Create theme

create_theme

Destructive

Creates a theme inside the workspace and applies it to the quiz immediately.

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": {
      "workspace_id": "<workspace_id>",
      "quiz_id": "<quiz_id>"
    },
    "name": "create_theme"
  }
}

Input Schema

Name	Required	Description
`name`	No	Theme title (optional, max 255 characters). If omitted, it is generated automatically.
`quiz_id`	Yes	Quiz ID the theme is applied to. Must belong to the specified workspace.
`bg_color`	No	Background color as #RRGGBB. Used when background_type_id=1. Example: #0f3460.
`base_font`	No	Base font name as a string (e.g. "Golos Text", "Montserrat"). Optional, max 255 characters. If empty, the default font is used.
`dark_mode`	No	Dark version: off — none, auto — follows the respondent device theme (colors in dark_colors).
`custom_css`	No	Your own CSS for the quiz page, up to 20000 characters.
`link_color`	No	Link color in texts, #RRGGBB. null — the active color (widget_active_color).
`dark_colors`	No	Dark version colors: object { field: "#RRGGBB" }. Keys: bg_color, header_color, answers_text_color, widget_active_color, buttons_color, buttons_text_color, dropdown_bg_color, link_color, error_color, backdrop_color, bg_gradient_start, bg_gradient_end. Unknown keys are dropped; fields without a key stay light.
`error_color`	No	Color of validation errors and the error field border, #RRGGBB. null — #e5484d.
`input_style`	No	Input field style: box — a framed field, underline — a single line.
`base_font_id`	No	Base font ID. Common values: 1=Native, 2=Roboto, 3=Open Sans, 4=Montserrat, 5=Source Sans Pro, 6=Merriweather, 9=PT Sans, 11=Ubuntu, 15=Rubik, 18=Comfortaa, 44=Golos Text. Full range 1–44.
`bg_video_url`	No	Background video URL (.mp4, .webm): a root-relative path or an http(s) URL. Used with background_type_id 3.
`header_color`	No	Header color as #RRGGBB. Example: #1a1a2e.
`heading_font`	No	Separate font for headings, a Google Fonts family name. Empty means the same font as the rest.
`service_text`	No	Service text, up to 500 characters. Simple markup is allowed, everything else is stripped out.
`workspace_id`	Yes	Workspace ID. From workspace://list.
`answer_border`	No	Answer option border width in px (0–999). Example: 1.
`buttons_color`	No	Button color as #RRGGBB. Example: #3b82f6.
`answer_letters`	No	Letters A, B, C… before options of choice questions; keyboard selection.
`backdrop_color`	No	Backdrop card color (question_backdrop: card), #RRGGBB.
`buttons_radius`	No	Button corner radius in px (0–999). Example: 8.
`progress_style`	No	Progress indicator: percent, line or steps.
`answers_size_id`	No	Answer options size: 0 — small, 1 — medium, 2 — large. null together with answers_size_percent — same as the question.
`bg_gradient_end`	No	Gradient end color as #RRGGBB. Example: #00ffd8.
`bg_logo_file_id`	No	Uploaded logo file ID on the background (min:1).
`bg_logo_size_id`	No	Logo size on the background: 0 — small, 1 — medium (default), 2 — large.
`buttons_type_id`	No	Button type: 1=background (solid color fill), 2=border (outline only).
`container_width`	No	Content width: narrow, normal, wide or full.
`custom_font_url`	No	Custom font file URL (.woff2, .woff, .ttf, .otf): a root-relative path or an http(s) URL. A file on a third-party server must be served with Access-Control-Allow-Origin.
`bg_image_file_id`	No	Uploaded background image file ID (min:1). Used when background_type_id=1.
`custom_font_name`	No	Custom font name, up to 60 characters: letters, digits, space, dot, hyphen, underscore. To apply the font, put the same name into base_font or heading_font.
`bg_gradient_start`	No	Gradient start color as #RRGGBB (exactly 6 hex digits). Example: #00d4ff.
`button_full_width`	No	Stretch the button to the full width of the container.
`dropdown_bg_color`	No	Expanded dropdown menu background color as #RRGGBB (optional). If omitted, inherits bg_color.
`question_backdrop`	No	Backdrop under questions: none, card — a card in backdrop_color, glass — frosted glass.
`questions_size_id`	No	Question text size: 0 — small, 1 — medium, 2 — large.
`service_text_size`	No	Service text size: 12, 14 or 16.
`answers_text_color`	No	Answers text color as #RRGGBB (optional). If omitted, inherits header_color.
`background_opacity`	No	Background opacity in percent (0–100). 100 = fully opaque.
`background_type_id`	No	Background type: 1=color_image (color / image), 2=gradient (gradient), 3=video (video from bg_video_url).
`bg_gradient_vector`	No	Gradient direction in degrees (0–360). Used when background_type_id=2. Example: 90 = left to right, 180 = top to bottom.
`buttons_text_color`	No	Button text color as #RRGGBB. Example: #ffffff.
`service_text_color`	No	Service text color as #RRGGBB.
`service_text_scope`	No	Where the service text is shown: all — every screen, welcome, questions or finish.
`background_contrast`	No	Background contrast (-100 – +100). 0 = no change.
`background_saturate`	No	Background saturation (-100 – +100). 0 = no change.
`bg_logo_position_id`	No	Logo position on the background: 0 — left (default), 1 — center, 2 — right. Its own numbering, different from background_position_id.
`bg_mobile_image_url`	No	Custom background image URL for phones: a root-relative path or an http(s) URL. null — the main image on phones.
`question_transition`	No	Transition between questions: slide, fade, zoom, blur or none.
`widget_active_color`	No	Active widget element color as #RRGGBB. Example: #e94560.
`answers_size_percent`	No	Custom answer options size, percent of medium: integer 50–200. Takes precedence over answers_size_id.
`background_lightness`	No	Background lightness (-100 – +100). 0 = no change.
`bg_gradient_animated`	No	Animated gradient: gradient background colors slowly flow.
`service_text_enabled`	No	Show the service text — a short line for a disclaimer or a consent note.
`answer_options_radius`	No	Answer option corner radius in px (0–999). Example: 4.
`answer_selected_style`	No	How a selected option is marked: fill — filled, frame — border, check — check mark on the right.
`questions_position_id`	No	Question text alignment: 0 — left, 1 — center.
`service_text_align_id`	No	Service text alignment: 0 — left, 1 — center, 2 — right. Right works only with the top placement: the bottom right corner holds the navigation arrows and the SurveyNinja badge.
`background_position_id`	No	Background position: 1=center center, 2=left center, 3=right center, 4=center top, 5=left top, 6=right top, 7=center bottom, 8=left bottom, 9=right bottom.
`questions_size_percent`	No	Custom question text size, percent of medium: integer 50–200. null — size by questions_size_id.
`background_placement_id`	No	Background placement: 1=stretch (stretch to fill), 2=drawin (fit inside), 3=cover (fill).
`service_text_placement_id`	No	Where the service text sits on the screen: 0 — bottom, 1 — top.
`welcome_and_finish_size_id`	No	Text size on the welcome and finish screens: 0 — small, 1 — medium, 2 — large.
`welcome_and_finish_position_id`	No	Text alignment on the welcome and finish screens: 0 — left, 1 — center.
`welcome_and_finish_size_percent`	No	Custom welcome and finish text size, percent of medium: integer 50–200. null — size by welcome_and_finish_size_id.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds one genuinely useful behavioral fact beyond that: the theme is applied to the quiz immediately, i.e. the call has a side effect on quiz appearance. It does not say what happens to the quiz's previous theme (overwritten? recoverable?), which is the key unknown given destructiveHint=true, nor does it mention permissions or limits.

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?

A single front-loaded sentence with no filler or redundancy; the primary effect is stated first and the side effect second. It is efficient, though arguably undersized for a 65-parameter destructive tool, a shortfall captured under contextual completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 65-parameter, non-idempotent, destructive-brief mutation with no output schema, one sentence leaves real gaps: whether the prior quiz theme is destroyed, whether the tool returns the new theme ID, and how it relates to update_theme/apply_quiz_theme. The rich schema covers inputs, but the description does not cover the consequences an agent needs before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with unusually detailed per-field docs (color formats, enum meanings, ID ranges, conditional dependencies such as background_type_id gating bg_image_file_id). The description adds nothing about parameters, but the schema carries the full burden, so the baseline of 3 applies.

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?

States a specific verb and resource (creates a theme) plus a scope (inside the workspace) and an immediate effect (applied to the quiz). However, it does not differentiate from close siblings such as update_theme, manage_theme, or apply_quiz_theme, so an agent cannot tell from the description alone whether this creates a new theme, applies an existing one, or overwrites.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and no prerequisites are mentioned (e.g., that a workspace and quiz must exist, or that an existing quiz theme will be replaced). The clause 'applies it to the quiz immediately' hints at intent but never routes the agent toward apply_quiz_theme or update_theme instead.

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

All SurveyNinja tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.