# Naming and discovery A sub-workflow nobody can find gets rebuilt. The community MCP can't read, write, or filter by tags — tags are a UI-only concept — so the **only searchable surface is the workflow's name and description**, via `n8n_list_workflows` (scan the library) and `n8n_get_workflow` (read a candidate's inputs/outputs and body). That makes naming the discovery mechanism, not a cosmetic nicety. Put your discovery hooks in the name and description deliberately. --- ## Tags don't help here n8n has tags in the UI, but the MCP can't see them. Don't rely on tags for AI-side discovery — anything you want re-found later has to be findable by name or description. --- ## The naming convention is the discovery mechanism Use verb-first prefix names. The prefix groups the library; the verb + object says what it does: ``` Subworkflow: # stateless, generic, reusable anywhere : # domain-specific (Customer, Billing, Notification, …) Tool: # exposed as an AI-agent tool ``` Examples: - `Subworkflow: Parse RFC2822 date` - `Subworkflow: Compute MRR from subscription` - `Subworkflow: Format invoice as HTML` - `Customer: hydrate from Stripe` - `Customer: write to billing table` - `Billing: compute MRR` - `Notification: send + log` - `Tool: list available credentials` Why this works when the only search is name/description matching: - Scanning the list for `Subworkflow:` surfaces every reusable sub-workflow. - Scanning for `Customer:` surfaces every customer-domain sub-workflow. - Scanning for `Tool:` surfaces every agent-callable tool. - Scanning for `date` surfaces anything with "date" in its name or description, regardless of prefix. Put a prefix on **every** sub-workflow, at create time. It's far easier than retrofitting once callers exist. --- ## Search-before-build, in practice Before writing logic for a generic problem, scan the library: ``` n8n_list_workflows() # then filter the results by name n8n_get_workflow({ id: "" }) # read description + inputs/outputs + body ``` When to look: any time you're about to build something that fits a domain or an operation keyword. About to parse a date? Look for `date`. Format an invoice? `invoice`. Send a Slack notification? `Slack` and `Notification`. Two scans is cheap; a duplicate is not. If a candidate matches, fetch it with `n8n_get_workflow` and read the `description` first — that's the contract. If the inputs/outputs fit, use it. If it's close-but-not-quite, decide whether to extend the existing one or build a deliberate variant (and name the variant so *it* is findable too). If you expected to find a workflow and it isn't showing up, the most common cause isn't naming — it's that the workflow isn't exposed to the MCP at all. Confirm it exists and is reachable before assuming it's missing. --- ## The description as a discoverability tool After a name match, the reader reads the `description`. Make it scan well — what it does, the output shape, the typical caller: ``` Parses an RFC2822-formatted date string into ISO format. Returns { ok: true, iso: "..." } or { ok: false, error: "invalid_format" }. Used by webhook handlers that receive email-style timestamps. ``` The description also feeds name/description matching, so seed it with representative keywords ("RFC2822", "date", "ISO", "webhook") so varied scans surface it. A sub-workflow with no description forces the reader to open and inspect every node to figure out what it is — which usually ends in them rebuilding it. --- ## Naming at create time Set the name and description when you create the workflow, not later: ``` n8n_update_partial_workflow({ id: "", operations: [ { type: "updateSettings", /* name + description carried on the workflow object */ } ] }) ``` In practice you'll set `name` and `description` on the workflow when you create it, then add the trigger and body nodes via `addNode` / `addConnection`. The point is: don't let a new sub-workflow ship without the prefix and a real description. --- ## What a healthy library looks like Roughly: - 5–20 `Subworkflow:` entries for common shapes (date parsing, ID generation, formatting…). - A handful of domain sub-workflows per main domain (`Customer:`, `Billing:`, `Notification:`). - Fewer per-domain "operations" sub-workflows (write to billing table, send email + log). Counter-signals: - **100 sub-workflows** → likely lots of near-duplicates to merge. - **0 sub-workflows** → no extraction; logic is being duplicated inline. - **50 entries named `Helper`, `Util1`, `Helper2`** → discoverability is broken. Rename to the prefix convention. When the user asks "what sub-workflows do we have?", scan with `n8n_list_workflows`, filter by prefix, and return a list with each name plus a one-line summary pulled from its description. That's also a good moment to spot duplicates and propose consolidating. --- ## Cross-project sub-workflows On Cloud or project-enabled instances, sub-workflows live inside a project, and by default a workflow can only call sub-workflows in its own project. Sharing across projects is opt-in. Only share cross-project when **both** hold: - **Stateless** — no project-scoped credentials, Data Tables, or other state that wouldn't make sense outside the owning project. - **Generic problem** — date parsing, ID generation, signature validation, formatting. Clearly not coupled to one project's domain. A stateful sub-workflow (`Customer: get by id`) shared across projects would pull one project's data into another's workflows, which is almost never intended. Keep those in-project and let each project own its repository layer. For ones that meet the bar, tell the user — they share via the n8n UI — and note the cross-project intent in the description. --- ## Renaming and reorganizing For duplicates or poorly-named sub-workflows: - **Renaming preserves the workflow ID**, so existing Execute Workflow callers (which reference the ID, not the name) keep working. The new name shows up in scans immediately. - n8n has no alias mechanism — just rename, update any sticky-note references inside callers, and move on. - For a mass rename, audit callers first: `n8n_list_workflows` to find candidates, then `n8n_get_workflow` on each to check its Execute Workflow node for the old workflow ID before you touch anything.