Shruwd

Mention rate and share of voice for the brand and each competitor on one engine over a window (default: last 30 days), plus per-prompt coverage. Each metric is {state: "ok", point, lo, hi, n} — a proportion with its 95% interval — or {state: "insufficient_data"} when fewer than ten responses exist, or {state: "undefined"}. A metric with state insufficient_data is NOT zero; do not report it as a number, and do not compare two metrics whose intervals overlap as if one were higher. "asOf" is the day the numbers describe. "historyFrom" is set when the window was clamped to the plan's history. "modelIds" lists the provider models seen; a change there can move metrics on its own. engine defaults to google_aio: call once per engine the brand measures (its engines) and report each separately.

shruwd_get_visibility

The window metric at every cycle close in a range (default: the last ninety days, 30-day window): for the brand and each competitor, mention rate and share of voice per close, each a {state: "ok", point, lo, hi, n} metric or an explicit non-number. Use it to answer "is this changing" — but two points whose intervals overlap have NOT moved, and a change across a "modelChanges" entry may be the provider's model rather than the brand (the comparison is confounded). "series" is index-aligned with "points"; null means no rollup row for that close.

shruwd_get_visibility_series

The plan, the entitlements in force (brands, the workspace-wide prompt pool, members, engines, cadence, history window, rechecks per month, and maxVisibleFindings — how many findings the plan shows in full), usage against the period allowance including activePrompts against promptsAllowance, whether the caller is the workspace owner or a member, and the brands the caller can reach with their role on each. Call this first: the role on a brand decides which of these tools are allowed on it. Usage is the whole workspace's, since the pools are shared.

shruwd_get_workspace

The active brands the caller can reach, with their prompt and competitor counts and the caller's role on each.

shruwd_list_brands

Names the AI answers use that the brand does not track yet — the products a person would recognise as competitors but never added. Each comes with the share of answers that named it (e.g. 0.34 = in 34% of a prompt cluster's responses) and, when the answers linked it, its domain. Review them with the user: accept the real competitors (they then count in share of voice), dismiss the rest. Suggestions appear only after a measurement cycle has closed.

shruwd_list_suggestions

Recent measurement cycles, newest first, with state (pending, running, complete, partial, failed, skipped_quota) and run counts. "partial" means some runs failed; "skipped_quota" means the allowance, the plan or billing stopped it. On a weekly plan the newest is next week's cycle, still pending: the newest that is not pending is the current measurement, and its results are in once it is complete or partial.

shruwd_list_cycles

The brand itself (isSelf) and every competitor, each with the exact aliases, domains, exclusions and context terms that decide what counts as a mention or a citation.

shruwd_list_entities

Diagnoses, ordered by severity, then confidence, then estimated impact. Each has a specific recommendation: what to change, where, and which metric should move. confidence: "observed" was measured from first-party data; "inferred" follows a reliable pattern; "heuristic" is a plausible cause that could not be confirmed — treat it as a hypothesis, not a fact. By default the open, acknowledged, fix_applied and rechecking findings; pass states to change that. "queued" counts open findings held back by the weekly cap. On plans that cap visible findings, "locked" counts the rest by severity: they exist and are not returned. When locked.count is above zero, never present the returned findings as the complete set — say how many are withheld.

shruwd_list_findings

The latest individual AI answers for the brand, newest first: the prompt, the engine, whether the brand was named and at what rank, the competitors named and the pages cited. Evidence, not a metric: never compute a rate from these; use shruwd_get_visibility, which withholds numbers below ten answers.

shruwd_list_answers

The brand's prompts. With an engine, each prompt carries its coverage over the window: how often the brand was mentioned in answers to it. Per-prompt n is small (three repetitions per cycle), so coverage is often insufficient_data; that is correct, not missing data.

shruwd_list_prompts

Closes a competitor as of now. The brand's own entity cannot be removed.

shruwd_remove_entity

Deactivates a prompt. Nothing is deleted; its history stays readable.

shruwd_remove_prompt

Schedules a measurement cycle now: every active prompt, on every entitled engine, repeated as the plan sets (three times on weekly plans, once for the free snapshot). It starts at once and completes over the following day; this response contains only the cycle id. Watch it with shruwd_list_cycles, then read shruwd_get_visibility and shruwd_list_findings. A cycle spends the period's run allowance (see shruwd_get_workspace); weekly plans already run one per week, so use this for a first read or after a change worth measuring. On the free tier it is the single free measurement.

shruwd_run_measurement

Sets the DESIRED aliases, domains, exclusions and context terms of an entity (the brand's own self entity included). Send the full lists: what is missing is closed as of now, what is new is added, what is unchanged is untouched, and past measurements keep the aliases that were valid when they ran. Read shruwd_list_entities first.

shruwd_set_entity

Reads the brand's homepage and drafts ten prompts and up to six competitors. Nothing is saved to the brand: show the draft to the user, then add each competitor they confirm with shruwd_add_competitor, passing its aliases and contextTerms from the draft, and after that the prompts they keep, in one shruwd_add_prompts call. Returns the stored draft when one exists unless regenerate is true. Three drafts per brand per day; a new draft can take up to a minute.

shruwd_suggest_setup

Moves a finding: "acknowledged" (seen), "fix_applied" (the recommended change is live), or "dismissed". Order matters: an open finding must be acknowledged before fix_applied, or the call is refused with 409 invalid_transition. fix_applied captures a baseline of the affected prompts and starts a fourteen-day clock; a recheck then measures again, and the finding becomes "resolved" ONLY if the movement gates pass (non-overlapping intervals and at least five points of change), else "not_moved". ACCESS findings are instead confirmed from the site's own logs, robots.txt or page, with no wait and no recheck spent. Neither resolved nor not_moved can be set here. Do not mark fix_applied until the change is actually deployed; the baseline is taken at that moment. A finding withheld by the plan is refused with 403 not_entitled.

shruwd_transition_finding

Renames a brand or changes its timezone. The name is for display; matching uses the self entity's aliases (shruwd_set_entity). The timezone moves the day boundary for cycles and rollups from the next cycle on. The domain cannot change: it defines the self entity, so a new domain is a new brand.

shruwd_update_brand

Edits a prompt by its promptGroupId. Changing text or intent creates a new version under the same group — history stays attached to the version that produced it. tags and active change in place. Reactivating counts against the plan limit.

shruwd_update_prompt