Stitch MCP tool schemas are misleading for designSystem, variantOptions, and selectedScreenInstance fields

[aakkino]

Summary

Some Stitch MCP tools fail with Request contains an invalid argument when clients pass arguments inferred from simplified or misleading tool schemas. The same tools work when object-shaped arguments are used.

This appears to be a tools/list input schema / documentation issue for the remote Stitch MCP endpoint:

https://stitch.googleapis.com/mcp

Client environments

This was observed while using the Stitch MCP server from:

• Codex
• Claude Code

Both clients can discover and call the tools, but the object-shaped arguments below are required for successful calls. Are there plans to make the Stitch MCP schemas and examples compatible with these generic MCP clients as well, or is the current extension primarily targeting Gemini CLI / Antigravity behavior?

Affected tools

• create_design_system
• update_design_system
• apply_design_system
• create_design_system_from_design_md
• generate_variants

Observed behavior

The tools can be discovered by MCP clients, but calls fail if the following fields are passed as strings or plain IDs:

• designSystem as a Markdown/string value
• variantOptions as a string value
• selectedScreenInstance as a screen instance ID string
• selectedScreenInstances as an array of screen instance ID strings

The server responds with:

Request contains an invalid argument.

Working input shapes

After testing against the same remote MCP endpoint, these tools work when the object shapes below are used.

designSystem

{
  "displayName": "Codex Schema Retest DS",
  "theme": {
    "colorMode": "LIGHT",
    "headlineFont": "INTER",
    "bodyFont": "INTER",
    "roundness": "ROUND_EIGHT",
    "customColor": "#2563EB",
    "colorVariant": "FIDELITY",
    "designMd": "# Design System\n\nClean dashboard style.",
    "overridePrimaryColor": "#2563EB",
    "overrideSecondaryColor": "#14B8A6",
    "overrideTertiaryColor": "#F1F5F9",
    "overrideNeutralColor": "#0F172A",
    "labelFont": "INTER"
  }
}

This works for:

• create_design_system
• update_design_system

selectedScreenInstance

{
  "id": "<screenInstanceId>",
  "sourceScreen": "projects/<projectId>/screens/<screenInstanceId>"
}

This works for:

• create_design_system_from_design_md

selectedScreenInstances

[
  {
    "id": "<screenInstanceId>",
    "sourceScreen": "projects/<projectId>/screens/<screenInstanceId>"
  }
]

This works for:

• apply_design_system

variantOptions

{
  "variantCount": 2,
  "creativeRange": "EXPLORE",
  "aspects": ["LAYOUT", "COLOR_SCHEME", "TEXT_FONT"]
}

This works for:

• generate_variants

Expected behavior

The Stitch MCP tools/list response should expose precise nested object schemas for these fields so generic MCP clients can call the tools correctly:

• designSystem
• designSystem.theme
• selectedScreenInstance
• selectedScreenInstances[]
• variantOptions

The README could also include examples for design system creation, applying a design system, creating a design system from DESIGN.md, and generating variants.

Related issue

This may be related to tool discovery/client compatibility concerns raised in:

• Hidden or broken remote mcp tools? #11

That issue focuses on hidden or broken remote MCP tools across clients. This issue is specifically about object input schemas for the tools that are visible but easy to call incorrectly.