Reference

#ToolCategoryRead-Only
1create_projectProject Managementfalse
2get_projectProject Managementtrue
3list_projectsProject Managementtrue
4list_screensScreen Managementtrue
5get_screenScreen Managementtrue
6generate_screen_from_textAI Generationfalse
7edit_screensAI Generationfalse
8generate_variantsAI Generationfalse
9create_design_systemDesign Systemsfalse
10update_design_systemDesign Systemsfalse
11list_design_systemsDesign Systemstrue
12apply_design_systemDesign Systemsfalse
13upload_design_mdDesign Systemsfalse
14create_design_system_from_design_mdDesign Systemsfalse

Tools

create_project

Creates a new Stitch project. A project is a container for UI designs and frontend code.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Optional. The title of the project."
    }
  },
  "required": []
}

Output

Returns the created Project resource with generated name, title, and metadata.

Example Prompts

PROMPT
Create a new Stitch project called ‘Marketing Site’ Start a new design project Set up a new project for my app

get_project

Retrieves the details of a specific Stitch project using its project name.

Annotations

readOnly

Input

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}`. Example: `projects/4044680601076201931`"
    }
  },
  "required": ["name"]
}

Output

Returns a Project resource object.

Example Prompts

PROMPT
Get the details of project 4044680601076201931 Show me the project info What’s in my project?

list_projects

Lists all Stitch projects accessible to the user. By default, it lists projects owned by the user.

Annotations

readOnly

Input

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "Optional. AIP-160 filter on `view` field. Supported: `view=owned` (default), `view=shared`."
    }
  },
  "required": []
}

Output

Array of Project resource objects.

Example Prompts

PROMPT
List all my Stitch projects Show me my projects List shared projects

list_screens

Lists all screens within a given Stitch project.

Annotations

readOnly

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID (e.g., '4044680601076201931'), without `projects/` prefix."
    }
  },
  "required": ["projectId"]
}

Output

Array of Screen objects.

Example Prompts

PROMPT
List all screens in project 12345 Show me the designs in this project What screens are in my project?

get_screen

Retrieves the details of a specific screen within a project.

Annotations

readOnly

Input

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
    },
    "projectId": {
      "type": "string",
      "description": "Required (deprecated). Project ID without prefix."
    },
    "screenId": {
      "type": "string",
      "description": "Required (deprecated). Screen ID without prefix."
    }
  },
  "required": ["name", "projectId", "screenId"]
}

projectId and screenId are deprecated in favor of name (resource name format), but all three are currently required.

Output

Returns a Screen object with htmlCode, screenshot, figmaExport file references and download URLs.

Example Prompts

PROMPT
Get the details of screen abc123 in project 12345 Show me the screen info Check the status of this screen

generate_screen_from_text

Generates a new screen from a text prompt. This process normally takes a few minutes. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using get_screen after a few minutes. If output_components contains suggestions, present them to the user. If accepted, call again with the suggestion as the new prompt.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Text prompt describing the screen to generate."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "prompt"]
}

GEMINI_3_PRO is deprecated. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead.

Output

Returns generated Screen objects and SessionOutputComponent entries (text, suggestions, or design references).

Example Prompts

PROMPT
Generate a mobile login screen for project 12345 Design a dashboard page with charts and statistics Create a landing page with a hero section, features grid, and footer Build a settings page for a dark-themed app

edit_screens

Edits existing screens using a text prompt. Similar to generate_screen_from_text, this process normally takes a few minutes. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using get_screen after a few minutes.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenIds": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Required. Screen IDs to edit, without `screens/` prefix."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Edit instruction."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "selectedScreenIds", "prompt"]
}

GEMINI_3_PRO is deprecated. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead.

Output

Returns the updated Screen objects.

Example Prompts

PROMPT
Change the button color to blue on screen abc123 Make the hero text larger and add a subtitle Add a navigation bar to these screens Switch the layout to a two-column grid

generate_variants

Generates design variants of existing screens.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenIds": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Required. Screen IDs to generate variants for."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Text guiding variant generation."
    },
    "variantOptions": {
      "$ref": "#/$defs/VariantOptions",
      "description": "Required. Variant configuration."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "selectedScreenIds", "prompt", "variantOptions"]
}

GEMINI_3_PRO is deprecated. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead.

VariantOptions
{
  "type": "object",
  "properties": {
    "variantCount": {
      "type": "integer",
      "description": "Number of variants (1–5). Default: 3."
    },
    "creativeRange": {
      "type": "string",
      "enum": ["CREATIVE_RANGE_UNSPECIFIED", "REFINE", "EXPLORE", "REIMAGINE"]
    },
    "aspects": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["VARIANT_ASPECT_UNSPECIFIED", "LAYOUT", "COLOR_SCHEME", "IMAGES", "TEXT_FONT", "TEXT_CONTENT"]
      }
    }
  }
}

Output

Returns generated variant Screen objects.

Example Prompts

PROMPT
Generate 3 variants of screen abc123 focusing on layout and color Reimagine my landing page with radical variations Create subtle refinements of these screens Show me 5 different color schemes for this design

create_design_system

Creates a new design system for a project. Establishes foundational design tokens (colors, typography, shapes, appearance) that apply across all screens.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "designSystem": {
      "$ref": "#/$defs/DesignSystem",
      "description": "Required. The design system to create."
    },
    "projectId": {
      "type": "string",
      "description": "Optional. Project ID. If empty, creates a global (unassociated) asset."
    }
  },
  "required": ["designSystem"]
}
DesignSystem
{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "description": "Required. Display name."
    },
    "theme": {
      "$ref": "#/$defs/DesignTheme",
      "description": "Required. Theme configuration."
    }
  },
  "required": ["displayName", "theme"]
}
DesignTheme
{
  "type": "object",
  "properties": {
    "colorMode": { "type": "string", "enum": ["COLOR_MODE_UNSPECIFIED", "LIGHT", "DARK"] },
    "headlineFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "bodyFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "labelFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "roundness": { "type": "string", "enum": ["ROUNDNESS_UNSPECIFIED", "ROUND_FOUR", "ROUND_EIGHT", "ROUND_TWELVE", "ROUND_FULL"] },
    "customColor": { "type": "string", "description": "Required. Hex color seed for the dynamic color system." },
    "colorVariant": { "type": "string", "enum": ["COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD"] },
    "overridePrimaryColor": { "type": "string", "description": "Optional. Override primary color (hex)." },
    "overrideSecondaryColor": { "type": "string", "description": "Optional. Override secondary color (hex)." },
    "overrideTertiaryColor": { "type": "string", "description": "Optional. Override tertiary color (hex)." },
    "overrideNeutralColor": { "type": "string", "description": "Optional. Override neutral color (hex)." },
    "designMd": { "type": "string", "description": "Optional. Markdown design instructions." }
  },
  "required": ["colorMode", "headlineFont", "bodyFont", "roundness", "customColor"]
}

Output

Returns the created design system Asset.

Example Prompts

PROMPT
Create a dark mode design system with Inter font and round corners Set up a design system with blue as the primary color Create a brand identity with Geist font and minimal roundness

update_design_system

Updates an existing design system. Identifies the asset by its name field.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `assets/{asset}`. Example: `assets/15996705518239280238`"
    },
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "designSystem": {
      "$ref": "#/$defs/DesignSystem",
      "description": "Required. The updated design system content."
    }
  },
  "required": ["name", "projectId", "designSystem"]
}

Uses the same DesignSystem and DesignTheme schemas as create_design_system.

Output

Returns the updated design system Asset.

Example Prompts

PROMPT
Update the design system to use dark mode Change the font to Geist in our design system Update the roundness to fully rounded

list_design_systems

Lists all design systems for a project (or global design systems if no projectId).

Annotations

readOnly

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Optional. Project ID. If empty, lists global design systems."
    }
  },
  "required": []
}

Output

Array of Asset objects containing design systems.

Example Prompts

PROMPT
List all design systems in project 12345 Show me the available design systems What design systems do I have?

apply_design_system

Applies a design system to one or more screens, modifying their appearance to match the system’s tokens (colors, fonts, shapes).

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenInstances": {
      "type": "array",
      "items": { "$ref": "#/$defs/SelectedScreenInstance" },
      "description": "Required. Screen instances to update (from `get_project`)."
    },
    "assetId": {
      "type": "string",
      "description": "Required. Design system asset ID (from `list_design_systems`), without `assets/` prefix."
    }
  },
  "required": ["projectId", "selectedScreenInstances", "assetId"]
}
SelectedScreenInstance
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Required. The screen instance ID (NOT the source screen ID). Available from `get_project`."
    },
    "sourceScreen": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
    }
  },
  "required": ["id", "sourceScreen"]
}

Output

Returns the updated Screen objects.

Example Prompts

PROMPT
Apply the blue design system to all screens in project 12345 Restyle these screens with the brand identity Use design system abc to update my screens

upload_design_md

Uploads a DESIGN.md file to a Stitch project. This is the first step in the two-step DESIGN.md workflow. After uploading, call create_design_system_from_design_md to create the design system.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID (e.g., '4044680601076201931'), without `projects/` prefix."
    },
    "designMdBase64": {
      "type": "string",
      "description": "Required. Base64-encoded DESIGN.md content. The decoded content must be valid UTF-8."
    }
  },
  "required": ["projectId", "designMdBase64"]
}

Output

Returns a screen instance object representing the uploaded DESIGN.md. The id and sourceScreen fields from this response are required as input to create_design_system_from_design_md.

Example Prompts

PROMPT
Upload my DESIGN.md to project 12345 Add a design system document to this project Upload this markdown design file to Stitch

create_design_system_from_design_md

Creates a design system from an uploaded DESIGN.md file and displays it in the UI. Must be called after upload_design_md.

Annotations

destructive

Input

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenInstance": {
      "$ref": "#/$defs/SelectedScreenInstance",
      "description": "Required. The screen instance created by `upload_design_md`."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"],
      "description": "Optional. The device type for the design system."
    }
  },
  "required": ["projectId", "selectedScreenInstance"]
}

Uses the same SelectedScreenInstance schema as apply_design_system.

Output

Returns a DesignSystem with an assetId that can be used with apply_design_system.

Example Prompts

PROMPT
Create a design system from the uploaded DESIGN.md Convert my design document into a design system Build a design system from my DESIGN.md file

Shared Types

Screen

A generated screen design within a Stitch project.

FieldTypeDescription
namestringResource name. Format: projects/{project}/screens/{screen}
idstring(Deprecated) The screen id.
titlestringTitle of the screen.
promptstringPrompt used to generate the screen.
screenshotFileScreenshot image of the screen.
htmlCodeFileHTML code of the screen.
figmaExportFileFigma export of the screen.
themeDesignThemeTheme used for generation.
deviceTypeDeviceTypeDevice type.
screenTypeScreenTypeScreen type.
screenMetadataScreenMetadataMetadata (agent, status, display mode).
widthstringWidth of the screen.
heightstringHeight of the screen.
groupIdstringGroup id for related screens (e.g., variants).
groupNamestringDisplay name of the group.
generatedBystringGenerator identifier.
isCreatedByClientbooleantrue if created via API upload, false if by agents.

File

FieldTypeDescription
namestringResource name. Format: projects/{project}/files/{file}
downloadUrlstringURL for download. FIFE base URL for images.
mimeTypestringE.g., "image/png", "text/html".
fileContentBase64string(Write-only) Base64-encoded content for uploads.
uploadBlobIdstringBlobId from upload service.
userFeedbackUserFeedback(Read-only) Latest feedback.

DesignSystem

Represents visual/functional design guidelines used to generate consistent, branded designs.

FieldTypeDescription
displayNamestringDisplay name of the design system.
themeDesignThemeTheme configuration.

Asset

Wrapper for design system resources (used by update_design_system).

FieldTypeDescription
namestringResource name. Format: assets/{asset}
designSystemDesignSystemThe design system content.
versionstring(Read-only) Version counter. 0 = unversioned.

DesignTheme

FieldTypeRequiredDescription
colorModeColorModetrueLight or dark mode.
headlineFontFonttrueHeadline typography.
bodyFontFonttrueBody typography.
labelFontFontfalseLabel typography.
roundnessRoundnesstrueCorner roundness.
customColorstringtrueSeed color for dynamic color system (hex, e.g., "#ff0000").
colorVariantColorVariantfalseDynamic color system variant.
overridePrimaryColorstringfalseOverride primary color (hex).
overrideSecondaryColorstringfalseOverride secondary color (hex).
overrideTertiaryColorstringfalseOverride tertiary color (hex).
overrideNeutralColorstringfalseOverride neutral color (hex).
designMdstringfalseMarkdown design instructions.

ScreenMetadata

FieldTypeDescription
agentTypeAgentTypeEnumTURBO_AGENT, PRO_AGENT, IMAGE_AGENT, GENIE_AGENT, IMAGE_PRO_AGENT, HATTER_AGENT, GEMINI_3_AGENT
statusScreenStatusEnumIN_PROGRESS, COMPLETE, FAILED
statusMessagestringHuman-readable status from agent.
displayModeDisplayModeEnumSCREENSHOT, HTML, CODE, MARKDOWN, STICKY_NOTE
isRemixedbooleanWhether screen was created from a remix.
componentRegionsComponentRegion[]Component region annotations.

SessionOutputComponent

Returned from generation tools in output_components.

FieldTypeDescription
textstringAgent text response.
suggestionstringSuggested follow-up for the user.
designDesignGenerated design reference.

UserFeedback

FieldTypeDescription
ratingstringPOSITIVE or NEGATIVE.
commentstringAdditional comment.
designFeedbackReasonstringDESIGN_DOESNT_MATCH_PROMPT, EDIT_DOESNT_MATCH_PROMPT, COMPONENT_ISSUE, INCORRECT_THEME, etc.

VariantOptions

FieldTypeDescription
variantCountintegerVariants to generate (1–5). Default: 3.
creativeRangeCreativeRangeCreative freedom level.
aspectsVariantAspect[]Aspects to focus on.

SelectedScreenInstance

Used by apply_design_system and create_design_system_from_design_md.

FieldTypeRequiredDescription
idstringtrueScreen instance ID (from get_project), not the source screen ID.
sourceScreenstringtrueResource name. Format: projects/{project}/screens/{screen}

Enums

DeviceType Enum

ValueDescription
DEVICE_TYPE_UNSPECIFIEDUnspecified.
MOBILEMobile device.
DESKTOPDesktop device.
TABLETTablet device.
AGNOSTICNot tied to a device.

ModelId Enum

ValueDescription
MODEL_ID_UNSPECIFIEDUnspecified.
GEMINI_3_PRO(Deprecated) Gemini 3 Pro. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead.
GEMINI_3_FLASHGemini 3 Flash.
GEMINI_3_1_PROGemini 3.1 Pro.

ScreenType Enum

ValueDescription
SCREEN_TYPE_UNSPECIFIEDDefaults to DESIGN.
DESIGNA design screen.
IMAGEA pure image.
PROTOTYPEA design prototype.
DOCUMENTA document (e.g., PRD).
PROTOTYPE_V2A design prototype v2.

ColorMode Enum

ValueDescription
COLOR_MODE_UNSPECIFIEDUnspecified.
LIGHTLight mode.
DARKDark mode.

ColorVariant Enum

ValueDescription
COLOR_VARIANT_UNSPECIFIEDUnspecified.
MONOCHROMEMonochrome variant.
NEUTRALNeutral variant.
TONAL_SPOTTonal spot variant.
VIBRANTVibrant variant.
EXPRESSIVEExpressive variant.
FIDELITYFidelity variant.
CONTENTContent variant.
RAINBOWRainbow variant.
FRUIT_SALADFruit salad variant.

Font Enum

29 supported font families:

INTER · DM_SANS · GEIST · SORA · MANROPE · LEXEND · EPILOGUE · BE_VIETNAM_PRO · PLUS_JAKARTA_SANS · PUBLIC_SANS · SPACE_GROTESK · SPLINE_SANS · WORK_SANS · MONTSERRAT · METROPOLIS · SOURCE_SANS_THREE · NUNITO_SANS · ARIMO · HANKEN_GROTESK · RUBIK · IBM_PLEX_SANS · NEWSREADER · NOTO_SERIF · DOMINE · LIBRE_CASLON_TEXT · EB_GARAMOND · LITERATA · SOURCE_SERIF_FOUR

Roundness Enum

ValueDescription
ROUNDNESS_UNSPECIFIEDUnspecified.
ROUND_TWO(Deprecated) Round 2.
ROUND_FOURRound 4.
ROUND_EIGHTRound 8.
ROUND_TWELVERound 12.
ROUND_FULLFully rounded.

CreativeRange Enum

ValueDescription
CREATIVE_RANGE_UNSPECIFIEDUnspecified.
REFINESubtle refinements, close to original.
EXPLOREBalanced exploration. (Default)
REIMAGINERadical explorations.

VariantAspect Enum

ValueDescription
VARIANT_ASPECT_UNSPECIFIEDUnspecified.
LAYOUTElement arrangement.
COLOR_SCHEMEColor palette.
IMAGESImage usage.
TEXT_FONTFont choices.
TEXT_CONTENTText content.

MCP Annotations

MCP Annotations are metadata hints that an MCP server attaches to each tool definition to tell the client (the AI agent or host application) about the tool’s behavioral characteristics. They’re part of the MCP spec and help clients make smarter decisions about tool usage without needing to understand the tool’s implementation.

Each tool includes behavior annotations:

AnnotationMeaning
readOnlyHinttrue = read-only, no mutations.
destructiveHinttrue = may create/modify/delete resources.
idempotentHinttrue = repeated calls produce same result.
openWorldHinttrue = interacts with external systems.

How they work with tools in practice

Each tool in the Stitch MCP server declares these as part of its tool registration. For example:

  • list_projects has readOnlyHint: true — it just fetches data, so an agent can call it without worrying about side effects.
  • create_project has readOnlyHint: false, destructiveHint: true, idempotentHint: false — it mutates state, so the client should confirm with the user first.
  • generate_screen_from_text has destructiveHint: true and idempotentHint: false — each call creates a new screen, so retrying on a timeout could produce duplicates.

Why they matter

These are hints, not enforced rules. They allow MCP clients to:

  • Auto-approve read-only tools without prompting the user
  • Show confirmation dialogs for destructive operations
  • Safely retry idempotent tools on network failures
  • Audit external interactions when openWorldHint is true

In the Stitch server’s case, all tools have openWorldHint: false because they interact only with the Stitch backend — not arbitrary third-party services.

Original: https://stitch.withgoogle.com/docs/mcp/reference/

Translated from the official Google Stitch documentation. Original content © Google LLC. This is an independent, unofficial translation.