> ## Documentation Index
> Fetch the complete documentation index at: https://widgetic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools reference

> The tools the Widgetic MCP server offers, what each does, what it costs and which permission it needs

Your assistant chooses between the tools from their descriptions, so you rarely name one yourself. The server describes each tool fully (inputs, outputs, when to use it) to the client; this page is the overview.

> [!NOTE]
>
> The list is the same for everyone. A tool you are not allowed to use is refused when called, not hidden.

## At a glance

| Tool | What it does | Permission | Credits |
| - | - | - | - |
| `get_profile` | Tells which Widgetic account the connection acts for | `widgetic.read` | 0 |
| `get_account_usage` | Reports your credits, storage, widget counts and whether you can publish | `widgetic.read` | 0 |
| `create_widget` | Starts building a new widget from a description | `widgetic.write` | 1 |
| `replicate_widget` | Offers the copy a Widgetic capture link points to as the replica; nothing is built | `widgetic.write` | 0 |
| `get_widget` | Reports a widget's state: building, ready, failed, published | `widgetic.read` | 0 |
| `revise_widget` | Starts a new build of an existing widget from your feedback | `widgetic.write` | 1 |
| `cancel_widget_creation` | Cancels a build that has not finished | `widgetic.write` | 0 |
| `show_widget` | Shows a widget as a card: progress, then the live preview | `widgetic.read` | 0 |
| `list_widgets` | Lists your widgets, drafts or published, a few at a time | `widgetic.read` | 0 |
| `publish_widget` | Makes the current draft, or an earlier version, live | `widgetic.publish` | 0 |
| `unpublish_widget` | Takes a published widget offline without deleting anything; it goes back to a draft and `publish_widget` brings it back | `widgetic.publish` | 0 |
| `list_widget_versions` | Lists the versions a widget has been through and which one is live | `widgetic.read` | 0 |
| `get_widget_customization_options` | Lists what you can change on a widget, a draft or a published one, without rebuilding | `widgetic.read` | 0 |
| `update_widget_customization` | Changes texts, images, list items, colors, fonts or sizes: at once on a published widget, saved on a draft until it is published | `widgetic.write` | 0 |
| `get_embed_code` | Returns the code or link to put a published widget on a website | `widgetic.read` | 0 |
| `duplicate_composition` | Makes a second embeddable copy of a published widget | `widgetic.write` | 0 |
| `list_widget_data` | Shows whether a published widget keeps what visitors send in (votes, RSVPs, form entries), and how much | `widgetic.read` | 0 |
| `get_widget_data` | Counts those entries, or tallies them per option; shows the entries themselves only when you ask | `widgetic.read` | 0 |
| `rename_widget` | Gives a widget a different name | `widgetic.write` | 0 |
| `delete_widget` | Permanently deletes a widget, after you confirm its title | `widgetic.delete` | 0 |
| `save_to_media_library` | Saves images (SVG too), videos, audio, PDFs or data files (CSV, JSON, Excel) you provide to your media library | `widgetic.write` | 0 |
| `list_media_library` | Lists the files in your media library, and which widgets each was given to | `widgetic.read` | 0 |
| `manage_media_library` | Renames files in your media library or moves them to another folder, up to 20 at a time; widgets already built keep working | `widgetic.write` | 0 |
| `delete_media_file` | Permanently deletes one file from your media library, after you confirm its name; a file that widgets use is refused unless you say you still want it gone | `widgetic.delete` | 0 |
| `list_workflows` | Lists your workflows, a few at a time, with their state | `widgetic.read` | 0 |
| `get_workflow_options` | Lists which of your published widgets a workflow can use, and what a visitor can do on each | `widgetic.read` | 0 |
| `get_workflow` | Shows one workflow as a script: its start, steps and moves, its state and, once published, its embed code | `widgetic.read` | 0 |
| `save_workflow` | Creates a workflow or saves a change to its draft; nothing a visitor sees changes | `widgetic.write` | 0 |
| `test_workflow` | Plays made-up visitor events through a workflow and says where each one ends up; nothing is saved | `widgetic.read` | 0 |
| `publish_workflow` | Makes the saved draft what visitors get on the embed, and returns the embed code | `widgetic.publish` | 0 |
| `set_workflow_state` | Pauses, resumes, archives or brings back a workflow | `widgetic.write` | 0 |
| `suggest_widgets` | Suggests which widgets would fit what you want to make (a page, a workflow) and the workflows they make where they fit, asking a few questions first when it needs to; builds nothing | `widgetic.read` | 0 |
| `create_widget_batch` | Starts several of the suggested widgets at once, up to 25, each as its own widget, in one project if you like and with a draft workflow that chains them if you ask; 1 credit for each widget | `widgetic.write` | 1 |
| `cancel_widget_batch` | Cancels the builds of several widgets at once; a build that had not started gets its credit back | `widgetic.write` | 0 |
| `draft_workflow_from_widgets` | Saves a draft workflow from widgets you built, one step for each, in the order you give; nothing a visitor sees changes | `widgetic.write` | 0 |
| `get_brand_kit` | Shows the Brand Kit your widgets start from: colors, fonts, corner radius, style notes and the names of your icons | `widgetic.read` | 0 |
| `update_brand_kit` | Changes parts of your Brand Kit (colors, fonts, corner radius, style notes); widgets already built keep their look | `widgetic.write` | 0 |
| `list_ab_tests` | Lists your A/B tests in the workspace you are signed in to, a few at a time | `widgetic.read` | 0 |
| `get_ab_test_options` | Lists the goals a test can use and your published widgets that can be a version | `widgetic.read` | 0 |
| `get_ab_test` | Shows one A/B test: setup, results, recommendation, winner and embed code | `widgetic.read` | 0 |
| `save_ab_test` | Creates a draft A/B test or changes a draft; nothing a visitor sees changes | `widgetic.write` | 0 |
| `set_ab_test_state` | Starts, pauses or stops an A/B test | `widgetic.write` | 0 |
| `list_translations` | Lists your translations in the workspace you are signed in to, a few at a time | `widgetic.read` | 0 |
| `get_translation_options` | Lists the languages available and how many a translation may hold | `widgetic.read` | 0 |
| `get_translation` | Shows one translation: each language's state and the embed code | `widgetic.read` | 0 |
| `create_translation` | Translates one of your widgets into up to five languages; nothing a visitor sees yet | `widgetic.write` | 0 |
| `add_translation_languages` | Adds up to five more languages to a translation | `widgetic.write` | 0 |
| `set_translation_state` | Activates or pauses a translation | `widgetic.write` | 0 |

Permissions are the scopes you approve when you sign in; see [Authentication](https://widgetic.com/docs/agents/authentication.md#permissions).

## Building

> [!NOTE]
>
> When a build finishes, the widget is published for you, so it is ready to customize and embed without a separate publish step. A plan that does not include publishing keeps the finished draft instead, and so does a connection you approved without the permission to publish (`widgetic.publish`); the result says so, and how to publish. To look at a widget before it goes live, or to try a change without touching what live embeds show, ask the assistant to keep it as a draft.

> [accordion] create\_widget
>
> Starts a new widget from a description: a quiz, countdown, gallery, timeline, FAQ, chart, calculator, list, carousel or similar. It returns at once with a widget id; the build usually takes a few minutes, and the finished widget is published unless you asked for a draft. Each call starts a separate widget and uses 1 credit, charged up front. A call that repeats the title of a widget started in the last two minutes returns that widget and charges nothing, so a retry after a failure or timeout does not build twice. If you are unsure, check your widgets before creating again. When the description needs it (a vote, a rating, a comment, an RSVP or a sign-up), the widget it builds keeps what visitors send, and you can read it with `list_widget_data` and `get_widget_data`. The widget goes to your default project unless you name one (see [Where a new widget goes](#where-a-new-widget-goes)).

> [accordion] replicate\_widget
>
> Offers the copy of a web page element that the Widgetic Chrome extension stored, from the temporary capture link it gave you (`wgc_…`). The copy is the replica: the model does not run, nothing is built, no credits are used, and nothing is added to your library or published, so the assistant does not follow it with a build card or wait for a build. The link is only looked up in Widgetic's own store and never fetched over the network; an expired, revoked or unknown link is refused, and the assistant asks you to copy the element again. A change you ask for is not made: the copy is offered as it was captured.

> [accordion] get\_widget
>
> The current state of one widget: still being built and how far along, draft ready, failed or cancelled, the link to its preview, and whether it is published and being served. For a published widget it also lists its copies (compositions) with their ids. While a build runs, the assistant checks it every 5 to 10 seconds.

> [accordion] show\_widget
>
> Shows a widget as a card, with the build progress and then the live preview, and actions to revise, publish, customize or copy the embed code. Assistants that cannot display cards get the same state as text.

> [accordion] revise\_widget
>
> For changes that need new code: new features, a different layout, another visual style. It starts a new build from the latest draft (1 credit). When the build finishes, the new version is published again on its own, so every copy of the widget and every embed shows the new code, and the embed code does not change. Every earlier version is kept, and `publish_widget` can bring one back. To try a change without touching what live embeds show, ask for it as a draft: embeds then keep showing the last published version until you publish.

> [accordion] cancel\_widget\_creation
>
> Cancels a build that is still queued or generating. A build already under way may still finish and leave a draft, and credits already charged are not refunded. It does nothing to a draft that is ready or a widget that is published.

## Where a new widget goes

`create_widget` and `create_widget_batch` make the widget in the workspace you are signed in to on widgetic.com, your own or a team's: the same one the [workflow](#workflows), A/B test and translation tools use. The assistant cannot pick another one: switch workspace on widgetic.com first. If you tell the assistant which workspace you mean, it checks that you are signed in to it and starts nothing, and uses no credit, if you are not. `replicate_widget` makes nothing in a workspace: it only offers the copy the extension stored.

In your own workspace nothing is different: the widget goes to your default project, or to the project you name. In a team:

* Your role in the team has to allow making widgets there. If it does not, or if the team cannot be read just then, the call is refused before any credit is used, and the assistant says why.
* The widget goes to the team's default project, or to the project you name: a project of the team with that name is used, and a new one is made when there is none and your role lets you make projects. A name that cannot be used never stops the build: the widget goes to the default project and the assistant says so.
* The team's Brand Kit applies to the widget, and the credit is always your own; the team's plan is read to see whether it allows the build.
* The answer says which team and which project the widget went to.

A widget that already exists stays where it is: nothing here moves one between workspaces. The tools reach the widgets you made yourself, not those of your teammates.

## What a build can start from

`create_widget` and `revise_widget` take more than a description. When you attach a file or paste a Figma link, the assistant passes it along; you do not name anything yourself. Whatever cannot be read refuses the whole call before any credit is used, and the answer says which file or link and why.

> [accordion] Files you attach
>
> Up to 5 files per call: images, videos, PDF documents, data files (CSV, JSON or Excel `.xlsx`, each read for its columns and rows) and Markdown or text files (`.md`, `.txt`), whose words are read as your own brief, spec or copy. A widget loads a JSON file from its address; it cannot load a workbook, so for an Excel file the builder is given its first rows (a long sheet is better sent as CSV). Other kinds, such as the old `.xls` Excel format, are refused. A file reaches Widgetic only through a file service Widgetic trusts (ChatGPT's, for example), never from an address typed into the chat; where your assistant cannot hand a file over that way, paste the text of a document into your description.

> [accordion] Figma links
>
> Paste up to 3 links to a frame or a selection in Figma ("Copy link to selection"), and the widget is built to match that design. Widgetic reads each design with your own connected Figma account: connect Figma once from the [Design page](https://widgetic.com/design). If you have not connected it yet, the assistant tells you to open that page, choose Connect Figma and send the link again; nothing is charged until the design can be read. A link to a file your account cannot open, or to a FigJam board or a Slides or Make file, is refused with the reason. Links written inside your description are read as well, and a design named twice is read once.

## Several widgets at once

A landing page, a course or an event is rarely one widget. Say what you want to make and the assistant can suggest the widgets that would fit (a scoreboard, a schedule, a gallery, cards for the team, a countdown), ask a few questions if it needs them, and, once you have chosen, start all of them in one go, each in its own canvas. The same works for a workflow: describe it, and the assistant offers to build the widgets its steps need, and can save a draft workflow that chains them (see [Workflows](#workflows)).

In a client that can draw them, the suggestions appear as a list you tick and the questions as a form with one field for each; in any other client the assistant shows the same as text and asks in the chat. Ticking a widget only tells the assistant which ones you want: the list builds nothing and uses no credits, and the assistant starts the batch when you agree.

> [accordion] suggest\_widgets
>
> Tells you which widgets would fit what you want to make, before anything is built. You say the goal in your own words. If it is too open, the assistant puts up to three questions to you first, once, and asks again with your answers. The answer lists the widgets worth building, each with what visitors would see and a description ready to be built, and says which of them stand on their own. Where some of the widgets work as a journey a visitor goes through step by step (a welcome and then a form, a quiz and then its results), it also offers that as a **workflow**: what it does and which widgets it is made of, in order. So the assistant tells you: these widgets stand on their own, this workflow does this and is made of these widgets, and this other workflow does that and is made of those. You choose widgets and workflows, and the assistant says how many widgets that makes before it starts anything (a widget that two workflows share is built once). It suggests up to nine widgets unless you ask for more (twelve at most), the widgets of a workflow counting among them; when your goal needs more than that, the summary says what was left out. It also says plainly what a widget cannot do for your goal (orders, payments, logins, data that updates by itself). The suggestions come from a language model that reasons from your words, not from a fixed list, and your words are checked with a content moderation service and sent to that model. It builds nothing and uses no credits: the assistant shows you the suggestions and builds only the ones you choose. If the model cannot answer at that moment, the assistant proposes the widgets itself.

> [accordion] create\_widget\_batch
>
> Starts the widgets you chose, up to 25 in one call, each as its own widget with its own canvas, the way `create_widget` starts one: 1 credit for each widget, charged when its build starts, and published when it finishes unless you asked for drafts (a workflow needs published widgets). The assistant tells you how many widgets and credits that is and waits for your yes first, and it passes the total you agreed to, so nothing is started if the widgets would cost more. The call returns at once with one entry per widget; the builds usually finish within a few minutes, and the assistant follows each one until it is ready. A title that repeats a widget started in the last two minutes is returned as it is and charged nothing, so a retry after a lost answer starts only what is missing; after those two minutes a repeat is charged again, so if you are unsure, check your widgets before starting the batch again. If one widget cannot be started, the ones before it keep building and stay charged, and the rest are not started and not charged. A batch can be started once a minute. Each widget can use up to 5 images from your media library; for attached files or Figma links, the assistant starts that widget with `create_widget` instead.
>
> Two things you can ask for with the batch. **A project:** the widgets are filed in one project of yours with the name you give (a project you already have with that name is used, otherwise a new one is made, in the workspace you are signed in to, with the rules of [Where a new widget goes](#where-a-new-widget-goes)); a name that cannot be used never stops the batch, the widgets then go to your default project and the assistant says so. **A workflow:** with a name for it, Widgetic saves a draft workflow that chains the widgets in the order you gave once every one of them is built and published, even if the conversation has closed by then. It is only a draft, made once, in the workspace you asked in: you publish it yourself, after trying it, and a widget that failed leaves it waiting (for up to three days) until you have it rebuilt. The name chains every widget of the batch, so the assistant passes it only when you chose exactly the widgets of one suggested workflow; for any other choice (two workflows, or a workflow beside other widgets) it starts the widgets without it and, once they are built and published, saves each workflow you chose with `draft_workflow_from_widgets`. If the draft is not made, `draft_workflow_from_widgets` makes it from the finished widgets.

> [accordion] cancel\_widget\_batch
>
> Stops the builds of several widgets at once, for when you change your mind about a batch: the assistant passes the widgets the batch returned. A build still waiting to start is stopped and its credit is returned. A build already being written is stopped too, but its credit is returned only if the model had not begun to write, and it can still finish as a draft, so the assistant tells you which is which. Each widget gets its own answer (cancelled, nothing was running, or not one of your widgets) and one never stops the others. If a draft workflow was waiting for those widgets, it is cancelled too. It uses no credits.

## Finding and publishing

> [accordion] list\_widgets
>
> All your widgets, only drafts that were never published, only published ones, or those whose name contains some words. It shows up to 8 at a time as a carousel and the assistant can ask for the next page.

> [accordion] publish\_widget
>
> Publishes the current draft (final build and upload), or an earlier version you choose, and returns the composition id and the published version. It can take up to a minute. Builds publish themselves unless you asked for a draft, so this is for a draft you kept or an earlier version you want back. It replaces the version existing embeds show, so the assistant calls it only after you agree. It needs a plan that includes publishing. Whatever you customized on the draft before its first publish goes live with it.

> [accordion] unpublish\_widget
>
> Takes a published widget offline without deleting anything: its embeds and share links stop showing it to pages that load them from then on, and it goes back to being a draft. Its versions, copies, embed codes, saved customizations and the entries visitors sent are all kept, and `publish_widget` brings it back with the same embed code; the answer names the version that was live, so the assistant can bring back that very one. A page that has already loaded the widget keeps showing it until it reloads: this recalls nothing that is already on a screen. It is refused, with the reason, while a running A/B test or a live or paused workflow uses the widget, because those would show a page that is not there; pause or stop them first. A build or a revision that finishes afterwards publishes the widget again, unless it was started as a draft. It uses no credits and needs the publish permission, and calling it on a widget that is already a draft changes nothing.

> [accordion] list\_widget\_versions
>
> The versions a widget has been through, newest first, with a short title for each when it has one, whether it was ever published and which one is live now. The assistant uses the numbers to bring an earlier version back with `publish_widget`. It shows up to 20 at a time and can ask for older ones. It does not show what a version contains.

## Customizing and embedding

> [accordion] get\_widget\_customization\_options
>
> Every content field, list and design control of a widget, with its current value and limits. The assistant reads this before changing anything. It works on a published widget and on a draft (a widget that was built and never published, or taken offline again), where it shows the values saved on the draft; a widget whose first build is still running has no options yet. The assistant names the widget by its id, or one published copy by its composition id, never both.

> [accordion] update\_widget\_customization
>
> Changes what a widget shows or how it looks: texts, images from your media library, list items, colors, fonts and sizes. On a published widget it applies at once and embeds show the change. On a draft the change is saved on the draft, shows in its preview and goes live with the widget when it is published: the first publish copies the saved values into the copy it creates, and never over values a copy already holds. It uses no credits. Only options the widget offers are accepted, values are checked against its limits, and a list the assistant sends replaces the whole list while anything left out stays as it is.

> [accordion] get\_embed\_code
>
> Plain HTML, an iframe, or a React, Vue, Svelte or Angular component, at a fixed size or fully responsive, plus a share link. If embeds are not being served right now because of your account's state, the result says so.

## Managing widgets

> [accordion] duplicate\_composition
>
> Makes a second embeddable copy of a published widget: the same content, design and embed settings, with its own id and embed code. Useful for the same widget on another page with different texts or colors. A widget can have up to 10 copies. It uses no credits and does not rebuild or republish anything.

> [accordion] list\_widget\_data
>
> For one of your published widgets that keeps what visitors send in, shows which tables of entries it has, their columns and how many entries each holds. A widget the assistant built keeps entries only when you asked for that (a poll, a rating, a comment wall); one that was not asked to, and one made from a pasted widget link, keeps nothing, and for those it says there is no data. It only reads and uses no credits.

> [accordion] get\_widget\_data
>
> Answers "how many votes did each option get?" or "how many said yes?" for a published widget that keeps entries: a count, or a tally per value of a column, largest first. The entries themselves (the newest 10, at most 25, long texts cut) come back only when you ask to read what visitors wrote. What visitors typed is reported as their words and is never treated as an instruction by the assistant. It only reads: it cannot change or delete an entry, and it uses no credits.

> [accordion] rename\_widget
>
> Gives a widget a different name. Only the widget's title changes: its published copies keep their names, nothing is rebuilt and embeds are not affected. The previous name is returned.

> [accordion] delete\_widget
>
> Permanently deletes a widget with all its versions and its published copies. Embeds already placed on websites stop working, credits already used are not refunded, and it cannot be undone. The assistant has to pass the exact title of the widget as you confirmed it, and a widget that is still being built cannot be deleted.

## Workflows

A workflow chains published widgets on one embed: a visitor sees the first, and when something happens on it (an entry they send, a goal the widget reports, an event your page sends, or a wait) the embed shows the next one in place. You describe it in words and the assistant writes it as a script: a start, the steps (each a published widget) and the moves between them, with rules that choose the next step. A workflow made this way opens in the workflow editor on widgetic.com, and the other way round.

> [!NOTE]
>
> The workflow tools work in the workspace you are signed in to on widgetic.com, your own or a team's, and every answer says which. The assistant cannot pick another one: switch workspace on widgetic.com first. Workflows belong to the plans that include them; on another plan the tools say so in plain words. None of them uses credits and none builds a widget: the widgets must already be published (see [Finding and publishing](#finding-and-publishing)); to make several first, see [Several widgets at once](#several-widgets-at-once).

> [accordion] list\_workflows
>
> Your workflows in the workspace you are signed in to, newest first, up to 20 at a time: the name, the state (draft, live, paused or archived), whether the saved draft has changes visitors do not have yet, how many widgets it shows and how many visitors started it. Archived workflows are left out unless you ask for them. It only reads.

> [accordion] get\_workflow\_options
>
> Which of your published widgets a workflow can use: the id to use as a step, the tables visitors can add entries to (with the columns a rule may read) and the actions the widget reports, such as a click. A move can wait only for what is listed here. Private columns such as an email or a phone number are never listed. It only reads.

> [accordion] get\_workflow
>
> One workflow as a script, in exactly the shape `save_workflow` takes: the start step, the steps and the moves between them, with the rules that choose the next step. It also gives the state, the revision, any problems and the names of the widgets. For a published workflow it returns the embed code and the snippet for events your page sends, and, when asked, how many visitors reached each step in the last 30 days. A draft drawn in the editor that a script cannot express is reported as unreadable, with the reasons. It only reads.

> [accordion] save\_workflow
>
> Creates a workflow (it needs a name) or replaces the draft script of one you name, starting from the revision the assistant read. If the draft changed since, in the editor or by another call, nothing is saved and the assistant is told to read it again, so a change made elsewhere is never overwritten. The answer lists any problems in plain words. Saving changes only the draft: nothing reaches visitors until `publish_workflow`. Every call without a workflow id creates another workflow, so after a failed call the assistant checks `list_workflows` before it tries again.

> [accordion] draft\_workflow\_from\_widgets
>
> Saves a draft workflow from widgets you already built: one step for each widget, in the order the assistant passes (the order visitors should meet them), under the name you gave. A step leads on to the next when its widget keeps entries (a visitor sends one) or reports an action (a click, a choice); a widget that offers neither is saved with no way on and the assistant asks you what should take visitors on, then sets it with `save_workflow`. A workflow holds up to 25 blocks, so a chain of more than 13 widgets cannot lead on from every step: the assistant is told which. Every widget must be built and published; if not, nothing is saved and the answer says which are not. It never publishes (visitors see nothing until `publish_workflow`), changes nothing that exists, and uses no credits.

> [accordion] test\_workflow
>
> Plays up to 20 visitor events (an entry added to a table, an action the widget reports, an event your page sends, or a wait that is over) through the saved draft, or through a script that is not saved, and says where the visitor ends up and why. Nothing is saved, no visitor is moved and no entry is created.

> [accordion] publish\_workflow
>
> Checks the saved draft and makes it the version visitors get on embeds. The assistant passes the revision it last read: if the draft changed since, nothing is published. Problems are listed in plain words and nothing is published until there are none. The result returns the embed code and, when the workflow waits for events from your page, the snippet that sends them. It replaces the version that is live now (every earlier version is kept), so the assistant calls it only after you agree. A paused workflow stays paused. It needs a plan that includes workflows and a connection approved with the publish permission.

> [accordion] set\_workflow\_state
>
> Pauses a live workflow (its embeds then show only the first widget and move no visitor on), resumes a paused one, archives a workflow to set it aside (it leaves the list and nothing is deleted) or brings an archived one back (a published one comes back paused, a never-published one as a draft). Every change can be undone. Resuming puts the workflow back in front of visitors, so it needs a connection approved with the publish permission.

## Media library

> [accordion] save\_to\_media\_library
>
> Saves images (PNG, JPEG, WebP, GIF, HEIC, SVG), videos (MP4, WebM, MOV), audio (MP3, WAV, OGG, M4A), PDFs or data files (CSV, JSON, Excel `.xlsx`) you attached or linked. Links must be HTTPS and are not followed through redirects; files up to 250 MB each, an SVG up to 2 MB, JSON and Excel files up to 10 MB. An SVG is rewritten from a list of safe elements before it is stored, so scripts and other active content are removed. A JSON or Excel file is read before it is saved and kept only if it holds a table: an Excel file is read from its first sheet (the values it stores, never a formula), and because a widget cannot load a workbook the builder is given its rows. They go into the folder you name (default "Assets") and count against your storage allowance. Files that cannot be saved are listed with the reason; the others are still saved.

> [accordion] list\_media\_library
>
> Browses what is already saved, as a carousel of thumbnails you can filter by folder, kind or name, and gives the file ids a widget can use. A file that widgets were given says which (how many, and the most recent few by name). Widgetic has recorded that only since it began keeping track, so a file without it may still be in use.

> [accordion] manage\_media\_library
>
> Renames files in your media library, moves them to another folder, or both: up to 20 changes in one call, each naming a file by the id `list_media_library` gave. A name keeps the file's extension, so the assistant sends it without one, and a folder is made by naming it. Only the name and the folder change: the file's address does not, so widgets that already use the file keep showing it. Each change stands alone: one that cannot be made (no such file, an empty name) is listed with its reason and the others are still made. The result shows each file as it is now and as it was, so a change can be put back, and a request that changes nothing writes nothing. It works on your own files only and uses no credits.

> [accordion] delete\_media\_file
>
> Permanently deletes one file from your media library and gives its space back to your storage allowance. It cannot be undone, and the assistant has to pass the exact file name as you confirmed it. A widget that loads the file from its address stops showing it, so Widgetic first looks for the widgets that use it (the record of builds and customizations, and the values saved in your widgets and Brand Kit): a file that is used is refused, with the widgets' names, and so is a file whose use could not be checked in full, unless you say you still want it deleted. Widgetic cannot read the code of a widget built before it kept that record, so "no widgets found" never means that none uses the file. It works on your own files only and uses no credits.

## Brand Kit

Your Brand Kit is the look every new widget starts from: a palette, a font for each of title, subtitle, body and caption, a corner radius, and a few style notes of your own. It belongs to your account and is the same wherever you set it (the Brand Kit page on widgetic.com, the API, the CLI or these tools). These tools read and change **your own** Brand Kit, the one a widget made in your own workspace starts from. A widget made in a team starts from the team's kit, which these tools never read or change: that is done on widgetic.com. Font files and icons are added on widgetic.com too.

> [accordion] get\_brand\_kit
>
> Shows your Brand Kit: the colors (name, hex and the role each plays), the font of each role, the corner radius, your style notes and the names of the icons you uploaded. When you have saved none it shows Widgetic's default look and says so. It also lists any text color that is hard to read on the background it is paired with. It changes nothing and uses no credits.

> [accordion] update\_brand\_kit
>
> Changes the parts you ask for and leaves the rest as it is: the colors (the whole palette, so the assistant reads it first and sends every color to keep), the font of any role, the corner radius (0 makes every corner square, 12 is the usual roundness) and your style notes (an empty note removes them). It says which parts are different now and what each was before. Widgets already built or published keep their look until they are revised; the next widget built or revised uses the new look. It uses no credits and does not upload font files or icons.

## A/B tests

An A/B test splits visitors between two to four of your published widgets on one embed and measures which version reaches a goal you choose. You set it up as a draft, start it when you are ready, read how it is doing, and stop it with an optional winner. A test made here opens on widgetic.com, and the other way round.

> [!NOTE]
>
> The A/B test tools work in the workspace you are signed in to on widgetic.com, your own or a team's, and every answer says which. The assistant cannot pick another one: switch workspace on widgetic.com first. A/B testing is included in the Teams plan and in a partner agreement; on another plan the tools say so in one plain sentence. None of them uses credits. Saving a test changes only the draft: nothing a visitor sees changes until the test is started. Starting a test needs a connection approved with the publish permission. While a test runs, its embed tag shows the versions; when it is paused or stopped the tag shows no widget, so after you stop with a winner you put that widget's own embed code on the page.

> [accordion] list\_ab\_tests
>
> Your A/B tests in the workspace you are signed in to, newest first, up to 20 at a time: the name, the state (draft, running, paused, completed or graduated), the goal, how many versions it has and how many days ago it started. You can filter by state, search the name, and ask for the next page with the cursor. It only reads and does not show how a test is doing.

> [accordion] get\_ab\_test\_options
>
> What a test can use before you make one: the goals (each says whether the embed counts it automatically or only when the widget reports it) and your published widgets that can be a version (each lists the goals it reports). Look up particular widgets by id, or search by name; widgets come newest first, up to 20 at a time, with a cursor for more. It only reads.

> [accordion] get\_ab\_test
>
> One A/B test: the goal, the versions with their share of traffic, the settings, the results so far (visitors, how many reached the goal, each version's rate and its lift over the control) with a recommendation (`continue`, pick a winner or stop), the winner once there is one, and the embed code. Visitors see the versions only while the test is running. A draft has no visitor numbers yet. It only reads.

> [accordion] save\_ab\_test
>
> Without a test id, creates a new draft (a name, a goal and two to four versions are required; each version is one of your published widgets by composition id, optionally named and with a share of traffic; leave out the shares for an even split). With a test id, changes a draft's name, description, goal or settings. Saving shows nothing to visitors: a test starts only with `set_ab_test_state`. The versions of a saved test cannot be changed here, and a test that has already started cannot be edited. The assistant should read `get_ab_test_options` first. It uses no credits.

> [accordion] set\_ab\_test\_state
>
> Starts a draft or a paused test (`start`), pauses a running one (`pause`), or stops a running or paused one for good (`stop`, with `winner_version_id` when there is one). Starting splits real visitors between the versions on every page that carries the test's embed code. Stopping cannot be undone: a stopped test cannot be started again. When you stop with a winner, put that widget's own embed code (`get_embed_code`) on the page in place of the test's tag, because a stopped test's tag shows no widget. Asking for the state a test is already in changes nothing. Starting needs a connection approved with the publish permission. It uses no credits.

## Translations

A translation makes one of your widgets available in several languages on one embed: each language is its own copy, and visitors see the copy that matches their browser's language while the translation is active. You make a translation, add more languages if you need them, and activate it when you are ready. A translation is made by a language model: the widget's text, and the text inside its design, is sent to it to be translated, and the assistant is asked to tell you so before it starts one.

> [!NOTE]
>
> The translation tools work in the workspace you are signed in to on widgetic.com, your own or a team's, and every answer says which. The assistant cannot pick another one: switch workspace on widgetic.com first. Translations are included in the Teams plan and in a partner agreement; on another plan the tools say so in one plain sentence. None of them uses credits. One call translates up to five languages; a translation holds at most twenty languages in all, the original included. Nothing is shown to visitors until `set_translation_state` activates the translation. Activating needs a connection approved with the publish permission. The widget must be one you made yourself.

> [accordion] list\_translations
>
> Your translations in the workspace you are signed in to, newest first, up to 20 at a time: the name, the state (making, ready, active, paused or unfinished), the original language, the languages it holds and the widget it was made from. You can filter by state, search the name, and ask for the next page with the cursor. It only reads.

> [accordion] get\_translation\_options
>
> Which languages a widget can be translated into (code, English and native name, region and whether it is one most translations start with) and the limits: how many languages one call translates and how many a translation holds in all. It takes no input and only reads.

> [accordion] get\_translation
>
> One translation: its state, the original language, and for each language whether its copy is ready, still being translated or failed, with the widget of each copy; the languages being added right now; and the embed code, which shows each visitor their language only while the translation is active. It only reads.

> [accordion] create\_translation
>
> Translates one of your widgets into other languages: it makes a copy of the widget for each language you name and groups them as one translation. Give the language the widget is written in now and one to five languages to translate into; the original is kept as it is. The widget's text is sent to a language model to be translated, so the assistant should tell you that before it calls. The call waits for under a minute and then answers even if some languages are still being translated; check them with `get_translation`, and add more later with `add_translation_languages`. The new translation is ready but not shown to visitors until `set_translation_state` activates it. It uses no credits.

> [accordion] add\_translation\_languages
>
> Adds one to five more languages to a translation you already made, or tries again for a language that failed or was left unfinished. The widget's text is sent to a language model to be translated, so the assistant should tell you that before it calls. A language that is already there and ready is skipped. A translation holds at most twenty languages in all. The call waits for under a minute and then answers even if some languages are still being translated; check them with `get_translation`. Visitors get a new language only while the translation is active. It uses no credits.

> [accordion] set\_translation\_state
>
> `activate` makes the embed show each visitor the language of their browser; `pause` takes it away again. A translation can be activated once it is ready, or when it is paused; not while it is still being made. Nothing is deleted and each action can be undone. Asking for the state a translation is already in changes nothing. Activating needs a connection approved with the publish permission. It uses no credits.

## Account

> [accordion] get\_profile
>
> The account the connection acts for: name, email and nickname when available, and an opaque id that stays the same across reconnects. Useful to confirm the connection works and whose widgets will be created. It cannot look up anyone else.

> [accordion] get\_account\_usage
>
> Your credits available (after those held for builds in progress) and how many builds they cover, your storage use and limit, how many widgets you have and how many are published, whether your plan includes publishing, and whether embeds are being served. A figure that cannot be read at that moment is reported as unknown, never as zero. It uses no credits.

## What the tool flags mean

Each tool declares, for assistants that show a confirmation before acting, whether it only reads, whether it can change or replace something that exists, and whether it interacts with the outside world.

| Tool | Reads only | Can change or replace | Interacts with the outside world |
| - | - | - | - |
| `get_profile`, `get_account_usage`, `get_widget`, `show_widget`, `list_widgets`, `list_widget_versions`, `list_widget_data`, `get_widget_data`, `get_widget_customization_options`, `get_embed_code`, `list_media_library`, `suggest_widgets`, `get_brand_kit` | yes | no | no |
| `create_widget` | no | no (it adds a widget, and a first publish replaces nothing) | yes (the finished widget is published and can be reached on the public internet; it also takes the files you attach and reads the Figma designs you link, with your connected Figma account) |
| `replicate_widget` | no | no (it adds no widget and replaces nothing) | no (it only looks up a copy held in Widgetic's own store; nothing is published and no address is opened) |
| `create_widget_batch` | no | no (it adds widgets, and a first publish replaces nothing) | yes (the finished widgets are published and can be reached on the public internet; it uses images already in your media library and fetches nothing) |
| `revise_widget` | no | yes (the finished revision is published again and replaces what embeds show; every earlier version is kept) | yes (it publishes, takes the files you attach and reads the Figma designs you link, with your connected Figma account) |
| `duplicate_composition` | no | no (it adds a copy) | no |
| `cancel_widget_creation`, `cancel_widget_batch`, `update_widget_customization` | no | yes | no |
| `rename_widget` | no | no (it only changes the name) | no |
| `delete_widget` | no | yes (it removes the widget for good) | no |
| `publish_widget` | no | yes (it replaces what embeds show) | yes (it makes the widget publicly reachable) |
| `unpublish_widget` | no | yes (it takes the widget offline: embeds stop showing it; nothing is deleted and `publish_widget` brings it back) | yes (it changes what embeds on the public internet show) |
| `save_to_media_library` | no | no | yes (it fetches the links you give) |
| `manage_media_library` | no | no (it changes a file's name or folder and returns what each was; the file's address does not change) | no |
| `delete_media_file` | no | yes (it removes the file for good) | no |
| `list_workflows`, `get_workflow_options`, `get_workflow`, `test_workflow` | yes | no | no |
| `update_brand_kit` | no | no (it changes your saved colors, fonts, corner radius and style notes; what each was is returned, no widget is rebuilt and nothing leaves your account) | no |
| `draft_workflow_from_widgets` | no | no (it adds a draft workflow and changes nothing that exists; what visitors see is not touched) | no |
| `save_workflow` | no | yes (it replaces the draft; what visitors see is not touched, and a change made elsewhere since the revision the assistant read is never overwritten) | no |
| `publish_workflow` | no | yes (it replaces the version visitors get; every earlier version is kept) | yes (it makes the workflow what embeds on the public internet show) |
| `set_workflow_state` | no | yes (it changes what visitors get; nothing is deleted and each change can be undone) | yes (it changes what embeds on the public internet show) |
| `list_ab_tests`, `get_ab_test_options`, `get_ab_test`, `list_translations`, `get_translation_options`, `get_translation` | yes | no | no |
| `save_ab_test` | no | yes (it replaces the draft; what visitors see is not touched) | no |
| `set_ab_test_state` | no | yes (it changes what visitors get on pages that carry the test's embed code; stopping cannot be undone) | yes (it changes what embeds on the public internet show) |
| `create_translation`, `add_translation_languages` | no | no (they add language copies; what visitors see is not touched until the translation is activated) | no |
| `set_translation_state` | no | yes (it changes what visitors get on pages that carry the translation's embed code; nothing is deleted and each action can be undone) | yes (it changes what embeds on the public internet show) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.