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

## Three jobs, 19 tools.

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.

| Tool | Reads or changes | What it does | Needs | Returns | Use it when | Not for |
| --- | --- | --- | --- | --- | --- | --- |
| `list_sites` · List connected sites | Reads | Lists the sites your account can open in Dr. Canary. | Nothing but optional `offset` and `limit` (1 to 50, 20 by default). | Each site’s `domainRoot`, `nextOffset`, and `entryKind` and `entryPath`, which say when access is missing or setup is unfinished. | First, whenever the exact `domainRoot` of a site is not already known. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | 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. | Before any change to a shopper, to get its exact reference and the settings to keep. | 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. | `domainRoot` from `list_sites`, an optional exact `assignmentRef`, optional `offset` and `limit` (1 to 50, 20 by default). | Each recorded check with its shopper where that was recorded, its link, and its inquiries with their `leadRef` and links. | A shopper’s past checks, or before opening an inquiry with `get_inquiry`. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | Each check’s `scanRef`, status, start and finish times, duration, and its `reportRef` once it has one. | Finding a check to open, or seeing whether a requested check is queued, running or finished. | 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. | `domainRoot` from `list_sites`, the exact `scanRef`, and optional `attemptOffset`, `captureOffset` and `limit` to page its details. | Its status and times, grouped attempts and captures, or, once its report is published, the link to that report. | Following a requested check, or opening the check a person picked. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | Each Group’s `groupRef` and name, totals across them, and the link to the portal’s sites view. | Before reading or rechecking a Group whose exact reference is not known. | 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. | `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`. | The Group’s grade and summary, its sites with their health and recheck state, its open findings with links, and the portal link. | How a Group is doing, and after a Group recheck, with the same `domainRoot` and `groupRef`. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | The inventory, whether it was detected or taken from a published check, a summary, and links. | Which tools are on the site. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | Each journey with its viewports and check link, how many were driven, and the portal link. | Which journeys were run, and which check to open for their assessments. | 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. | `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). | The check’s assessments with their links, or the one assessment asked for. | What a check concluded about each journey. | 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. | `domainRoot` from `list_sites`, optional `offset` and `limit` (1 to 50, 20 by default). | Each version’s number, status (assembling, published or unavailable), caption and `reportRef`, and the current `reportRef`. | Choosing a published report to read, or confirming that a report is published. | Treating an assembling report as published. |
| `get_report` · Read a customer report | Reads | Reads the customer-visible facts of one report. | `domainRoot` from `list_sites` and the exact `reportRef`. | 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. | Explaining what a report found, or showing the evidence for a finding. | 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. | `domainRoot` from `list_sites`, and the `scanRef` and `leadRef` recorded in `list_assignment_runs`. | The inquiry, the replies and their review, current and earlier, with timing, delivered images and links. | What the store sent back after an inquiry. | 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.

| Tool | Reads or changes | What it does | Needs | Returns | Use it when | Not for |
| --- | --- | --- | --- | --- | --- | --- |
| `save_assignment` · Save a shopper | Changes | Creates a saved shopper, or replaces an existing shopper’s settings. | `domainRoot` from `list_sites`, `assignmentRef` (null creates), `name`, `departments` (new, used, service, parts), `submits`, `cadence` (null follows the plan), `paused`, and optional `focus`. | The save receipt: the shopper’s reference, whether it is paused, and whether anything changed. | Creating a shopper, or changing its name, departments, inquiry choice, frequency, pause or areas of focus. | 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. | `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. | The calendar receipt, with the day, the time zone and the date it takes effect. | Moving a shopper’s checks to another day. | 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. | `domainRoot` from `list_sites` and the exact `assignmentRef`. | The retirement receipt. The shopper’s recorded checks remain. | A shopper is no longer wanted. | 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.

| Tool | Reads or changes | What it does | Needs | Returns | Use it when | Not for |
| --- | --- | --- | --- | --- | --- | --- |
| `request_recheck` · Request a basic site check | Changes · may use allowance · may send test inquiries | Requests the basic check of a monitored site. | `domainRoot` from `list_sites`. | A receipt: queued or running, and the check references in `scan_refs`, which `get_run` follows. | A person asks to check the site again and accepts what that check uses. | 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. | `domainRoot` from `list_sites` and the exact `groupRef` from `list_groups`. | A receipt with the check references. It does not say which site each one belongs to. | A person asks to recheck a Group they can see in `list_groups`. | 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. | `domainRoot` and `findingRef` from a report’s non-null `recheckTarget`, or from a Group finding row. | A receipt with the check references. | A person wants the site rechecked and noted on that finding, and accepts the whole-site scope. | 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.

## Related

- [Connect](https://www.drcanary.com/mcp/) · [markdown](https://www.drcanary.com/mcp.md)
- [Examples](https://www.drcanary.com/mcp/examples/) · [markdown](https://www.drcanary.com/mcp/examples.md)
- [Permissions](https://www.drcanary.com/mcp/permissions/) · [markdown](https://www.drcanary.com/mcp/permissions.md)
- [Troubleshooting](https://www.drcanary.com/mcp/troubleshooting/) · [markdown](https://www.drcanary.com/mcp/troubleshooting.md)
- [Capabilities](https://www.drcanary.com/capabilities/) · [markdown](https://www.drcanary.com/capabilities.md)

https://www.drcanary.com/mcp/tools/ · updated 2026-11-11