Lucid

Add a new block (shape) to a Lucid document. DISCOVERY: Use lucid_shape_library to find valid block_type values for the target document, and lucid_shape_details to fetch a shape's default size, colors, and text-area names before calling this tool. Hallucinated class names produce 400 errors. Args: document_id: UUID of the document to modify block_type: Block class name. Examples: StickiesStickyNoteBlock, TextBlock, SparkFrameBlock, LucidCardBlock, RectangleBlock, ShapeDiamondBlock, ShapeCircleBlock x: X coordinate position (default 0) y: Y coordinate position (default 0) text: Text content for the block text_areas: Named text-area content updates, as a non-empty list of {"key": str, "text": str}. Use this for shapes with multiple text areas. Mutually exclusive with text. width: Block width in pixels height: Block height in pixels fill_color: Fill color in #RRGGBB format line_color: Border color in #RRGGBB format line_width: Border width stroke_style: Border style — one of "solid", "dashed", "dotted", "dashdot", "dashdotdot", "dashed24", "dashed32", "dashed44", "dashlongdash", "dotdotdot", "longdash" rotation: Rotation in degrees text_align: Horizontal text alignment — "left", "center", or "right" text_v_align: Vertical text alignment — "top", "middle", or "bottom" container_id: Item ID of a container block to place this block inside page_id: Page ID to add the block to (defaults to first page if omitted) bold: Whether to make the text bold italic: Whether to make the text italic underline: Whether to underline the text font_size: Font size in points (e.g. 14) text_color: Text color in #RRGGBB format strike: Whether to strikethrough the text superscript: Whether to make the text superscript subscript: Whether to make the text subscript font_family: Font family name (e.g. "Arial"); canvas falls back if unknown highlight_color: Text highlight color in #RRGGBB format link: Hyperlink to attach to the block. Accepts the same inputs the canvas "Link to" field accepts: an http(s) or ftp URL, a bare domain like "www.example.com" (auto-prefixed with http://), or the API-only forms "mailto:<email>" and "page://<pageId>". The page id form references a page in the same document. auto_font_size: Toggles Lucid's auto-fit-to-shape font sizing on the new block. True enables it (text resizes to fit the shape); False disables it (text keeps an explicit point size); omitted uses the block class's default. Providing a concrete font_size automatically disables auto-font-size, so callers do not need to also pass auto_font_size=False alongside a font_size. Mutually exclusive with a non-null font_size when set to True. Returns: JSON with success status and new itemId Example: Add a blue sticky note with bold text at position (200, 150): lucid_add_block( document_id="8fb1756d-d7f1-4f8c-933a-40e30fa5d102", block_type="StickiesStickyNoteBlock", x=200, y=150, text="Hello world", fill_color="#FFD700", bold=True, )

lucid_add_block

Add a dynamic table to a Lucid document. Dynamic tables organize items into rows and columns and can be used for matrices, grids, kanban-style boards, planning tables, and prioritization maps. The table is created empty; add shapes/cards separately after the table exists. Args: document_id: UUID of the document to modify x: X coordinate position for the table's top-left placement (default 0) y: Y coordinate position for the table's top-left placement (default 0) rows: Optional row labels. If omitted, the canvas creates default rows. columns: Optional column labels. If omitted, the canvas creates default columns. page_id: Page ID to add the table to (defaults to first page if omitted) Returns: JSON with success status and generatorId for the new dynamic table Example: Create a simple priority matrix: lucid_add_dynamic_table( document_id="8fb1756d-d7f1-4f8c-933a-40e30fa5d102", x=100, y=100, rows=["High impact", "Low impact"], columns=["Low effort", "High effort"], )

lucid_add_dynamic_table

Add existing canvas blocks to a dynamic table. The generator's grouping logic places each block in the correct row/column based on its pivot-field value. Blocks whose pivot field does not match any row/column label land in the table's default cell. Args: document_id: UUID of the document containing the dynamic table generator_id: ID of the dynamic table generator (use the fetch tool to get the generator ID from the document) block_ids: IDs of existing blocks on the canvas to add to the table Returns: JSON with success status, number of blocks added, and an optional error message if some or all blocks could not be added.

lucid_add_items_to_dynamic_table

Add a new line to a Lucid document, connecting two points or shapes. Each endpoint is either: - A position endpoint: provide endpoint_x and endpoint_y (absolute canvas coords). - A shape endpoint: provide endpoint_shape_id. STRONGLY PREFER setting endpoint_auto_link=True for shape endpoints — the canvas will attach the line to the best side of the shape based on the line's direction and will re-route automatically as the shape is moved or resized. This is almost always the right choice when connecting two shapes and removes the need to reason about which side the line should enter from. Only set endpoint_position_x/y (a 0–1 relative coordinate on the shape) when you need a specific attachment point on the shape — for example when the user explicitly requests "connect to the top of the box" or when the line must terminate at a fixed anchor. If you do set explicit positions, avoid the default center (0.5, 0.5) because the line will overlap text inside the shape; pick a side instead (e.g. position_x=0, position_y=0.5 for the left edge). Use the fetch tool to get shape IDs from the document. Args: document_id: UUID of the document to modify endpoint1_x: X coordinate of the line's start point endpoint1_y: Y coordinate of the line's start point endpoint1_shape_id: Item ID of the shape to connect the start to endpoint1_position_x: Relative X position on start shape (0=left, 1=right, default 0.5) endpoint1_position_y: Relative Y position on start shape (0=top, 1=bottom, default 0.5) endpoint2_x: X coordinate of the line's end point endpoint2_y: Y coordinate of the line's end point endpoint2_shape_id: Item ID of the shape to connect the end to endpoint2_position_x: Relative X position on end shape (default 0.5) endpoint2_position_y: Relative Y position on end shape (default 0.5) line_color: Line color in #RRGGBB format line_width: Line width in pixels stroke_style: Line style — one of "solid", "dashed", "dotted", "dashdot", "dashdotdot", "dashed24", "dashed32", "dashed44", "dashlongdash", "dotdotdot", "longdash" text: Label text on the line page_id: Page ID to add the line to (defaults to first page if omitted) line_shape: Line routing — exactly one of "elbow" (right-angle), "diagonal" (straight), "curve" (smooth Bezier), or "cyclical" (loop). Omit to let the canvas pick its default routing. Set explicitly to "elbow" to force right-angle even when the canvas would default elsewhere. When the user says "curved" or "smooth" → "curve"; "straight" or "direct" → "diagonal"; "right angle" or "orthogonal" → "elbow"; "loop" → "cyclical". endpoint1_style: Arrow/terminator at the start. Case-sensitive. Examples: "None", "Arrow", "Hollow Arrow", "Open Arrow", "Diamond", "Circle One". Read resource lucid://endpoint-styles for the full list (UML, BPMN, ERD). endpoint2_style: Arrow/terminator at the end (same allowed values). endpoint1_auto_link: Only applies when endpoint1 connects to a shape. STRONGLY PREFERRED when connecting to a shape: set to True and the canvas picks the optimal side of the shape for the line to attach to and automatically re-routes when the shape moves or resizes. Overrides endpoint1_position_x/y when True. Leave False/unset only when you need to pin the endpoint to a specific spot on the shape. endpoint2_auto_link: Same as endpoint1_auto_link, for the end endpoint. Strongly preferred when endpoint2 connects to a shape. bold: Whether to make the label text bold italic: Whether to italicize the label text underline: Whether to underline the label text font_size: Label font size in points (e.g. 14) text_color: Label text color in #RRGGBB format strike: Whether to strikethrough the label text superscript: Whether to make the label text superscript subscript: Whether to make the label text subscript font_family: Label font family name (e.g. "Arial"); canvas falls back if unknown highlight_color: Label highlight color in #RRGGBB format Returns: JSON with success status and new itemId Example: Connect two shapes with a curved red arrow and a bold label: lucid_add_line( document_id="8fb1756d-d7f1-4f8c-933a-40e30fa5d102", endpoint1_shape_id="kydGSpnbx.C4", endpoint1_auto_link=True, endpoint2_shape_id="mydGB1ri3RCq", endpoint2_auto_link=True, line_shape="curve", line_color="#FF0000", endpoint2_style="Arrow", text="connects to", bold=True, )

lucid_add_line

Discover shapes/blocks available to INSERT into a Lucid document. This does NOT find documents or text inside a document. To find a document by name follow the `lucid://skills/readme` resource; to find text within one open document use `lucid_search_document`. Only use this tool when the user wants a shape to add to a diagram. Use this tool to find valid block class names before calling lucid_add_block or lucid_edit_item on an existing document; hallucinating class names will produce 400 errors and this tool returns the canonical list. Note: this requires a document_id and operates on an existing document, so it cannot pre-validate class names for lucid_create_diagram_from_specification (which creates a new document) — for that flow, use the lucid://skills/diagram-specification resource as the canonical shape reference. Modes (all driven by the same call): - No params: lists every visible shape library by id and name. - libraryId only: lists groups (folders) within that library, with shapes inlined when the library has a single group. - libraryId + groupIds: returns the shapes within the specified groups. - searchTerm: searches across libraries (or within libraryId if also provided) and returns matching shapes. Cannot be combined with groupIds. The no-param library listing is paginated: when the response includes a NextPageToken, pass it back as page_token to fetch the next page of libraries. After narrowing to a candidate shape, call lucid_shape_details with its className to get default size/colors and any custom properties before passing it to add/create tools. Args: document_id: UUID of the document context (libraries available depend on product and the user's allow-listed libraries). search_term: Optional free-text query against shape names and keywords. library_id: Optional library identifier from a previous response. group_ids: Optional list of group identifiers within library_id; only valid when library_id is also provided (groups belong to a specific library). page_token: Optional pagination cursor; pass the NextPageToken from a previous no-param listing response to fetch the next page of libraries. Returns: JSON string from the underlying tool (success/result envelope).

lucid_shape_library

Convert existing SVG source into an editable Lucid diagram. If SVG source is available, pass it verbatim. Do not redraw, simplify, optimize, or repair it first. The converter handles common flowchart shapes, text, simple filled paths, decorative curves, groups, basic CSS, symbols, and translate/rotate/scale transforms. It approximates gradients and may omit complex paths, patterns, masks, filters, or skew. Partial conversion warnings are returned with the document link. Args: title: The title for the new document. svg: Original SVG markup (max 256KB). product: "lucidchart" or "lucidspark" (default: "lucidchart").

lucid_convert_svg_to_diagram

Creates a Lucid document containing a data-backed Entity Relationship Diagram (ERD). Use this tool when the user wants to create an ERD / database schema diagram from a set of entities (tables) and the foreign-key relationships between them. If the user provides raw SQL DDL, a CSV schema, or a Salesforce export, convert it into the structured `entities` / `relationships` form. The result is a real, editable ERD: each entity becomes an editable entity table and each relationship becomes a crow's-foot foreign-key line between the foreign key column and the column it references. The schema is stored as ERD data on the document, not as loose shapes. Before calling, check that every relationship the user described has a foreign key column on the referencing entity and a matching entry in `relationships`. When a table is split out to hold many rows per parent (e.g. a customer's address history), it needs a foreign key back to that parent, even if other tables also reference it. Example entities: [ {"id": "user", "name": "User", "attributes": [ {"name": "id", "type": "uuid NOT NULL", "key": "PK"}, {"name": "email", "type": "varchar NOT NULL"} ]}, {"id": "post", "name": "Post", "attributes": [ {"name": "id", "type": "uuid NOT NULL", "key": "PK"}, {"name": "author_id", "type": "uuid NOT NULL"} ]} ] Example relationships: [ {"from": "post", "fromAttribute": "author_id", "to": "user", "toAttribute": "id", "fromCardinality": "zeroOrMore", "toCardinality": "exactlyOne", "label": "written by"} ] Returns: JSON with the created document details including document ID and edit URL

lucid_create_erd

Import records from a third-party integration as linked cards. You MUST call `lucid_list_integrations` first to obtain `instance_id` — it is the exact `instanceId` field returned for the desired integration instance, not a free-form string, and cannot be guessed from context. The import backend checks the user's Jira credentials. Args: document_id: UUID of the Lucid document to add cards to. integration_id: Which integration the records live in. Today only "jira" is supported. instance_id: The `instanceId` field from a `lucid_list_integrations` entry, identifying which instance of `integration_id` to pull records from. Must come from `lucid_list_integrations`; do not construct it. record_keys: Integration-specific identifiers for the records to import (e.g. Jira issue keys like ["MCP-1", "MCP-2"]). page_id: Page to drop the cards on (defaults to the first page). x: Top-left x coordinate of the first card. Defaults to 0. y: Top-left y coordinate of the first card. Defaults to 0. layout: One of "grid", "row", "column". Defaults to "grid". If the requested instance is not listed or Jira authorization is unavailable during import, returns `{status: "not_connected", connect_url, ...}` — send the user to `connect_url` (their Lucid Apps & Integrations page) to connect. Do NOT attempt to authenticate on their behalf. Returns: JSON with `{success, blockIds, dataSourceId, errors}` on success, or a structured `{status: "not_connected" | "unsupported_integration", ...}` response when Jira access needs attention. `errors` is a list of `{recordKey, error}` entries for keys that could not be imported or whose AddBlock op failed; this tool returns partial success when only some keys fail.

lucid_import_integration_cards

Creates a Lucid document from existing Mermaid code at the user's request. STOP. Read this ENTIRE description before calling. The rules below are load-bearing — skipping them produces broken documents or wastes the user's tokens. Re-read on every call; don't rely on memory. Use this tool with Mermaid source code already present in the conversation or a user-provided file, including previously shared assistant-generated Mermaid that the user now wants to import. When the user asks to create, render, visualize, or share a diagram from that code, use this tool. The user does not need to explicitly name Lucid or request a conversion. Do not generate Mermaid solely as an intermediate step to call this tool. When the user requests a diagram without asking for Mermaid or a diagram from existing Mermaid source code, prefer creating the diagram directly in Lucid using lucid_create_diagram_from_specification over generating Mermaid code in the conversation. Follow that tool's prerequisites and intent rules. If the user explicitly requests Mermaid source code as the output, honor that request; you should then offer to import it into Lucid. If the user asks only to explain, review, or debug Mermaid code, answer that request without creating a document unless they also ask to see the diagram. For sequence diagrams, use lucid_create_sequence_diagram. For ERDs, use lucid_create_erd. Args: title: The title for the new document. mermaid_markup: Mermaid source code the user wants to import (must contain a valid Mermaid diagram). product: Target product - "lucidchart" or "lucidspark". Defaults to "lucidchart".

lucid_create_diagram_from_mermaid

Creates a Lucid document using the Standard Import format (.lucid file). When the user requests a diagram without explicitly asking for Mermaid or a diagram from existing Mermaid source code, prefer creating the diagram directly in Lucid over generating Mermaid code in the conversation. The user does not need to explicitly name Lucid. If the user explicitly requests Mermaid source code as the output, honor that request; you should then offer to import it into Lucid. Do not generate Mermaid solely as an intermediate step to call lucid_create_diagram_from_mermaid. Follow the prerequisites and intent rules below when creating a Lucid document. PREFLIGHT HARD GATE: - If SVG source exists, pass it unchanged to lucid_convert_svg_to_diagram. Do not hand-author Standard Import JSON from it. - If Mermaid source code already exists in the conversation or a user-provided file and the user asks to create, render, visualize, or share a diagram from it, use lucid_create_diagram_from_mermaid instead (or lucid_create_sequence_diagram for sequence diagrams and lucid_create_erd for ERDs). The user does not need to explicitly name Lucid or request a conversion. - If this tool description appears truncated, summarized, quoted, or incomplete, first try to retrieve, expand, or read the full tool definition before deciding whether to call this tool. - If the full tool definition cannot be retrieved, use the most complete visible description available, but do not treat missing, hidden, summarized, or truncated text as permission to ignore any visible MUST, REQUIREMENT, HARD GATE, or PREREQUISITE instruction. - Read: lucid://skills/diagram-specification - Reading lucid://skills/diagram-specification is required before every call to this tool. - Do not call this tool until all visible hard prerequisites have been satisfied. - Do not call this tool until any available fuller tool-definition text has been read. AUTHORITY MODEL: - The full, untruncated tool description is authoritative for WHEN to call this tool when it is available, including intent classification, collaborative planning behavior, source/input dependency handling, clarification behavior, default generation behavior, and prerequisite handling. - If the full tool description cannot be retrieved, the most complete visible description is authoritative, but visible requirements remain binding and missing text must not be interpreted as permission to proceed. - The resource at lucid://skills/diagram-specification is authoritative for HOW to construct the standard_import_json argument. - Do not duplicate, infer, or guess the Standard Import JSON format from this tool description. Read and follow lucid://skills/diagram-specification for supported shapes, line syntax, container behavior, assisted layout rules, validation constraints, and all other formatting requirements. - Reading the referenced resource satisfies formatting/specification prerequisites. It does not replace the tool description's behavioral rules about when to call the tool, when to plan collaboratively, when to check for missing source/input dependencies, or when to ask clarifying questions. EXECUTION ORDER: A. Honor visible hard prerequisites. B. If the visible tool description appears truncated or incomplete, try to retrieve, expand, or read the full tool definition. C. If the full tool definition cannot be retrieved, continue only with the most complete visible description available and keep all visible MUST/REQUIREMENT/HARD GATE/PREREQUISITE instructions binding. D. Read all required referenced resources, including lucid://skills/diagram-specification. E. Use the full available tool description, or the most complete visible description if the full definition cannot be retrieved, to decide WHEN to call the tool. F. Classify the user's intent. G. Apply intent precedence: collaborative planning beats default generation. H. Apply the source/input dependency gate. If required referenced source content is missing or inaccessible, ask for it and do not generate. I. If generation is appropriate, construct and validate standard_import_json using lucid://skills/diagram-specification. J. Call the tool. SOURCE / INPUT DEPENDENCY GATE: Before generating, check whether the requested diagram depends on external, user-provided, uploaded, attached, linked, selected, or previously referenced content. A request depends on referenced source content when the user asks for a diagram based on content such as: - "my file" - "the file" - "the uploaded file" - "the attached document" - "this PDF" - "this spreadsheet" - "this image" - "this screenshot" - "the link" - "this URL" - "the document I mentioned" - "the data" - "the dataset" - "the spec" - "the text above" - "the previous diagram" - "the selected content" If the referenced source content is not actually available in the conversation, tool context, connected source, or provided arguments, do NOT generate a substitute, generic, or placeholder diagram. Ask exactly one short question requesting the missing source or clarifying what content to use. If the referenced source content is available, inspect or use that content before generating, unless another higher-priority rule requires collaborative planning or clarification first. This gate takes precedence over ordinary generation. A missing referenced source means the request is not an ordinary request, even if a plausible diagram type can be inferred. Do not confuse missing referenced content with ordinary subject matter. For example, "Create a diagram about a file upload workflow" is an ordinary generation request because "file upload workflow" is the subject, not a missing referenced file. Examples: - User: "Create a diagram about my file." No file is available. Correct: ask the user to upload or link the file. - User: "Make a flowchart from the attached PDF." No PDF is available. Correct: ask for the PDF. - User: "Create a diagram from this spreadsheet." A spreadsheet is available. Correct: inspect/use the spreadsheet, then generate if appropriate. - User: "Create a diagram about a file upload workflow." Correct: generate, because the user named the workflow as the subject. INTENT PRECEDENCE: Before generating, classify the user's request. Collaborative planning mode has precedence over default generation. Enter collaborative planning mode when the user explicitly asks the assistant to help with the planning, brainstorming, design, thinking, mapping, or iteration process before or while creating the diagram. Trigger collaborative planning mode for phrases such as: - "help me plan..." - "help me design..." - "help me brainstorm..." - "help me think through..." - "help me work through..." - "help me map out..." - "help me iterate..." - "let's plan..." - "let's design..." - "let's brainstorm..." - "let's map out..." - "let's iterate..." - "work with me to..." - "before you generate..." - "before creating..." In collaborative planning mode: 1. Do NOT create the diagram immediately. 2. Ask focused planning questions about the diagram type, subject, key elements, audience, level of detail, and desired output. 3. Propose a concise draft diagram spec or outline for confirmation. 4. Generate only after the user confirms, provides enough direction, or asks you to proceed. Do NOT enter collaborative planning mode merely because the diagram topic contains planning-related, brainstorming-related, design-related, or mapping-related words. Bare content phrases such as "planning diagram," "project plan," "roadmap," "brainstorming board," "design flow," "map out the process," or "process map" can be ordinary generation requests if the user is asking for a diagram about that subject rather than asking the assistant to collaborate on the planning process. ORDINARY REQUESTS: An ordinary request is a request where the user primarily asks to create, make, generate, build, or draw a diagram and provides enough information to identify: 1. a plausible diagram type, 2. a concrete or reasonably inferable subject, and 3. any referenced source content needed to create the requested diagram is available. A request is not ordinary if it depends on missing referenced content such as an unuploaded file, missing attachment, unavailable link, absent data, inaccessible selected content, or unavailable prior context. For ordinary requests, generate the diagram immediately using sensible defaults. Do NOT ask clarifying questions for ordinary requests, because users expect this tool to produce a diagram, not start a planning conversation. Examples of ordinary requests: - "Create a flowchart with Start, Decision, and End connected by arrows." - "Build a BPMN process with a start event and parallel tasks." - "Create a project planning flowchart." - "Make a mind map for a marketing launch plan." - "Create a diagram that maps out our onboarding process." - "Generate a simple architecture diagram for a web app." - "Create a roadmap diagram for Q3 planning." - "Create a diagram about a file upload workflow." Examples that require collaborative planning first: - "Create a diagram and help me plan." - "Help me plan a project flowchart." - "Let's map out the onboarding process before creating the diagram." - "Work with me to design the architecture diagram." - "Before you generate, help me think through the process." Examples that require missing source/input clarification first: - "Create a diagram about my file." when no file is available. - "Make a flowchart from the attached PDF." when no PDF is attached. - "Create a diagram from this spreadsheet." when no spreadsheet is available. - "Generate a process map based on the link." when no link is provided or accessible. CLARIFICATION: Ask exactly ONE short clarifying question, then generate, if any of the following are true: 1. The request is internally contradictory, such as "create a sequence diagram of our org structure." 2. The request is so abstract that no reasonable default exists, such as "make me a diagram," meaning you cannot name both a concrete subject and a plausible diagram type. 3. Required referenced source content is missing or inaccessible, such as an unuploaded file, missing attachment, unavailable link, absent data, inaccessible selected content, or unavailable prior context. 4. Two defensible interpretations would produce substantively different diagrams and the user signaled they care about correctness with words such as "important," "for a presentation," "get it right," or similar. Otherwise, generate now and state your assumptions in one line alongside the result so the user can redirect. Example: "Generated as a flowchart with 5 stages; say 'change' to adjust." TOOL OUTPUT: This tool creates a .lucid ZIP file containing a document.json built from standard_import_json. This tool runs the checks in lucid://skills/diagram-specification over your JSON before it creates anything, and treats their two kinds of finding differently. Structural findings - a missing required field (including an image stroke nested under style), a value outside an enum, a duplicate id, an endpoint pointing at a shape that is not on the page, a relative position pinned on only one endpoint, a malformed color - describe JSON the importer rejects. The tool reports those instead of creating a document, naming the page, the item, and the field, because the API answers such a request with a bare 400 that names nothing. Fix what it lists and call the tool again. Layout findings - text that renders small, shapes that collide, connectors that cross unrelated shapes, labels that land on something - describe a document that imports and looks wrong. Those never block creation. They come back in a bounded "input_preflight" report on the response, whose "truncated" and "skipped_checks" fields say whether the report is incomplete. When use_assisted_layout is true the report covers only what survives import - text fit, colors, and structure - because assisted layout replaces the coordinates you supplied; the position checks (shape clearance, containment, connector paths, label placement) run only when use_assisted_layout is false. To see every check against the JSON you wrote, including the position checks, call lucid_validate_diagram_specification. Do not attempt to guess the Standard Import JSON format. The API validates strictly. Invalid or unsupported JSON can cause import failure. Use lucid://skills/diagram-specification as the source of truth for all Standard Import JSON formatting, validation, layout, and supported-shape details. SHAPE NAMES: Standard Import requires canonical class names, so guessing them will fail validation. Use lucid://skills/diagram-specification and its shape-library resources for supported shapes and their class names. Args: title: The title for the new document. standard_import_json: JSON string in Lucid Standard Import format. Construct this according to lucid://skills/diagram-specification. product: Target product, either "lucidchart" or "lucidspark". Unauthenticated creation only supports "lucidchart"; sign in to create a Lucidspark board. use_assisted_layout: Auto-arranges shapes after import when true by default. See lucid://skills/diagram-specification for when to set this true or false. Size Limits: - Final document.json must be smaller than 2 MiB (2,097,152 UTF-8 bytes). - The response reports submitted and final byte sizes plus inline image URL contributions.

lucid_create_diagram_from_specification