mcp-server

Report a bug, request a feature, escalate an issue, or ask the Agentled team a question. Use this when you encounter something broken, have a suggestion for improvement, need human help from the Agentled team, or want to escalate a problem you cannot solve. Include a clear title and detailed description. Save the returned feedbackId and use get_feedback to read its status and the latest team response. The team can also reply by email: pass userEmail to choose where; if omitted, replies go to the email of the account that owns this API key. Requires write access when connected with OAuth.

Test an AI prompt in isolation without creating a workflow or execution. Pass a prompt template with {{variable}} syntax and variable values to run the AI and see the response. Useful for tuning prompts and response structures before adding an AI step to a workflow. Example: test_ai_action("Analyze this company: {{company}}", { company: "Stripe" }, { score: "number 0-100", summary: "string" }) Requires write access when connected with OAuth.

Test an app action in isolation without creating a workflow or execution. Pass the appId and actionId (from list_apps / get_app_actions) plus input data to run the action directly and see results immediately. Useful for verifying inputs before wiring a step into a workflow. Example: test_app_action("web-scraping", "scrape", { url: "https://example.com" }) Requires write access when connected with OAuth.

Test a code step in isolation without creating a workflow or execution. Pass JavaScript code with optional {{variable}} template syntax and variable values to execute in the same sandboxed vm context as the production orchestrator. Useful for verifying code logic and template variable resolution before adding a code step to a workflow. No credits consumed. Example: test_code_action("javascript", "const items = {{items}};\nreturn items.map(p => ({ name: p.fullName }));", { items: [{ fullName: "John" }, { fullName: "Jane" }] }) Requires write access when connected with OAuth.

Run a routine immediately without changing its scheduled cadence. Free-tier workspaces cannot trigger routines. Use a short reason, for example "verify analytics monitor". Source must be one of: codex, claude, ui, api, mcp. Requires write access when connected with OAuth.

Remove one typed live-enforcement pointer on an onboarding-goal approval requirement. This updates the requirement binding only. It does not change the referenced workflow, agent, channel, or routine; run providers; spend credits; make approval decisions; or execute external writes. Removing a path from a send, write, or delete safeguard requires confirm=true. The server reuses the UI validator and writes an actor-attributed audit row. Requires write access when connected with OAuth.

Remove one exact skill and agent reference from an onboarding goal. This changes goal configuration only. It does not remove the skill from the agent, revoke tools or app permissions, run providers, spend credits, or perform external writes. The server reuses the UI validator and writes an actor-attributed audit row. Requires write access when connected with OAuth.

Delete one step path. Thin wrapper around `update_step({ unset: [path] })`. Use for removing a stale input, config key, or leftover type-specific field after a shape change. The path must currently exist on the step. Returns the same shape as `update_step`. Requires write access when connected with OAuth.

Surgical update of one agent. **Preferred path for any single-field edit on an existing agent** — only the fields in `updates` / `replace` / `unset` are touched, every other field is left as-is. Same merge model as `update_step`. ## Merge semantics `update_agent` accepts three independent operations on the same call. At least one must be non-empty. - **`updates`** — partial agent patch. Top-level fields (`name`, `description`, `instructions`, `status`, `goals`, `chatModel`, `enabledApps`, etc.) are shallow-replaced. Nested objects (`configFiles`, `avatar`, `appPermissions`) are deep-merged ONE LEVEL — keys you don't mention are preserved. Arrays (`enabledApps`, `enabledActions`, `assignedWorkflowIds`, `linkedFileIds`) are replaced wholesale. - **`replace: string[]`** — dot-paths whose values from `updates` are assigned WHOLESALE, skipping deep-merge. Use this when you genuinely want to wipe a dictionary (e.g. `replace: ["configFiles"]` swaps the whole configFiles dict instead of merging key-by-key). - **`unset: string[]`** — dot-paths to DELETE (e.g. `["goals"]`, `["configFiles.SOUL.md"]`). Each must currently exist on the agent. - **`null` in updates** — shortcut for unset (e.g. `updates: { goals: null }`). ## Common edit recipes | Goal | Call | |---|---| | Update one config file (preserve others) | `updates: { configFiles: { "SOUL.md": "new persona…" } }` | | Replace all instructions | `updates: { instructions: "new system prompt" }` | | Rename agent slug/email address | `updates: { slug: "pitchnight" }` | | Assign workflows (full replace) | `updates: { assignedWorkflowIds: ["wf-1", "wf-2"] }` | | Add to assigned workflows | fetch via `get_agent`, modify locally, send full new array (or use `manage_agent_workflows`) | | Allow an app to write with approval | `updates: { enabledApps: ["linkedin"], appPermissions: { linkedin: { access: "write", writeApprovalRequired: true } } }` | | Override one action approval | `updates: { enabledApps: ["linkedin"], appPermissions: { linkedin: { access: "write", writeApprovalRequired: true, actionApprovals: { "linkedin.create-comment": false } } } }` | | Keep an app read-only | `updates: { enabledApps: ["linkedin"], appPermissions: { linkedin: { access: "read" } } }` | | Change avatar color only | `updates: { avatar: { color: "#7C3AED" } }` (iconName preserved) | | Activate (fail-fast on missing fields) | `updates: { status: "active" }` | | Deactivate / pause | `updates: { status: "paused" }` or `updates: { status: "draft" }` | | Unset a scalar field | `updates: { goals: null }` or `unset: ["goals"]` | | Wipe + reset configFiles wholesale | `updates: { configFiles: { "SOUL.md": "…", "TOOLS.md": "…" } }, replace: ["configFiles"]` | | Remove just one config file | `unset: ["configFiles.SOUL.md"]` | **The trap.** Default deep-merge for `configFiles` and `avatar` is one level — sending a partial dict preserves siblings. To force a full wipe, use `replace: ["configFiles"]`. ## Activation requirements (fail-fast on `status: "active"`) When transitioning to `active`, the agent is validated: - `instructions` must be non-empty - `configFiles["SOUL.md"]` must be present, > 200 chars, and not contain the placeholder marker - `configFiles["TOOLS.md"]` must be present, > 200 chars, and not contain the placeholder marker If any check fails, the agent is NOT updated. The response is `{ ok: false, errors: ["…"] }` (HTTP 400). Fix the missing fields and retry. For scheduled / autonomous behaviour, attach routines via `create_routine` AFTER activation. Routines are first-class entities — they are NOT a field on the agent. ## What update_agent will NOT do - Cannot change `agent.id` (immutable, 400) - Changing `agent.slug` moves the AgentEntity to a new `{slug}@{workspace}` id, rebinds routines/file links/channel sessions/chat sessions where available, and updates the agent email address derived from the slug. - Slug convention: `slug` is the short role ID used in URLs/email. Keep "Agent" in the display name when useful, but do not append `-agent` to the slug just because the display name includes it; e.g. `Deal Sourcing Agent` should use `deal-sourcing`, not `deal-sourcing-agent`. - Cannot create new agents (use `create_agent`) - Cannot delete agents (use `delete_agent`) - Does not edit routines (use `update_routine` / `create_routine` / `pause_routine`) - Does not validate the merged result is internally consistent — only the activation guard runs. Other invariants are caller's responsibility. ## Diff + warnings Response includes `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. ≥6 fields removed without explicit `unset` triggers a warning — usually a "you wiped a dictionary" signal. Requires write access when connected with OAuth.

Update a file that is already attached to an agent. Use this for durable reflection context such as JOURNAL.md, OBJECTIVES.md, and PEOPLE.md: read the current file first with get_agent_file, then send the full updated content. Update only when there is durable signal (decisions, corrections, objectives, people context, or useful learning), not for every chat turn. The file must already be linked to the agent, so this tool cannot accidentally edit an unrelated workspace file. Requires write access when connected with OAuth.

Update the workspace's whitelabel branding configuration. Set any combination of branding fields. Pass null or empty string to clear a field. Fields: - displayName: Brand name shown to clients (e.g., "Acme Corp") - logoUrl: URL to brand logo image - tagline: Short tagline under the brand name - primaryColor: Hex color for light mode (e.g., "#6366f1") - primaryColorDark: Hex color for dark mode (e.g., "#818cf8") - faviconUrl: URL to custom favicon - hideBadge: Boolean — hide the "Built with Agentled" badge (requires teams/enterprise plan) Requires write access when connected with OAuth.

Add or remove fields on an existing knowledge list schema. Use this to evolve a list's schema — add new columns or remove unused ones. Existing rows are not modified; new fields will be missing from old rows until updated. Returns: { listKey, fieldCount }. Requires write access when connected with OAuth.

Update a workflow public form link, including enabling/disabling it, limits, auto-share, expiry, and success message. Requires write access when connected with OAuth.

Update a routine's fields. Only provided fields are changed. If interval is updated, nextRunAt is automatically recalculated. Requires write access when connected with OAuth.

Update a single step by ID. Low-level merge primitive — prefer surgical tools for common single-path edits: - `replace_step_dictionary` — merge keys into `fieldUpdates` / `responseStructure` / `fieldMapping` without dropping siblings - `replace_step_path` — set one nested path while preserving siblings (e.g. `renderer.config.layout`) - `unset_step_path` — delete one path - `append_step_array_item` / `remove_step_array_item` — mutate `tools` / `integrations` safely Keep `update_step` for complex multi-path edits, shape conversions, and batch changes. Prefer it over `update_workflow` for any one-step change; full `steps` arrays are for imports/round-trips only. ## KG-First — when editing a prompt template If this edit introduces or changes workspace-specific content in a prompt template (thesis, ICP, rubric, sector list, geo focus, brand voice), check the KG first: call `list_memories` / `list_knowledge_lists` / `get_knowledge_text`. Seed the content there if it isn't already present, then reference it at runtime (`{{steps.read-kg.content}}`) instead of pasting text inline. **Boundary: strategy → KG; execution wiring → workflow context; workflow structure → workflow.** ## Merge semantics `update_step` accepts three independent operations on the same call. At least one must be non-empty. - **`updates`** — partial step patch. Top-level fields are replaced; nested objects (`pipelineStepPrompt`, `stepInputData`, `entryConditions`, `renderer`, etc.) are deep-merged ONE LEVEL deep — keys nested two levels deep are overwritten as a unit, not merged. Arrays are replaced wholesale. - **`replace: string[]`** — dot-paths (e.g. `"stepInputData.fieldUpdates"`) whose values from `updates` are assigned WHOLESALE onto the step, skipping the deep-merge. Use for dictionary-shaped fields where keys are user data. - **`unset: string[]`** — dot-paths to DELETE. Each must exist on the original step. ## When to use which | Situation | Verb | Example | |---|---|---| | Change one config key, keep siblings | `updates` | `updates: { pipelineStepPrompt: { template: "new..." } }` | | Add a stepInputData entry | `updates` | `updates: { stepInputData: { profileUrls: "{{input.url}}" } }` | | Dictionary key merge | surgical | `replace_step_dictionary({ path: "stepInputData.fieldUpdates", value: {...} })` | | Remove a step input | `unset` / surgical | `unset_step_path` or `unset: ["stepInputData.oldKey"]` | | Swap full arrays | `updates` / surgical | `append_step_array_item` or `updates: { tools: [...] }` | **The trap.** Patching `stepInputData.fieldUpdates` with a partial dict via raw `updates` silently wipes siblings. Prefer `replace_step_dictionary`. ## Diff + warnings Response includes `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. ≥6 fields removed without explicit `unset` triggers a warning. ## Shape conversions Fetch the canonical example before changing shape: - email: `get_step_schema({ stepType: "aiAction", shape: "email" })` - report: `get_step_schema({ stepType: "aiAction", shape: "report" })` Send under `updates`, `replace[]` for dictionary children, `unset[]` for stale type-specific fields. ## Won't do - **Cannot change `step.id`** — root id is immutable; API returns 400. Nested `*.id` is fine. - **Does not enforce `step.type` immutability.** Stale type-specific fields (`pipelineStepPrompt`, `app`, `tools`) persist unless `unset`. For clean conversions, prefer `remove_step` + `add_step`. - **Does not validate the merged result against shape rules** — call `validate_workflow` after edits. ## Draft routing (live workflows) Edits are routed to a draft snapshot (`editingDraft: true` in response). Inspect via `get_draft`, ship via `promote_draft`, discard via `discard_draft`. When a draft exists, the response carries a `draft` summary: `{ exists, draftCreatedAt, liveUpdatedAt, stale, modifiedStepIds, modifiedFields }`. **If `draft.stale === true`, the live workflow advanced past the draft** — promoting will land older values for fields you didn't touch. A staleness warning is pushed into `warnings[]`. Recovery: `discard_draft` + retry, or inspect via `get_draft` first. Requires write access when connected with OAuth.

Update a WorkspaceUseCase product record by stored id, key, or workflowGraphId. Use this to attach existing workflows, agents, routines, AgentFiles, KG refs, data sources, config, validation, owner, collaborators, or lifecycle status to the use-case hub. config.onboardingGoal.approvalRequirements is read-only through external tools and must be edited from Use case > Safeguards. For config.useCasePage.header, use source pointers rather than copied labels: workflow analytics require { source: "workflow-analytics", workflowId, metricId, window }, and channels require { channel, workflowId, stepId }. For config.useCasePage.body.columns, preserve every existing column, set integer order values for an explicit order, and set semanticRole: "company" when a company-like column such as Startup should render before Status. Badge columns can map any case-insensitive value to a fixed semantic color with valueRoles, for example { type: "badge", field: "qualification", valueRoles: { ready: "success", warm: "warning" }, defaultRole: "neutral" }. Numeric score columns use { type: "score", field, thresholds: [{ min, role }], defaultRole }; the highest matching minimum wins. Allowed color roles are neutral, accent, warning, success, and danger; never store CSS classes in config. The platform derives metric labels/formats and channel approval/provider modes from those sources; validate each referenced workflow after updating the use case. This updates the use-case record only; it does not run workflows, mutate providers, spend credits, or make approval decisions. Requires write access when connected with OAuth.

Update an existing workflow. ## Recommended flow for agent-driven edits For editing an existing workflow step-by-step, prefer the per-step tools — they catch errors incrementally and avoid the bulk-JSON vocabulary traps (`ai` / `integration` / `knowledge_graph_query`, silently-stripped root fields like `prompt` / `listKey` / `appId`): - `update_step({ workflowId, stepId, updates })` — change one step (prompt, inputs, next, etc.). Safest and most common. - `add_step({ workflowId, step, insertAfter? })` — append or insert a new step. - `remove_step({ workflowId, stepId })` — delete a step and re-wire its neighbors. - After a series of edits: `validate_workflow` → (if live) `promote_draft` / `discard_draft`. The bulk `updates` param below is supported for **imports, templated rewrites, and programmatic round-trips** (export → edit JSON → re-import). Agents editing interactively should not use it for step changes — use `update_step` instead. ## Trigger type guidance Prefer `schedule` (polling) for email intake, document processing, and any workflow where exact-millisecond latency is not required — it is idempotent, supports backfill, and needs no webhook infrastructure. Use `app_event` or `webhook` only when the user explicitly says "as soon as", "within X seconds", or "real-time". When in doubt, schedule wins. ## Draft routing (live workflows) If the workflow is live, config edits (steps, context, name, etc.) are automatically routed to a draft snapshot instead of modifying the live pipeline. The response will include `editingDraft: true`. Use `get_draft` to view the draft, `promote_draft` to make it live, or `discard_draft` to throw away the changes. Non-live workflows are updated directly with an automatic pre-edit snapshot for rollback. ## Bulk updates param (imports / round-trips only) ⚠️ Avoid sending a full `steps` array for large workflows — use `update_step` instead. Sending more than ~20 steps risks silent truncation at the MCP transport layer. Full steps array replacement is only safe when doing a complete pipeline replacement from a known-good JSON source (import, template, export round-trip). For editing individual steps, always use `update_step`. ## `context` merge semantics (read before patching) **Root level:** `updates.context` is **shallow-merged** with the stored workflow’s `context` (`{ ...existingContext, ...patchContext }`). Sibling keys at the root (`inputPages`, `outputPages`, `executionInputConfig`, etc.) do not clobber each other: **omitting a key preserves the stored value**; only keys present in the patch are overwritten. To clear a collection explicitly, send an empty value (e.g. `inputPages: []`). Silent deletion-by-omission no longer applies at the root — same spirit as `update_step`’s deep-merge for nested step fields. **One level down:** Each **value** under `context` is still replaced **wholesale** when the patch includes that key. For example, `context: { executionInputConfig: { someKey: "x" } }` replaces the entire `executionInputConfig` object — any sibling fields under it (e.g. `defaults`, `fields`, `internal`) that are not in the payload are dropped. To partial-patch a nested object, **`get_workflow` first**, merge the current value with your changes client-side, then send the **full merged** object for that key in `update_workflow`. **Surgical alternative (preferred for context/metadata):** `update_workflow_context` is the workflow-level analog of `update_step` — it accepts the same three explicit verbs (`updates` / `replace` / `unset`) on workflow-relative paths under `context.<anything>` (both page schemas like `context.inputPages` AND user-saved page values like `context.outreachProfile`) and `metadata`. Returns `diff` + `warnings`. Use it instead of bulk `update_workflow` for any context or metadata edit, including pre-filling configuration input pages programmatically (e.g. `updates: { context: { outreachProfile: { name: "Alberto", signature: "..." } } }`). To flip a single nested key like `executionInputConfig.internal`, fetch with `get_workflow` first, merge locally, then `updates: { context: { executionInputConfig: {...full merged...} } }, replace: ["context.executionInputConfig"]` — the same merge-order trap as `update_step` applies (deep-merge runs before replace[], so replace at the parent level). ## Internal-only workflows Set `context.executionInputConfig.internal: true` to mark a workflow as a child / sub-workflow that runs only via `agentled.call-workflow`. The UI hides the Run button and replaces the manual run form with a banner; orchestrators still pass inputs via `executionInputData` (UI guard, not runtime restriction). Use for child workflows that end in a `return` step. To toggle on an existing workflow, fetch the current value with `get_workflow`, then call `update_workflow_context` with the explicit ops shape replacing at the parent level: `updates: { context: { executionInputConfig: {...merged...} } }, replace: ["context.executionInputConfig"]`. Requires write access when connected with OAuth.

Surgical edit of `workflow.context` (and `workflow.metadata`) — the workflow-level analog of `update_step`. Does NOT reach into `steps` (use `update_step` for that). ## Calling shape (preferred): three explicit verbs `{ updates, replace, unset }` — same merge model as `update_step`, but on **workflow-relative paths**. At least one must be non-empty. - **`updates`** — partial workflow patch. Top-level keys are limited to `context` and `metadata`. Each is shallow-merged (`{ ...stored, ...patch }`) so omitting a sibling preserves it. Direct sub-objects under `context` (e.g. `executionInputConfig`) are still replaced wholesale by default — use `replace[]` for explicit deep replacement, `unset[]` for deletion. - **`replace: string[]`** — workflow-relative dot-paths whose values from `updates` are assigned WHOLESALE, skipping the deep-merge. Path examples: `"context.executionInputConfig.fields"`, `"context.inputPages"`, `"metadata.tags"`. The path's value MUST be present in `updates`. - **`unset: string[]`** — workflow-relative dot-paths to delete. Each must currently exist on the workflow. ## What lives under `context` `workflow.context` holds two things, side by side as siblings: 1. **Page schemas** — `context.inputPages`, `context.outputPages`, `context.executionInputConfig`. Field definitions, defaults, shortDescriptionFields, etc. 2. **User-saved page values** — `context.<contextKey>`, where `<contextKey>` mirrors a page's `contextKey`. e.g. `context.outreachProfile`, `context.cadence`, `context.introductionWorkflow`. These are the values a user persists when clicking "Save" on a configuration input page. ### Page entry shapes (read these BEFORE writing to `context.outputPages` or `context.inputPages`) The workflow detail UI crashes on load if a page entry is missing required fields, and `validate_workflow` now rejects bad shapes with `MISSING_OUTPUT_PAGE_FIELD` / `INVALID_OUTPUT_STEPS_TYPE`. - **`context.outputPages`** — `PipelineOutputPage[]`. Authoritative example: `get_step_schema({ stepType: "outputPage", shape: "standard" })`. - Required: `id` (string, unique), `title` (string), `pathname` (string, URL slug), `outputSteps` (string[] of step IDs that exist in `workflow.steps`). - Optional: `description`, `iconName`, `displayConfig.showExecutionsList` (boolean), `displayConfig.executionNameTemplate`, `displayConfig.filterStatuses`, `displayConfig.defaultFilterStatus`, `displayConfig.sortField`, `displayConfig.sortDirection`. - Product rule: choose only the 1-3 user-facing result surfaces that match the workflow, e.g. LinkedIn publish, X/Twitter publish, scheduled email/outreach, report, or canonical results list. Group related step outputs on one page. Do not create output pages for approval placeholders, status markers, or internal implementation details. - **`context.inputPages`** — `PipelineInputPage[]`. Authoritative example: `get_step_schema({ stepType: "inputPage", shape: "standard" })`. - Required: `title`, `pathname`, `configuration.contextKey`, `configuration.fields[]`. Saved values land at `context.<contextKey>` (sibling). Both shapes are dictionaries the workflow author owns, both are read at runtime via `{{context.<key>.<field>}}`, and both are edited through this tool with the same three-verb model. To pre-fill a config page programmatically: ```jsonc update_workflow_context({ workflowId, updates: { context: { outreachProfile: { name: "Alberto", signature: "<p>Best, Alberto</p>" } } } }) ``` Sibling context keys are preserved by the one-level deep-merge. Live workflows route to draft. ## Allowed path scope (both replace and unset) Paths must begin with one of: - `context.<anything>` — page schemas (`context.inputPages`, …) or user-saved page values (`context.outreachProfile`, `context.cadence`, …). - `metadata` (exact, or any `metadata.*` sub-path). Anything else (e.g. `steps.*`, `name`, `goal`, `status`) is rejected with `PATH_OUT_OF_SCOPE`. Use `update_step` for step-level edits and `update_workflow` for top-level scalars (`name`, `goal`, `description`, `style`). ## Diff and warnings The ops shape returns `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. If ≥6 fields were silently removed without an explicit `unset`, a warning fires — that's usually a "you wiped a dictionary" signal. Read it. ## Errors (400) | Code | When | |---|---| | `EMPTY_PAYLOAD` | All three of `updates`/`replace`/`unset` are missing or empty. | | `INVALID_PATH` | Dot-path syntax violation (empty segment, leading/trailing dot, prototype-pollution segment). | | `PATH_OUT_OF_SCOPE` | Path is not under `context.<anything>` or `metadata` (e.g. `steps.*`, `name`). | | `REPLACE_VALUE_MISSING` | A `replace[]` path has no corresponding value in `updates`. | | `UNSET_PATH_NOT_FOUND` | An `unset[]` path doesn't exist on the workflow. | ## Draft routing (live workflows) Context edits are routed to a draft snapshot (`editingDraft: true`). Metadata is NOT part of the snapshot config — metadata edits write directly to the Pipeline row, **immediately and on the live workflow**. ⚠ **Mixed metadata + context in one call**: metadata is applied immediately while context goes to the pending draft. `discard_draft` reverts the pending context changes but **does NOT revert metadata**. If you need a single atomic checkpoint covering metadata too, call `create_snapshot` first, or split the call. ## Compatibility body shape A legacy `{ contextKey, value }` shape is still accepted for one-shot wholesale replacement of a single root context key (`inputPages` / `outputPages` / `executionInputConfig` only — saved-values keys are not reachable through this shape). It does not return `diff` / `warnings` and cannot edit metadata. Prefer the three-verb shape above for new code. ## Recipes ```jsonc // Add a single field to executionInputConfig.fields without rebuilding the array. // Step 1: get_workflow → read context.executionInputConfig.fields // Step 2: { updates: { context: { executionInputConfig: {...full new value with the appended field...} } }, replace: ["context.executionInputConfig"] } // Replace inputPages wholesale. { updates: { context: { inputPages: [...new pages...] } }, replace: ["context.inputPages"] } // Pre-fill a config page (user-saved values land at context.<contextKey>). // Uses one-level deep-merge under updates.context — sibling saved-values // dictionaries are preserved. { updates: { context: { outreachProfile: { name: "Alberto", signature: "<p>Best, Alberto</p>" } } } } // Wholesale-replace a single saved-values dictionary. { updates: { context: { cadence: { firstNudgeDays: 3, secondNudgeDays: 7 } } }, replace: ["context.cadence"] } // Delete a saved-values dictionary. { unset: ["context.introductionWorkflow"] } // Add a metadata tag. { updates: { metadata: { tags: ["beta"] } } } // Save an operator-facing executive summary for a workflow or workflow group. // Use this when a user asks to save a summary for the workflow, cluster, group, // or home card. Store it in metadata, not as KG text, unless the user explicitly // asks for a reusable knowledge note. For groups, write once to the owner // pipeline: prefer workflowGraph.role === "orchestrator"; otherwise use the // lowest workflowGraph.order pipeline. Keep body short, include concrete metrics // and the reporting period when available, and set author to the active // workspace agent name only (for example "AngelHive Assistant"), not the // external coding/tool agent, and without a leading "by". { updates: { metadata: { executiveSummary: { body: "Startup Outreach sent 46 founder emails for the reporting period, with 28 opens and 9 clicks: a 60.9% open rate, 19.6% click rate, and 32.1% click-to-open rate.", bullets: ["Clicks: 6 UTM Pitch Night, 2 plain Pitch Night, 1 calendar."], generatedAt: "2026-06-03T00:00:00.000Z", author: "AngelHive Assistant" } } } } // Delete an obsolete metadata key. { unset: ["metadata.legacyFlag"] } // Toggle executionInputConfig.internal: fetch first (get_workflow), merge locally, replace at the // PARENT level. The one-level deep-merge under updates.context wipes nested-object siblings BEFORE // replace[] runs (same merge-order trap as update_step) — so replace at "context.executionInputConfig" // (not ".internal") and pass the full object in updates. { updates: { context: { executionInputConfig: {...full merged executionInputConfig with internal: true...} } }, replace: ["context.executionInputConfig"] } ``` Response: `{ editingDraft?, context, metadata?, diff?, warnings?, validation }`. Requires write access when connected with OAuth.

Update top-level workspace company profile fields. Use this for company identity and summary information such as name, industry, size, logo, website URLs, and company description. Products and services live in the company.products knowledge text, not in this structured profile. Requires write access when connected with OAuth.

Write the workspace-wide executive summary shown on the Workspace Assistant card. Uses the same summary signature as cluster executive summaries: body, optional bullets, and optional author. The API writes only Workspace.metadata.executiveSummary and preserves other workspace metadata keys. Requires write access when connected with OAuth.

Update a draft workspace-created skill. Published and archived workspace skills are immutable through this tool; archive and create a new version instead. Requires write access when connected with OAuth.

Update a saved WorkspaceView by id or key. This updates only the view manifest. It does not mutate source rows, execute view actions, start workflows, make approval decisions, call providers, or spend credits. Requires write access when connected with OAuth.

Upload a file to an agent. Files provide the agent with additional context such as reference documents, knowledge bases, or configuration data. - name: Filename (e.g. 'thesis.md', 'company-context.txt') - content: Raw text or markdown content (max 400KB) - mime_type: MIME type (default: 'text/plain', use 'text/markdown' for .md files) - role: Optional label describing the file's purpose (e.g. 'knowledge', 'context') Requires write access when connected with OAuth.

Create or update the external AI builder profile linked to this authenticated API key. Clients should call this after receiving a scoped API key; workspaceId and apiKeyId are derived server-side. Setup cadence for the builder: poll every 4h when idle/no active topic, every 1h when there is an active topic or recent assigned work, every 30m while work is in progress, and opportunistically call list_builder_work_items when already engaging with the user on another topic. Requires write access when connected with OAuth.

Create or update rows in a knowledge list. Maximum 500 rows per call — paginate for larger datasets. Resolution order per row: - rows with `id` → update existing row by id - rows with `userKey` → O(1) upsert (same userKey in the same list always maps to the same row, across calls and runs — ideal for idempotent sourcing/enrichment workflows) - rows with neither → plain insert with a fresh UUID (no dedup) Pick one stable key per row. `userKey` is caller-defined: a candidateId, a normalized URL, a domain, etc. Whatever string uniquely identifies the entity within the list for your use case. mergeStrategy controls how updates are applied to existing rows: - "overwrite" (default): replace existing rowData entirely with the new values - "merge": shallow-merge new values into existing rowData (preserves downstream-added fields like scores or notes) Returns: { inserted, updated, errors[] } — errors are per-row and do not abort the batch. Requires write access when connected with OAuth.

Create or update a text-based knowledge entry. Use this to store free-form text (notes, prompts, ICP descriptions, etc.) that can be retrieved by key. Returns: { key, upserted, created }. Requires write access when connected with OAuth.

Validate a workflow's pipeline definition. Returns structured errors per step. Use this after creating or updating a workflow to check for: - Missing step connections (broken next.stepId references) - Missing required fields (app action without inputs, AI step without prompt) - Unreachable steps (not connected to the trigger chain) - Invalid app/action IDs (not in the app registry) - Missing trigger or milestone steps - List field misconfigurations (missing itemFields, defaultValue format mismatches) - Config page field validation (missing name/type on input page fields) Each error/warning may include a "suggestedFix" with a concrete remediation. You can also pass a pipeline object to validate a draft before saving. Returns: { valid: boolean, errors: [...], warnings: [...], stepCount: number }

Verify whether a native OAuth connection is currently usable without executing an app action. Returns only a provider-neutral state, safe account label, and checkedAt timestamp. States are healthy, refresh-required, reconnect-required, missing-scope, provider-unavailable, or unsupported. API-key callers receive unsupported for user-owned native OAuth connections because their tokens remain available only to the authenticated Agentled workspace UI and authorized workflow runtime. Use list_connections to inspect safe connection metadata. Ask the user to verify from Workspace Settings > Integrations or run the action through an existing workflow; do not treat test_app_action as an OAuth-token escalation path. Requires write access when connected with OAuth.