Dr. Canary

19 tools, one bird.

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

Three jobs: read what the bird found, change a saved shopper, request a check. 13 tools only read. 6 change something, and 3 of those can use allowance.

Dr. Canary in a lab coat, reading a tablet

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, departments, inquiry choice, stored and effective timing and areas of focus, the plan’s frequency, and what the account may edit.
    Use it when
    Before any change to a shopper, to get its exact reference and the settings to keep.
    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, 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 or edit a shopper, set its calendar, pause it, or retire it. Saved settings include its name, departments, inquiry choice, and frequency. Saving never starts a check.

  • save_assignment · Save a shopper

    Changes

    Creates a saved shopper, or replaces an existing shopper’s settings.

    Needs
    domainRoot from list_sites, assignmentRef (null creates), name, departments (new, used, service, parts), submits, cadence (null follows the plan), paused, and optional focus.
    Returns
    The save receipt: the shopper’s reference, whether it is paused, and whether anything changed.
    Use it when
    Creating a shopper, or changing its name, departments, inquiry choice, frequency, pause or areas of focus.
    Not for
    Running a check: saving never starts one. Calendar days and retiring have their own tools. It replaces every setting, so the tool tells the assistant to read the ones that stay and send them back unchanged.

  • 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.

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. save_assignment replaces every setting, so the ones that stay are sent back as they were.

  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.

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?

19, in three jobs: 13 read what the bird found, 3 change a saved shopper, and 3 request a check. Each has a card on this page.

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. The troubleshooting page has each one.

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