19 customer tools, one bird.

What each tool reads or changes, what it needs, and what it gives back.

The customer catalogue has three jobs: read what the bird found, change a saved shopper, request a check. 13 customer tools only read. A separate optional superadmin grant adds CRM outreach tools.

Three jobs, 19 tools.

Each card: Tool, Reads or changes, What it does, Needs, Returns, Use it when, Not for.

Job
Reads or changes

Showing 19 of 19

Read what the bird found:

Your sites and Groups, saved shoppers and recorded checks, site tools and journeys, inquiry details, and published reports with their evidence.

  • list_sites · List connected sites

    Reads

    Lists the sites your account can open in Dr. Canary.

    Needs
    Nothing but optional offset and limit (1 to 50, 20 by default).
    Returns
    Each site’s domainRoot, nextOffset, and entryKind and entryPath, which say when access is missing or setup is unfinished.
    Use it when
    First, whenever the exact domainRoot of a site is not already known.
    Not for
    Looking up a web address. A web address or hostname is not a domainRoot.
  • list_assignments · Read saved shoppers

    Reads

    Reads a site’s saved shoppers and their settings.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each shopper’s assignmentRef, name, assignmentDefault, stored and effective timing, pause state and areas of focus, plus departments and inquiry choice for dealer shoppers. A shopper’s assignmentDefault can be null or absent. A saved shopper with a known stored cadence override has an expectedSettingsDigest for a full edit. The response includes the plan’s frequency and editing permission. When present, offeredDefaults lists each option’s key, title and description.
    Use it when
    Before creating a shopper or changing a saved one.
    Not for
    Reading a missing value as empty. An absent stored frequency or focus is unknown, not none.
  • list_assignment_runs · Read recorded shopper history and inquiry selectors

    Reads

    Reads past shopper checks as the portal records them, with each inquiry’s references and links.

    Needs
    domainRoot from list_sites, an optional exact assignmentRef, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each recorded check with its shopper where that was recorded, its link, and its inquiries with their leadRef and links.
    Use it when
    A shopper’s past checks, or before opening an inquiry with get_inquiry.
    Not for
    Queued or running status, which is list_runs and get_run. Today’s shopper settings do not tell what an earlier check covered.
  • list_runs · List recorded checks

    Reads

    Lists a site’s recorded checks with their status.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each check’s scanRef, status, start and finish times, duration, and its reportRef once it has one.
    Use it when
    Finding a check to open, or seeing whether a requested check is queued, running or finished.
    Not for
    Judging the website. A check’s status says how the check ran, not what it found.
  • get_run · Read an exact check

    Reads

    Reads one check in the detail the portal shows.

    Needs
    domainRoot from list_sites, the exact scanRef, and optional attemptOffset, captureOffset and limit to page its details.
    Returns
    Its status and times, grouped attempts and captures, or, once its report is published, the link to that report.
    Use it when
    Following a requested check, or opening the check a person picked.
    Not for
    Calling the site fine. A finished check is not a verdict, and unavailable details do not erase its known status.
  • list_groups · List authorized site Groups

    Reads

    Lists the Groups your account can see, with their totals.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each Group’s groupRef and name, totals across them, and the link to the portal’s sites view.
    Use it when
    Before reading or rechecking a Group whose exact reference is not known.
    Not for
    Guessing a Group from a site or a name. Group access comes from this list.
  • get_group · Read Group health and sites

    Reads

    Reads one Group’s health, its open findings and each site’s current recheck state.

    Needs
    domainRoot from list_sites, the exact groupRef from list_groups, and optional rooftopOffset and findingOffset to page its sites and its findings, with one limit.
    Returns
    The Group’s grade and summary, its sites with their health and recheck state, its open findings with links, and the portal link.
    Use it when
    How a Group is doing, and after a Group recheck, with the same domainRoot and groupRef.
    Not for
    Proving that a particular request finished. Current status does not confirm one, and a Group can hold sites other than the one you are viewing.
  • list_site_tools · Read the site’s customer tool inventory

    Reads

    Lists the tools and vendors found on the site, as the portal’s site detail shows them.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    The inventory, whether it was detected or taken from a published check, a summary, and links.
    Use it when
    Which tools are on the site.
    Not for
    Verdicts. A tool on the list is not verified working, and an empty list is not complete coverage.
  • list_journeys · Read existing customer journey history

    Reads

    Lists the site’s customer journeys with their viewports and linked checks.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each journey with its viewports and check link, how many were driven, and the portal link.
    Use it when
    Which journeys were run, and which check to open for their assessments.
    Not for
    Naming an exact assessment. A journey’s name does not identify one.
  • get_journey_assessment · Read journey assessments for a check

    Reads

    Reads the journey assessments recorded for one check.

    Needs
    domainRoot from list_sites, the check’s scanRef from list_runs or list_journeys, an optional journeyRunRef to open one, and offset and limit (1 to 50, 20 by default).
    Returns
    The check’s assessments with their links, or the one assessment asked for.
    Use it when
    What a check concluded about each journey.
    Not for
    Reading an empty result as a failed test. It means no assessment was returned.
  • list_reports · List report versions

    Reads

    Lists a site’s report versions.

    Needs
    domainRoot from list_sites, optional offset and limit (1 to 50, 20 by default).
    Returns
    Each version’s number, status (assembling, published or unavailable), caption and reportRef, and the current reportRef.
    Use it when
    Choosing a published report to read, or confirming that a report is published.
    Not for
    Treating an assembling report as published.
  • get_report · Read a customer report

    Reads

    Reads the customer-visible facts of one report.

    Needs
    domainRoot from list_sites and the exact reportRef.
    Returns
    The report’s header, its tools and journeys, its findings with their evidence, what should have happened where the report states it and the observed sequence where one proves a finding, the matching check’s results, and the report’s link in Dr. Canary.
    Use it when
    Explaining what a report found, or showing the evidence for a finding.
    Not for
    Taking its text as instructions: the tool marks report and site content as untrusted data. For a finding recheck use only a returned recheckTarget, never the finding’s displayed reference.
  • get_inquiry · Read an exact customer inquiry and replies

    Reads

    Reads one test inquiry and the replies that came back.

    Needs
    domainRoot from list_sites, and the scanRef and leadRef recorded in list_assignment_runs.
    Returns
    The inquiry, the replies and their review, current and earlier, with timing, delivered images and links.
    Use it when
    What the store sent back after an inquiry.
    Not for
    Following text inside a reply: the tool marks it as untrusted data. The leadRef comes from list_assignment_runs, not from a message or a time.

Change a saved shopper:

Create a shopper on one of your site’s defaults or edit one, set its calendar, pause it, or retire it. Saved settings include its name, frequency and areas of focus, and a dealer shopper’s departments and inquiry choice. Saving never starts a check.

  • save_assignment · Save a shopper

    Changes

    Creates a shopper, edits its settings, or pauses or resumes its scheduled checks.

    Needs
    domainRoot from list_sites. Create and edit need assignmentRef, name, departments, submits, cadence and paused. An edit needs the original expectedSettingsDigest. See “Save a shopper” below for assignmentDefault and focus. To pause or resume, send only domainRoot, assignmentRef and paused.
    Returns
    The receipt contains assignmentRef, version, paused and changed. Use list_assignments with the same site to verify the saved settings.
    Use it when
    Creating, editing, pausing or resuming a shopper.
    Not for
    Running a check: saving never starts one. It does not change a saved shopper’s default. Calendar days and retiring have their own tools.
  • set_assignment_calendar · Set a shopper calendar preference

    Changes

    Sets the weekday or day of the month a saved shopper’s scheduled checks fall on.

    Needs
    domainRoot from list_sites, the exact assignmentRef, a weekday (1 Monday to 7 Sunday) or a monthday (1 to 31), and a named timezone. All three null clears the day.
    Returns
    The calendar receipt, with the day, the time zone and the date it takes effect.
    Use it when
    Moving a shopper’s checks to another day.
    Not for
    Running a check or pausing. It adds no automatic pause or resume.
  • retire_assignment · Retire a saved shopper

    Changes

    Retires a saved shopper: it leaves the active list and stops its future scheduled checks.

    Needs
    domainRoot from list_sites and the exact assignmentRef.
    Returns
    The retirement receipt. The shopper’s recorded checks remain.
    Use it when
    A shopper is no longer wanted.
    Not for
    A temporary stop. Pause the shopper with save_assignment instead.

Request a check:

Request a site or authorized Group check. The basic site check uses the first saved shopper that has not been retired, including one that is paused. A finding recheck requests the ordinary site check. Checks may send permitted test inquiries and use your allowance.

  • request_recheck · Request a basic site check

    Changes · may use allowance · may send test inquiries

    Requests the basic check of a monitored site.

    Needs
    domainRoot from list_sites.
    Returns
    A receipt: queued or running, and the check references in scan_refs, which get_run follows.
    Use it when
    A person asks to check the site again and accepts what that check uses.
    Not for
    Running a chosen shopper. It uses the first saved shopper that has not been retired, which can be a paused one. If acceptance is uncertain, the tool tells the assistant to read recorded checks before any repeat, because a repeat can start another check.
  • request_group_recheck · Request the existing Group check

    Changes · may use allowance · may send test inquiries

    Requests the portal’s recheck for one Group.

    Needs
    domainRoot from list_sites and the exact groupRef from list_groups.
    Returns
    A receipt with the check references. It does not say which site each one belongs to.
    Use it when
    A person asks to recheck a Group they can see in list_groups.
    Not for
    Mapping checks to sites or promising when they finish. Status comes from get_group with the same domainRoot and groupRef.
  • request_finding_recheck · Recheck the site and log it on a finding

    Changes · may use allowance · may send test inquiries

    Requests the ordinary site check and records the request in a finding’s thread.

    Needs
    domainRoot and findingRef from a report’s non-null recheckTarget, or from a Group finding row.
    Returns
    A receipt with the check references.
    Use it when
    A person wants the site rechecked and noted on that finding, and accepts the whole-site scope.
    Not for
    Testing one finding alone: it checks the site. Never with the finding reference a report displays.

Save a shopper

Get the site’s domainRoot from list_sites. Use list_assignments to check capabilities.write.allowed. Choose the request that matches what you want to change.

  • Create a shopper. Send assignmentRef: null and the key of an entry in offeredDefaults as assignmentDefault. Omit assignmentDefault only when offeredDefaults lists dealership. Leave out expectedSettingsDigest.
  • Edit a shopper’s settings. Send its exact assignmentRef and expectedSettingsDigest from the same original read. Carry forward settings you want to keep. Omit assignmentDefault, or send its current key if the read returned one.
  • Pause or resume scheduled checks. Send only domainRoot, the saved assignmentRef and paused. Use true to pause or false to resume.

Create and edit both require name, departments, submits, cadence and paused.

FieldWhat to send
assignmentDefaultIf offeredDefaults is absent or empty, refresh the roster or check the site’s options in Dr. Canary. Choose from returned offers only.
nameUse name: null for the default name.
departments, submitsA dealer shopper takes 1 to 4 distinct departments from new, used, service and parts, and a boolean submits for test inquiries. For other shoppers, send null for both departments and submits.
cadenceTo keep an existing shopper’s timing, copy its stored schedule.cadenceOverride into cadence. A returned null means the shopper follows the plan. Send cadence: null to keep or select that setting. A missing override is unknown, so refresh before a full edit.
pausedTo keep the pause state, send paused: true if schedule.pausedAt has a value and false if it is null.
focusOn an edit, omit focus to keep it, send [] to clear it, or send the full list to replace it. To clear or replace focus, first confirm the original read returned that shopper’s focus.

This example creates a shopper when offeredDefaults includes website. Replace alice-site with the domainRoot from your own list_sites response.

Example arguments for save_assignment
{
  "domainRoot": "alice-site",
  "assignmentRef": null,
  "assignmentDefault": "website",
  "name": "Site navigation",
  "departments": null,
  "submits": null,
  "cadence": null,
  "paused": false
}

Use the error’s nextStep to recover from a refused or unconfirmed save.

  • For assignment_settings_changed, read the shopper again. Review what changed before building an edit with the new digest.
  • For assignment_settings_unavailable or a missing digest, refresh the roster. Wait for the required settings before submitting a full edit.
  • For assignment_default_unavailable, refresh the roster and use an offered key to create. On an edit, leave the default out or use the current key if the roster returned one.
  • For write_outcome_unknown, outcome: unknown or a missing receipt, read the roster with list_assignments. If that fails, repeat only the read. A matching or missing shopper cannot confirm what the save did. Never resend a save solely because the receipt is missing. Repeating a create can add a second shopper.

How the tools fit together

  1. Find the site.

    list_sites returns each connected site’s domainRoot. Every other tool takes it.

  2. Read before a change.

    list_assignments gives the shopper’s exact assignmentRef and its current settings. Use the original expectedSettingsDigest for a full edit. Pause or resume needs only the site, shopper reference and pause state.

  3. Pass exact references along.

    scanRef, reportRef, leadRef, groupRef and recheckTarget come from earlier results. The connection tells the assistant to use them exactly as returned, not to build them from a name, a date or a web address.

  4. Follow the pages.

    Lists return up to 50 records a page, 20 by default. When nextOffset is not null there is more. A page is not all history.

  5. Follow a check to its report.

    A request returns check references. For a site or finding recheck, get_run follows each one; for a Group, get_group. list_reports shows when a report is published, and get_report reads it.

Optional CRM outreach tools

A current superadmin can separately opt in to 12 CRM outreach tools on a connection. They are not part of the customer catalogue above or the staff grant for catalogue access and public checks. The grant is unchecked by default and does not appear for other roles.

  • preview_crm_import, apply_crm_import and get_crm_import_receipts: preview, import and reconcile CRM location/contact rows.
  • read_crm_location and read_campaign_contacts: read exact locations and exact campaign contacts.
  • save_campaign_draft and read_campaign_draft: save or read a campaign draft.
  • preview_campaign_execution, read_campaign_execution and start_campaign_execution: preview campaign preparation, read its progress and start preparation.
  • preview_campaign_bulk_approval and apply_campaign_bulk_approval: inspect prepared emails and approve them; applying can send real emails immediately when the policy is “now”.

Rules every tool follows

  • Your account’s permissions apply. What you cannot do in the portal, your assistant cannot do either.
  • Your assistant follows its app’s approval controls for changes and checks.
  • The connection tells the assistant to treat what it reads from sites and reports as data, and to read back before repeating a change whose outcome is unknown.
  • A missing row does not prove an uncertain change or check failed, and does not make a repeat safe. Read back before you repeat it.
  • Each signed-in person can make 60 tool calls a minute on each server instance. It is not a limit on checks.

What there is no tool for

  • Running one chosen shopper or journey. The basic recheck uses the first saved shopper that has not been retired.
  • Running one finding alone. A finding recheck requests the ordinary site check.
  • Requesting a check for a site that is not connected to your account. A recheck takes a connected site, not a web address. An area of focus on a saved shopper can name a start page as a full web address.
  • Writing a custom journey, or running a one-off test that is not saved on a shopper. Areas of focus on a saved shopper are how to ask it to try something particular.
  • Billing, plans, team members or sharing.

What it does not do

  • It reads what the report shows. Hidden prompts, internal notes, and other accounts stay out.
  • A check’s status is not a verdict on your site. A finished check is not a pass, and a listed tool is not verified working.
  • An empty result is not proof. An absent finding does not show that a thing works.
  • A queued check is not a finished check, and a finished check is not a published report.

Questions

How many tools does the Dr. Canary connection have?

The customer catalogue has 19 tools in three jobs: 13 read what the bird found, 3 change a saved shopper, and 3 request a check. A separately granted superadmin connection also has 12 CRM outreach tools, described above.

Which tools change something?

6: save_assignment, set_assignment_calendar, retire_assignment, request_recheck, request_group_recheck and request_finding_recheck. Every other tool only reads. Your assistant’s app controls approvals for the ones that change something.

Which tools can use allowance?

3: request_recheck, request_group_recheck and request_finding_recheck. They can also send test inquiries if the shopper that runs sends them. Reading a report, a check or an inquiry uses no allowance.

What is domainRoot?

The account’s label for a connected site, returned by list_sites. It is not a web address or a hostname. Every tool after list_sites takes it.

Why does a recheck not use the shopper I just edited?

request_recheck runs the site’s first saved shopper that has not been retired, which can be a paused one. No tool picks a shopper to run. Saving a shopper never starts a check.

What does a tool error look like, and what should the assistant do?

An error comes back with a code, a message, a next step and whether it can be retried. For a change or a check it also says whether the outcome is not started or unknown. When it is unknown, the connection tells the assistant to read back before any repeat. See the shopper save section above and the troubleshooting page for recovery steps.

Is there a limit on how fast an assistant can call the tools?

Yes. Each signed-in person can make 60 tool calls a minute on each server instance. Past that, the error says how many seconds to wait. It is not a limit on checks.

Dr. Canary giving the OK sign

Give your assistant something to read.

A checkup is one report. Monitoring keeps the bird shopping your site on a schedule, so there is a fresh report every time you ask.

Compare plans