Archive

PURPOSE: Delete a Collection (a saved tag set) from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the Collection itself — its tag set and every tag association, so the tag is stripped from every item it was applied to and can no longer be used as a filter. WHAT SURVIVES: the ITEMS ARE NEVER DELETED — they lose only this one tag; every other tag, field, and piece of data on them is untouched. INPUT: - id (required string): the Collection's id, as returned by getCollections / createCollection for this workspace. Resolve ids with getCollections first — NEVER guess a Collection id. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first fetch the Collection with getCollection(id:) and CONFIRM WITH THE USER, echoing the Collection's name back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedCollectionId: null` — deleting an already-deleted Collection is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). AVAILABILITY: Collection management is available only in workspaces whose Collections use the standard storage. In a workspace that stores Collections in an older format, the ids getCollections returns are not accepted here and the call returns a userError without changing anything. OUTPUT: { deletedCollectionId: string | null, userErrors: [{ field, message }] }. `deletedCollectionId` echoes the deleted id on success, or is null when the Collection was not found. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal with getCollection(id:) — it returns null once the Collection is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteCollection

PURPOSE: Delete a saved Content View from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the saved view itself — its stored filters, sort, and settings. It disappears from the workspace's saved views. WHAT SURVIVES: the underlying CONTENT IS NEVER DELETED — the items the view listed remain in the workspace untouched; only this saved filter configuration is removed. INPUT: - id (required string): the view's canonical FilterPreset UUID (as returned by getContentViews / createContentView). Resolve ids with getContentViews first — NEVER guess. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first fetch the view with getContentView(id:) and CONFIRM WITH THE USER, echoing the view's name back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedContentViewId: null` — deleting an already-deleted view is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). OUTPUT: { deletedContentViewId: string | null, userErrors: [{ field, message }] }. `deletedContentViewId` echoes the deleted id on success, or is null when the view was not found. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal with getContentView(id:) — it returns null once the view is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteContentView

PURPOSE: Delete a saved Creator View from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the saved view itself — its stored filters, sort, and settings. It disappears from the workspace's saved views. WHAT SURVIVES: the underlying CREATORS ARE NEVER DELETED — the creators the view listed remain in the workspace untouched; only this saved filter configuration is removed. INPUT: - id (required string): the view's canonical FilterPreset UUID (as returned by getCreatorViews / createCreatorView). Resolve ids with getCreatorViews first — NEVER guess. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first fetch the view with getCreatorView(id:) and CONFIRM WITH THE USER, echoing the view's name back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedCreatorViewId: null` — deleting an already-deleted view is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). OUTPUT: { deletedCreatorViewId: string | null, userErrors: [{ field, message }] }. `deletedCreatorViewId` echoes the deleted id on success, or is null when the view was not found. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal with getCreatorView(id:) — it returns null once the view is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteCreatorView

PURPOSE: Permanently deletes the label from the whole workspace and removes it from every creator that carries it; the creators themselves are kept. This is irreversible and completes in the background — confirm with the user, echoing the label name, before calling. IRREVERSIBLE, workspace-wide. WHAT IS DESTROYED: the label itself, across the whole workspace — it leaves the label taxonomy AND is stripped from every creator that carries it, in every spelling that matches (matching ignores case and surrounding whitespace). WHAT SURVIVES: the CREATORS ARE NEVER DELETED — only the label value is removed from them. Every other label, campaign, collection and view is untouched. INPUT: - labelName (required string): the label to delete, exactly as getLabels returned it. Resolve the spelling with getLabels first — never guess. Not length-limited: a name too long to create may still exist and stays deletable. A blank name is a userError on ["labelName"]. CONFIRM BEFORE CALLING: list the labels with getLabels and CONFIRM WITH THE USER, echoing the label name back to them, before you call this tool. SCHEDULED, NOT IMMEDIATE: deletion is eventual. The label stays in getLabels (it shows `deleting: true` once the background run has marked it) and may remain in creator `customAttributes.labels` and in search until the deletion completes. Calling again while a deletion is in flight returns `scheduled: true` with the same operationId. FAILURES: a name that matches nothing in this workspace is a userError on ["labelName"] with `scheduled: false`; nothing is scheduled. The not-found check is best-effort: a concurrent delete may still yield `scheduled: true`. Lock contention or a scheduling outage is an error result, not a userError: retry it, and the retry resumes the same deletion. OUTPUT: { scheduled, operationId, labelName, userErrors: [{ field, message }] }. `labelName` echoes the name you submitted; `operationId` is null when userErrors is non-empty. VERIFY AFTER DELETE: poll getLabels until the name is ABSENT; follow progress with getOperation(id: operationId) until COMPLETED — its succeeded/failed/pending counts are always 0 for a label operation; read status, total and processed. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteLabel

PURPOSE: Delete a saved Social Profile view from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the saved view itself — its stored filters, sort, and settings. It disappears from the workspace's saved views. WHAT SURVIVES: the underlying SOCIAL PROFILES ARE NEVER DELETED — the profiles the view listed remain in the workspace untouched; only this saved filter configuration is removed. INPUT: - id (required string): the view's canonical FilterPreset UUID (as returned by getSocialProfileViews / createSocialProfileView). Resolve ids with getSocialProfileViews first — NEVER guess. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first fetch the view with getSocialProfileView(id:) and CONFIRM WITH THE USER, echoing the view's name back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedSocialProfileViewId: null` — deleting an already-deleted view is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). OUTPUT: { deletedSocialProfileViewId: string | null, userErrors: [{ field, message }] }. `deletedSocialProfileViewId` echoes the deleted id on success, or is null when the view was not found. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal with getSocialProfileView(id:) — it returns null once the view is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteSocialProfileView

PURPOSE: Delete a view group from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the view group itself — the sidebar bucket and its membership rows. It disappears from the workspace's groups. WHAT SURVIVES: the MEMBERS ARE NEVER DELETED — every Content View, Social Profile View, Creator View, and Collection that was in the group becomes ungrouped. Their FilterPreset UUIDs are returned as `movedViewIds` so you can re-file them into another group if you want. INPUT: - id (required string): the view group's UUID (as returned by getViewGroups / createViewGroup). Resolve ids with getViewGroups first — NEVER guess a group id. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first fetch the group with getViewGroup(id:) and CONFIRM WITH THE USER, echoing the group's name back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedViewGroupId: null` and `movedViewIds: []` — deleting an already-deleted group is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). OUTPUT: { deletedViewGroupId: string | null, movedViewIds: [string], userErrors: [{ field, message }] }. `deletedViewGroupId` echoes the deleted id on success, or is null when the group was not found. `movedViewIds` lists the FilterPreset UUIDs of the views and Collections that were ungrouped (empty on not-found or when the group had no members) — invalidate any cached ContentView / SocialProfileView / CreatorView / Collection rows in this list. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal with getViewGroup(id:) — it returns null once the group is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteViewGroup

PURPOSE: Delete a webhook subscription from the current workspace. This is a HARD, IRREVERSIBLE delete. WHAT IS DESTROYED: the subscription itself AND all of its delivery records (the deliveries cascade). The endpoint stops receiving any further events immediately. WHAT SURVIVES: the content views the subscription pointed at are NEVER deleted — only this subscription (and its delivery history) is removed. INPUT: - id (required string): the subscription's UUID (as returned by getWebhookSubscriptions). Resolve ids with getWebhookSubscriptions first — NEVER guess. CONFIRM BEFORE CALLING: because this is IRREVERSIBLE, first look up the subscription and CONFIRM WITH THE USER, echoing the subscription's name/url back to them, before you call this tool. FAILURES: an unknown id, an already-deleted id, or an id owned by another workspace returns a not_found userError (field ["id"]) with `deletedWebhookSubscriptionId: null` — deleting an already-deleted subscription is a safe no-op (idempotent). Same observable for unknown vs cross-workspace, on purpose (no existence leak). OUTPUT: { deletedWebhookSubscriptionId: string | null, userErrors: [{ field, message }] }. `deletedWebhookSubscriptionId` echoes the deleted id on success, or is null when the subscription was not found. `userErrors[].field` is an array of path segments (e.g. ["id"]). VERIFY AFTER DELETE: confirm removal by calling getWebhookSubscriptions — the id is gone. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

deleteWebhookSubscription

PURPOSE: Re-enable a webhook subscription in the current workspace that was AUTO-DISABLED by repeated delivery failures (status DISABLED_BY_FAILURES). Clears the failure counters and, by default, replays the last 24h of terminal FAILED deliveries (nextAttemptAt null) one-shot per row (one more attempt each, lifetime attemptCount preserved, no backoff-ladder reset) — a bounded catch-up, never a retry storm. A FAILED delivery still awaiting its scheduled retry (nextAttemptAt set) is left to the automatic retry, and `subscription.ping` deliveries are never replayed. A replayed delivery keeps its lastError / lastResponseStatus until the replay settles. INPUT: - id (required string): the failure-disabled subscription's UUID. Resolve it via getWebhookSubscriptions first (look for status DISABLED_BY_FAILURES) — never guess. - replayFailedSince24h (optional boolean, default true): when true, replays each terminal failed delivery from the last 24h once. Pass false to re-enable WITHOUT replaying the backlog. ONLY DISABLED_BY_FAILURES SUBSCRIPTIONS ARE ENABLEABLE: a subscription in any other status (active / disabled_by_user) returns a not_disabled_by_failures userError (field ["id"]) and changes nothing. An already-enabled subscription is no longer DISABLED_BY_FAILURES, so re-calling is a safe no-op not_disabled_by_failures (this is what makes the tool idempotent-safe). To resume a user-paused (DISABLED_BY_USER) subscription, use updateWebhookSubscription with status ACTIVE. FAILURES: an unknown id, or a subscription owned by another workspace, returns a not_found userError (field ["id"]) — same observable on purpose (no cross-workspace existence leak). RATE LIMIT: a re-enable within 5 minutes of the auto-disable returns a userError (field ["id"]) "Rate limit exceeded. Retry after N seconds." and changes nothing — wait the stated seconds and retry. OUTPUT: { webhookSubscription: { id, name, url, viewIds, eventTypes, metadata, status, consecutiveFailures, lastSuccessAt, disabledAt } | null, userErrors: [{ field, message }] }. On success `webhookSubscription.status` is `ACTIVE` and `consecutiveFailures` is 0. `webhookSubscription` is null on a not_found / not_disabled_by_failures / rate-limited failure. `userErrors[].field` is an array of path segments. VERIFY AFTER WRITE: confirm by calling getWebhookSubscriptions (status back to ACTIVE); if you replayed, poll getWebhookDeliveries (filter by subscriptionId) for the catch-up attempts settling. WRITE NOTES (apply to every write tool): - userErrors report domain rejections in a SUCCESSFUL tool result, NOT a crash. Atomicity is tool-specific: valid changes may apply alongside errors. Read each `field` path and `message` plus returned state; verify what applied before retrying rejected work. - Verify after write: after a success, confirm the change with the READ tool this tool's own description names (e.g. a get*/search* tool) before reporting success to the user. Deletes are confirmed when that read returns null. - Retry discipline on a timeout / transport error (you cannot tell if the write landed): `idempotentHint: true` tools MAY be retried within their documented guarantee. For every OTHER write, READ FIRST with its verify tools, including queued operations, before retrying. NEVER blind-retry non-idempotent create tools, uploadItemFromUrl or refetchEngagementBulk: duplicates create entities/imports or re-spend credits. - Destructive tools (`destructiveHint: true`) CHANGE OR REMOVE data that already exists, or trigger a real delivery attempt — they are not purely additive. Say what will change before you call one. Being destructive does NOT on its own require a confirmation round-trip; only the IRREVERSIBLE tools named below do. - IRREVERSIBLE tools — every delete*, plus mergeLabels, rotateWebhookSubscriptionSecret (the previous signing secret is gone for good) and refetchEngagementBulk (credits for refreshed items are not refunded): CONFIRM WITH THE USER first, echoing the target entity's name/id back to them, and state that the effect is IRREVERSIBLE, before you call. No other write tool needs a confirmation round-trip. - Cost: a write costs 50 + 1 per selected payload field unless its description states its own price, charged against the workspace's shared rate-limit bucket; the per-workspace throttle (below) applies. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

enableWebhookSubscription

PURPOSE: Check a Deep Research report before starting it: validates the input exactly as createDeepResearchReport would and returns its cost and whether the workspace can afford it. Creates nothing and spends nothing. INPUT: the same fields as createDeepResearchReport — inputType and templateSlug, plus the source field for that inputType (VIEW → viewId, CREATOR → creatorId, CAMPAIGN → campaignId, BRAND → brandIds). OUTPUT: { deepResearchQuote: { inputType, templateSlug, affordable, holdCredits, estimateCredits, availableCredits } }. An invalid input is an error naming the field. REFUSALS: getDeepResearchQuote and createDeepResearchReport can be refused. Retrying does not help; tell the user why. DEEP_RESEARCH_NOT_AVAILABLE: the workspace's plan does not include Deep Research. NOT_AUTHORIZED: the user's workspace role cannot spend credits, or this connection lacks write access (the user can reconnect with write access). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getDeepResearchQuote

PURPOSE: Read one Deep Research report: its progress while it runs, and once it has completed, the full report as Markdown plus its public share link. Poll this after createDeepResearchReport until running is false — reports take minutes; wait between polls. running follows the status Deep Research holds, so a report that stalls stays running true until Deep Research fails or cancels it: cap how long you poll (for example, give up once createdAt is hours old). INPUT: id (required: the report UUID from createDeepResearchReport or getDeepResearchReports). OUTPUT: { deepResearchReport: { id, status, running, phase, progressMessage, errorMessage, title, templateSlug, inputType, sourceId, sourceName, createdAt, completedAt, postsAnalyzed, shareUrl, markdown } | null }. markdown and shareUrl are null until status is COMPLETED; errorMessage says why a FAILED report failed. Returns { deepResearchReport: null } (NOT an error) when there is no such report in this workspace. REFUSALS: getDeepResearchQuote and createDeepResearchReport can be refused. Retrying does not help; tell the user why. DEEP_RESEARCH_NOT_AVAILABLE: the workspace's plan does not include Deep Research. NOT_AUTHORIZED: the user's workspace role cannot spend credits, or this connection lacks write access (the user can reconnect with write access). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getDeepResearchReport

PURPOSE: List the Deep Research reports in the current workspace, newest first, whoever started them (the Archive app or the API). INPUT: status (optional: PENDING, FETCHING, PROCESSING, COMPLETED, FAILED or CANCELLED); first (optional page size 1–100, default 20); after (optional: pageInfo.endCursor of the previous page — keep `first` the same while paging). OUTPUT: { deepResearchReports: { nodes: [{ id, status, running, title, templateSlug, inputType, sourceName, createdAt, completedAt, shareUrl, ... }], pageInfo: { hasNextPage, endCursor }, totalCount } }. status is PENDING, FETCHING or PROCESSING (in flight) or COMPLETED, FAILED or CANCELLED (final). A report also reads PROCESSING when Deep Research left it paused in a deprecated state (running false) or has it in a step this list does not name separately; the PROCESSING filter matches neither. Poll on running, not status, to know whether to keep waiting. running follows the status Deep Research holds: a report that stalls in flight stays running true until Deep Research fails or cancels it, so cap how long you poll. inputType is VIEW, CREATOR, CAMPAIGN or BRAND. Read one report's Markdown with getDeepResearchReport. REFUSALS: getDeepResearchQuote and createDeepResearchReport can be refused. Retrying does not help; tell the user why. DEEP_RESEARCH_NOT_AVAILABLE: the workspace's plan does not include Deep Research. NOT_AUTHORIZED: the user's workspace role cannot spend credits, or this connection lacks write access (the user can reconnect with write access). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getDeepResearchReports

PURPOSE: List the Deep Research report templates this workspace can run — the same list the Archive app offers. Start here: a report needs a template slug and a source type the template accepts. INPUT: inputType (optional: VIEW, CREATOR, CAMPAIGN or BRAND) — only templates that run on it. OUTPUT: { deepResearchTemplates: [{ slug, name, description, inputTypes, audienceComments, brandThreads }] }. audienceComments / brandThreads are NOT_SUPPORTED, OPTIONAL or REQUIRED. inputTypes lists only VIEW, CREATOR, CAMPAIGN and BRAND; a template is listed when it runs on at least one of them and its audienceComments / brandThreads are one of the values above. NEXT: getDeepResearchQuote with a slug, then createDeepResearchReport. REFUSALS: getDeepResearchQuote and createDeepResearchReport can be refused. Retrying does not help; tell the user why. DEEP_RESEARCH_NOT_AVAILABLE: the workspace's plan does not include Deep Research. NOT_AUTHORIZED: the user's workspace role cannot spend credits, or this connection lacks write access (the user can reconnect with write access). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getDeepResearchTemplates

PURPOSE: Look up a single campaign by id in the current workspace, with its type, externalId, dates and roster size. INPUT: id (required string — the campaign UUID as returned by createCampaign or getCampaigns). OUTPUT: { campaign: { id, name, createdAt, campaignType, externalId, dateStart, dateEnd, tagNames, creatorsCount } | null }. campaignType is CREATOR_MONITORING or CONTENT_CAPTURE, or null for a campaign of a type the API does not expose (such a campaign cannot be changed with updateCampaign). externalId is null for a campaign created in the Archive app. dateStart / dateEnd are UTC, null when the campaign has none. tagNames is the stored settings.creatorMonitoring.tagNames of a CREATOR_MONITORING campaign (empty captures every post), null for another type. creatorsCount counts the creators on the roster now; creators added with updateCampaign join it once their background import resolves them. Returns { campaign: null } (NOT an error) when no campaign with that id exists in the current workspace: an unknown id, an id owned by another workspace, or an internal workflow row that getCampaigns does not list either — the same observable, on purpose. Use getCampaigns to list campaigns; createCampaign / updateCampaign to create or change one. Read a campaign's posts with searchItems using filter.campaignsIds. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCampaign

PURPOSE: Look up a single Collection (saved tag set) by id in the current workspace. INPUT: id (required string — a Collection id as returned by getCollections / createCollection for this workspace). Ids differ between workspaces depending on how each one stores Collections, so always resolve the id through getCollections rather than constructing or reusing one. OUTPUT: { collection: { id, name, customAttributeOptionId, itemCount, group: { id, name } | null } | null }. Returns { collection: null } (NOT an error) when no Collection with that id exists in the current workspace (unknown id, or id owned by another workspace — same observable, on purpose). `customAttributeOptionId` is the Collection's option id in the ITEM "collections" custom attribute — the value a "collections" custom-attribute condition takes, different from `id`; null where the workspace uses the older Collection storage. `itemCount` is the number of items tagged with the Collection in this workspace. `group` is the view group the Collection belongs to (set with moveCollectionToGroup), or null when ungrouped — always null where the workspace uses the older Collection storage. In workspaces whose Collections are preset-backed you can pair the returned `id` with searchItems(presetId:) to fetch the items tagged with the Collection; that pairing does not apply where the workspace uses the older storage. Creating/renaming/deleting a Collection (createCollection / updateCollection / deleteCollection) is available only in workspaces whose Collections use the standard storage — where the workspace uses the older storage those calls return a userError and change nothing. Tagging items with addItemToCollections / removeItemFromCollections works in both. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCollection

PURPOSE: Look up a single Competitor Insights brand by id in the current workspace, with aggregate metrics over a period/date window. Also resolves the workspace's own brand by its stable id (isOwnBrand: true). INPUT: id (required string, the brand's Archive id), optional period ("WEEK"|"MONTH", default "MONTH") and date (ISO date, defaults to the latest complete month or week; a later date is moved back to it). OUTPUT: { id, name, displayName, isOwnBrand, earnedMediaValue, engagementsTotal, impressions, reach, postsCount, influencersCount, ownMetricsStatus, ownMetricsHasData } on success. displayName is the name the Archive app shows: the brand name for competitors, the linked own brand's name for the own entry ("You" when none is linked). For the own entry, ownMetricsStatus is AVAILABLE (null metrics then mean no data in the window) or UNAVAILABLE (retry later); it is null for competitors. ownMetricsHasData is true when AVAILABLE metrics carry data, false when AVAILABLE but the window has no own-brand data (the null metrics are missing, not zero), and null for competitors or when UNAVAILABLE. Returns an isError tool result with the text "Competitor brand not found" when no brand with that id is tracked in the current workspace (unknown id, or known id tracked only by another workspace — same observable, on purpose). WARNINGS: If the metrics store is temporarily unavailable, brand identity data is still returned with null metrics and a `warnings` array containing the message below. An own-brand result has ownMetricsStatus "UNAVAILABLE". Back off for minutes before retrying; do not immediately repeat the call. "Competitor metrics are temporarily unavailable. Retry later." RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCompetitorBrand

PURPOSE: Look up a single saved Content View by id in the current workspace. INPUT: id (required string, the content view's Archive id / FilterPreset UUID). OUTPUT: { contentView: { id, name, filters, customAttributeConditions, sort, showReportingStats, group } | null }. Returns { contentView: null } (NOT an error) when no media_deck view with that id exists in the current workspace (unknown id, id owned by another workspace, or a view hidden in the Archive app — same observable, on purpose). Pair the returned `id` with searchItems(presetId:) to fetch the items belonging to the view. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getContentView

PURPOSE: Look up a single creator (influencer) by id in the current workspace. INPUT: id (required string, the creator's Archive id). OUTPUT: { id, customAttributes } on success. Returns an isError tool result with the text "Creator not found" when no creator with that id exists in the current workspace (unknown id, or known id owned by another workspace — same observable, on purpose). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCreator

PURPOSE: Look up a single saved Creator View by id in the current workspace. INPUT: id (required string — the Creator View's Archive id / FilterPreset UUID, as returned by getCreatorViews). OUTPUT: { creatorView: { id, name, filters, customAttributeConditions, sort, showReportingStats, group } | null }. Returns { creatorView: null } (NOT an error) when no creator view with that id exists in the current workspace (unknown id, id owned by another workspace, or a view hidden in the Archive app — same observable, on purpose). Pair the returned `id` with searchCreators(presetId:) to fetch the view's creators. To create/update/delete use createCreatorView / updateCreatorView / deleteCreatorView. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCreatorView

PURPOSE: List custom attribute schemas for the current workspace, used both to INTERPRET values in the `customAttributes` JSON field on items/creators AND to BUILD `customAttributeConditions` filters for searchItems / searchCreators. INPUT: entity (required: "ITEM" or "CREATOR"). ITEM → schemas attached to items (`shop_item`); CREATOR → schemas attached to creators. OUTPUT: { items: [{ key, name, type, aiGenerated, options: [{ id, name }] }] } - `key` matches a top-level field inside the entity's customAttributes hash (and is the `field` in a filter condition). - `type` is the upper-case attribute type (TEXT, SINGLE_SELECT_V2, MULTIPLE_SELECT_V2, etc.) — pass it as `type` in a filter condition. - `aiGenerated` is true when the attribute's value is produced by an AI Filter; searchItems returns the model's explanation for those keys in each item's `aiFilterReasons`. - `options` is `[]` for non-select schemas; for select-type schemas each option's `id` is what appears as the value (or array element) in customAttributes and is the `value` you pass when filtering on that field. CUSTOM ATTRIBUTE FILTERS (customAttributeConditions): Filter by the workspace's user-defined custom fields. An array of { field, operator, type, value } objects; multiple entries are AND-ed together. Step 1 - discover fields: call getCustomAttributeSchemas(entity: ITEM | CREATOR). Each schema returns `key` (use as `field`), `type` (use as `type`), and `options: [{ id, name }]` for select fields (use an option `id` as `value`). Step 2 - build each condition: - field : the schema `key` (e.g. "sentiment", "links"). - type : the schema `type`, UPPERCASE - one of TEXT, EMAIL, PHONE, URL, NUMBER, BOOLEAN, DATE, DATETIME, SINGLE_SELECT_V2, SINGLE_SELECT_V3, MULTIPLE_SELECT, MULTIPLE_SELECT_V2, TEXT_LIST, NUMBER_LIST, DATE_LIST, DATETIME_LIST, BOOLEAN_LIST. - operator : UPPERCASE; the valid set depends on the field's type group (see below). - value : depends on `type`: * TEXT / EMAIL / PHONE / URL -> a string. * SINGLE_SELECT_V2 / SINGLE_SELECT_V3 -> option `id` (UUID), or with no options in the schema (e.g. `sentiment`) the stored string ("Positive"). * NUMBER -> a number; BETWEEN takes { from, to }. * DATE / DATETIME -> ISO-8601 string; BETWEEN takes { from, to }. * BOOLEAN -> true / false. * MULTIPLE_SELECT / MULTIPLE_SELECT_V2 -> array of at least one option `id`. * TEXT_LIST / NUMBER_LIST / DATE_LIST / ... -> array of values. * IS_EMPTY / IS_NOT_EMPTY -> value is ignored; pass null. Operators by type group (an operator outside its group, or a SHIPPING_ADDRESS-typed condition, is rejected with an error naming the field): - Text & single-select (TEXT, EMAIL, PHONE, URL, SINGLE_SELECT_V2, SINGLE_SELECT_V3): IS, IS_NOT, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH, IS_EMPTY, IS_NOT_EMPTY. (IS / IS_NOT are exact match on the select value described above.) - Number (NUMBER): EQUAL, NOT_EQUAL, MORE_THAN, MORE_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, BETWEEN, IS_EMPTY, IS_NOT_EMPTY. - Date (DATE, DATETIME): EQUAL, NOT_EQUAL, MORE_THAN, MORE_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, BETWEEN, IS_EMPTY, IS_NOT_EMPTY, IS_RELATIVE_TO_TODAY. IS_RELATIVE_TO_TODAY value: { relation: "past"|"this"|"next", period: "day"|"week"|"month"|"year" } with an optional whole-number offset (at most 100 years) and an optional IANA time zone "tz". - Boolean (BOOLEAN): IS (value true / false). - Multi-value (MULTIPLE_SELECT, MULTIPLE_SELECT_V2, and every *_LIST type): CONTAINS (matches ANY of the values, OR), CONTAINS_ALL (must contain ALL, AND), DOES_NOT_CONTAIN, IS_EMPTY, IS_NOT_EMPTY. NOTE: post_summary and shipping_address are stored but NOT indexed: positive operators match NOTHING, negated ones (IS_NOT, DOES_NOT_CONTAIN, IS_EMPTY) match EVERY record — read them from each item's `customAttributes` instead. NOTE: on items, `post_date` is the post time: DATE/DATETIME with a plain date (whole UTC day), datetime, { from, to } or IS_RELATIVE_TO_TODAY; NOT_EQUAL, IS_EMPTY and "$now" are rejected. `labels` takes the multi-value operators with label NAMES as values (its schema lists no options), matched CASE-SENSITIVELY, unlike the label tools. A blank `field` or an empty option list is rejected, as is a string value starting with "$" other than "$now". At most 20 conditions; a string value at most 256 characters; at most 50 values per list (500 option ids for a multi-select). Details: README §5.3. Examples: [{ "field": "sentiment", "operator": "IS", "type": "SINGLE_SELECT_V2", "value": "Positive" }] [{ "field": "links", "operator": "CONTAINS", "type": "TEXT_LIST", "value": ["https://example.com/promo"] }] [{ "field": "lead_score", "operator": "BETWEEN", "type": "NUMBER", "value": { "from": 10, "to": 100 } }] [{ "field": "notes", "operator": "IS_NOT_EMPTY", "type": "TEXT", "value": null }] RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCustomAttributeSchemas

PURPOSE: Paginated history of engagement metric snapshots for a single item, newest first. INPUT: itemId (required string). Optional cursor, limit (default 20, max 100), and filter { capturedAt: { from, to } } (ISO-8601 date-time bounds, UTC only — offsets other than Z/+00:00/-00:00 are rejected; both bounds are optional). An unknown or foreign itemId returns an isError result with the coded text "Item not found". OUTPUT: { items: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. Each item node is { at, likes, comments, views, shares, impressions, earnedMediaValue, followers, linearViralityScore }. Metric values in nodes may be null when data has not been captured. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getEngagementHistory

PURPOSE: Retrieve media contents (images / videos) for shop items OR for tracked Competitor Insights items in the current workspace. INPUT: exactly one of itemIds (Item / shop-item UUIDs) OR competitorBrandItemIds (CompetitorBrandItem UUIDs from getCompetitorBrandItems). Each is an array of 1..100 string IDs. Passing both, or neither, returns an isError result. OUTPUT: { items: [...] } — one node per media-content row. Each node carries id, mediaItemId, type, fileUrl, thumbnailUrl, width, height, deleted; videos additionally carry videoDuration. NOTE: fileUrl and thumbnailUrl are raw CDN URLs (unsigned); YouTube nodes always have fileUrl: null and thumbnailUrl may be null. Unknown, cross-workspace, or non-entitled competitor item IDs yield zero rows (not an error). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getMediaContents

PURPOSE: Look up a single async operation by id in the current workspace — poll its status and progress (e.g. after refetchEngagementBulk). INPUT: id (required string, the operation's Archive id). OUTPUT: { id, status, operationType, total, processed, succeededCount, failedCount, pendingCount, succeededItemIds, failedItemIds, pendingItemIds, itemIdsTruncated, createdAt, completedAt, failedRecordsCsvUrl, successfulRecordsCsvUrl, importSource } on success (completedAt is null until the operation finishes). The three counts are always exact. Each item-id list holds at most 1000 ids: when itemIdsTruncated is true some ids were omitted — use the counts for exact sizes and page through getOperationRecords for the remaining ids; do not report a partial list as the whole outcome. For a creator import (operationType oneschema_creator_import) the three lists are always empty and itemIdsTruncated is false: its records are uploaded rows, not items — page through getOperationRecords for them. A label operation (delete_label, rename_label, merge_labels) keeps no per-item records: its succeededCount / failedCount / pendingCount are always 0 and its lists empty, even when COMPLETED, so they do not add up to processed. Read status, total and processed for its progress. Counts and id lists are separate reads: while status is QUEUED or PROCESSING they are a moving snapshot and may briefly disagree as records finish; on a terminal status records no longer change, so the response is exact and self-consistent. status values: QUEUED (not yet started), PROCESSING (in progress), COMPLETED (all items succeeded — terminal), PARTIAL (finished with some failures — terminal), FAILED (all items failed — terminal). Returns an isError tool result with the text "Operation not found" when no operation with that id exists in the current workspace (unknown id, or known id owned by another workspace — same observable, on purpose). CREATOR IMPORT: this is where to poll a creator import (operationType oneschema_creator_import) until its status is terminal. failedRecordsCsvUrl and successfulRecordsCsvUrl are download links valid for 1 hour, written shortly after a PARTIAL or FAILED import finishes, null otherwise; importSource is CSV_UPLOAD or PUBLIC_API. All three are null for every other operation type. Page through getOperationRecords for each row's handles, creatorId and error. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getOperation

PURPOSE: Page through the per-item records of one operation, newest first — the follow-up to getOperation when itemIdsTruncated is true, and the way to enumerate an operation's items with their per-item status. INPUT: operationId (required string), optional status filter (SUCCEEDED | FAILED | PENDING — PENDING covers not-started, in-progress and retrying records), optional cursor, limit (default 100, max 1000). OUTPUT: { records: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. Each record is { itemId, status }; itemId is a documented input to getMediaContents / getTranscriptions. totalCount is the exact number of records matching the filter. Returns an isError tool result with the text "Operation not found" when no operation with that id exists in the current workspace, and "Invalid cursor" for a cursor this connection did not issue. CREATOR IMPORT: each record also carries { handles, creatorId, errorCode, errorMessage }, filled for the rows of a creator import (operationType oneschema_creator_import) and null for every other operation type. On those rows itemId is the row key within the import (import_0, ...), not an item id. handles lists the row's [{ provider, handle }] (null for rows stored in a format it cannot read); creatorId is the creator a SUCCEEDED row created or updated, an input to getCreator; errorCode and errorMessage say why a FAILED row failed, the message in words fit to show a person. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getOperationRecords

PURPOSE: Look up ONE social profile (influencer) in the current workspace. For MANY profiles do NOT loop this per id — call getSocialProfiles once to list/filter a whole page of profiles in a single call (the batch path). INPUT: provide EXACTLY ONE of: - id (the social profile's Archive id), OR - accountName + provider (provider is one of instagram, tiktok, youtube). Optional fallback (default false): when true and the profile is not archived locally, fetch it live from the social platform (slower). Passing both id and accountName/provider, or accountName without provider, or neither, returns an isError result. OUTPUT: { socialProfile: { id, provider, originalUrl, accountName, avatar, private, verified, followers, following, fullName, email, phoneNumbers, proAccount, creator { id } } } on success, or { socialProfile: null } when no profile matches in the current workspace (workspace-scoped lookup; profiles archived only in other workspaces are treated as misses and return null, not an error). With fallback: true a miss may instead return isError: true with one of: - "Upstream social-platform service is temporarily unavailable. Please retry." (UPSTREAM_UNAVAILABLE code in extensions — safe to retry); - a PROVIDER_ERROR message from the platform (e.g. rate-limited); - "User not found on <provider>." (the account does not exist on the platform). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getSocialProfile

PURPOSE: Look up a single saved Social Profile view by id in the current workspace. INPUT: id (required string — the Social Profile view's Archive id / FilterPreset UUID, as returned by getSocialProfileViews). OUTPUT: { socialProfileView: { id, name, filters, customAttributeConditions, sort, showReportingStats, group } | null }. Returns { socialProfileView: null } (NOT an error) when no social-profiles view with that id exists in the current workspace (unknown id, id owned by another workspace, or a view hidden in the Archive app — same observable, on purpose). Pair the returned `id` with getSocialProfiles(presetId:) to fetch the view's social profiles. To create/update/delete use createSocialProfileView / updateSocialProfileView / deleteSocialProfileView. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getSocialProfileView

PURPOSE: Fetch transcriptions for the media contents of one or more items in the current workspace. INPUT: itemIds (required) — an array of 1..1000 Item UUIDs. OUTPUT: { items: [...] } — one node per media content that has a non-empty transcript across the requested items. Each node carries mediaContentId and transcript. Items with no (or only empty) transcriptions yield no rows. NOTE: v0 exposes only the itemIds (Elasticsearch) path; the deferred mediaContentIds (DB) path is not available. NOTE: rate-limit cost scales with the number of itemIds but is capped at 100 — a request with more than 100 ids (up to the 1000 max) is charged as 100. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getTranscriptions

PURPOSE: Look up a single user-created view group by id in the current workspace, including its member views. INPUT: id (required string — the ViewGroup UUID as returned by getViewGroups / createViewGroup). OUTPUT: { viewGroup: { id, name, contentViews: [{ id, name }], socialProfileViews: [{ id, name }], creatorViews: [{ id, name }], collections: [{ id, name }] } | null }. Member views carry id and name only — fetch a member's configuration (filters, sort, …) with getContentView / getSocialProfileView / getCreatorView / getCollection. `contentViews`, `socialProfileViews`, `creatorViews`, and `collections` enumerate the group's members in their within-group position order (ties break on id for a stable order). CAMPAIGN Creator Views are never group members (they are campaign-scoped, not workspace-scoped) — workspace Creator Views ARE groupable and appear in `creatorViews`. Returns { viewGroup: null } (NOT an error) when no group with that id exists in the current workspace (unknown id, or id owned by another workspace — same observable, on purpose). To create/rename/delete a group use createViewGroup / updateViewGroup / deleteViewGroup; to move a view into/out of a group use moveContentViewToGroup / moveSocialProfileViewToGroup / moveCreatorViewToGroup / moveCollectionToGroup. reorderViewsInGroup rewrites member positions — read the full member list from this tool first, since a reorder that omits members leaves their positions unchanged. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getViewGroup

PURPOSE: Get the workspace's outbound-webhook caps and its current usage, so you can check headroom before createWebhookSubscription / updateWebhookSubscription instead of hitting a limit userError. INPUT: none (beyond the workspace selector). OUTPUT: { limits: { tier, maxSubscriptions, usedSubscriptions, maxViewsPerSubscription, metadataMaxBytes, capsSource } } usedSubscriptions counts subscriptions in any status. capsSource is the highest override level that replaced at least one cap: "workspace_override", "org_override", or "plan" (both caps are tier defaults). Each cap resolves on its own, so "workspace_override" does not mean both caps came from the workspace. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getWebhookLimits

PURPOSE: Get a workspace — its tracked hashtags/mentions/keywords and connected social integrations — in one call. The workspace is selected by the optional `workspaceId` argument (falling back to the `WORKSPACE-ID` header, or your sole workspace when you can access exactly one). Call getWorkspaces first to discover the ids you can access. INPUT: optional workspaceId — the workspace UUID (from getWorkspaces) or the numeric workspace id shown in the Archive app. OUTPUT: { workspace: { id, name, hashtags: [...], mentions: [...], keywords: [...], integrations: [...] } }. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getWorkspace

PURPOSE: List campaigns for the current workspace, newest first. INPUT: optional cursor, limit (default 20, max 100). No filter, no sorting (results are always newest first). OUTPUT: { campaigns: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. Each campaign node is { id, name, createdAt }. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCampaigns

PURPOSE: List Collections (saved tag sets) for the current workspace, in the workspace's saved display order. INPUT: none (beyond the workspace selector). OUTPUT: { items: [{ id, name, customAttributeOptionId, itemCount, group: { id, name } | null }] } `id` is the id this workspace accepts for addItemToCollections / removeItemFromCollections and for getCollection(id:). ALWAYS take Collection ids from this tool — never construct them, cache them, or reuse one across workspaces. Some workspaces store Collections in an older format and their ids look different; the ids listed here are always the ones that workspace accepts. `customAttributeOptionId` is the Collection's option id in the ITEM "collections" custom attribute (getCustomAttributeSchemas entity ITEM). It differs from `id`: use it as the value of a "collections" custom-attribute condition and to match an item's customAttributes.collections. Null where the workspace uses the older Collection storage. `itemCount` is the number of items in this workspace tagged with the Collection. `group` is the view group the Collection belongs to (set with moveCollectionToGroup), or null when ungrouped — always null where the workspace uses the older Collection storage. In workspaces whose Collections are preset-backed you can pair a Collection's `id` with searchItems(presetId:) to fetch the items tagged with that Collection; that pairing does not apply where the workspace uses the older storage. Creating/renaming/deleting a Collection (createCollection / updateCollection / deleteCollection) is available only in workspaces whose Collections use the standard storage — where the workspace uses the older storage those calls return a userError and change nothing. Tagging items with addItemToCollections / removeItemFromCollections works in both. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCollections

PURPOSE: Paginate posts attributed to a single tracked Competitor Insights brand within a required `takenAt` time window. INPUT: brandId (required string, the brand's Archive id — not an ISO-8601 date-time); takenAtFrom and takenAtTo (required ISO-8601 date-time, UTC only — offsets other than Z/+00:00/-00:00 are rejected); optional sorting ({ sortKey: TAKEN_AT|EARNED_MEDIA_VALUE, sortOrder: ASC|DESC }, default TAKEN_AT DESC), limit (default 20, max 100), cursor, responseFormat (concise | detailed, default detailed — see OUTPUT). An unknown or foreign brandId returns an empty connection (not an error). EARNED_MEDIA_VALUE ranks posts as one ordering across the whole window. OUTPUT: { items: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. responseFormat "detailed" (default) returns the full per-node shape; "concise" trims each node to id, takenAt, provider, type, originalUrl, caption, socialProfile { id accountName }, and currentEngagement — for listing / filtering / ranking. NOTE: a month's posts become available on day 9 of the following month — the current month is never queryable. The cursor is positional — pass pageInfo.endCursor back with the same brandId, takenAtFrom/takenAtTo, and sorting; responseFormat may change freely between pages. A malformed cursor (including one minted before the ClickHouse cutover) is rejected with "Invalid cursor", and pagination depth is capped at 10,000 posts per query — narrow the takenAt window to go deeper. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCompetitorBrandItems

PURPOSE: List Competitor Insights brands tracked for the current workspace, newest first, with aggregate metrics over a period/date window, so self-vs-competitor Share of Voice is computable in one call. INPUT: optional cursor, limit (default 20, max 100), period ("WEEK"|"MONTH", default "MONTH"), date (ISO date, defaults to the latest complete month or week; a later date is moved back to it). No filter, no sorting (results are always newest first). OUTPUT: { brands: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. Each brand node is { id, name, displayName, isOwnBrand, earnedMediaValue, engagementsTotal, impressions, reach, postsCount, influencersCount, ownMetricsStatus, ownMetricsHasData }. The workspace's own brand is returned as one additional pinned node on the first page (isOwnBrand: true, name "You"; displayName is the linked own brand's name as the Archive app shows it, or "You" when none is linked), in addition to up to `limit` competitor brands; totalCount counts competitor brands only and excludes the own entry. For the own entry, ownMetricsStatus is AVAILABLE (null metrics then mean no data in the window) or UNAVAILABLE (retry later); it is null for competitors. ownMetricsHasData is true when AVAILABLE metrics carry data, false when AVAILABLE but the window has no own-brand data (the null metrics are missing, not zero), and null for competitors or when UNAVAILABLE. WARNINGS: If the metrics store is temporarily unavailable, the roster is still returned with null metrics, ownMetricsStatus "UNAVAILABLE", and a `warnings` array containing the message below. Back off for minutes before retrying; do not immediately repeat the call. "Competitor metrics are temporarily unavailable. Retry later." RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCompetitorBrands

PURPOSE: List saved Content Views for the current workspace, ordered most-recently-updated first. INPUT: optional groupId (filters to one group; omitted/null returns all Content Views). Views hidden in the Archive app are never returned. An unknown or foreign groupId returns an empty list (not an error). OUTPUT: { items: [{ id, name, filters, customAttributeConditions, sort, showReportingStats, group }] } Pair an item's `id` with searchItems(presetId:) to fetch the items belonging to a view. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getContentViews

PURPOSE: List saved Creator Views for the current workspace, ordered most-recently-updated first. INPUT: optional groupId (filters to one group; omitted/null returns all creator views). Views hidden in the Archive app are never returned. An unknown or foreign groupId returns an empty list (not an error). OUTPUT: { items: [{ id, name, filters, customAttributeConditions, sort, showReportingStats, group }] } Pair an item's `id` with searchCreators(presetId:) to fetch the view's creators. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getCreatorViews

PURPOSE: DEPRECATED — prefer the typed view tools getContentViews (accessor MEDIA_DECK) and getCollections (accessor COLLECTIONS); their ids work the same way as a presetId input. This tool still lists saved filter presets for the current workspace (no removal window announced), but new integrations should not adopt it. Use the returned id as `presetId:` when calling items(...) to scope a search to the preset's saved filter set. INPUT: none (no arguments). OUTPUT: { items: [{ id, name, accessor }, ...] }. `accessor` is one of "MEDIA_DECK" or "COLLECTIONS" (the resolver only exposes those two; presets with other accessors or `visible: false` are filtered out). Ordered by the workspace's default group position, then by creation time. Empty workspaces return `{ items: [] }`. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getFilterPresets

PURPOSE: List the creator labels of the current workspace, alphabetically by name (case-insensitive). Symbols and emoji follow the database collation, not code-point order (e.g. "zz-🎉" sorts before "zz-alpha"). INPUT: none (beyond the workspace selector). OUTPUT: { items: [{ name, deleting }] } `name` is the label's identity; labels have no id in this API. Pass a name back exactly as returned. The label tools match names ignoring case and surrounding whitespace; the `labels` customAttributeConditions filter on searchCreators matches the exact, case-sensitive name. A label with `deleting: true` is being removed; do not assign it, and do not recreate it until it disappears from getLabels. Capped at 1000 entries and not paginated. VERIFY-AFTER-WRITE TARGET: call this after any label change in this workspace, including labels that importCreators registers, and confirm the name is present (or gone). RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getLabels

PURPOSE: List operations for the current workspace, newest first. Only `refetch_engagement`, creator-import, label operations (delete_label, rename_label, merge_labels) and creator label bulk operations are listed here; an operation id visible via getOperation may be absent from this list if it is of another internal type. A label operation's record counts are always 0 — read status, total and processed. INPUT: optional cursor, limit (default 20, max 100). No filter, no sorting (results are always newest first). OUTPUT: { operations: [...], pageInfo: { hasNextPage, endCursor }, totalCount }. Each operation node is { id, status, operationType, total, createdAt }. status values: QUEUED (not yet started), PROCESSING (in progress), COMPLETED (all items succeeded — terminal), PARTIAL (finished with some failures — terminal), FAILED (all items failed — terminal). CREATOR IMPORT: the list also holds the workspace's creator imports (operationType oneschema_creator_import). Poll an import with getOperation and read its rows with getOperationRecords. LABEL BULK: the list also holds creator label bulk operations (operationType update_custom_attributes for bulkAddLabelsToCreators, remove_custom_attributes for bulkRemoveLabelsFromCreators, and the same bulk edits made in the Archive app); those carry one record per creator — read them with getOperationRecords. No other custom-attribute edit is listed. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getOperations

PURPOSE: List saved Social Profile views for the current workspace, ordered most-recently-updated first. INPUT: optional groupId (filters to one group; omitted/null returns all social-profile views). Views hidden in the Archive app are never returned. An unknown or foreign groupId returns an empty list (not an error). OUTPUT: { items: [{ id, name, filters, customAttributeConditions, sort, showReportingStats, group }] } Pair an item's `id` with getSocialProfiles(presetId:) to fetch the view's social profiles. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getSocialProfileViews

PURPOSE: List social profiles (Instagram / TikTok / YouTube accounts) tracked for the current workspace, profiles with the most recent content first. This is the batch / multi-profile path — reach for it instead of calling getSocialProfile once per id when you need more than one profile. INPUT (all optional): - filter (object): a SocialProfileFilterInput. Fields: * platform: one of INSTAGRAM, TIKTOK, YOUTUBE, INTERNAL. - presetId (string): a saved Social Profile View id (from getSocialProfileViews / getSocialProfileView). When set, the view's stored customAttributeConditions and sort drive the results and the inline filter argument is IGNORED (the view's `filters` blob is never applied on read). A non-Social-Profile-View id returns a coded error with extensions.code = "WRONG_VIEW_TYPE"; an unknown or foreign id returns extensions.code = "NOT_FOUND" (cross-workspace ids collapse to NOT_FOUND — no enumeration leak). - cursor (string), limit (integer, default 20, max 100). Cursor note: pass pageInfo.endCursor only — per-node edge cursors are not valid here. - responseFormat (string): "concise" or "detailed" (default) — see OUTPUT. No sorting argument — results are most-recent-content first (a preset's stored sort overrides this). OUTPUT: { socialProfiles: [{ id, provider, originalUrl, accountName, avatar, private, verified, followers, following, fullName, email, phoneNumbers, proAccount, creator { id } }], pageInfo: { hasNextPage, endCursor }, totalCount } responseFormat "detailed" (default) returns the node shape above; "concise" returns { id, accountName, provider, followers, verified } per node — for listing / filtering / ranking. Use "detailed" when contact fields (email, phoneNumbers, fullName) or the full profile shape are needed. NOTE: no inline custom-attribute filter exists on this query — to narrow by custom attributes, create/point at a Social Profile View with customAttributeConditions (createSocialProfileView) and pass its id as presetId. RUNTIME NOTES: - Rate limiting: a weighted per-workspace rate limit is enforced on every call. A throttled call returns isError text: "Rate limit exceeded. Retry after N seconds." - Argument validation: arguments failing schema validation return isError text like "Invalid argument '$.<path>': <reason>". - Unexpected failures: any other error returns isError text "Tool execution failed".

getSocialProfiles