get_styleguide_rules
Fetches style guide rules from your Ditto workspace, including both workspace-level and project-specific rules. Use this to ensure AI-generated UI text follows your team’s content guidelines. To create and manage style guide rules in Ditto, see How to use Ditto’s AI content systems.search_ditto_text
Searches your Ditto workspace for existing text items and/or library components by content. Use this to find and reuse strings that already exist in your team’s content, rather than generating new text.list_projects
Lists all projects in your workspace with their names and developer IDs. Use this to find a project’s developer ID when you only know its name — for example, before creating, updating, or searching text items.list_project_folders
Lists all project folders in the workspace with their developer IDs, names, and parent folder (by developer ID; no parent means the folder sits directly under the workspace root). Use this to find a folder’s developer ID beforecreate_ditto_project, which takes a folderId to create the project inside a folder. Folders are a separate namespace from projects — list_projects will not surface them.
create_ditto_project
Creates a new project in the workspace. Projects hold project-scoped text items, as opposed to library components which are reusable across projects. Use the returned developer ID (orlist_projects) to reference it afterward, for example with create_text_items.
list_component_folders
Lists all folders in your component library with their names, developer IDs, and parent folder (by developer ID; no parent means the folder sits directly under the library root). Use this to find a folder’s developer ID before filing a component into it withcreate_library_components or update_library_components, or before managing the folders themselves with create_component_folders, update_component_folders, and delete_component_folders. Folders are a separate namespace from projects — list_projects will not surface them.
create_component_folders
Creates new folders in the component library. Each folder can optionally specify a developer ID (must be unique in the workspace) and a parent folder to nest inside — omit the parent to create the folder at the library root. Batch calls are all-or-nothing: if any folder in the call fails (e.g. a duplicate developer ID), none of the folders are created.update_component_folders
Updates existing folders by their developer IDs. Only the fields you provide are changed. SetparentId to move a folder — provide null or "root" to move it to the library root, or omit to leave it in place. To rename a folder’s developer ID, set newDeveloperId.
Batch calls are all-or-nothing: if any update in the call fails (e.g. a duplicate developer ID, or a move that would create a circular hierarchy), none of the updates are applied.
delete_component_folders
Permanently deletes folders from the component library by their developer IDs. This cannot be undone. Components and subfolders inside a deleted folder are not deleted — they’re moved up into the deleted folder’s parent folder (or the library root).list_project_blocks
Lists the blocks in a Ditto project with their developer IDs and names, in display order. Blocks group text items within a project. Use this to find a block’s developer ID beforeupdate_project_blocks or delete_project_blocks. If you only know the project’s name, call list_projects to look up its developer ID.
create_project_blocks
Creates new blocks in a Ditto project. Blocks group text items within a project. New blocks are appended to the end of the project. Use the returned developer IDs (orlist_project_blocks) to reference them afterward.
update_project_blocks
Updates existing blocks in a Ditto project by their developer IDs (find them withlist_project_blocks). Only the fields you provide are changed. To rename a block’s developer ID, set newDeveloperId — it can be combined with a name change in the same update object.
Batch calls are all-or-nothing: if any update fails (e.g. a duplicate developer ID within the project), none of the updates in the call are applied.
delete_project_blocks
Permanently deletes blocks from a Ditto project by their developer IDs (find them withlist_project_blocks). This cannot be undone. Text items in a deleted block are not deleted — they’re unassigned and moved to the end of the project’s root level.
list_variables
Lists all variables in the workspace with their developer IDs, types, and data. Use this to find a variable’s developer ID (its name) before referencing it increate_text_items or update_text_items — list the id in the variables field and reference it as a {{variable_name}} placeholder in the text.
create_variables
Creates variables in the workspace. A variable is a reusable placeholder that resolves to a different value at runtime. Each has a type that determines what it holds: astring or number variable holds an example and an optional fallback, a hyperlink holds link text and a url, a list holds the set of values the variable can take, and a map holds key-value pairs. A variable’s name doubles as its developer ID: letters, numbers, and underscores only, and unique in the workspace. Creating a variable adds it to no text on its own — reference it from create_text_items or update_text_items by listing it in the variables field and writing it as a {{variable_name}} placeholder in the text.
Batch calls are all-or-nothing: if any variable in the call fails (for example, a name already in use), none of them are created.
update_variables
Renames variables or changes their type or value. Because a variable’s name is its developer ID, renaming one withnewName changes how it is referenced — but nothing inside Ditto is orphaned, because every {{placeholder}} using it is rewritten to match, across text items, library components, variant text, and plurals. What breaks is outside Ditto: anything naming the old id, such as code, an integration config, or CLI output, along with later API and MCP calls. Use list_variables to find a variable’s current developer ID.
Only the fields you provide are changed, and each update must change at least one of newName, type, or data. Changing a type requires sending data alongside it, even when the value itself stays the same. How data is applied depends on the type: string, number, and hyperlink variables have fixed fields, so sending only some of them leaves the rest alone — send an empty string to clear one. A list’s value is an array and a map’s is an object, and each is the variable’s entire content, so what you send replaces it outright.
Batch calls are all-or-nothing: if any update in the call is invalid, none of the updates are applied.
delete_variables
Permanently deletes variables from the workspace by their developer IDs (their names). This cannot be undone. A variable cannot be deleted while any text item or library component still references it, and one such variable rejects the whole batch — remove the{{placeholder}} from that text first, then retry. Confirm the developer IDs with the user before calling.
list_variants
Lists all variants in the workspace with their developer IDs, names, descriptions, and locale codes. Use this to find a variant’s developer ID when you only know its name — for example, beforecreate_text_items or update_text_items, which take variant developer IDs to set variant-specific text. When translating text for a variant, treat its localeCode (e.g. es, fr-ca) as the authoritative target locale — do not infer the locale from the variant’s name or description. If a variant’s localeCode is null, it is not locale-scoped; confirm the intended locale with the user rather than guessing.
create_variants
Creates variants in the workspace. A variant is a named alternative that text items and library components can each have their own text for — most often a locale to translate into, but also a tone or brand variation. Creating a variant adds no text on its own: usecreate_text_items or update_text_items with the variant’s developer ID to set a text item’s text for that variant. Set localeCode whenever the variant represents a language, because translation tools treat it as the authoritative target locale rather than inferring one from the name; at most one variant per workspace can hold a given locale code. A developer ID is generated from the name unless you pass one explicitly, so read the developer IDs off the response rather than assuming them.
update_variants
Renames variants or changes their description, locale code, or developer ID. A variant’s name and its developer ID are independent. The name is the human-readable label shown in Ditto; the developer ID is the stable key that code, integrations, and CLI output use to refer to the variant. Renaming a variant leaves its developer ID untouched, so anything already referencing it keeps resolving — set newDeveloperId only when you want that key itself to change. Nothing inside Ditto is orphaned or rewritten by either change: text items and library components reference a variant by an internal id rather than its developer ID, so each keeps its text for the variant, and variant-scoped style guides stay attached. What breaks is outside Ditto — anything naming the old developer ID, such as CLI output, an integration config, or code, along with later API and MCP calls, which have to use the new one. Uselist_variants to find a variant’s current developer ID. At most one variant per workspace can hold a given locale code. Changing a locale code reaches past the variant itself: variant-scoped style guides and AI translation targeting both resolve a locale to a variant, so moving a locale onto a different variant changes which style guide governs that locale’s text and where translated text is suggested. The whole batch is rejected if any update is invalid.
delete_variants
Permanently deletes variants from the workspace by their developer IDs. This cannot be undone. A variant cannot be deleted while any text item or library component still has text for it, and one such variant rejects the whole batch — remove that text first, then retry. Style guides scoped to a deleted variant survive but stop being variant-scoped.create_text_items
Creates new text items in a project. Provide the project’s developer ID and the items to add. Each item supports text, an optional developer ID, status, tags, assignee (by email), notes, a character limit, a development-integration flag, and plural forms. Usesearch_ditto_text first to check whether equivalent text already exists to reuse.
Batch calls are all-or-nothing: if any item in the call fails (e.g. a duplicate developer ID), none of the items are created.
update_text_items
Updates existing text items by their developer IDs. Only the fields you provide are changed; the rest are left as-is. Supports text, status, tags, assignee, notes, character limit, the development-integration flag, and plural updates. Tags are replaced wholesale — pass the full desired set. Batch calls are all-or-nothing: if any update in the call fails, none of the updates are applied.delete_text_items
Permanently deletes text items by their developer IDs. This cannot be undone, and text items that are library instances cannot be deleted.create_library_components
Creates new components in the Ditto component library. Library components are reusable text shared across projects, as opposed to project-scoped text items. Each component supports a name, text, an optional developer ID, folder, status, tags, assignee (by email), notes, a character limit, a development-integration flag, and plural forms. Usesearch_ditto_text first to check whether equivalent text already exists to reuse.
Batch calls are all-or-nothing: if any component in the call fails (e.g. a duplicate developer ID), none of the components are created.
update_library_components
Updates existing library components by their developer IDs. Only the fields you provide are changed; the rest are left as-is. Supports text, folder, status, tags, assignee, notes, character limit, the development-integration flag, and plural updates. Tags are replaced wholesale — pass the full desired set. Batch calls are all-or-nothing: if any update in the call fails, none of the updates are applied.create_styleguide
Create a new style guide (name, description, sections, whether it’s enabled by default). Sections organize rules and word list entries; if omitted, a default set of sections is used. If you provide sections, each section ID must be unique and the list must include at least one rules section and one word list section. Returns the new style guide’s developer ID. PassvariantId to scope the style guide to a single variant — because a locale in Ditto is a variant’s locale code, this is how a style guide is associated with a locale. The variant must have a locale code — for now, style guides can only be scoped to variants that have one.
list_styleguides
Lists all style guides in the workspace with their developer IDs, descriptions, sections, and rules. Use this to find a style guide’s developer ID and section IDs before callingcreate_styleguide_rules or update_styleguide.
update_styleguide
Update an existing style guide by developer ID (any field: name, description, enabled by default, variant, sections). Only the fields you provide are changed. Pass developer IDdefault to toggle the built-in Ditto Style Guide’s enabled-by-default setting.
Pass variantId to scope the style guide to a single variant — because a locale in Ditto is a variant’s locale code, this is how a style guide is associated with a locale — or null to unscope it so it applies to all text. The variant must have a locale code — for now, style guides can only be scoped to variants that have one.
Updating sections replaces the full list — each section ID must be unique, and the list must include at least one rules section and one word list section — rules in a removed section move automatically to the first remaining rules section.
create_styleguide_rules
Create one or more rules in a style guide section. Use the{name, description, examples, tags} shape for a ‘rules’ section, or the {term, disallowed, description, tags} shape for a ‘wordlist’ section — the shape must match the target section’s kind. Batch calls are all-or-nothing: if any rule fails, none are created.
update_styleguide_rules
Update one or more existing rules by ID (fromget_styleguide_rules or create_styleguide_rules). Only the fields you provide are changed. Use name/examples for a rule in a ‘rules’ section, or term/disallowed for a rule in a ‘wordlist’ section — the shape must match that rule’s own section. Batch calls are all-or-nothing: if any update fails, none are applied.
delete_styleguide_rules
Permanently delete one or more rules by ID. This cannot be undone. Batch calls are all-or-nothing: if any rule ID doesn’t exist, none are deleted.suggest_edit
Checks text against your Ditto workspace’s style guide rules and returns suggested edits — the same rule-based suggestions shown in the Ditto app. Check an existing text item by its developer ID, or check freeform text that isn’t saved as a text item yet. Results are cached per exact input; passforceNewGeneration to force a fresh check.
An empty result means the text already complies with the style guide, or that this exact suggestion was already reviewed and dismissed in the app.