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.
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 sitesReads
Lists the sites your account can open in Dr. Canary.
- Needs
- Nothing but optional
offsetandlimit(1 to 50, 20 by default). - Returns
- Each site’s
domainRoot,nextOffset, andentryKindandentryPath, which say when access is missing or setup is unfinished. - Use it when
- First, whenever the exact
domainRootof 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 shoppersReads
Reads a site’s saved shoppers and their settings.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(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’sassignmentDefaultcan benullor absent. A saved shopper with a known stored cadence override has anexpectedSettingsDigestfor a full edit. The response includes the plan’s frequency and editing permission. When present,offeredDefaultslists 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 selectorsReads
Reads past shopper checks as the portal records them, with each inquiry’s references and links.
- Needs
domainRootfromlist_sites, an optional exactassignmentRef, optionaloffsetandlimit(1 to 50, 20 by default).- Returns
- Each recorded check with its shopper where that was recorded, its link, and its inquiries with their
leadRefand 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_runsandget_run. Today’s shopper settings do not tell what an earlier check covered.
list_runs· List recorded checksReads
Lists a site’s recorded checks with their status.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(1 to 50, 20 by default).- Returns
- Each check’s
scanRef, status, start and finish times, duration, and itsreportRefonce 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 checkReads
Reads one check in the detail the portal shows.
- Needs
domainRootfromlist_sites, the exactscanRef, and optionalattemptOffset,captureOffsetandlimitto 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 GroupsReads
Lists the Groups your account can see, with their totals.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(1 to 50, 20 by default).- Returns
- Each Group’s
groupRefand 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 sitesReads
Reads one Group’s health, its open findings and each site’s current recheck state.
- Needs
domainRootfromlist_sites, the exactgroupReffromlist_groups, and optionalrooftopOffsetandfindingOffsetto page its sites and its findings, with onelimit.- 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
domainRootandgroupRef. - 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 inventoryReads
Lists the tools and vendors found on the site, as the portal’s site detail shows them.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(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 historyReads
Lists the site’s customer journeys with their viewports and linked checks.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(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 checkReads
Reads the journey assessments recorded for one check.
- Needs
domainRootfromlist_sites, the check’sscanReffromlist_runsorlist_journeys, an optionaljourneyRunRefto open one, andoffsetandlimit(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 versionsReads
Lists a site’s report versions.
- Needs
domainRootfromlist_sites, optionaloffsetandlimit(1 to 50, 20 by default).- Returns
- Each version’s number, status (assembling, published or unavailable), caption and
reportRef, and the currentreportRef. - 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 reportReads
Reads the customer-visible facts of one report.
- Needs
domainRootfromlist_sitesand the exactreportRef.- 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 repliesReads
Reads one test inquiry and the replies that came back.
- Needs
domainRootfromlist_sites, and thescanRefandleadRefrecorded inlist_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
leadRefcomes fromlist_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 shopperChanges
Creates a shopper, edits its settings, or pauses or resumes its scheduled checks.
- Needs
domainRootfromlist_sites. Create and edit needassignmentRef,name,departments,submits,cadenceandpaused. An edit needs the originalexpectedSettingsDigest. See “Save a shopper” below forassignmentDefaultandfocus. To pause or resume, send onlydomainRoot,assignmentRefandpaused.- Returns
- The
receiptcontainsassignmentRef,version,pausedandchanged. Uselist_assignmentswith 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 preferenceChanges
Sets the weekday or day of the month a saved shopper’s scheduled checks fall on.
- Needs
domainRootfromlist_sites, the exactassignmentRef, aweekday(1 Monday to 7 Sunday) or amonthday(1 to 31), and a namedtimezone. 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 shopperChanges
Retires a saved shopper: it leaves the active list and stops its future scheduled checks.
- Needs
domainRootfromlist_sitesand the exactassignmentRef.- 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_assignmentinstead.
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 checkChanges · may use allowance · may send test inquiries
Requests the basic check of a monitored site.
- Needs
domainRootfromlist_sites.- Returns
- A receipt: queued or running, and the check references in
scan_refs, whichget_runfollows. - 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 checkChanges · may use allowance · may send test inquiries
Requests the portal’s recheck for one Group.
- Needs
domainRootfromlist_sitesand the exactgroupReffromlist_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_groupwith the samedomainRootandgroupRef.
request_finding_recheck· Recheck the site and log it on a findingChanges · may use allowance · may send test inquiries
Requests the ordinary site check and records the request in a finding’s thread.
- Needs
domainRootandfindingReffrom a report’s non-nullrecheckTarget, 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: nulland thekeyof an entry inofferedDefaultsasassignmentDefault. OmitassignmentDefaultonly whenofferedDefaultslistsdealership. Leave outexpectedSettingsDigest. - Edit a shopper’s settings. Send its exact
assignmentRefandexpectedSettingsDigestfrom the same original read. Carry forward settings you want to keep. OmitassignmentDefault, or send its currentkeyif the read returned one. - Pause or resume scheduled checks. Send only
domainRoot, the savedassignmentRefandpaused. Usetrueto pause orfalseto resume.
Create and edit both require name, departments, submits, cadence and paused.
| Field | What to send |
|---|---|
assignmentDefault | If offeredDefaults is absent or empty, refresh the roster or check the site’s options in Dr. Canary. Choose from returned offers only. |
name | Use name: null for the default name. |
departments, submits | A 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. |
cadence | To 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. |
paused | To keep the pause state, send paused: true if schedule.pausedAt has a value and false if it is null. |
focus | On 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.
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_unavailableor 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: unknownor a missing receipt, read the roster withlist_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
Find the site.
list_sitesreturns each connected site’sdomainRoot. Every other tool takes it.Read before a change.
list_assignmentsgives the shopper’s exactassignmentRefand its current settings. Use the originalexpectedSettingsDigestfor a full edit. Pause or resume needs only the site, shopper reference and pause state.Pass exact references along.
scanRef,reportRef,leadRef,groupRefandrecheckTargetcome 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.Follow the pages.
Lists return up to 50 records a page, 20 by default. When
nextOffsetis not null there is more. A page is not all history.Follow a check to its report.
A request returns check references. For a site or finding recheck,
get_runfollows each one; for a Group,get_group.list_reportsshows when a report is published, andget_reportreads 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_importandget_crm_import_receipts: preview, import and reconcile CRM location/contact rows.read_crm_locationandread_campaign_contacts: read exact locations and exact campaign contacts.save_campaign_draftandread_campaign_draft: save or read a campaign draft.preview_campaign_execution,read_campaign_executionandstart_campaign_execution: preview campaign preparation, read its progress and start preparation.preview_campaign_bulk_approvalandapply_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.

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.
