Referência de ferramentas do MCP

Em caso de sucesso, todas as ferramentas, exceto get-screen-image, retornam o resultado duas vezes: como structuredContent (validado contra o esquema de saída publicado da ferramenta) e como o mesmo objeto serializado em um bloco de texto, { type: "text", text: "<json-string>" }, para clientes que não leem conteúdo estruturado. get-screen-image retorna somente um bloco de imagem do MCP: { type: "image", data: "<base64>", mimeType: "image/png" }. Em caso de falha, isError: true é definido e o bloco de texto contém uma mensagem de erro curta. Erros que você pode resolver, como um nome que não corresponde na exclusão, um link inválido do Figma, diretrizes de design inválidas, um problema com anexo ou um tempo limite de geração, explicam o que corrigir. Outras falhas retornam uma mensagem genérica, como Failed to list files.

Preços: as três ferramentas de design com IA (ai-design-screens, ai-generate-screen-variant e ai-edit-screen-variant) usam a mesma cota de mensagens do aplicativo Flowstep. Todas as outras ferramentas são gratuitas. Veja Limites de uso.

Cada ferramenta também publica anotações do MCP para que o seu cliente saiba o que ela faz. delete-file, delete-screen, delete-design-guidelines, replace-screen-jsx, ai-design-screens e ai-edit-screen-variant são marcadas como destrutivas, porque removem ou sobrescrevem conteúdo existente.

Ferramentas de arquivo

`list-files`

Lista os metadados dos seus arquivos do Flowstep. Chame-a primeiro para verificar se já existe um arquivo relevante. Ela não retorna conteúdo de telas: use get-screen-image ou get-screen-jsx para isso. Entrada

Parâmetro	Tipo	Padrão	Descrição
`orderByCreation`	`boolean`	`true`	Ordena do mais recente para o mais antigo por `created_at` (`true`) ou por `updated_at` (`false`). Use `false` para encontrar arquivos editados recentemente
`limit`	`integer` (1–100)	`20`	Número máximo de arquivos retornados. Uma página cheia pode significar que existem mais arquivos
`offset`	`integer` (≥0)	`0`	Arquivos a pular. A próxima página é `offset + limit`

Saída: { files }.

{
  "files": [
    {
      "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
      "name": "Dashboard redesign",
      "created_at": "2026-04-30T15:02:13.120152+00:00",
      "updated_at": "2026-04-30T15:02:13.120152+00:00",
      "organisation_id": "0b7f3c9e-2d4a-4f1b-9a5e-6c8d7e1f2a3b",
      "shared_with_me": false,
      "owner": true,
      "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
    }
  ]
}

owner: true se você criou o arquivo.
shared_with_me: true se o arquivo foi compartilhado diretamente com você, não apenas pela sua organização.
url: abre o arquivo no editor do Flowstep.

`get-file`

Obtém os metadados de um único arquivo. O conteúdo do arquivo é omitido de propósito: use get-screen-image ou get-screen-jsx para inspecionar telas e get-design-guidelines para obter as diretrizes anexadas. Se você tiver um convite pendente para o arquivo, chamar get-file o aceita. Entrada

Parâmetro	Tipo	Descrição
`id`	`uuid`	ID do arquivo

Saída: { file, user_access_level }.

{
  "file": {
    "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
    "name": "Dashboard redesign",
    "created_at": "2026-04-30T15:02:13.120152+00:00",
    "updated_at": "2026-04-30T15:02:13.120152+00:00",
    "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d",
    "access_level": "private",
    "visibility": "private",
    "owner": true,
    "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
  },
  "user_access_level": "write"
}

access_level: private, read ou write.
visibility: private, member ou public.
user_access_level: o seu acesso ao arquivo: read ou write.

`create-file`

Cria um arquivo em branco do Flowstep, sem telas. Para criar um arquivo e gerar telas em uma única etapa, chame ai-design-screens sem fileId. Use create-file em fluxos que começam pelo código, seguido de add-screen-jsx. Entrada

Parâmetro	Tipo	Descrição
`name`	`string` (mín. 1)	Nome de exibição do novo arquivo

Saída: { file, user_access_level }, no mesmo formato de get-file. owner é sempre true e user_access_level é sempre write. Use o file.id retornado como fileId nas chamadas de ferramenta seguintes.

`update-file`

Renomeia um arquivo. Entrada

Parâmetro	Tipo	Descrição
`id`	`uuid`	ID do arquivo
`name`	`string` (mín. 1)	Novo nome de exibição

Saída: { file, user_access_level }, no mesmo formato de get-file.

`delete-file`

Exclui um arquivo permanentemente. O name que você passa é comparado com o nome de exibição atual do arquivo antes da exclusão. Se não corresponder, a exclusão é cancelada. Isso evita apagar o arquivo errado por engano. Os agentes são instruídos a confirmar com você antes. Entrada

Parâmetro	Tipo	Descrição
`id`	`uuid`	ID do arquivo
`name`	`string`	Nome de exibição atual do arquivo: precisa corresponder, ou a exclusão é cancelada

Saída: { "deleted": true }

Esta ação é irreversível. Todas as telas do arquivo são excluídas.

Ferramentas de tela

`list-screens`

Lista as telas de um arquivo, na ordem do canvas. Chame-a depois de list-files para ver o que já existe em um arquivo. Use os valores screenId retornados com as outras ferramentas de tela e com as ferramentas de design com IA. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo

Saída: { screens }.

{
  "screens": [
    {
      "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
      "name": "Mobile login screen",
      "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button",
      "fidelity": "ui"
    }
  ]
}

prompt: o último prompt de geração da tela, ou uma string vazia se ela nunca foi gerada (por exemplo, uma tela adicionada com add-screen-jsx).
fidelity: lofi, hifi ou ui.

`get-screen-image`

Renderiza uma tela em PNG e a retorna como imagem na conversa. Requer um cliente que ofereça suporte a blocos de conteúdo de imagem. Chame-a uma vez para cada screenId retornado por uma ferramenta de design com IA, por add-screen-jsx, replace-screen-jsx ou import-figma. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo
`screenId`	`uuid`	Um `screenId` de `list-screens` ou do array `screenIds` retornado por uma ferramenta de design

Saída: bloco de conteúdo de imagem do MCP (image/png). data é base64 padrão dos bytes do PNG, não uma data URI. Essa ferramenta não tem structuredContent.

`get-screen-jsx`

Obtém uma tela como JSX, junto com os seus metadados, para que você possa construir a partir dela no seu código ou editá-la e gravá-la de volta com replace-screen-jsx. Use get-screen-image para uma prévia visual. Entrada

Parâmetro	Tipo	Padrão	Descrição
`fileId`	`uuid`	—	ID do arquivo
`screenId`	`uuid`	—	Um `screenId` de `list-screens` ou do array `screenIds` retornado por uma ferramenta de design
`includeIds`	`boolean`	`false`	Inclui um atributo `data-id` nos elementos de `jsx`. Use-o quando precisar dos ids dos elementos para passar como `elementIds` para `ai-design-screens`, seja para editar no lugar, seja como referência visual

Saída: { fileId, screenId, name, prompt, fidelity, screenType, colorTheme, jsx, fragments }.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0",
  "name": "World clock",
  "prompt": "A world clock screen with a city search and alert button",
  "fidelity": "ui",
  "screenType": "iphone-x-vertical",
  "colorTheme": "blue",
  "jsx": "<div className=\"bg-white text-zinc-950 w-full h-fit\">\n  <div className=\"flex p-6 flex-col gap-6\">\n    …\n  </div>\n</div>",
  "fragments": []
}

jsx: somente a marcação. Os atributos data-id são incluídos apenas quando includeIds é true.
prompt: o último prompt de geração, ou uma string vazia se a tela nunca foi gerada.
fragments: elementos compartilhados armazenados na tela, como uma barra de navegação, um cabeçalho ou um logotipo, no formato de objetos { purpose, markup }. Vazio quando não há nenhum. Passe-os de volta para replace-screen-jsx para mantê-los ou atualizá-los.

Veja Valores dos campos da tela para os valores de fidelity, screenType e colorTheme.

`add-screen-jsx`

Adiciona uma nova tela a um arquivo a partir de JSX que você escreveu. É o caminho para quem começa pelo código e é gratuito: use ai-design-screens quando quiser que a IA do Flowstep desenhe a tela. add-screen-jsx sempre cria uma nova tela: para sobrescrever uma existente, use replace-screen-jsx. Para mostrar uma imagem que você enviou, veja Imagens em JSX. Quando a nova tela se basear em uma existente, comece por get-screen-jsx (sem includeIds) para name, fidelity, screenType, colorTheme e jsx, e depois altere o que deve ser diferente. Entrada

Parâmetro	Tipo	Padrão	Descrição
`fileId`	`uuid`	—	ID do arquivo
`name`	`string` (1–100 caracteres)	—	Nome de exibição opcional. Se omitido, a tela recebe o nome automático `Screen N`
`fidelity`	`string`	`"ui"`	Fidelidade da tela
`screenType`	`string`	—	Obrigatório: o dispositivo ou a janela de visualização para os quais a tela é projetada
`colorTheme`	`string`	`"default"`	Tema de cores
`jsx`	`string`	—	Somente marcação JSX. Atributos `data-id` são ignorados: a nova tela recebe novos ids de elementos

Saída: { fileId, screenId }. Chame get-screen-image com screenId para ver o resultado.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf"
}

`replace-screen-jsx`

Sobrescreve uma tela existente com JSX que você escreveu. A tela mantém o seu screenId e a sua posição no canvas; os elementos aninhados recebem novos ids. É o caminho para quem começa pelo código e é gratuito: use ai-design-screens ou ai-edit-screen-variant para alterações com IA, e add-screen-jsx para criar uma nova tela. Comece por get-screen-jsx (sem includeIds) e depois altere o que deve ser diferente. Para mostrar uma imagem que você enviou, veja Imagens em JSX. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo
`screenId`	`uuid`	A tela a ser sobrescrita
`jsx`	`string`	Somente marcação JSX. Atributos `data-id` são ignorados
`name`	`string` (1–100 caracteres)	Opcional. Omita para manter o nome atual
`fidelity`	`string`	Opcional. Omita para manter a fidelidade atual
`screenType`	`string`	Opcional. Omita para manter o tipo de tela atual
`colorTheme`	`string`	Opcional. Omita para manter o tema de cores atual
`fragments`	`{ purpose, markup }[]`	Opcional. Elementos compartilhados de `get-screen-jsx`. Omita para manter os fragmentos atuais, ou passe `[]` para limpá-los

Saída: { fileId, screenId }. Chame get-screen-image com screenId para ver o resultado.

Isso substitui o conteúdo da tela no lugar.

`rename-screen`

Renomeia o rótulo da tela no canvas: o nome exibido em list-screens e no editor. Isso altera somente o rótulo, não o layout, o tamanho ou o conteúdo da tela. Para isso, use ai-design-screens. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo
`screenId`	`uuid`	O `screenId` retornado por `list-screens`
`name`	`string` (1–100 caracteres)	Novo nome da tela. Espaços no início e no fim são removidos

Saída: { screenId, name }.

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Checkout — empty cart" }

`delete-screen`

Exclui uma tela de um arquivo permanentemente. O name que você passa é comparado com o nome de exibição atual da tela. Se não corresponder, a exclusão é cancelada. Os agentes são instruídos a confirmar com você antes. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo
`screenId`	`uuid`	A tela a ser excluída
`name`	`string`	Nome de exibição atual da tela: precisa corresponder, ou a exclusão é cancelada

Saída: { "deleted": true }

Imagens em JSX

add-screen-jsx e replace-screen-jsx aceitam imagens em um src de img ou como plano de fundo em className, com bg-[url(...)]. Escreva o texto de alt e dimensione cada imagem de acordo com a sua finalidade. Para colocar uma imagem sua:

Envie-a com upload-attachment no Modo A (mimeType + fileName) e execute o uploadCommand retornado.
Se o type da resposta for "image", cole o assetUrl exatamente como retornado no img src ou em bg-[url(assetUrl)].

Mantenha todas as outras URLs de imagem exatamente como get-screen-jsx as retornou. Não coloque path, signedUrl ou uploadCommand em src.

<img src="ASSET_URL" alt="Team photo" className="w-full h-48 object-cover rounded-lg" />

Valores dos campos da tela

get-screen-jsx retorna, e add-screen-jsx e replace-screen-jsx aceitam, estes valores:

Campo	Valores
`fidelity`	`lofi`, `hifi`, `ui`
`screenType`	`web`, `desktop`, `desktop-large`, `desktop-medium`, `desktop-small`, `tablet`, `ipad-tablet-horizontal`, `ipad-tablet-vertical`, `android-tablet-horizontal`, `android-tablet-vertical`, `mobile_ios`, `mobile_android`, `iphone-vertical`, `iphone-horizontal`, `iphone-x-vertical`, `iphone-x-horizontal`, `android-vertical`, `android-horizontal`, `android-small-vertical`, `android-small-horizontal`
`colorTheme`	`default`, `defaultDark`, `blue`, `blueDark`, `ice`, `iceDark`, `grayscale`, `grayscaleDark`, `green`, `greenDark`, `orange`, `orangeDark`, `red`, `redDark`, `rose`, `roseDark`, `violet`, `violetDark`, `yellow`, `yellowDark`

Ferramentas de diretrizes de design

As diretrizes de design são texto DESIGN.md armazenado em um arquivo. Quando definidas, são injetadas em todas as gerações de IA desse arquivo. Veja Diretrizes de design.

`get-design-guidelines`

Obtém as diretrizes de design anexadas a um arquivo. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo

Saída: { guidelines }.

{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter"
}

guidelines é null se nenhuma diretriz tiver sido definida.

`update-design-guidelines`

Define ou substitui as diretrizes de design de um arquivo. Passe as diretrizes como uma string simples no formato DESIGN.md do Google, não como objeto ou JSON. Se você estiver lendo de um arquivo, passe o texto desse arquivo. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo
`designGuidelines`	`string` (mín. 1)	Texto bruto das diretrizes. Precisa ser uma string simples, não codificada em JSON

Regras de validação

O frontmatter precisa ser aberto e fechado corretamente
As linhas do frontmatter precisam ser YAML válido no estilo de blocos
O corpo em Markdown não pode conter cabeçalhos de seção ## duplicados

Se a validação falhar, a chamada retorna um erro que começa com Invalid design guidelines:. Saída: { updated, warnings? }.

{ "updated": true, "warnings": ["…"] }

warnings lista problemas de validação leves (chaves desconhecidas, cores que não são hexadecimais) que foram aceitos, mas que a IA pode ignorar. Ele é omitido quando não há nenhum. Mostre esses avisos ao usuário.

`delete-design-guidelines`

Limpa as diretrizes de design de um arquivo. Excluir diretrizes que não existem não tem efeito. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo

Saída: { "deleted": true }

Ferramentas de chat

`get-chat-history`

Obtém a conversa de design associada a um arquivo: o chat do Flowstep do arquivo, não a conversa do seu cliente MCP. Use-a para retomar um trabalho anterior no arquivo. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do arquivo

Saída: { messages }. messages fica vazio quando você não tem uma conversa de design no arquivo. Cada mensagem tem um type ("request" ou "response"), um author ("human" ou "ai") e um content_type. Mensagens de resposta usam "text", "summary" ou "followup".

{
  "messages": [
    {
      "id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "type": "request",
      "status": "success",
      "content": "Generate a simple mobile login screen with email and password fields",
      "author": "human",
      "content_type": "text",
      "sequence": 1,
      "targets": [],
      "attachments": []
    },
    {
      "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf",
      "type": "response",
      "status": "success",
      "content": "Generated a mobile login screen with email and password input fields, a sign in button, and a sign up link.",
      "author": "ai",
      "content_type": "summary",
      "sequence": 7,
      "request_message_id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "targets": [{ "target_id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" }]
    }
  ]
}

Ferramentas de anexos

`upload-attachment`

Envia um arquivo de referência para usar como anexo em ai-design-screens, ou uma imagem para colocar no seu próprio JSX com add-screen-jsx ou replace-screen-jsx. ai-generate-screen-variant e ai-edit-screen-variant não aceitam anexos. Os bytes do arquivo nunca passam pelo modelo, e o servidor nunca busca URLs em seu nome. Para referenciar uma página da web, inclua a URL no message de ai-design-screens. Há dois modos. Use exatamente um deles e não os combine. Modo A: arquivos e imagens (mimeType + fileName) Um fluxo obrigatório de três etapas para qualquer imagem, PDF ou arquivo de texto grande:

Chame upload-attachment somente com mimeType e fileName (por exemplo, image/png e dog.png). A resposta é um envio preparado, não um arquivo armazenado:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

Substitua LOCAL_FILE_PATH em uploadCommand pelo caminho absoluto do seu arquivo e execute esse comando exato no seu shell. Ele precisa terminar com código 0. O token em signedUrl autoriza somente este envio único. Pular esta etapa deixa o armazenamento vazio, e a ferramenta de design falha na verificação prévia.
Passe somente { id, path, type } para o array attachments de ai-design-screens, não signedUrl, uploadCommand nem nextStep. Para colocar uma imagem no seu próprio JSX, coloque o assetUrl no img src ou em bg-[url(...)] do JSX que você passa para add-screen-jsx ou replace-screen-jsx. Veja Imagens em JSX.

Para anexar um arquivo remoto, baixe-o antes para um caminho local (por exemplo, com curl) e depois siga as mesmas três etapas. Nunca passe uma URL para upload-attachment.

Parâmetro	Tipo	Descrição
`mimeType`	enum	Tipo MIME do arquivo. Um de `image/jpeg`, `image/png`, `image/webp`, `application/pdf`, `text/markdown`, `text/plain`, `text/javascript`. Use `text/javascript` para arquivos `.jsx`, `.tsx`, `.js` e `.ts`
`fileName`	`string` (mín. 1)	Nome original do arquivo com extensão, por exemplo `cat.png` ou `design.md`

Modo B: texto curto (text + mimeType) Envia texto que já está no contexto, sem comando de shell. A resposta já pode ser usada diretamente:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "document",
  "mimeType": "text/plain"
}

Parâmetro	Tipo	Descrição
`text`	`string` (máx. 64.000 caracteres)	Conteúdo de texto bruto. Somente arquivos de texto; não use para imagens ou PDFs. Mais de 64.000 caracteres? Use o Modo A
`mimeType`	enum	Um de `text/markdown`, `text/plain`, `text/javascript`

Passe o { id, path, type } resultante para o array attachments de ai-design-screens. O tamanho máximo do arquivo é de 3 MB nos dois modos, e PDFs são limitados a 100 páginas. Saída: { id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }.

type: "image" para arquivos de imagem e "document" para PDFs e arquivos de texto.
assetUrl: a URL do arquivo enviado, retornada nos dois modos. Use-a no JSX de add-screen-jsx ou replace-screen-jsx somente quando type for "image", e somente depois de executar o uploadCommand do Modo A.
signedUrl, uploadCommand, nextStep: definidos somente no Modo A. Não os passe para as ferramentas de design.

Ferramentas do Figma

`import-figma`

Importa um quadro do Figma para um arquivo do Flowstep como elementos editáveis no canvas dele. Cada importação adiciona uma nova tela: importar o mesmo quadro duas vezes gera duas telas, então exclua a antiga com delete-screen se você quis substituí-la. A organização do arquivo precisa ter o Figma conectado nas configurações do Flowstep. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	O arquivo do Flowstep em que o quadro será importado. Não é a chave do arquivo do Figma em `figmaUrl`
`figmaUrl`	`string`	Link para um quadro específico do Figma, com um `node-id`. No Figma, clique com o botão direito no quadro e escolha Copy/Paste as → Copy link to selection. Um link de página importa todos os quadros de nível superior dessa página (limitado a 20 quadros pelo MCP)

Saída: { fileId, screenId, frameCount? }. screenId é a tela importada: passe-o para get-screen-image para ver o resultado. Quando um link de página importa vários quadros, screenId é null e frameCount é retornado no lugar; chame list-screens e depois get-screen-image para cada nova tela.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe"
}

Ferramentas de plano e cobrança

`get-plan-details`

Obtém o plano do Flowstep da sua organização, o status da assinatura, o uso e a cota restante. Não recebe entrada: a organização é identificada pelo usuário conectado. Use-a para verificar sua cota antes de chamar as ferramentas de design com IA. Saída: { plan, subscription, limits, usage, remaining }.

Campo	Descrição
`plan`	`{ name, code, type }`. `type` é `"free"` ou `"paid"`
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	Limites por recurso, indexados pelo recurso (por exemplo `messages`). Cada um tem objetos opcionais `daily` e `monthly` com valores `max` e `warn`, além de uma flag `unlimited`
`usage`	Uso por recurso até agora, no formato `{ daily, monthly }`
`remaining`	Cota restante por recurso, no formato `{ daily, monthly }`. Omitida para recursos ilimitados

Os limites variam conforme o plano. Veja Preços e Limites de uso.

Ferramentas de design com IA

Essas três ferramentas desenham a partir de uma descrição ou de uma predefinição. Elas nunca recebem nem reutilizam JSX. Cada chamada usa a mesma cota de mensagens do aplicativo Flowstep e bloqueia até que a geração termine ou atinja o tempo limite (180 segundos).

Ferramenta	Use-a para
`ai-design-screens`	Gerar telas novas, alterar telas existentes no lugar, ou as duas coisas, a partir de uma descrição livre
`ai-generate-screen-variant`	Adicionar uma variante de próxima etapa, de estado de erro ou vazio, ou de plataforma de uma tela existente
`ai-edit-screen-variant`	Aplicar uma predefinição de edição ou redesenho a uma tela existente inteira

As três retornam { status, fileId, screenIds, designGuidelinesUpdated }. Chame get-screen-image uma vez para cada screenId para ver o resultado.

designGuidelinesUpdated: um resumo curto da alteração quando as diretrizes DESIGN.md do arquivo foram atualizadas automaticamente durante este turno; caso contrário, null.

`ai-design-screens`

Gera uma ou mais telas novas, altera telas existentes no lugar, ou faz as duas coisas em uma única chamada, a partir de uma descrição em texto: novos fluxos, temas, textos, layout ou alterações coordenadas em várias telas. É o mesmo agente de design do chat no editor do Flowstep: ele decide, com base na sua message e em elementIds, o que criar e o que alterar. Omita fileId para começar um novo arquivo; passe fileId para trabalhar em um arquivo existente. Se o pedido puder se aplicar a um arquivo que você já tem, o agente deve verificar list-files e list-screens primeiro. Para uma variante de próxima etapa, de estado de erro ou vazio, ou de plataforma de uma tela, use ai-generate-screen-variant. Para uma edição predefinida ou um redesenho de uma tela, use ai-edit-screen-variant. Se você já tiver JSX, use add-screen-jsx ou replace-screen-jsx. Entrada

Parâmetro	Tipo	Padrão	Descrição
`fileId`	`uuid`	—	Arquivo de destino. Omita para criar um novo arquivo. Obrigatório quando `elementIds` é definido
`message`	`string`	—	Descrição das telas a gerar e/ou das alterações a fazer. Ao passar `elementIds`, diga se devem ser editados ou usados como referência. Inclua aqui as URLs de páginas da web que você quer que o Flowstep use como referência
`elementIds`	`uuid[]`	`[]`	`screenId`s opcionais de `list-screens` e/ou `data-id`s de elementos de `get-screen-jsx` (com `includeIds`), como uma seleção no editor. Podem ser editados no lugar ou usados como referência visual para telas novas. Um `screenId` tem como alvo a tela inteira
`attachments`	`{ id, path, type }[]` (máx. 5)	`[]`	Arquivos de `upload-attachment`: imagens, PDFs ou arquivos de código e texto. Não coloque o conteúdo dos arquivos na mensagem

Exemplo: edite uma tela e adicione outra em uma única chamada:

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "message": "Switch this sign-in screen to dark mode, then add a matching forgot-password screen.",
  "elementIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

Saída: { status, fileId, screenIds, designGuidelinesUpdated, reply? }.

{
  "status": "generated",
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": [
    "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0"
  ],
  "designGuidelinesUpdated": null
}

status: "generated" quando telas foram criadas ou alteradas. "chat" quando o Flowstep respondeu sem construir nada; nesse caso, reply contém a resposta e screenIds fica vazio. Se o seu pedido for ambíguo, o agente deve pedir que você esclareça e chamar a ferramenta novamente.
screenIds: todas as telas criadas ou alteradas durante a chamada, incluindo as telas editadas no lugar. Se a chamada atingir o tempo limite depois que algumas telas já foram criadas, ela retorna essas telas em vez de um erro.

As telas que você pede para editar são sobrescritas no lugar.

`ai-generate-screen-variant`

Adiciona uma nova tela derivada de exatamente uma tela existente: a próxima etapa do fluxo, um estado de erro ou vazio, ou uma versão para outra plataforma. A tela original não é alterada. Para adicionar uma tela que não é variante de uma existente (por exemplo, uma tela de configurações), use ai-design-screens com um fileId. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	Arquivo de destino
`screenId`	`uuid`	A tela existente da qual derivar
`operationVariant`	enum	Obrigatório: como a nova tela se relaciona com a existente

`operationVariant`	Adiciona
`next_screen`	A próxima tela no fluxo do usuário
`error_state`	Um estado de erro da tela
`empty_state`	Um estado vazio da tela
`web_version`	Uma versão web
`mobile_version`	Uma versão mobile
`tablet_version`	Uma versão tablet
`mobile_ios_version`	Uma versão para iOS
`mobile_android_version`	Uma versão para Android

Saída: { status, fileId, screenIds, designGuidelinesUpdated }. status é sempre "generated".

`ai-edit-screen-variant`

Altera exatamente uma tela existente no lugar, usando uma predefinição: aplica um tema ou um acabamento visual, testa outro layout ou estilo visual, ou redesenha a tela do zero. Para instruções livres ou para uma edição precisa de elementos individuais, use ai-design-screens. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	Arquivo de destino
`screenId`	`uuid`	A tela existente a ser alterada
`operationVariant`	enum	Obrigatório: a predefinição de edição ou redesenho a aplicar

`operationVariant`	Tipo	Efeito
`dark_theme`	Edição	Muda a tela para um tema escuro
`light_theme`	Edição	Muda a tela para um tema claro
`make_pretty`	Edição	Refina o design visual da tela
`different_layout`	Redesenho	Testa um layout diferente
`different_style`	Redesenho	Testa um estilo visual diferente
`from_scratch`	Redesenho	Redesenha a tela do zero

Saída: { status, fileId, screenIds, designGuidelinesUpdated }. status é sempre "generated".

Isso sobrescreve o conteúdo da tela no lugar.

Ferramentas renomeadas

Os nomes de algumas ferramentas mudaram em setembro e outubro de 2026. Se você tiver prompts, scripts ou instruções de agente que usem os nomes antigos, atualize-os:

Nome antigo	Nome novo
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`ai-generate-screens`	`ai-design-screens`
`ai-edit-screens`	`ai-design-screens`
`create-new-design`	`ai-design-screens`
`edit-design` (instruções livres)	`ai-design-screens`
`edit-design` (com uma predefinição `operationVariant`)	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

Os parâmetros também mudaram: as ferramentas de design com IA recebem elementIds (ou um único screenId nas ferramentas de variante) em vez de targets; add-screen-jsx recebe jsx e campos de metadados explícitos em vez de jsxContent com um comentário de metadados; create-file recebe name em vez de title; e as ferramentas de diretrizes de design recebem fileId em vez de resourceId e linkedTo.

​Ferramentas de arquivo

​list-files

​get-file

​create-file

​update-file

​delete-file

​Ferramentas de tela

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​Imagens em JSX

​Valores dos campos da tela

​Ferramentas de diretrizes de design

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​Ferramentas de chat

​get-chat-history

​Ferramentas de anexos

​upload-attachment

​Ferramentas do Figma

​import-figma

​Ferramentas de plano e cobrança

​get-plan-details

​Ferramentas de design com IA

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​Ferramentas renomeadas

Ferramentas de arquivo

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Ferramentas de tela

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

Imagens em JSX

Valores dos campos da tela

Ferramentas de diretrizes de design

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Ferramentas de chat

`get-chat-history`

Ferramentas de anexos

`upload-attachment`

Ferramentas do Figma

`import-figma`

Ferramentas de plano e cobrança

`get-plan-details`

Ferramentas de design com IA

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

Ferramentas renomeadas