Referência de ferramentas MCP

Em caso de sucesso, todas as ferramentas exceto get-screen-image devolvem o resultado duas vezes: como structuredContent (validado contra o esquema de saída publicado da ferramenta) e como o mesmo objeto serializado num bloco de texto, { type: "text", text: "<json-string>" }, para clientes que não leem conteúdo estruturado. get-screen-image devolve apenas um bloco de imagem 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. Os erros que pode resolver (uma incompatibilidade de nome ao eliminar, uma ligação inválida do Figma, diretrizes de design inválidas, um problema com um anexo ou um tempo limite de geração) explicam o que corrigir. Outras falhas devolvem 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 quota de mensagens da aplicação Flowstep. Todas as outras ferramentas são gratuitas. Consulte Limites de utilização.

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

Ferramentas de ficheiros

`list-files`

Lista os metadados dos seus ficheiros do Flowstep. Chame esta ferramenta primeiro para verificar se já existe um ficheiro relevante. Não devolve conteúdo de ecrãs: para isso, use get-screen-image ou get-screen-jsx. Entrada

Parâmetro	Tipo	Predefiniçã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 ficheiros editados recentemente
`limit`	`integer` (1–100)	`20`	Número máximo de ficheiros devolvidos. Uma página cheia pode significar que existem mais ficheiros
`offset`	`integer` (≥0)	`0`	Número de ficheiros a saltar. A página seguinte é `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 criou o ficheiro.
shared_with_me: true se o ficheiro foi partilhado consigo diretamente, e não apenas através da sua organização.
url: abre o ficheiro no editor do Flowstep.

`get-file`

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

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

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 ficheiro: read ou write.

`create-file`

Cria um ficheiro do Flowstep em branco, sem ecrãs. Para criar um ficheiro e gerar ecrãs num só passo, chame ai-design-screens sem fileId. Use create-file em fluxos de trabalho centrados no código, seguido de add-screen-jsx. Entrada

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

Saída: { file, user_access_level }, com a mesma estrutura de get-file. owner é sempre true e user_access_level é sempre write. Use o file.id devolvido como fileId nas chamadas seguintes.

`update-file`

Muda o nome de um ficheiro. Entrada

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

Saída: { file, user_access_level }, com a mesma estrutura de get-file.

`delete-file`

Elimina permanentemente um ficheiro. O name que passa é comparado com o nome de apresentação atual do ficheiro antes da eliminação. Se não corresponder, a eliminação é cancelada. Isto evita eliminar o ficheiro errado por engano. Os agentes têm instruções para confirmar consigo primeiro. Entrada

Parâmetro	Tipo	Descrição
`id`	`uuid`	ID do ficheiro
`name`	`string`	Nome de apresentação atual do ficheiro. Tem de corresponder, ou a eliminação é cancelada

Saída: { "deleted": true }

Esta ação é irreversível. Todos os ecrãs do ficheiro são eliminados.

Ferramentas de ecrãs

`list-screens`

Lista os ecrãs de um ficheiro, pela ordem da tela. Chame esta ferramenta depois de list-files para ver o que já existe num ficheiro. Use os valores screenId devolvidos com as outras ferramentas de ecrãs e com as ferramentas de design com IA. Entrada

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

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 do ecrã, ou uma string vazia se nunca foi gerado (por exemplo, um ecrã adicionado com add-screen-jsx).
fidelity: lofi, hifi ou ui.

`get-screen-image`

Renderiza um ecrã em PNG e devolve-o como imagem em linha. Requer um cliente que suporte blocos de conteúdo de imagem. Chame esta ferramenta uma vez para cada screenId devolvido por uma ferramenta de design com IA, por add-screen-jsx, por replace-screen-jsx ou por import-figma. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do ficheiro
`screenId`	`uuid`	Um `screenId` de `list-screens` ou da matriz `screenIds` devolvida por uma ferramenta de design

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

`get-screen-jsx`

Obtém um ecrã como JSX, junto com os respetivos metadados, para que possa construir a partir dele no seu código ou editá-lo e devolvê-lo com replace-screen-jsx. Use get-screen-image para uma pré-visualização visual. Entrada

Parâmetro	Tipo	Predefinição	Descrição
`fileId`	`uuid`	—	ID do ficheiro
`screenId`	`uuid`	—	Um `screenId` de `list-screens` ou da matriz `screenIds` devolvida por uma ferramenta de design
`includeIds`	`boolean`	`false`	Inclui um atributo `data-id` nos elementos de `jsx`. Use-o quando precisar de IDs de elementos para passar como `elementIds` a `ai-design-screens`, para editar no lugar ou 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: apenas marcação. Os atributos data-id só são incluídos quando includeIds é true.
prompt: o último prompt de geração, ou uma string vazia se o ecrã nunca foi gerado.
fragments: elementos partilhados guardados no ecrã, como uma barra de navegação, um cabeçalho ou um logótipo, na forma de objetos { purpose, markup }. Vazio quando não há nenhum. Passe-os de volta para replace-screen-jsx para os manter ou atualizar.

Consulte Valores dos campos para os valores de fidelity, screenType e colorTheme.

`add-screen-jsx`

Adiciona um novo ecrã a um ficheiro a partir de JSX que escreveu. É o caminho centrado no código e é gratuito. Use ai-design-screens quando quiser que a IA do Flowstep desenhe o ecrã. add-screen-jsx cria sempre um novo ecrã: para substituir um existente, use replace-screen-jsx. Para mostrar uma imagem que carregou, consulte Imagens em JSX. Quando o novo ecrã se baseia num existente, comece por get-screen-jsx (sem includeIds) para obter name, fidelity, screenType, colorTheme e jsx, e depois altere o que deve ser diferente. Entrada

Parâmetro	Tipo	Predefinição	Descrição
`fileId`	`uuid`	—	ID do ficheiro
`name`	`string` (1–100 caracteres)	—	Nome de apresentação opcional. Omita-o para o ecrã receber o nome automático `Screen N`
`fidelity`	`string`	`"ui"`	Fidelidade do ecrã
`screenType`	`string`	—	Obrigatório: o dispositivo ou janela para a qual o ecrã é desenhado
`colorTheme`	`string`	`"default"`	Tema de cores
`jsx`	`string`	—	Apenas marcação JSX. Os atributos `data-id` são ignorados: o novo ecrã recebe novos IDs de elementos

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

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

`replace-screen-jsx`

Substitui um ecrã existente por JSX que escreveu. O ecrã mantém o seu screenId e a sua posição na tela, e os elementos aninhados recebem novos IDs. É o caminho centrado no código e é gratuito. Use ai-design-screens ou ai-edit-screen-variant para alterações feitas por IA, e add-screen-jsx para criar um novo ecrã. Comece por get-screen-jsx (sem includeIds) e depois altere o que deve ser diferente. Para mostrar uma imagem que carregou, consulte Imagens em JSX. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do ficheiro
`screenId`	`uuid`	O ecrã a substituir
`jsx`	`string`	Apenas marcação JSX. Os atributos `data-id` são ignorados
`name`	`string` (1–100 caracteres)	Opcional. Omita-o para manter o nome atual
`fidelity`	`string`	Opcional. Omita-o para manter a fidelidade atual
`screenType`	`string`	Opcional. Omita-o para manter o tipo de ecrã atual
`colorTheme`	`string`	Opcional. Omita-o para manter o tema de cores atual
`fragments`	`{ purpose, markup }[]`	Elementos partilhados opcionais, obtidos de `get-screen-jsx`. Omita-o para manter os fragmentos atuais, ou passe `[]` para os limpar

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

Isto substitui o conteúdo do ecrã no próprio lugar.

`rename-screen`

Muda o nome de um ecrã na tela, ou seja, o nome apresentado em list-screens e no editor. Altera apenas a etiqueta, e não o layout, o tamanho ou o conteúdo do ecrã. Para isso, use ai-design-screens. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do ficheiro
`screenId`	`uuid`	O `screenId` devolvido por `list-screens`
`name`	`string` (1–100 caracteres)	Novo nome do ecrã. Os espaços em branco 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`

Elimina permanentemente um ecrã de um ficheiro. O name que passa é comparado com o nome de apresentação atual do ecrã. Se não corresponder, a eliminação é cancelada. Os agentes têm instruções para confirmar consigo primeiro. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	ID do ficheiro
`screenId`	`uuid`	O ecrã a eliminar
`name`	`string`	Nome de apresentação atual do ecrã. Tem de corresponder, ou a eliminação é cancelada

Saída: { "deleted": true }

Imagens em JSX

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

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

Mantenha todos os outros URLs de imagens exatamente como get-screen-jsx os devolveu. Não coloque path, signedUrl nem uploadCommand em src.

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

Valores dos campos

get-screen-jsx devolve, 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 guardado num ficheiro. Quando estão definidas, são injetadas em cada geração de IA desse ficheiro. Consulte Diretrizes de design.

`get-design-guidelines`

Obtém as diretrizes de design associadas a um ficheiro. Entrada

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

Saída: { guidelines }.

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

guidelines é null se não tiverem sido definidas diretrizes.

`update-design-guidelines`

Define ou substitui as diretrizes de design de um ficheiro. Passe as diretrizes como uma string simples no formato DESIGN.md da Google, e não como objeto ou JSON. Se estiver a ler de um ficheiro, passe o texto desse ficheiro. Entrada

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

Regras de validação

O cabeçalho (frontmatter) tem de ser aberto e fechado corretamente
As linhas do cabeçalho têm de ser YAML válido em estilo de blocos
O corpo em Markdown não pode conter títulos de secção ## duplicados

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

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

warnings lista problemas de validação não bloqueantes (chaves desconhecidas, cores que não são hexadecimais) que foram aceites, mas que podem ser ignorados pela IA. Fica omitido quando não há nenhum. Apresente-os ao utilizador.

`delete-design-guidelines`

Limpa as diretrizes de design de um ficheiro. Eliminar diretrizes que não existem não tem efeito. Entrada

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

Saída: { "deleted": true }

Ferramentas de chat

`get-chat-history`

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

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

Saída: { messages }. messages fica vazio quando não tem nenhuma conversa de design no ficheiro. Cada mensagem tem um type ("request" ou "response"), um author ("human" ou "ai") e um content_type. As 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`

Carrega um ficheiro de referência para o 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 ficheiro nunca passam pelo modelo, e o servidor nunca vai buscar URLs em seu nome. Para referenciar uma página web, inclua o respetivo URL na message de ai-design-screens. Existem dois modos. Use exatamente um e não os combine. Modo A: ficheiros e imagens (mimeType + fileName) Um fluxo obrigatório de três passos para qualquer imagem, PDF ou ficheiro de texto maior:

Chame upload-attachment apenas com mimeType e fileName (por exemplo, image/png e dog.png). A resposta é um upload preparado, e não um ficheiro guardado:

{
  "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 ficheiro e execute esse comando exato na shell. Tem de terminar com código 0. O token em signedUrl autoriza apenas este carregamento único. Se saltar este passo, o armazenamento fica vazio e a ferramenta de design falha a verificação prévia.
Passe apenas { id, path, type } para o array attachments de ai-design-screens. Não passe 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 passa a add-screen-jsx ou a replace-screen-jsx. Consulte Imagens em JSX.

Para anexar um ficheiro remoto, transfira-o primeiro para um caminho local (por exemplo, com curl) e depois siga os mesmos três passos. Nunca passe um URL para upload-attachment.

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

Modo B: texto curto (text + mimeType) Carrega texto que já está no contexto, sem necessidade de comando de shell. A resposta fica pronta a usar 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. Apenas ficheiros de texto: não use para imagens nem 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 de ficheiro é de 3 MB em ambos os modos, e os PDFs estão limitados a 100 páginas. Saída: { id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }.

type: "image" para ficheiros de imagem e "document" para PDFs e ficheiros de texto.
assetUrl: o URL do ficheiro carregado, devolvido nos dois modos. Use-o em JSX para add-screen-jsx ou replace-screen-jsx apenas quando type for "image", e só depois de o uploadCommand do Modo A ter sido executado.
signedUrl, uploadCommand, nextStep: definidos apenas no Modo A. Não os passe às ferramentas de design.

Ferramentas do Figma

`import-figma`

Importa um frame do Figma para um ficheiro do Flowstep como elementos editáveis na tela desse ficheiro. Cada importação adiciona um novo ecrã. Importar o mesmo frame duas vezes dá-lhe dois ecrãs, por isso elimine o antigo com delete-screen se pretendia substituí-lo. A organização do ficheiro tem de ter o Figma ligado nas definições do Flowstep. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	O ficheiro do Flowstep onde o frame será importado. Não é a chave do ficheiro Figma em `figmaUrl`
`figmaUrl`	`string`	Ligação a um frame específico do Figma, com um `node-id`. No Figma, clique com o botão direito no frame e escolha Copy/Paste as → Copy link to selection. Uma ligação a uma página importa todos os frames de nível superior dessa página (limitado a 20 frames através do MCP)

Saída: { fileId, screenId, frameCount? }. screenId é o ecrã importado: passe-o para get-screen-image para ver o resultado. Quando um URL de página importa vários frames, screenId é null e é devolvido frameCount. Nesse caso, chame list-screens e depois get-screen-image para cada novo ecrã.

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

Ferramentas de plano e faturação

`get-plan-details`

Obtém o plano do Flowstep da sua organização, o estado da subscrição, a utilização e a quota restante. Não recebe entradas: a organização é resolvida a partir do utilizador com sessão iniciada. Use-a para verificar a sua quota 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 funcionalidade, identificados pela funcionalidade (por exemplo, `messages`). Cada um tem objetos opcionais `daily` e `monthly` com valores `max` e `warn`, além de uma flag `unlimited`
`usage`	Utilização por funcionalidade até ao momento, como `{ daily, monthly }`
`remaining`	Quota restante por funcionalidade, como `{ daily, monthly }`. Omitido nas funcionalidades ilimitadas

Os limites variam consoante o plano. Consulte Preços e Limites de utilização.

Ferramentas de design com IA

Estas três ferramentas desenham a partir de uma descrição ou de uma predefinição. Nunca recebem nem reutilizam JSX. Cada chamada usa a mesma quota de mensagens da aplicação Flowstep e aguarda até a geração terminar ou expirar (180 segundos).

Ferramenta	Use-a para
`ai-design-screens`	Gerar ecrãs novos, alterar ecrãs existentes no lugar, ou ambos, a partir de uma descrição de texto livre
`ai-generate-screen-variant`	Adicionar um próximo passo, um estado de erro ou vazio, ou uma variante de plataforma de um ecrã existente
`ai-edit-screen-variant`	Aplicar uma predefinição de edição ou redesenho a um ecrã existente inteiro

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

designGuidelinesUpdated: um resumo breve da alteração quando as diretrizes DESIGN.md do ficheiro foram atualizadas automaticamente durante este turno. Caso contrário, é null.

`ai-design-screens`

Gera um ou mais ecrãs novos, altera ecrãs existentes no lugar, ou faz as duas coisas numa só chamada, a partir de uma descrição em texto: novos fluxos, temas, texto, layout ou alterações coordenadas em vários ecrãs. É o mesmo agente de design do chat no editor do Flowstep: decide, a partir da sua message e de elementIds, o que criar e o que alterar. Omita fileId para começar um novo ficheiro. Passe fileId para trabalhar num ficheiro existente. Se o pedido puder aplicar-se a um ficheiro que já tem, o seu agente deve verificar primeiro list-files e list-screens. Para um próximo passo, um estado de erro ou vazio, ou uma variante de plataforma de um ecrã, use ai-generate-screen-variant. Para uma edição ou redesenho predefinido de um ecrã, use ai-edit-screen-variant. Se já tiver JSX, use add-screen-jsx ou replace-screen-jsx. Entrada

Parâmetro	Tipo	Predefinição	Descrição
`fileId`	`uuid`	—	Ficheiro de destino. Omita-o para criar um novo ficheiro. Obrigatório quando `elementIds` está definido
`message`	`string`	—	Descrição dos ecrãs a gerar e/ou das alterações a fazer. Quando passar `elementIds`, indique se devem ser editados ou usados como referência. Inclua aqui os URLs de páginas web que quer que o Flowstep consulte
`elementIds`	`uuid[]`	`[]`	`screenId` opcionais de `list-screens` e/ou `data-id` de elementos obtidos de `get-screen-jsx` (com `includeIds`), como uma seleção no editor. Podem ser editados no lugar ou usados como referência visual para ecrãs novos. Um `screenId` tem como alvo o ecrã inteiro
`attachments`	`{ id, path, type }[]` (máx. 5)	`[]`	Ficheiros de `upload-attachment`: imagens, PDFs, ou ficheiros de código e texto. Não inclua o conteúdo dos ficheiros na mensagem

Exemplo: editar um ecrã e adicionar outro numa ú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 foram criados ou alterados ecrãs. "chat" quando o Flowstep respondeu sem criar nada, caso em que reply contém a resposta e screenIds fica vazio. Se o seu pedido for ambíguo, o agente deve pedir-lhe que esclareça e voltar a chamar a ferramenta.
screenIds: todos os ecrãs criados ou alterados durante a chamada, incluindo os ecrãs editados no lugar. Se a chamada expirar depois de alguns ecrãs terem sido criados, devolve esses ecrãs em vez de um erro.

Os ecrãs que pede para editar são substituídos no próprio lugar.

`ai-generate-screen-variant`

Adiciona um novo ecrã derivado de exatamente um ecrã existente: o passo seguinte do fluxo, um estado de erro ou vazio, ou uma versão para outra plataforma. O ecrã original não é alterado. Para adicionar um ecrã que não seja uma variante de um existente (por exemplo, um ecrã de definições), use ai-design-screens com um fileId. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	Ficheiro de destino
`screenId`	`uuid`	O ecrã existente a partir do qual derivar
`operationVariant`	enum	Obrigatório: a relação entre o novo ecrã e o existente

`operationVariant`	Adiciona
`next_screen`	O ecrã seguinte no fluxo do utilizador
`error_state`	Um estado de erro do ecrã
`empty_state`	Um estado vazio do ecrã
`web_version`	Uma versão web
`mobile_version`	Uma versão mobile
`tablet_version`	Uma versão tablet
`mobile_ios_version`	Uma versão iOS
`mobile_android_version`	Uma versão Android

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

`ai-edit-screen-variant`

Altera exatamente um ecrã existente no lugar, usando uma predefinição: aplicar um tema ou polir o ecrã, experimentar um layout ou estilo visual diferente, ou redesenhá-lo de raiz. Para ecrãs novos, instruções de texto livre ou uma edição precisa de elementos individuais, use ai-design-screens. Entrada

Parâmetro	Tipo	Descrição
`fileId`	`uuid`	Ficheiro de destino
`screenId`	`uuid`	O ecrã existente a alterar
`operationVariant`	enum	Obrigatório: a predefinição de edição ou redesenho a aplicar

`operationVariant`	Tipo	Efeito
`dark_theme`	Edição	Muda o ecrã para um tema escuro
`light_theme`	Edição	Muda o ecrã para um tema claro
`make_pretty`	Edição	Melhora o design visual do ecrã
`different_layout`	Redesenho	Experimenta um layout diferente
`different_style`	Redesenho	Experimenta um estilo visual diferente
`from_scratch`	Redesenho	Redesenha o ecrã de raiz

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

Isto substitui o conteúdo do ecrã no próprio lugar.

Ferramentas renomeadas

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

Nome antigo	Novo nome
`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 de texto livre)	`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 variantes) 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. As ferramentas de diretrizes de design recebem fileId em vez de resourceId e linkedTo.

​Ferramentas de ficheiros

​list-files

​get-file

​create-file

​update-file

​delete-file

​Ferramentas de ecrãs

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​Imagens em JSX

​Valores dos campos

​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 faturação

​get-plan-details

​Ferramentas de design com IA

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​Ferramentas renomeadas

Ferramentas de ficheiros

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Ferramentas de ecrãs

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

Imagens em JSX

Valores dos campos

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 faturação

`get-plan-details`

Ferramentas de design com IA

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

Ferramentas renomeadas