Tool search 164,478 tools · 10,067 live servers

Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), parse_mode: classic markdown/html/auto (entities) or rich (Rich Message document; dialect auto-detected). parse_mode=rich cannot be combined with files. File attachments as http(s) URLs, local paths, or data: URIs. When files are provided, the message text becomes a caption. For channel posts with reply_to_id, automatically posts in the linked discussion group. Success: dict with message_id, date, chat, text, status='sent', and sender info (rich messages also set rich=true and rich_format). Error: dict with ok=false and error string. Use send_message to create new messages; use edit_message to modify existing ones. Use send_message_to_phone when targeting a phone number instead of a chat_id. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Load profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

Send to a phone number: may create a temporary contact, then send text or files. Supports parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). parse_mode=rich cannot be combined with files. Success: send result plus contact_was_new / contact_removed when applicable. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md

List all profiles. Profiles group multiple social accounts together for easier management.

Get details of a specific profile including name, description, and color.

Create a new profile for grouping social accounts.

Update an existing profile. Only provided fields will be changed.

Delete a profile. The profile must have no connected accounts.

Create a social media post. Can be saved as DRAFT, SCHEDULED, or PUBLISHED immediately. ⚠️ IMPORTANT - Choose the correct mode based on user intent: **DRAFT MODE (is_draft=True)** Use when user says: "draft", "borrador", "save for later", "don't publish", "save it", "guardar" → Post is saved but NOT published and NOT scheduled. User can edit it later. **IMMEDIATE MODE (publish_now=True)** Use when user says: "publish now", "post now", "publica ya", "immediately", "right now", "ahora" → Post goes live IMMEDIATELY. **SCHEDULED MODE (default)** Use when user says: "schedule", "programar", "in X minutes/hours", "at 3pm", "tomorrow" → Post is scheduled for future publication. Use schedule_minutes to set the delay. ⚠️ MULTI-ACCOUNT USERS (agencies, multi-client setups): If the user has more than one account on the target platform, you MUST pass `account_id`. Call `accounts_list` (or `profiles_list` then `accounts_list`) first to discover the right ID. If you omit account_id when multiple accounts exist, the tool returns an error listing the candidates - use it to retry. Examples: - "Create a draft tweet" → is_draft=True - "Post this to Twitter now" → publish_now=True - "Schedule a LinkedIn post for 2 hours from now" → schedule_minutes=120 - "Post this to Acme's Twitter" → call accounts_list, find Acme's twitter ID, pass account_id

Get your data in. Pass `data` as an array of row objects to create the dataset immediately and get a dataset_ref ready for create_analysis; omit it to get an upload link for a file only the user can reach.

Attach a TikTok account by logging in ON THE SERVER, into that account's own persistent browser profile: returns a connect_url to hand a human, who scans the QR in the TikTok app. The recommended path — the browser that authenticates is the browser that later acts, and every other TikTok tool then works with `cookies` omitted (no jar to move). The paying wallet becomes the account's owner. Async: poll tiktok_connect_status with the returned token. Costs 0.01 USDC, paid per-action via x402.

List the TikTok accounts the paying wallet owns, with session health (status, profile_present, hours_since_success, last_error_code) — i.e. which of your accounts are still logged in. Costs 0.001 USDC, paid per-action via x402.

Fetch a tweet or a user from one reference. A tweet URL (incl. handle-less /i/status/<id>) returns the tweet with full thread context, parent, and optional replies/quotes; a profile URL (https://x.com/<handle>) returns the user with recent tweets. Prefer full URLs - if you only have a numeric id, pass it as a quoted string. Returns a compact human-readable view by default; pass format='json' for full structured data.

Fetch a Reddit post, subreddit, or user by ref. Posts return comments; subreddits and users return profile metadata plus recent activity.

Fetch a single web page and extract clean content. Auto-tier server-side: handles SSR (Next.js, Nuxt, TikTok, Pinterest, YouTube), SPA shells, PDFs, paywall detection, residential-proxy escalation, and stealth profiles for TikTok / Instagram / Pinterest / YouTube. Returns clean markdown (default) with a YAML frontmatter header (url, outcome, total_chars). Read 'outcome' to classify the result (success | teaser | thin_content | paywall | bot_challenge | consent_wall | login_wall | rate_limited | timeout | transient_upstream | unsupported_target | not_found | error). Large pages (>80k chars) are truncated inline with truncated_chars + a download_full_url to the complete extraction (expires ~1h). Permanently unsupported (outcome=unsupported_target, cost=0 upstream): Bluesky search, Instagram post/reel and tag/explore pages (profiles work), Pinterest search, g2.com, Truth Social, Xiaohongshu. Threads and Instagram profile pages ARE supported.

Search GitHub repositories, conversations (issues+PRs), discussions, or code, with full GitHub search syntax in the query: qualifiers (repo:, org:/user:, language:, path:, symbol:, content:, is:, stars:, label:, sort:stars), boolean AND/OR/NOT with parentheses, "exact strings", and /regex/. kind='repos': MINIMAL distinctive keywords - the project/library name only ('rtk', 'react query'); every extra word must ALL match and buries the canonical repo - filter with qualifiers, not prose. kind='code': ONE literal code pattern as it appears in files ('useState('), an "exact string", a /regex/, or symbol:name to find definitions, across 2.8M+ public repos; narrow with repo:/language:/path:. Not supported in code search: license:, enterprise:, is:vendored, is:generated. kind='conversations': returns compact previews - use glim_github_get for full content; sort: REPLACES relevance ranking (words match anywhere incl. comments), omit it for best matches. kind='discussions': GitHub Discussions, a SEPARATE index from issues/PRs - a question answered there never appears under conversations, so reach for it when a repo does its Q&A in Discussions; supports repo:/org:/author:/is:answered plus category: (the repo's own category name, needs a repo: scope), up to 10 results per page, no sort:. Set repo='owner/name' to scope to one repository (works with any kind; with repos it routes to conversations). kind is optional - inferred from the query (is:answered/category: -> discussions, is:/label: -> conversations, path:/symbol://regex/ -> code, stars:/topic: -> repos, else repos); a conversations search with no matches is retried as discussions and says so. Returns compact text by default; pass format='json' for full structured data.

Fetch GitHub data from a single ref. GitHub URL or 'owner/repo' shorthand. A repo URL or owner/repo returns metadata + README; /pull/N -> PR (with comments + changed files), /issues/N -> issue, /discussions/N -> discussion (with threaded replies), /blob/<ref>/<path> -> file (raw.githubusercontent.com URLs work too), /tree/<ref>[/<path>] -> file tree (optionally scoped to a subdirectory), /commit/<sha> -> one commit with diff, /commits[/<ref>/<path>] -> history (optionally for one file), /branches, /releases (or /releases/tag/<tag> | /releases/latest -> one release), /topics/<name> -> top repos with that topic (by stars).

Detect AI-generated text. Scores any text for AI-authorship likelihood and returns an overall verdict (AI / human / mixed) with confidence, the AI/human/AI-assisted fractions, and a segment-by-segment breakdown showing exactly which parts read as AI-written - including per-segment humanizer flags (AI output run through paraphrasing/'humanizer' tools). Use it to verify whether content (comments, articles, profiles) is AI-generated, or to check text before publishing to see which segments would trip AI detectors - revise the flagged segments and re-check. Cost scales with text length: $0.06 per 100 words, rounded up, minimum $0.06. Max input 20,000 characters.

Submits exactly ONE respondent-visible question in an existing Study. Applicability: one standalone question, or one adaptive follow-up whose wording could not be known before earlier results. Exclusion: never use this operation for a questionnaire, survey, battery, section, cohesive question set, or any request containing two or more known questions—even when every question targets the same Study. The complete known set belongs in one planned and confirmed multi-question block inside the Study and must be submitted once, not question by question. Follow-up questions remain within the existing Study; this operation does not create or enumerate Studies. The full question value may reach respondents and is not planner-only metadata. Scale, categorical, and qualitative questions are classified automatically, and the response includes status and workspace links. Automatic classification may reformulate the question; this operation does not promise verbatim wording. Locked respondent wording and response formats require a reviewed and confirmed Study plan. The question is classified before it is queued, so the returned status is authoritative: queued or running means it was submitted to respondents, while planning_required means it was declined as an unrefined research objective and nothing was submitted. A planning_required response carries the original request plus a proposed headline and respondent questions for study planning. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset.

Generates a branded profile for one existing Mind, identified by exact ID or fuzzy name. Markdown is returned inline by default; PDF, DOCX, and PPTX artifacts are returned as base64 with a workspace link.

Supports operationId-only requests to read a previously accepted preview or creation job and retrieve its result without creating another Audience. Creates a grounded Audience of synthetic Minds from a population or audience brief. It can combine authoritative web research, supplied sources, research files, and reviewed spreadsheet distributions; persists provenance and allocation audits; supports balanced, segment-coverage, and benchmark-depth sizing; generates the same member portraits and Audience cover as in-app creation; can individually train every member of a large reviewed-dataset cohort in the background (trainMembers); is idempotent for identical inputs; and keeps the Audience private unless link sharing is enabled.

Submits exactly one respondent-visible standalone question to one existing Audience, identified by exact ID or fuzzy name. It creates a private Study for that Audience, starts asynchronous responses from its Minds, and returns the Study identifier and links. Automatic classification may reformulate the question; this operation does not promise verbatim wording. Locked respondent wording and response formats require a reviewed and confirmed Study plan. Never use this operation for a questionnaire, battery, section, cohesive question set, or any request with two or more known questions; create a Study and plan the complete multi-question block instead. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset.

Creates or revises a non-executing draft for a multi-question plan inside an existing Study. Applicability: this is the setup operation for every questionnaire, survey, battery, section, cohesive question set, or request containing two or more known questions—even when the user did not say “study.” Include every question known now in this ONE draft, group related questions into cohesive named modules (question blocks or batteries), preserve their logical order, and execute them later as one confirmed run inside the Study. Never split a known set across one-question drafts or sequential runs. A one-question draft is valid only for genuinely standalone research; an adaptive follow-up whose wording depends on unavailable results can be planned later. The draft records intent, respondent-visible stimulus and questions, response formats, locale, method, outputs, confirmation questions, execution source policy, and revision metadata. Its source policy is part of the exact revision the user reviews; omitted means the controlled request_only default, while auto is an explicit experiment opt-in. It does not start research. When the user supplies a fixed or pre-registered instrument whose wording, order, and response formats must not change, pass it as questions (one entry per item with its exact response contract) instead of request; the planner is then bypassed and the draft is an exact transcription. Explicit response contracts remain authoritative during execution, including with attachments: categoricalOptions retain their labels and order rather than being replaced by inferred A/B file labels. MCP cannot read or upload a local file:// path. Use a fetchable HTTP(S) URL, a signed URL supplied by the client for the attached file, or an existing Minds workspace upload URL/path. Study tools import external file URLs into durable Minds storage before saving or running. The Study refuses to start if Minds cannot read the asset.

Executes the exact stored multi-question draft revision inside the target Study after explicit confirmation. One execution submits the ENTIRE draft—all named modules and all questions—as one durable run. Never execute each known question separately and never create one run per module. This operation is valid only after the person explicitly confirms the exact draft revision. The server reloads and validates the revision, method availability, runner configuration, reviewed capabilities, optional advanced-method consent, and idempotency key before queuing durable research. MCP cannot upload or read a local file:// path: attach the file through the client and use its signed HTTPS URL, upload it to Minds first, or use another fetchable HTTPS URL. Before invoking any Mind or using Study quota, the server verifies that required respondent-visible source material is readable and refuses the entire run if it is not.

Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links. Permission: workspace:read. API reference: https://mailrith.com/developers/api-reference.

Updates profile fields, status, custom fields, tags, or sequence assignments for one subscriber. Fields omitted from the request stay unchanged. Blank optional custom field values also leave saved values unchanged, and filled-in invalid values are rejected. Effect: subscriber-change. Retry after reading the current resource state. Permission: subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Changes the delivery status for one Subscriber without changing profile, targeting, or Sequence enrollment fields. Making a Subscriber Active requires consent_evidence; its collected_at value must include the correct UTC offset and must not be later than Mailrith's server time. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Put a website live at a public URL. Use this when the user wants to publish, launch, or get a page online — e.g. 'I need a website', 'put up a page for my business', 'make this live'. Takes static files (HTML, CSS, JS, images) and returns a working URL anyone can open. No build step, no config. First call: omit site_id and edit_token — you get back a url, a site_id, and an edit_token. Keep the edit_token; it's the only way to change this site later. Later calls: pass site_id + edit_token to publish over the same site. deploy REPLACES the whole site — any file you leave out is DELETED. To change just one or a few files, use update_site_file instead. To see what's currently live before editing, use get_site_files first.

Read the files of a site you already published, so you can make a targeted edit instead of rebuilding the whole site from memory. Returns a complete manifest (every file's path, size, content-type, sha256) plus the contents of the text files (HTML/CSS/JS/etc). Also returns the site's current `version` — pass it back to update_site_file so you don't overwrite a newer change. Pass `paths` to fetch only specific files; omit it to get all text files. Requires site_id + edit_token.

Change one or a few files of an already-published site, leaving every other file untouched (a merge — unlike deploy, which replaces the whole site). Ideal for small edits: fix a typo in index.html, swap a stylesheet, add one page. Best practice: call get_site_files first, edit the returned content, then call this with the files you changed and the `expected_version` from that read — if the site changed in the meantime you get a clear conflict telling you to re-read. Requires site_id + edit_token. Cannot delete files (use deploy to drop a file) and cannot remove index.html.

"Tell me about X" / "research Acme" / "brief me on Tesla" / "what does Apple do" / "company profile for Microsoft" / "give me the rundown on NVDA" / "everything you know about $TICKER" — full cross-source profile of a US public company in ONE parallel call. ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. Fans out across SEC EDGAR, XBRL, USPTO patents, federal contracts (USAspending), FDA-licensed biologics (Purple Book), H-1B hiring (DOL LCA), news and GLEIF, and returns: cik + company_name (+ resolved_from/resolved_to when `value` was a name); recent_filings (up to 5 with pipeworx://edgar/company/{cik}/filings/{accession} URIs); fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC); patents (USPTO PatentsView API sunset May 2025 — soft-fails until reactivated); federal_contracts (USAspending awards where the company is the recipient); fda_products (FDA-licensed biologics — vaccines, cell/gene therapies — from the Purple Book; a company with only small-molecule/generic drugs will show none here, that is expected, not a failure); hiring (H-1B sponsorship volume + salary range from DOL LCA filings); recent news mentions via GDELT→GNews fallback; LEI via GLEIF. `sources_used` / `sources_failed` say which of these actually returned data for THIS company — an empty section is a real "no data", not a bug. Pass a ticker ("AAPL"), zero-padded CIK ("0000320193"), OR a company name ("Moderna") — names now resolve via SEC EDGAR's company-name match; a private company (no CIK/ticker) returns resolved:false with an explicit `notes` line, not a bare failure. `type` accepts "company" or "ticker" interchangeably — both take the same `value` shapes above.

"What's new with X" / "latest on Y" / "what happened to Z this week / month / quarter" / "updates on Acme" / "news on Tesla recently" / "what's happening with Apple" — change feed for a company in the last N days/weeks/months in ONE parallel call. Fans out to SEC EDGAR (filings since `since`), GDELT→GNews fallback (news mentions in window — GDELT preferred, GNews when rate-limited or 5xx), USPTO (patents granted; PatentsView API sunset May 2025 so this soft-fails until reactivated). `since` accepts ISO date ("2026-04-01") or relative shorthand ("7d", "30d", "3m", "1y"). Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs. Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.

What can I ask Pipeworx? / what is Pipeworx good for? / what can you do? / give me ideas / show me examples / getting started / what data do you have? — the onboarding entry point for an agent that just connected and wants to know what is worth asking. Returns category-bucketed example questions (company financials, drugs & clinical trials, economics, real estate, prediction markets, weather, government & patents, science & academia, news) — each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools. Call with no arguments for the full spread, or pass `topic` (e.g. "finance", "pharma", "betting") to focus. Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).

Generate a production-ready llms.txt file for any URL so AI crawlers (ChatGPT, Claude, Perplexity) can index the site cleanly. Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt. Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.

Tell the Pipeworx team something is broken, missing, or needs to exist. Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise). ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server in your client (another vendor's Gmail, Splunk, Slack, etc. connector), we cannot fix it and reporting it here only delays you; file it with that server instead. Not sure? Pipeworx tool names are the ones this connection lists. Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt. Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed. The team reads digests daily and signal directly affects roadmap. Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.

Give your agent a free identity at <handle>.domani.run - a live profile page, no domain purchase, instantly. The frictionless way to start; upgrade to your own real domain later. Optional name/bio/emoji/email/links.

Place a backorder on a domain that is currently registered to someone else. We watch it and automatically register it for the user when it becomes available (drops) - availability is polled every few minutes. The user is charged only if the catch succeeds - no upfront fee. Requires a card on file or payment_method 'balance'. Confirm the domain with the user first. Best-effort: a contested drop may be taken by a specialized drop-catcher first.

Use this when you need to look up a Twitter/X user profile by username or URL. Returns structured profile data including bio, follower/following counts, tweet count, verification status, and recent activity. 1. username: the @handle 2. displayName: full name 3. bio: profile description text 4. followers: follower count 5. following: following count 6. tweetCount: total tweets posted 7. verified: blue checkmark status 8. createdAt: account creation date 9. avatarUrl: profile picture URL 10. bannerUrl: header image URL 11. location: stated location 12. website: linked URL 13. pinnedTweet: text of pinned tweet if any Example output: { "username": "elonmusk", "displayName": "Elon Musk", "bio": "...", "followers": 195000000, "following": 850, "tweetCount": 45000, "verified": true, "createdAt": "2009-06-02" } Use this FOR social media due diligence, influencer research, competitor monitoring, or verifying the legitimacy of an account before trusting its content. Do NOT use for tweet search -- use twitter_search_tweets instead. Do NOT use for trust/security scoring -- use trust_score_evaluate instead. Do NOT use for email lookup from social -- use email_find_by_name instead.

Use this when you need to find tweets about a topic, brand, event, or keyword. Returns up to 20 recent tweets matching the query with full text, engagement metrics, author info, and timestamps. 1. query: the search term used 2. results: array of tweet objects 3. Each tweet contains: id, text, author (username + displayName), createdAt, likes, retweets, replies, views, url 4. resultCount: number of tweets found Example output: { "query": "x402 protocol", "resultCount": 15, "results": [{ "id": "1234567890", "text": "x402 is the future of agent payments...", "author": { "username": "web3dev", "displayName": "Web3 Dev" }, "likes": 42, "retweets": 12, "replies": 5, "views": 1200, "createdAt": "2026-04-13T09:30:00Z" }] } Use this FOR market sentiment analysis, brand monitoring, competitor tracking, news discovery, trend detection, or finding what people say about a topic in real-time. Do NOT use for profile data -- use twitter_scrape_profile instead. Do NOT use for web search (non-Twitter) -- use web_search_query instead. Do NOT use for sentiment analysis of text -- use text_analyze_sentiment instead. Do NOT use for crypto news -- use crypto_get_news instead.

Use this when you need to see what a specific Twitter/X user has been posting recently. Returns their latest tweets with full text, engagement metrics, and timestamps. 1. username: the @handle queried 2. tweets: array of tweet objects with id, text, createdAt, likes, retweets, replies, views, isRetweet, isReply 3. tweetCount: number of tweets returned Example output: { "username": "VitalikButerin", "tweetCount": 10, "tweets": [{ "id": "...", "text": "Excited about the new EIP proposal...", "likes": 5200, "retweets": 890, "views": 250000, "createdAt": "2026-04-12T14:00:00Z", "isRetweet": false }] } Use this FOR monitoring specific accounts, tracking influencer activity, analyzing posting patterns, or gathering content from thought leaders. Do NOT use for profile bio/stats -- use twitter_scrape_profile instead. Do NOT use for topic search -- use twitter_search_tweets instead. Do NOT use for social profile lookup across platforms -- use social_lookup_profile instead.

Provision sending infrastructure: buy branded lookalike domains, create mailboxes, start warmup. New mailboxes are ramp-limited server-side — 5 sends/day in week 1, rising to 40/day after 4 weeks — and your own calls cannot exceed that cap; poll infrastructure_status for the current dailyCap. Inputs: brand, primaryDomain, domains + inboxesEach counts, persona, physicalAddress, senderIdentity. Billing is per-provisioned-mailbox ($10/mailbox + $49 platform, min 5) and the billed quantity follows what you provision here — pass quoteOnly:true first to preview the new count + projected monthly price before committing (no silent capacity addition). Every response carries a `billing` projection { provisionedAfter (the live count AFTER this call — reality, not the ask), projectedMonthlyCents, formula }: on quoteOnly it's the preview, on an actual provision it's the real post-provision bill (a capacity-limited partial reflects only what landed). Returns { jobId, billing } — `jobId` is a correlation id only, not a trackable job handle: there is no job store and no endpoint that accepts it, so do not poll for it or treat its presence as meaningful; it exists to correlate this response with logs. A `provisioning` field is present ONLY when the call returned still OWING work, and names which state: 'pending' (a domain's DNS registration is still completing — `pendingDomain` names one of them) or 'capacity_pending' (held at a spend/plan-slot limit, so polling will NOT progress until an operator raises it — call contact_operator instead of waiting). Its ABSENCE is what says the provision finished; the only way to find out is to re-call setup_infrastructure or read infrastructure_status's `nextSteps`. An outcome carrying `provisioning`, and a quoteOnly preview, are deliberately NOT recorded against your idempotencyKey — retrying with the same key re-runs the call and finishes the job rather than replaying the unfinished answer. `domains` and `inboxesEach` are the infrastructure you want to HAVE, not an amount to add: each call keeps and resumes what this account already has and buys only the shortfall, so to provision MORE you ask for a LARGER number (domains:2 after a call that provisioned one buys the second; raising inboxesEach tops each domain up). Repeating a call therefore never buys twice, whatever you do with idempotencyKey — resend it, change it, or omit it. The key controls response replay only and has no bearing on what is purchased, so a retry is always safe. A domain this account already registered but that never landed in your account (a prior call that failed after the purchase) is ADOPTED on the retry at zero extra cost rather than bought again. A domain whose DNS setup has not finished yet is recorded and never lost — there is no per-domain DNS field to poll (infrastructure_status reports a domain count, not per-domain detail), so read its `nextSteps` for what to do next, and repeat this same call to converge on the domain and finish its DNS setup. Slot semantics: `domains: N` covers ordinals 0..N-1, and each ordinal fills to its own mailbox count (uniform via `inboxesEach`, or per-ordinal via `distribution` — see below); a repeat call at the SAME `domains` provisions nothing new once every ordinal is satisfied, so reaching ordinal 1 needs `domains:2`, not a second `domains:1` call. Mailbox addresses are DETERMINISTIC — derived from `persona` + ordinal + slot — so keep `persona` EXACTLY as it was on a resume or retry; changing it mid-account does not move existing addresses but does change what a NEW ordinal derives. `distribution` (optional, alternative to `inboxesEach`) names the per-ordinal mailbox count directly — one entry per domain ordinal, e.g. `[3, 2]` for 3 mailboxes on domain 0 and 2 on domain 1 — for a shape `inboxesEach`'s single uniform number cannot express; supply exactly one of the two (an array with `domains` entries, or the uniform count). `registerDomains` is this tenant's opt-in consent to real domain purchases made on the platform's own account (our COGS — your bill is unchanged, mailbox-count-based only); only the operator's own global switch being armed too can ever actually enable it. OMITTING it leaves any consent you previously gave UNCHANGED — pass `false` explicitly to revoke it. A call that omits `registerDomains` (or sends it `false`) on a buy-bearing request (one that needs to purchase a new domain) is refused BEFORE any spend. Once this account has consented at least once, that refusal is a 400 `registrar_optin_missing`: 'registerDomains was not set on this request' — resend the identical call with it set to true to self-correct; this is never an operator escalation. (An account that has never consented, on a platform where domain registration is not yet enabled at all, instead sees the operator-facing 503 `registrar_unarmed` — indistinguishable from the outside except by status code, but the fix is the same: set `registerDomains: true` and retry.) Separately, a `registerDomains:true` call with NO `registrant` anywhere (neither in this request nor persisted from a prior one) fails with a 400 `incomplete_registrant` naming the missing fields — also before any purchase. Fresh candidates are de-duplicated against what this account already owns and checked for availability; if a call needs to buy a domain and no available un-owned candidate exists it fails with a 400 naming that, never a silent repeat purchase (a call that needs to buy nothing is unaffected). `registrant` (a full registrant-of-record object { firstName, lastName, email, phone, addressLine1, city, state, country, postalCode, organization (optional, defaults to brand) }) is OPTIONAL even when `registerDomains` is true whenever a complete registrant is already on file from a prior call — supplying one makes it authoritative for THIS call; omitting it re-uses the persisted one. This platform never invents a domain registrant's legal identity, so a call with no registrant anywhere (neither supplied nor persisted) is rejected naming the missing fields, at or before the actual purchase — never silently. There is NO background retry: a call returning `provisioning` needs the caller to retry it; the platform does not complete it for you on a timer. Every response carries `nextSteps` (see the discriminated `status`/`steps` shape) — the account's own next action, computed fresh each time, so a stalled setup is never silent.

Reach a human operator — for anything list_messages/infrastructure_status can't answer (a stuck vendor issue, a billing question, an account-level ask). Inputs: body (1-2000 chars), urgency ('normal' | 'needs_human', default 'normal'). Files a support ticket and notifies the operator; returns { ticketId, note, deduplicated }. Works in every account state a tenant token still authenticates in, including dunning-suspended, canceling and canceled — this is exactly the channel for 'why is my account suspended?'. The ONE exception is an admin-TERMINATED (abuse) account, whose token is rejected at auth with 401 before this tool runs. The operator's reply arrives as a message on THIS account (poll list_messages / infrastructure_status.messages[] — there is no separate reply-fetch call). Sending the IDENTICAL body AND urgency again within an hour returns the SAME ticketId and does not file a second ticket or send a second alert (`deduplicated: true` on that response; `false` when a new ticket was actually filed) — no separate idempotency key is needed to retry a dropped response. This is a TEXT match, not an intent match: the platform cannot tell a deliberate retry from a coincidentally-identical NEW message, so a genuinely new ask with the same wording collapses into the earlier ticket just as silently — vary the wording (or raise urgency, which is always treated as an escalation and files a new ticket) if you have something new to say. 'needs_human' also bypasses the ~10-minute ops-email throttle so an urgent message is pushed immediately. Rate-limited to 5 calls/hour per tenant — a 429 names retryAfter (seconds) when hit.

The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/<slug> link that opens without login.

Preferred media path when you can HTTP PUT. Returns a presigned URL. PUT the file bytes to that URL, then pass the returned public url into create_post. If your runtime cannot reach the storage host (common in ChatGPT), call upload_media instead.

Fallback when you cannot PUT to the presigned URL from get_media_upload_url. Pass a ChatGPT file in file, or a public https sourceUrl. SocialRobot fetches the bytes and stores them, then returns the permanent url for create_post. Prefer get_media_upload_url when you can PUT. Max 50MB.

Create one scheduled item that can publish to one or more connected social accounts. For TikTok targets, set postMode to DIRECT_POST (profile publish; privacyLevel required from tiktok_get_creator_info) or UPLOAD (inbox draft finished in the TikTok app). For X and Threads targets, pass an ordered segments array to publish a thread: segment captions/medias are posted as replies chaining from the root post.

Return the bot's own user profile (id, username, discriminator, avatar, etc).

Public profile of any Discord user by id. Bulk support: accepts user_ids for batched execution.

The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/<slug> link that opens without login.

getAccountSummary: Get a comprehensive summary of the user's account: profile, balance, domain count, VPS count, and pending transfers. Requires authentication.

getMyProfile: Get the authenticated user's profile and account information including name, email, organization, balance, and domain/VPS counts. Requires authentication.

osirAppGetSource: Get a short-lived signed download URL for an Osir app's current source zip. Use this to make edits to a deployed app without the user re-attaching the project: download, patch the files, then osirAppCreateUpload (PUT the new zip) and osirAppDeploy under the SAME name; the platform rebuilds and, for owned-tier apps, auto-ships the new version to the user's box. Requires authentication.

osirSitePublish: Publish a single-page website to a live HTTPS URL on Osir (free tier). ANY complete HTML document works: the user's own site, a page designed in this chat, or one from the osirSiteDesignBrief flow. Calling again with the same name redeploys the new version. For MULTI-FILE sites (separate CSS/JS/images) use osirAppCreateUpload + osirAppDeploy with a zip instead. Then poll osirAppStatus until READY. Requires authentication.

Adds a source to a project and fetches it immediately (bounded by a few seconds), returning `storiesAdded` so the next generate_content can use it; if it is still fetching it returns `fetched:false` with a note. Doubles as manual source import: paste any URL (RSS/Atom feed, article, or a page, profile, or post on a supported platform) and leave `type` as autodetect, or create a recurring keyword search by setting `value` to the search terms and `type` to a search kind (see `type`).

Who you are and what you are allowed to do. Returns the account, the channels connected right now, the credit balance, and, when an agent is calling, ITS OWN limits: which profiles and networks it may post to, its daily cap, how many posts it has already made today and how many remain. Call this first: it is how you plan work you can actually complete, instead of finding the boundary by being refused. Limits are set by the account owner in the dashboard and cannot be changed from here.

Change a connected account's own profile: display name, bio, avatar or banner. Only the fields you give are changed; the rest are left alone. Images are given as public URLs and uploaded for you. A network that does not allow this refuses and says so.

Prepare or upload media so it can be attached to posts. For a public asset, pass `url` and PostLake fetches it. For a file on the agent's own machine, omit `url`, pass `contentType` and preferably `sizeBytes`, then PUT the file bytes to the short-lived upload target returned by this tool. Both paths validate type/size (images ≤20MB: jpeg/png/webp/gif; videos ≤200MB: mp4/mov/webm) and produce a med_… id for create_post. Never put file bytes or base64 in the tool call.

Create a profile: a named set of connected channels, usually one brand or client. Give the name as a person would write it, spaces and capitals included; it is slugified into the identifier you then pass as `profile` on other calls, and the response tells you what that became. Create one before connecting channels when an account is running more than one brand.

Rename a profile. The channels and posts inside it are untouched, but the identifier is re-derived from the new name, so anything holding the old `profile` string stops resolving. The response says whether the identifier actually moved, so you only have to update references when it did.

Delete a profile. This ALSO disconnects every channel in it, and reconnecting each one needs its owner to approve access on that network again, which you cannot do for them. So it refuses by default while channels are attached and tells you exactly which ones would go. Only pass force after a human has agreed to lose them.

Get detailed profile for a specific member/account by ID.

Update CRM account/customer profile fields such as name, phone, email, life stage, owner, notes, or member code.

Append one or more blocks to the end of a post. Each block must be a valid block object: { id, version, type, data }. Types: paragraph, heading, image, list, quote, code, divider, spacer, embed, html, youtube, file, faq, callout, gallery, cta, accordion, product.

Read the text/Markdown content of a file attached to a Workroom thread or sent by a customer (PDF, image, or document). Extracts on first read and caches the result. Returns status "ready" with markdown, or "skipped"/"failed"/"not_found" with a reason. Use when a message references an attachment you need to read.

Send a WhatsApp message (text or media). Actions: - text: { to, text, reply_to? } - media: { to, type ('image'|'video'|'audio'|'document'|'sticker'), media_url | media_base64, caption?, filename?, mimetype? } `to` accepts either a JID ('5511999999999@s.whatsapp.net', '<id>@g.us') or a plain phone (digits, country code included). For groups always use the '<id>@g.us' JID — get it from whatsapp_groups. [Flattened action: text]

Send a WhatsApp message (text or media). Actions: - text: { to, text, reply_to? } - media: { to, type ('image'|'video'|'audio'|'document'|'sticker'), media_url | media_base64, caption?, filename?, mimetype? } `to` accepts either a JID ('5511999999999@s.whatsapp.net', '<id>@g.us') or a plain phone (digits, country code included). For groups always use the '<id>@g.us' JID — get it from whatsapp_groups. [Flattened action: media]

The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/<slug> link that opens without login.

Use this when you need public profile data from a social media handle or URL. Returns structured profile data in JSON. Returns: 1. displayName and bio 2. avatarUrl 3. followerCount and followingCount 4. postCount 5. location and website 6. createdAt (account creation date) 7. isVerified (boolean) 8. platform. Example output: {"platform":"github","handle":"torvalds","displayName":"Linus Torvalds","bio":"Linux kernel developer","avatarUrl":"https://avatars.githubusercontent.com/u/1024025","followerCount":213000,"followingCount":0,"postCount":729,"location":"Portland, OR","isVerified":true} Use this FOR influencer research, lead enrichment, social listening, building contact profiles, and verifying social media presence. Do NOT use for email lookup -- use email_find_by_name instead. Do NOT use for company data -- use company_enrich_from_domain instead. Do NOT use for person enrichment by email -- use person_enrich_from_email instead.

Use this when you need public profile data from a social media handle or URL. Returns structured profile data in JSON. Returns: 1. displayName and bio 2. avatarUrl 3. followerCount and followingCount 4. postCount 5. location and website 6. createdAt (account creation date) 7. isVerified (boolean) 8. platform. Example output: {"platform":"github","handle":"torvalds","displayName":"Linus Torvalds","bio":"Linux kernel developer","avatarUrl":"https://avatars.githubusercontent.com/u/1024025","followerCount":213000,"followingCount":0,"postCount":729,"location":"Portland, OR","isVerified":true} Use this FOR influencer research, lead enrichment, social listening, building contact profiles, and verifying social media presence. Do NOT use for email lookup -- use email_find_by_name instead. Do NOT use for company data -- use company_enrich_from_domain instead. Do NOT use for person enrichment by email -- use person_enrich_from_email instead.

"Tell me about X" / "research Acme" / "brief me on Tesla" / "what does Apple do" / "company profile for Microsoft" / "give me the rundown on NVDA" / "everything you know about $TICKER" — full cross-source profile of a US public company in ONE parallel call. ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. Fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF and returns: cik + company_name; recent_filings (up to 5 with pipeworx://edgar/company/{cik}/filings/{accession} URIs); fundamentals (LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC); patents (USPTO PatentsView API sunset May 2025 — soft-fails until reactivated); recent news mentions via GDELT→GNews fallback; LEI via GLEIF. Pass ticker "AAPL" or zero-padded CIK "0000320193" — names not supported (use resolve_entity first if you only have a name).

"What's new with X" / "latest on Y" / "what happened to Z this week / month / quarter" / "updates on Acme" / "news on Tesla recently" / "what's happening with Apple" — change feed for a company in the last N days/weeks/months in ONE parallel call. Fans out to SEC EDGAR (filings since `since`), GDELT→GNews fallback (news mentions in window — GDELT preferred, GNews when rate-limited or 5xx), USPTO (patents granted; PatentsView API sunset May 2025 so this soft-fails until reactivated). `since` accepts ISO date ("2026-04-01") or relative shorthand ("7d", "30d", "3m", "1y"). Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs. Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.

What can I ask Pipeworx? / what is Pipeworx good for? / what can you do? / give me ideas / show me examples / getting started / what data do you have? — the onboarding entry point for an agent that just connected and wants to know what is worth asking. Returns category-bucketed example questions (company financials, drugs & clinical trials, economics, real estate, prediction markets, weather, government & patents, science & academia, news) — each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools. Call with no arguments for the full spread, or pass `topic` (e.g. "finance", "pharma", "betting") to focus. Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).

Generate a production-ready llms.txt file for any URL so AI crawlers (ChatGPT, Claude, Perplexity) can index the site cleanly. Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. Output is a single text blob ready to drop at site-root/llms.txt. Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.

Tell the Pipeworx team something is broken, missing, or needs to exist. Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise). ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server in your client (another vendor's Gmail, Splunk, Slack, etc. connector), we cannot fix it and reporting it here only delays you; file it with that server instead. Not sure? Pipeworx tool names are the ones this connection lists. Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt. Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed. The team reads digests daily and signal directly affects roadmap. Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.

Browse users: top posters leaderboard, user profile, follow/unfollow. Follow/unfollow require API key.

Goal-driven autonomous planning: set goals, get AI-suggested goals based on agent profile, track progress, and manage goal execution. Requires API key.

Get the authenticated Famulor user profile, including total balance.

Add a website (URL-scraped) document to a knowledge base. File uploads (pdf/txt/docx) must use the Famulor dashboard or a direct multipart/form-data call.

Look up WhatsApp's current limits and rules from the site's dated reference table: group and community size, broadcast lists, message and media/file sizes, character counts, forwarding, calls, Channels, linked devices, and WhatsApp Business app and Business API limits. Each value is single-sourced and dated. Returns the limits (optionally filtered to one area), the last-verified date, the source and the CC BY licence. Prefer this over recalling limits from memory. They change over time. Runs locally.

Return the agent profile for the presented API key.

Check whether a path looks safe. No disk access.

Parse a Figma file URL. Path discarded.

Check whether a path looks safe. No disk access.

Parse a Figma file URL. Path discarded.

Search Wedyesday's directory of wedding vendors — venues, photographers, caterers, florists, celebrants and more. Returns real published listings with ratings, price bands and a link to each profile. Use list_wedding_markets first if you are unsure which category or country code to pass.

Get a summary of the couple's Wedyesday guest list: headcount, groups, how many have contact details on file, plus_ones and children. Guests' email addresses and phone numbers are never returned — those stay in the dashboard. Requires a connected Wedyesday account.

Creates and displays an interactive draw.io diagram. Accepts either draw.io XML or Mermaid.js syntax — provide exactly one. **Format decision — this is the first thing to settle before you write anything:** if the diagram type appears on the Mermaid list below, use `mermaid`. Only use `xml` when the diagram type isn't on that list (UI mockups, floorplans, cloud/network/electrical architecture with stencils, hand-placed UML, etc.) or when the user has explicitly asked for draw.io XML. **Use Mermaid** for the following diagram types (all rendered natively, no upstream mermaid runtime): - flowchart / graph (TD, LR, …) - sequenceDiagram - classDiagram - stateDiagram / stateDiagram-v2 - erDiagram - gantt - pie - journey (user-journey) - gitGraph - mindmap - timeline - quadrantChart - xychart-beta - sankey-beta - requirementDiagram - C4Context / C4Container / C4Component - block-beta - architecture-beta - packet-beta - kanban - radar-beta - treemap-beta - treeview-beta (draw.io-specific) - venn (draw.io-specific) — syntax: `venn` then `set A ["Label"]` for each set, `union A,B` for declared overlaps (informational), and `text A` / `text A,B` followed by `["Region label"]` for text inside a region. Do NOT use `A AND B[...]` or `A["..."]` shorthand — those lines are ignored. - ishikawa (draw.io-specific) - zenuml **Strong default: use Mermaid for every diagram type on that list above.** Mermaid is simpler, more reliable, and the native Mermaid layout handles positioning and routing for you. For a flowchart, state diagram, sequence, ER, class, gantt, gitGraph, mindmap, etc. — reach for the `mermaid` parameter, not `xml`. Do not default to XML for flowcharts. **Use XML** when the diagram type isn't on the Mermaid list above OR when the user explicitly asks for XML / draw.io format. Typical cases where XML is the right choice: - **UI mockups / wireframes / screen designs** — buttons, form fields, sidebars, modal dialogs (`shape=mxgraph.bootstrap.*`, `shape=mxgraph.ios.*`, `shape=mxgraph.android.*`) - **Floor plans / seating charts / room layouts** — rooms, doors, furniture (`shape=mxgraph.floorplan.*`) - **Cloud architecture** with AWS / Azure / GCP / Kubernetes icons (`shape=mxgraph.aws4.*`, `shape=mxgraph.azure.*`, `shape=mxgraph.gcp2.*`, `shape=mxgraph.kubernetes.*`) - **Network topology** with Cisco / Rack / networking shapes (`shape=mxgraph.cisco*.*`, `shape=mxgraph.rack.*`, `shape=mxgraph.networking.*`) - **P&ID / electrical / engineering schematics** (`shape=mxgraph.pid2.*`, `shape=mxgraph.electrical.*`, `shape=mxgraph.mscae.*`) - **Swimlanes / pools** with custom colors and hand-placed contents - **UML class / component / deployment diagrams** where positioning carries meaning - **Venn diagrams, quadrant charts, concept maps** with custom regions — anything where hand-placed geometry is the point - **Any diagram requiring specific colors, fonts, stencils, or layouts** that Mermaid can't control precisely Call `search_shapes` first when you need industry icons (AWS / Azure / Cisco / P&ID / Kubernetes / floorplan / mockup / electrical) or brand logos / pictorial concept icons (e.g. 'react', 'slack', 'shopping cart') to find the correct `style` string for each shape. --- **XML reasoning discipline (applies ONLY when you chose XML — skip this whole section if you're using Mermaid):** Your job in XML is declaring logical structure — nodes, edges, labels, groupings. Follow these steps in order: (1) **Decide `postLayout` and `routing` FIRST, before writing any XML.** If the XML diagram is a flowchart, state diagram, decision tree, or any directional/hierarchical process diagram (which you should rarely be writing as XML — prefer Mermaid), you MUST pass `postLayout: "elk"` (add `direction: "horizontal"` when the flow is drawn left-to-right; it defaults to vertical). Omit `postLayout` only when the layout carries hand-crafted meaning (swimlanes, containers, architecture, UML) — the typical reason you chose XML in the first place. When `postLayout` is set, your x/y coordinates only need to express rough direction; ELK re-lays out the vertices. For those hand-placed diagrams where you omit `postLayout`, consider `routing: "libavoid"` — it leaves your positions untouched and only routes the edges around the boxes in clean right angles (set it whenever connectors would otherwise overlap or cut through shapes). Treat `postLayout` and `routing` as alternatives: ELK already routes its own edges, so if you set `postLayout: "elk"` do NOT also set `routing` (redundant); use `routing` only on a hand-placed layout where you are NOT re-laying-out with ELK. (2) Pick ONE concrete scenario on your first impulse and commit — do not pitch alternatives, do not flip-flop between approaches. (3) Use the rigid grid in the XML reference (`x = col*180 + 40`, `y = row*120 + 40`) without computing spacings, canvas dimensions, or overlap checks. (4) Never add `<Array as="points">` waypoints or `exitX/exitY/entryX/entryY` — when postLayout or routing runs it sets them; otherwise drawio's edge router handles it. (5) Do NOT narrate in your reasoning: no "building the diagram", no column enumeration, no coordinate math in prose, no coordinate re-verification after placement. Go straight to XML. **User preference override — XML only.** If the user expresses a preference for draw.io XML over Mermaid in any phrasing (examples: "no mermaid", "skip mermaid", "use xml", "I want drawio format", "stop using mermaid", "give me the xml", "native drawio only", etc.), from that point onward in the conversation you MUST use the `xml` parameter exclusively and MUST NOT use the `mermaid` parameter, even for diagram types where Mermaid would normally be preferable. This preference persists for the remainder of the conversation unless the user clearly reverses it (e.g. "mermaid is fine again"). When the preference is active, translate any diagram request — including flowcharts, sequence diagrams, ER diagrams, etc. — directly to well-formed mxGraphModel XML. When using XML: IMPORTANT — the XML must be well-formed. Do NOT include ANY XML comments (<!-- -->) in the output. # draw.io XML Reference Detailed reference for styles, edge routing, containers, layers, tags, metadata, and dark mode. Consult this when generating draw.io XML diagrams. ## Reasoning budget (read this first) Your job is to declare the **logical structure** of the diagram — what nodes exist, what edges connect them, what labels they carry, what lane/container groups them. draw.io's edge router and (when available) a post-layout pass handle routing and placement; you do **not** need to do layout math. **Do NOT** in your reasoning: - Do NOT debate the topic. The user asked for a flowchart / architecture / sequence / etc. — pick one concrete scenario on your first impulse and commit. Never write "Actually, let me think of something else…" or pitch alternatives. - Do NOT debate flat-lanes vs nested-pools, horizontal vs vertical orientation, one vs multiple variations. Pick the first reasonable option (almost always: flat swimlanes, top-down or left-right based on what fits the content). Do not flip-flop. - Do NOT compute x/y coordinates in prose. No "column spacings of 160px totaling 1840px width — that's too wide, let me tighten to 1700…" loops. Use the rigid grid below; do the arithmetic in your head and write the XML. - Do NOT re-derive drawio mechanics (`horizontal=0`, `startSize=110`, nested-lane coordinates). Use the templates below as-is. - Do NOT enumerate columns ("customer lane columns 0-10, web app 1-7"). Place a node, move on. - Do NOT add `<Array as="points">` waypoints. Edges are routed automatically. - Do NOT set `exitX` / `exitY` / `entryX` / `entryY` connection-point overrides unless you have specific geometric intent. - Do NOT verify, re-check, or adjust coordinates after placing a node. - Do NOT narrate "building the diagram / finalizing the XML / now let me…". Just emit XML. - Do NOT write out lists of node positions as planning text. Emit them as `<mxCell>` elements directly. **Do** in your reasoning: - Identify the diagram type + actors/stages (1-2 short sentences). - Identify any grouping (swimlanes? containers? none?). - Go straight to XML. **Rigid grid — use for every XML diagram:** - Column x = `col_index * 180 + 40` (col 0 = 40, col 1 = 220, col 2 = 400, …) - Row y = `row_index * 120 + 40` (row 0 = 40, row 1 = 160, row 2 = 280, …) - Node size: rectangles `140×60`, diamonds `140×80`, circles `60×60`, documents `120×80`, cylinders `100×70` Pick a `(col, row)` for each node. Don't think about centers, gaps, or overlap — ELK handles routing between rough positions. Slight misalignment is invisible in the result. ## General principles - **Use proper draw.io shapes and connectors** — choose the semantically correct shape for each element (e.g., `shape=cylinder3` for databases and tanks, `rhombus` for decisions, `shape=mxgraph.pid2valves.*` for valves in P&IDs). draw.io has extensive shape libraries; prefer domain-appropriate shapes over generic rectangles. - **Decide whether to search for shapes** — before generating a diagram, decide if it needs domain-specific shapes from draw.io's extended libraries. **Skip `search_shapes`** for standard diagram types that use basic geometric shapes: flowcharts, UML (class, sequence, state, activity), ERD, org charts, mind maps, Venn diagrams, timelines, wireframes, and any diagram using only rectangles, diamonds, circles, cylinders, and arrows. Also skip if the user explicitly asks to use basic/simple shapes or says not to search. **Use `search_shapes`** when the diagram requires industry-specific or branded icons: cloud architecture (AWS, Azure, GCP), network topology (Cisco, rack equipment), P&ID (valves, instruments, vessels), electrical/circuit diagrams, Kubernetes, BPMN with specific task types, or any domain where the user expects realistic/standardized symbols rather than labeled boxes. It also finds brand/product logos and general-purpose pictorial icons (e.g. `react`, `slack`, `shopping cart`, `solar panel`) — returned as ready-to-use `shape=image` styles — so use it too when the user asks for logos or everyday concept icons. - **Match the language of labels to the user's language** — if the user writes in German, French, Japanese, etc., all diagram labels, titles, and annotations should be in that same language. - **Group related nodes, and surface a hub when edges converge** — put nodes that belong together inside a container or swimlane, and keep external actors (users, files, third-party systems) outside implementation containers. When many edges converge on one area or cross several groups, route them through a single hub/gateway node (a registry, broker, event log, …) instead of drawing every low-level dependency across the canvas — fewer crossings, clearer contract. - **Encode secondary detail in node text, not edges** — draw an edge only when the relationship itself carries meaning; push incidental detail into the node label so the connector layer stays readable. ## Common styles **Rounded rectangle:** ```xml <mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/> </mxCell> ``` **Diamond (decision):** ```xml <mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="200" width="120" height="80" as="geometry"/> </mxCell> ``` **Arrow (edge):** ```xml <mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" source="2" target="3" parent="1"> <mxGeometry relative="1" as="geometry"/> </mxCell> ``` **Labeled arrow:** ```xml <mxCell id="5" value="Yes" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" source="3" target="6" parent="1"> <mxGeometry relative="1" as="geometry"/> </mxCell> ``` ## Style properties | Property | Values | Use for | |----------|--------|---------| | `rounded=1` | 0 or 1 | Rounded corners | | `whiteSpace=wrap` | wrap | Text wrapping | | `fillColor=#dae8fc` | Hex color | Background color | | `strokeColor=#6c8ebf` | Hex color | Border color | | `fontColor=#333333` | Hex color | Text color | | `shape=cylinder3` | shape name | Database cylinders | | `shape=mxgraph.flowchart.document` | shape name | Document shapes | | `ellipse` | style keyword | Circles/ovals | | `rhombus` | style keyword | Diamonds | | `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors | | `edgeStyle=elbowEdgeStyle` | style keyword | Elbow connectors | | `dashed=1` | 0 or 1 | Dashed lines | | `swimlane` | style keyword | Swimlane containers | | `group` | style keyword | Invisible container (pointerEvents=0) | | `container=1` | 0 or 1 | Enable container behavior on any shape | | `pointerEvents=0` | 0 or 1 | Prevent container from capturing child connections | | `html=1` | 0 or 1 | Enable HTML rendering in labels (required for `<b>`, `<br>`, `<font>`, etc.) | | `shape=umlLifeline;perimeter=lifelinePerimeter;size=16` | shape | UML sequence diagram lifeline (size = header height) | ## HTML labels **Always include `html=1` in the style** when the `value` attribute contains any HTML tags (`<b>`, `<br>`, `<font>`, `<i>`, `<u>`, `<hr>`, `<p>`, `<table>`, etc.). Without `html=1`, HTML tags are displayed as literal text instead of being rendered. HTML in attribute values must be **XML-escaped**: `<` → `&lt;`, `>` → `&gt;`, `&` → `&amp;`, `"` → `&quot;` ```xml <mxCell value="&lt;b&gt;Title&lt;/b&gt;&lt;br&gt;Description" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/> </mxCell> ``` **Line breaks:** Use `&#xa;` (works with both `html=1` and `html=0`) or `&lt;br&gt;` (requires `html=1`) for line breaks — never use `\n`, which renders as literal backslash-n text instead of a newline. **Best practice:** Always include `html=1` in every cell style. This ensures labels render correctly whether they contain HTML or plain text — plain text is unaffected by the flag. **Bold/italic/underline:** Use `fontStyle` in the style string when the entire label should be bold (`fontStyle=1`), italic (`fontStyle=2`), or underline (`fontStyle=4`). Values can be combined via bitwise OR (e.g., `fontStyle=3` = bold+italic). Use HTML tags (`<b>`, `<i>`, `<u>`) only when formatting part of the label (e.g., bold title with normal description). Never combine `fontStyle` with HTML tags for the same effect — this is redundant and causes visible raw tags if `html=1` is missing. ## Edges **CRITICAL: Every edge `mxCell` must contain a `<mxGeometry relative="1" as="geometry" />` child element.** Self-closing edge cells (e.g. `<mxCell ... edge="1" ... />`) are invalid and will not render correctly. Always use the expanded form: ```xml <mxCell id="e1" edge="1" parent="1" source="a" target="b" style="..."> <mxGeometry relative="1" as="geometry" /> </mxCell> ``` **Don't hand-route edges.** Just declare `source` and `target`. You do **not** need to: - Add `<mxPoint>` waypoints - Set `exitX` / `exitY` / `entryX` / `entryY` - Route around obstacles - Worry about edge-vertex collisions or parallel edge spacing draw.io's built-in router is **basic**: it draws each edge as a straight line or a simple right-angle path between `source` and `target`, with **no awareness of other shapes** — a wire will run straight across any box that sits between its endpoints. That's fine when connected nodes have open space between them. When edges would otherwise cross over shapes, or you want consistently clean orthogonal wires that route *around* the boxes, set **`routing: "libavoid"`** on `create_diagram`; for a full re-layout use **`postLayout: "elk"`** (see **Edge routing & layout passes** below). Both compute the waypoints for you — you never add them by hand either way. **What you still choose: the edge style.** The style determines the overall look (orthogonal angles, curves, straight lines) — the router honors the style family. | Style | Syntax | Best for | |-------|--------|---------| | **Orthogonal** | `edgeStyle=orthogonalEdgeStyle` | Flowcharts, architecture, network diagrams, BPMN — any diagram with right-angle connectors | | **Straight** | no `edgeStyle` | UML class/sequence diagrams, direct point-to-point connections. For sequence diagram messages use `endSize=6;startSize=6;` to keep arrowheads small | | **Entity Relation** | `edgeStyle=entityRelationEdgeStyle` | ER diagrams — creates perpendicular stubs at both ends | | **Curved** | `curved=1` | Mind maps, informal diagrams | | **Elbow** | `edgeStyle=elbowEdgeStyle;elbow=vertical;` | Rarely needed — `orthogonalEdgeStyle` handles almost all cases; use this only for simple 1-bend linear flows | **Use a consistent edge style within each diagram.** Pick one based on diagram type and apply it to all edges: ER → `entityRelationEdgeStyle`; UML class → straight; mind maps → curved; flowcharts/architecture/network → `orthogonalEdgeStyle`. **Useful edge style attributes** that apply regardless of routing: - `rounded=1` — rounded corners at bend points (recommended for orthogonal) - `endArrow=classic` / `endArrow=none` — arrow heads - `dashed=1` — dashed line - `strokeColor=#...`, `strokeWidth=2` — color/width - Edge labels: set `value` directly on the edge cell **Keep edge labels short and meaningful** — one to three words (`Yes`, `async`, `reads`). Drop labels that merely restate an obvious action (`call`, `register`); move longer explanations into node text or a small legend node. **Visual semantics — stay consistent, add a legend when mixing styles.** Within one diagram apply `dashed=1`, `strokeColor`, and `strokeWidth` consistently for one chosen meaning (e.g. dashed = optional / async / inferred relationship). Don't mix several dashed meanings without a small legend explaining them. ## Containers and groups For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes. ### How containment works Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container. ### Container types | Type | Style | When to use | |------|-------|-------------| | **Group** (invisible) | `group;` | No visual border needed, container has no connections. Includes `pointerEvents=0` so child connections are not captured | | **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections | | **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container without its own connections | ### Key rules - **Edges to children inside containers naturally cross the container boundary** — this is correct and expected. Do not add extra waypoints or complex routing to avoid a parent container when connecting to shapes inside it. - **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children - Only omit `pointerEvents=0` when the container itself needs to be connectable — in that case, use `swimlane` style which handles this correctly (the client area is transparent for mouse events while the header remains connectable) - Children must set `parent="containerId"` and use coordinates **relative to the container** ### Example: Architecture container with swimlane ```xml <mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/> </mxCell> <mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1"> <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/> </mxCell> <mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1"> <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/> </mxCell> ``` ### Example: Invisible group container ```xml <mxCell id="grp1" value="" style="group;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/> </mxCell> <mxCell id="c1" value="Component A" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="grp1"> <mxGeometry x="10" y="10" width="120" height="60" as="geometry"/> </mxCell> ``` ### Swimlanes for grouped actors (BPMN-style flowcharts) Use **flat swimlanes** at `parent="1"`, stacked vertically. One row of nodes per lane. **Fixed values — do not compute or debate:** - Lane size: `x=0, y=lane_index*150, width=CANVAS_W, height=150` - Lane style: `swimlane;horizontal=0;startSize=110;fillColor=<pastel>;html=1;` - Child nodes inside a lane: `parent="<lane_id>"`, `x = 120 + col*180`, `y = 45` (always 45), size 140×60 (or 140×80 for diamonds) - Cross-lane edges: `parent="1"` (not inside a lane) Pick `CANVAS_W = max_col * 180 + 300`. Choose lane colors from `#f5f5f5, #e8f4f8, #fff0e6, #e8f5e9, #fff9e6, #fce4ec` in that order. ```xml <mxCell id="lane1" value="Customer" style="swimlane;horizontal=0;startSize=110;fillColor=#f5f5f5;html=1;" vertex="1" parent="1"> <mxGeometry x="0" y="0" width="1800" height="150" as="geometry"/> </mxCell> <mxCell id="n1" value="Place Order" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="lane1"> <mxGeometry x="120" y="45" width="140" height="60" as="geometry"/> </mxCell> <mxCell id="lane2" value="System" style="swimlane;horizontal=0;startSize=110;fillColor=#e8f4f8;html=1;" vertex="1" parent="1"> <mxGeometry x="0" y="150" width="1800" height="150" as="geometry"/> </mxCell> <mxCell id="n2" value="Validate" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="lane2"> <mxGeometry x="300" y="45" width="140" height="60" as="geometry"/> </mxCell> <mxCell id="e1" edge="1" parent="1" source="n1" target="n2" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;"> <mxGeometry relative="1" as="geometry"/> </mxCell> ``` Do NOT nest lanes inside a pool. Do NOT vary lane heights. Do NOT compute title-area offset — it is always 110, children start at x=120 to clear it. ### Nested architecture containers (cloud, infra, network topologies) For diagrams with **nested groupings** — VPC → Availability Zone → EC2 instance, Datacenter → Rack → Server, Region → Environment → Service — use nested swimlanes. This is where the AI most often flattens hierarchy that should be nested. Treat each level as a swimlane container. **Rules:** - Every container is a `swimlane` with `startSize=24` (title area at the top). - Child cells set `parent="<container_id>"` and use coordinates **relative to their parent** (origin 0,0 is the parent's top-left, below the title). - Edges between cells in **different** containers must have `parent="1"` (not a container) — otherwise they render inside the container and get clipped. - For industry-specific icons (AWS/Azure/GCP logos, Cisco equipment, etc.), call `search_shapes` to get the exact `style` string and substitute it into a regular vertex — the container structure stays the same. ```xml <mxCell id="vpc" value="VPC" style="swimlane;startSize=24;fillColor=#dae8fc;strokeColor=#6c8ebf;html=1;" vertex="1" parent="1"> <mxGeometry x="0" y="0" width="720" height="360" as="geometry"/> </mxCell> <mxCell id="az1" value="AZ us-east-1a" style="swimlane;startSize=24;fillColor=#fff2cc;strokeColor=#d6b656;html=1;" vertex="1" parent="vpc"> <mxGeometry x="20" y="36" width="320" height="300" as="geometry"/> </mxCell> <mxCell id="web1" value="web-1" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="az1"> <mxGeometry x="30" y="40" width="120" height="60" as="geometry"/> </mxCell> <mxCell id="db1" value="db-1" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="az1"> <mxGeometry x="180" y="40" width="100" height="70" as="geometry"/> </mxCell> <mxCell id="az2" value="AZ us-east-1b" style="swimlane;startSize=24;fillColor=#fff2cc;strokeColor=#d6b656;html=1;" vertex="1" parent="vpc"> <mxGeometry x="360" y="36" width="340" height="300" as="geometry"/> </mxCell> <mxCell id="web2" value="web-2" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="az2"> <mxGeometry x="30" y="40" width="120" height="60" as="geometry"/> </mxCell> <mxCell id="e1" edge="1" parent="1" source="web1" target="web2" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;"> <mxGeometry relative="1" as="geometry"/> </mxCell> ``` ### Cross-functional flowcharts (actor × phase grid, as a table) Cross-functional flowcharts show a process across **two axes at once** — actors (rows) and phases (columns). Use drawio's `table` shape, which auto-arranges cells into a grid via `childLayout=tableLayout`. This is the canonical draw.io pattern and is distinct from plain swimlanes (which only group on one axis). **Structure:** - Outer container: `shape=table;childLayout=tableLayout;startSize=0;collapsible=0;fillColor=none;` - Rows are children of the table: `shape=tableRow;horizontal=0;startSize=0;collapsible=0;` - Cells are children of rows — regular vertices, one per (actor, phase) intersection - Row heights and cell widths are set via `mxGeometry`; they tile automatically - First row = phase headers; first cell of every other row = actor label - Process nodes go INSIDE the appropriate cell (parent = cell id) at coordinates relative to the cell - Cross-cell edges must use `parent="1"` (same rule as containers) ```xml <mxCell id="tbl" style="shape=table;childLayout=tableLayout;startSize=0;collapsible=0;fillColor=none;" vertex="1" parent="1"> <mxGeometry x="0" y="0" width="900" height="320" as="geometry"/> </mxCell> <mxCell id="r0" style="shape=tableRow;horizontal=0;startSize=0;collapsible=0;" vertex="1" parent="tbl"> <mxGeometry width="900" height="40" as="geometry"/> </mxCell> <mxCell id="h0" style="text;html=1;" vertex="1" parent="r0"> <mxGeometry width="140" height="40" as="geometry"/> </mxCell> <mxCell id="h1" value="Order" style="text;align=center;fontStyle=1;fillColor=#e8e8e8;" vertex="1" parent="r0"> <mxGeometry x="140" width="380" height="40" as="geometry"/> </mxCell> <mxCell id="h2" value="Fulfill" style="text;align=center;fontStyle=1;fillColor=#e8e8e8;" vertex="1" parent="r0"> <mxGeometry x="520" width="380" height="40" as="geometry"/> </mxCell> <mxCell id="r1" style="shape=tableRow;horizontal=0;startSize=0;collapsible=0;" vertex="1" parent="tbl"> <mxGeometry y="40" width="900" height="140" as="geometry"/> </mxCell> <mxCell id="a1" value="Customer" style="fillColor=#dae8fc;fontStyle=1;" vertex="1" parent="r1"> <mxGeometry width="140" height="140" as="geometry"/> </mxCell> <mxCell id="c_cust_order" style="fillColor=none;" vertex="1" parent="r1"> <mxGeometry x="140" width="380" height="140" as="geometry"/> </mxCell> <mxCell id="t_place" value="Place Order" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="c_cust_order"> <mxGeometry x="120" y="40" width="140" height="60" as="geometry"/> </mxCell> <mxCell id="c_cust_fulfill" style="fillColor=none;" vertex="1" parent="r1"> <mxGeometry x="520" width="380" height="140" as="geometry"/> </mxCell> <mxCell id="r2" style="shape=tableRow;horizontal=0;startSize=0;collapsible=0;" vertex="1" parent="tbl"> <mxGeometry y="180" width="900" height="140" as="geometry"/> </mxCell> <mxCell id="a2" value="System" style="fillColor=#d5e8d4;fontStyle=1;" vertex="1" parent="r2"> <mxGeometry width="140" height="140" as="geometry"/> </mxCell> <mxCell id="c_sys_order" style="fillColor=none;" vertex="1" parent="r2"> <mxGeometry x="140" width="380" height="140" as="geometry"/> </mxCell> <mxCell id="t_validate" value="Validate" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="c_sys_order"> <mxGeometry x="120" y="40" width="140" height="60" as="geometry"/> </mxCell> <mxCell id="c_sys_fulfill" style="fillColor=none;" vertex="1" parent="r2"> <mxGeometry x="520" width="380" height="140" as="geometry"/> </mxCell> <mxCell id="t_ship" value="Ship" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="c_sys_fulfill"> <mxGeometry x="120" y="40" width="140" height="60" as="geometry"/> </mxCell> <mxCell id="e1" edge="1" parent="1" source="t_place" target="t_validate" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;"> <mxGeometry relative="1" as="geometry"/> </mxCell> <mxCell id="e2" edge="1" parent="1" source="t_validate" target="t_ship" style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;"> <mxGeometry relative="1" as="geometry"/> </mxCell> ``` **When to use cross-functional tables vs flat swimlanes:** - Flat swimlanes — one-dimensional (actors only, or phases only). Simpler. Use this when you just need to show who does what in sequence. - Cross-functional table — two-dimensional (actors AND phases). Use this when **both** the actor and the process stage matter, and every step belongs to a specific (actor, phase) cell. **Do NOT** nest swimlanes inside a table row, do NOT set `startSize` on rows or cells (columns tile from `x=0`), and do NOT rely on the AI to produce exact widths that sum to the table width — close-enough totals are fine, the `tableLayout` normalizes them. ## Layers Layers control visibility and z-order. Every cell belongs to exactly one layer. Use layers to manage diagram complexity — viewers can toggle layer visibility to show or hide groups of elements (e.g., "Physical Infrastructure" vs "Logical Network" vs "Security Zones"). Cell `id="0"` is the root and cell `id="1"` is the default layer — both always exist. Additional layers are `mxCell` elements with `parent="0"`: ```xml <mxGraphModel> <root> <mxCell id="0"/> <mxCell id="1" parent="0"/> <mxCell id="2" value="Annotations" parent="0"/> <mxCell id="10" value="Server" style="rounded=1;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/> </mxCell> <mxCell id="20" value="Note: deprecated" style="text;" vertex="1" parent="2"> <mxGeometry x="100" y="170" width="120" height="30" as="geometry"/> </mxCell> </root> </mxGraphModel> ``` - A layer is an `mxCell` with `parent="0"` and no `vertex` or `edge` attribute - Assign shapes to a layer by setting `parent` to the layer's id - Later layers render on top of earlier layers (higher z-order) - Add `visible="0"` as an attribute on the layer cell to hide it by default - Use layers when the diagram has distinct conceptual groupings that viewers may want to toggle independently ## Tags Tags are visual filters that let viewers show or hide elements by category. Unlike layers, a single element can have multiple tags, making tags ideal for cross-cutting concerns (e.g., tagging shapes as "critical", "v2", or "backend"). Tags require wrapping `mxCell` in an `<object>` element. Tags are assigned via the `tags` attribute as a space-separated string: ```xml <mxGraphModel> <root> <mxCell id="0"/> <mxCell id="1" parent="0"/> <object id="2" label="Auth Service" tags="critical v2"> <mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/> </mxCell> </object> <object id="3" label="Legacy API" tags="critical deprecated"> <mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="300" y="100" width="120" height="60" as="geometry"/> </mxCell> </object> </root> </mxGraphModel> ``` - Tags require the `<object>` wrapper — a plain `mxCell` cannot have tags - The `label` attribute on `<object>` replaces `value` on `mxCell` - Tags are space-separated in the `tags` attribute - Viewers filter the diagram by selecting tags in the draw.io UI (Edit > Tags) - Tags do not affect z-order or structural grouping — they are purely a visibility filter ## Metadata and placeholders Metadata stores custom key-value properties on shapes as additional attributes on the `<object>` wrapper element. Combined with placeholders, metadata values can be displayed in labels — useful for data-driven diagrams showing status, owner, IP addresses, or versions on each shape. Set `placeholders="1"` on the `<object>` to enable `%propertyName%` substitution in the `label`: ```xml <mxGraphModel> <root> <mxCell id="0"/> <mxCell id="1" parent="0"/> <object id="2" label="&lt;b&gt;%component%&lt;/b&gt;&lt;br&gt;Owner: %owner%&lt;br&gt;Status: %status%" placeholders="1" component="Auth Service" owner="Team Backend" status="Active"> <mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="160" height="80" as="geometry"/> </mxCell> </object> </root> </mxGraphModel> ``` - Custom properties are plain XML attributes on `<object>` (e.g., `component="Auth Service"`) - Set `placeholders="1"` to enable `%key%` substitution in the label and tooltip - The label must use `html=1` style when using HTML formatting with placeholders - Placeholders resolve by walking up the containment hierarchy: shape attributes first, then parent container, then layer, then root — first match wins - Predefined placeholders work without custom properties: `%id%`, `%width%`, `%height%`, `%date%`, `%time%`, `%timestamp%`, `%page%`, `%pagenumber%`, `%pagecount%`, `%filename%` - Use `%%` for a literal percent sign in labels - Tags, metadata, and placeholders can all be combined on the same `<object>` element - Use metadata when shapes represent data records (servers, services, components) and you want to attach structured information beyond the visible label ## Dark mode colors draw.io supports automatic dark mode rendering. How colors behave depends on the property: - **`strokeColor`, `fillColor`, `fontColor`** default to `"default"`, which renders as black in light theme and white in dark theme. When no explicit color is set, colors adapt automatically. - **Explicit colors** (e.g. `fillColor=#DAE8FC`) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180° (via `mxUtils.getInverseColor`). - **`light-dark()` function** — To specify both colors explicitly, use `light-dark(lightColor,darkColor)` in the style string, e.g. `fontColor=light-dark(#7EA6E0,#FF0000)`. The first argument is used in light mode, the second in dark mode. To enable dark mode color adaptation, the `mxGraphModel` element must include `adaptiveColors="auto"`. When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use `light-dark()` only when the automatic inverse color is unsatisfactory. ## Edge routing & layout passes By default, edges are drawn by draw.io's **built-in router**, which is intentionally basic: each edge is a straight line or a simple right-angle path between its endpoints, with **no obstacle avoidance** — a connector runs straight through any shape lying between its `source` and `target`. There is no server-side post-processing. Two **opt-in** passes on `create_diagram` upgrade this; they are independent and combine freely, run client-side after the diagram renders, and the exported XML (copy/clipboard, "Open in draw.io") reflects the final routed result. - **`routing: "libavoid"`** (XML only) — obstacle-avoiding orthogonal **edge routing**. Vertices stay exactly where you placed them; only the connectors are recomputed, so they run in clean right-angle segments that route *around* the boxes (and spread apart when parallel) instead of cutting across them. Use it for diagrams you laid out deliberately — architecture, network topology, deployment, swimlanes, UML, floor plans — where you want tidy wires without disturbing your layout. - **`postLayout: "elk"`** — a **full re-layout** (ELK `layered` flow). Vertices animate (morph) from your positions to canonical hierarchical positions, and the edges are routed as part of that. Best for flowcharts, process/state diagrams, decision flows, pipelines, and other directional/hierarchical diagrams. (You should rarely hand-write these as XML — prefer Mermaid.) Flow **direction**: on XML set the optional `direction` field (`"vertical"` (default) / `"horizontal"`); on Mermaid it is read from the flowchart code (`flowchart TD/TB` vs `LR/RL`) and `direction` is ignored. The four combinations: | `postLayout` | `routing` | Result | |---|---|---| | — | — | basic built-in router (straight / simple right-angle, no obstacle avoidance); your positions kept | | — | `libavoid` | your positions kept; wires re-routed orthogonally *around* the shapes | | `elk` | — | ELK places the vertices **and** routes the edges (decent routing built in) | | `elk` | `libavoid` | rarely worth it — ELK already routes; only add `libavoid` if ELK's routing specifically comes out poor | **Pick ONE — they are essentially alternatives, not a stack:** - **Neither** — fine when connected nodes sit in clear rows/columns with open space between them, so the basic router's straight/right-angle lines won't cross another shape. Simplest and lightest; do this by default for sparse layouts. - **`routing: "libavoid"`** — keep your hand-placed layout but clean up the wires: use whenever an edge would otherwise cut across a box, or you want consistently clean orthogonal wires routed around shapes (architecture, network topology, deployment, UML, floor plans — anything densely connected). - **`postLayout: "elk"`** — when you want a canonical re-layout (vertices moved). ELK routes the edges itself as part of the layout, so **do not also set `routing`** — the combination is redundant in almost all cases. Add `direction: "horizontal"` for left-to-right flow. **For Mermaid diagrams: see the `postLayout` parameter description for when to set it.** Complex Mermaid flowcharts (≥ ~20 nodes, ≥ 3 decision diamonds, feedback edges, or ≥ 3 endpoints) need `postLayout: "elk"` because the native parser's layout goes cramped or unbalanced past that threshold — the direction follows the flowchart code, so no `direction` is needed. Simple flowcharts and all non-flowchart Mermaid types (sequence, class, ER, sankey, …) need no `postLayout`. **When NOT to use (XML):** - The user has asked for specific positions (swim lanes with exact lanes, architecture diagrams with meaningful spatial arrangement). - The diagram relies on containers/grouping where spatial layout encodes information. ## Style reference Complete style reference (all shape types, style properties, color palettes, HTML labels, and more): https://github.com/jgraph/drawio-mcp/blob/main/shared/style-reference.md XML Schema (XSD): https://github.com/jgraph/drawio-mcp/blob/main/shared/mxfile.xsd ## CRITICAL: XML well-formedness When generating draw.io XML, the output **must** be well-formed XML: - **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML. - Escape special characters in attribute values: `&amp;`, `&lt;`, `&gt;`, `&quot;` - Always use unique `id` values for each `mxCell` --- # Mermaid Reference Short hints for generating Mermaid diagrams that render correctly in draw.io. draw.io's Mermaid parser covers 28 diagram types — the header keyword on the first non-directive line selects the type. _Canonical list & dialog/ELK docs: <https://github.com/jgraph/drawio/discussions/5643>._ ## General rules - **Pick the type keyword carefully.** `graph`/`flowchart`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `sequenceDiagram`, `gitGraph`, `journey`, `pie`, `gantt`, `mindmap`, `timeline`, `quadrantChart`, `requirementDiagram`, `sankey-beta`, `xychart-beta`, `block-beta`, `c4Context`/`C4Container`/`C4Component`, `architecture-beta`, `radar-beta`, `packet-beta`, `venn-beta`, `treemap-beta`, `treeView-beta`, `ishikawa-beta`, `kanban`, `zenuml`, `wardley-beta`, `eventmodeling`. Misspelling the header yields a blank diagram. - **No trailing punctuation on node IDs.** IDs are identifiers (`myNode`, `node_1`, `A`) — spaces, hyphens (in some contexts), and reserved words (`end`, `class`, `subgraph`) break the parse. Put display text in brackets or quotes instead: `A["User's Account"]`. - **One statement per line.** Separate statements with newlines; `;` works as a delimiter in flowchart but not everywhere. - **Quote labels with special characters** (`:`, `-`, parentheses, non-ASCII). Use `"` not `'`. - **HTML in labels:** only `<br>`, `<b>`, `<i>`, `<u>` are reliable across types. Use `#` for hex colors in styles, never `rgb()`. - **Diagrams can take a title block** for some types: ``` --- title: My Diagram --- flowchart TD ``` - **Match the language of labels to the user's language** — if the user writes in German, French, etc., the diagram labels should be in that language too. ## Flowchart (most common) ``` flowchart TD A[Start] --> B{Decision?} B -->|Yes| C[Do thing] B -->|No| D[Skip] C --> E((End)) D --> E ``` - **Direction:** `TD`/`TB` (top-down), `BT`, `LR`, `RL`. - **Node shapes by bracket:** `[rect]`, `(rounded)`, `([stadium])`, `[[subroutine]]`, `[(cylinder)]`, `((circle))`, `{rhombus}`, `{{hexagon}}`, `[/parallelogram/]`, `[\parallelogram alt\]`, `[/trapezoid\]`, `>asymmetric]`. - **Edges:** `-->` arrow, `---` no arrow, `-.->` dotted, `==>` thick, `<-->` bidirectional. Inline label: `A -- text --> B` or `A -->|text| B`. - **Subgraphs:** ``` subgraph Frontend A --> B end ``` ### Styling & colors Three ways — pick one, don't mix for the same node: **1. Inline per-node (`style`):** ``` flowchart LR A[Start] --> B[End] style A fill:#f9f,stroke:#333,stroke-width:2px,color:#fff style B fill:#bbf,stroke:#f66,stroke-dasharray:5 5 ``` **2. Reusable classes (`classDef` + `:::`):** ``` flowchart LR A:::happy --> B:::sad classDef happy fill:#dfd,stroke:#0a0 classDef sad fill:#fdd,stroke:#a00 ``` Or apply to many: `class A,B,C happy`. **3. Link styling (edges):** ``` linkStyle 0 stroke:#f00,stroke-width:3px linkStyle default stroke:#999 ``` `0` = first edge in order defined; `default` targets unstyled edges. Style properties that work: `fill`, `stroke`, `stroke-width`, `stroke-dasharray`, `color` (font color). ## Sequence diagram ``` sequenceDiagram participant U as User participant S as Server U->>S: Request S-->>U: Response Note right of S: Logged ``` - **Arrows:** `->` (no head), `->>` (arrow), `-->>` (dashed), `-x` (X end), `--x` (dashed X). - **Activate/deactivate:** `activate S` / `deactivate S` or `S->>+S2: call` / `S2-->>-S: return`. - **Blocks:** `alt/else/end`, `opt/end`, `loop/end`, `par/and/end`, `critical/option/end`. - **Notes:** `Note left of A`, `Note over A,B: text`. - Optional `autonumber` after header numbers the messages. ## Class diagram ``` classDiagram class Animal { +String name +int age +eat() void } class Dog Animal <|-- Dog : inherits Dog "1" --> "*" Bone : has ``` - **Relations:** `<|--` inherit, `*--` composition, `o--` aggregation, `-->` association, `..>` dependency, `..|>` realize, `<-->` bidirectional. - **Visibility:** `+` public, `-` private, `#` protected, `~` package. - **Annotations:** `<<interface>>`, `<<abstract>>`, `<<enumeration>>` inside the class block or via `Animal <<interface>>`. - **Cardinality:** quoted strings flanking the arrow (`"1"`, `"0..*"`, `"*"`). ## State diagram ``` stateDiagram-v2 [*] --> Idle Idle --> Running : start Running --> Idle : stop Running --> [*] state Running { [*] --> Working Working --> Waiting : block Waiting --> Working : unblock } ``` - Use `stateDiagram-v2`, not `stateDiagram` (v1 is legacy). - `[*]` = start (source) or end (target) depending on direction. - `state X { ... }` nests a compound state; `state fork1 <<fork>>`, `<<join>>`, `<<choice>>` mark junction nodes. - Transition labels: `A --> B : event [guard] / action`. ## ER diagram ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER { string name string email PK } ``` - **Cardinality symbols:** `|o` zero-or-one, `||` exactly-one, `}o` zero-or-many, `}|` one-or-many. Mirror on both sides (e.g., `||--o{`). - Attribute blocks list `type name [PK|FK|UK]` plus optional comment in quotes. - Entity names are typically UPPERCASE by convention. ## Journey ``` journey title Morning routine section Wake up Coffee: 5: Me Read news: 3: Me section Commute Drive: 2: Me, Traffic ``` Each task: `Name: score(1-5): Actor[, Actor...]`. Section headers group tasks. ## Pie ``` pie showData title Browser share "Chrome" : 60 "Firefox" : 20 "Safari" : 20 ``` `showData` is optional (renders the numbers). Quotes on labels, colon, numeric value. ## Gantt ``` gantt title Project timeline dateFormat YYYY-MM-DD section Phase 1 Design : a1, 2025-01-01, 7d Build : after a1, 14d section Phase 2 Test : 2025-01-25, 5d ``` - `dateFormat` is mandatory. - Task line: `Name : [id,] [after id | YYYY-MM-DD], duration[d/w]`. - Status tags: `done`, `active`, `crit` before the id (`crit a1`). ## Gitgraph ``` gitGraph commit branch develop checkout develop commit commit checkout main merge develop ``` Commands: `commit [id: "x"] [tag: "v1"]`, `branch name`, `checkout name`, `merge name`, `cherry-pick id: "x"`. ## Mindmap ``` mindmap root((Project)) Frontend React CSS Backend Node DB ``` - Indentation (2-space increments) defines hierarchy. - Root shape: `((circle))`, `[rect]`, `(rounded)`, `))cloud((`, `)hexagon(`, `{{hexagon}}`. - No edges — they are implied by nesting. ## Timeline ``` timeline title Company history section 2020s 2021 : Founded 2022 : Series A : Launched product section 2030s 2030 : IPO ``` Colon separates year/label; multiple `:` lines under one year add sub-events. ## Quadrant chart ``` quadrantChart title Reach vs Engagement x-axis Low --> High y-axis Low --> High quadrant-1 Stars quadrant-2 Question Marks quadrant-3 Dogs quadrant-4 Cash Cows Campaign A: [0.3, 0.6] Campaign B: [0.75, 0.85] ``` Point coords are `[0..1, 0..1]`. ## Requirement diagram ``` requirementDiagram requirement req1 { id: "1" text: "The system shall..." risk: high verifymethod: test } element user_story { type: "story" } user_story - satisfies -> req1 ``` Requirement types: `requirement`, `functionalRequirement`, `performanceRequirement`, `interfaceRequirement`, `physicalRequirement`, `designConstraint`. Relations: `contains`, `copies`, `derives`, `satisfies`, `verifies`, `refines`, `traces`. ## Sankey ``` sankey-beta Source,Intermediate,10 Source,Direct,5 Intermediate,Sink,10 ``` CSV-style: `source,target,value`. No header. No `title` (use frontmatter). ## XY chart ``` xychart-beta title "Revenue" x-axis [jan, feb, mar, apr] y-axis "USD" 0 --> 10000 bar [2500, 5000, 7500, 9000] line [3000, 4500, 6500, 8500] ``` `bar [...]` and `line [...]` can stack; order matters (later overlays earlier). ## Block ``` block-beta columns 3 A B C D["Wide"]:2 E A --> D ``` `columns N` sets grid width. `Name:N` spans N columns. Edges use flowchart arrow syntax. ## C4 ``` C4Context Person(user, "User") System(app, "App", "Does things") Rel(user, app, "Uses") ``` - Variants: `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`. - Element helpers: `Person`, `System`, `System_Ext`, `Container`, `ComponentDb`, `Boundary(id, "label", "type")`, etc. Arguments are positional: `(id, label, [type/tech], [description])`. - `UpdateElementStyle(tag, $bgColor="#…")` and `AddElementTag` tweak appearance. ## Architecture ``` architecture-beta group cloud(cloud)[Cloud] service api(server)[API] in cloud service db(database)[DB] in cloud api:R --> L:db ``` - Built-in icons: `cloud`, `server`, `database`, `disk`, `internet`. Suffix edge ends with `:T`, `:B`, `:L`, `:R` to pick the side. - `group id(icon)[Label]` then `in groupId` on services places nodes. ## Radar ``` radar-beta title Skills axis js["JS"], py["Python"], go["Go"] curve alice["Alice"]{80, 60, 70} curve bob["Bob"]{50, 90, 65} ``` Axes and curves are positionally aligned — list values in axis order, 0–100. ## Packet ``` packet-beta 0-15: "Source Port" 16-31: "Dest Port" 32-63: "Seq Number" ``` `start-end` (bit ranges) or single-bit `N`. Use a title frontmatter. ## Venn ``` venn-beta set A ["Set A"] set B ["Set B"] union A,B text A ["only A"] text A,B ["shared"] ``` Define every `union` combination whose region you plan to label. `text A,B [...]` places text in intersections. ## Treemap ``` treemap-beta "Category" "Leaf 1": 40 "Leaf 2": 60 ``` Numbers are values (area-weighted). Indent (2+ spaces) for hierarchy. ## Tree view ``` treeView-beta "Root" "Child 1" "Grandchild" "Child 2" ``` Pure indentation hierarchy, no numbers. ## Ishikawa (fishbone) ``` ishikawa-beta Main Problem Category Cause Sub-cause Another Category Cause ``` First line after header is the problem; top-level indents are categories (Materials, Methods, Machinery, etc. — use whatever makes sense). ## Kanban ``` kanban todo[To Do] task1[Write spec]@{ assigned: "Alice", priority: "High" } doing[In progress] task2[Build feature] done[Done] ``` Columns are `id[Label]` at indent 0; cards are `id[Label]@{ metadata }` inside. Metadata keys: `assigned`, `priority` (`Very Low`/`Low`/`Medium`/`High`/`Very High`), `ticket`. ## ZenUML ``` zenuml @Actor User @Boundary Web @Control Service User -> Web: request Web -> Service: process() Service -> Web: result ``` Participant roles: `@Actor`, `@Boundary`, `@Control`, `@Entity`, `@Database`. Messages use `->` with a colon-separated label. Supports `if/else`, `while`, `par` blocks like sequence diagrams. ## Wardley map ``` wardley-beta title Tea Shop anchor Business [0.95, 0.63] component Cup of Tea [0.79, 0.61] component Kettle [0.43, 0.35] (inertia) Business -> Cup of Tea Cup of Tea -> Kettle evolve Kettle 0.62 ``` - Header `wardley` or `wardley-beta`; `title` optional. - `anchor`/`component Name [visibility, evolution]` — coords are `[0..1, 0..1]` (y = value-chain visibility, x = evolution from Genesis to Commodity). - Component evolution markers in parens: `(inertia)`, `(build)`, `(buy)`, `(outsource)`, `(market)`. - Links: `A -> B` dependency, `A +> B` flow. `evolve Name <x>` adds an evolution target; `evolution Genesis -> Custom -> Product -> Commodity` relabels the x-axis stages. - Extras: `note "text" [x,y]`, `annotation N,[x,y] "text"`, `accelerator`/`deaccelerator "text" [x,y]`. ## Event Modeling ``` eventmodeling tf 01 ui CartUI tf 02 cmd AddItem tf 03 evt ItemAdded tf 04 rmo Cart ``` - Each `tf <id> <type> <Name>` is a time-frame (column). Types: `ui` / `pcr` (processor), `cmd` / `command`, `rmo` / `readmodel`, `evt` / `event` — placed on the UI/Automation, Command/Read-Model, and Events swimlanes. - Wire frames with `->>`: `tf 04 evt ItemChanged ->> 02 ->> 03` links frame 04 back to 02 and 03. - `Namespace.Name` groups frames into slices (e.g. `Order.ChangeOrder`). - `data <id> { ... }` blocks attach payloads, referenced inline with `[[id]]`: `tf 02 cmd AddItem [[AddItem01]]`. ## When to prefer XML over Mermaid - Precise positions / custom coordinates. - draw.io-native shapes (AWS, Azure, GCP, P&ID, Cisco, electrical). - Mixed shape libraries or complex multi-layer diagrams. - Anything that needs exact colors per element with many variations — Mermaid's styling works but at scale XML is easier to reason about. Default to Mermaid for the standard types above; reach for XML only when Mermaid's syntax clearly can't express what's needed.