Agent door · Reference

Tools reference

The 25 tools the agent door exposes today. Generated from the server's tool registry and drift-checked in CI on every change, so this table stays in lockstep with what the door serves.

Each tool gates on a capability the calling grant must hold, except describe_yellowhead, which describes Yellowhead and its plans and needs no sign-in. A parameter marked * is required. Write tools are held for human approval by default — see Write approvals.

One tool has the kind action: start_diagnostic starts a free Diagnostic through a confirmation in the conversation, not the approval queue. Its first call returns a preview and starts nothing; a second call with the preview's confirmation_token starts the run. It is available only on connections a person makes through an AI assistant's sign-in, and it uses only the account's included monthly Diagnostics. Its file_as parameter takes the app's five report types: my_business, client, competitor, research and prospect.

Which tools a connection lists depends on how it was made. A connection an account admin sets up in the Yellowhead app lists all 25. A connection a person makes through an AI assistant's sign-in lists 21, and an assistant that has not signed in yet is shown the same 21. The other 4 (get_approval_status, update_action_item, add_action_item_comment and run_diagnostic) are left out of that list because a sign-in connection cannot use them on any plan. The Listed on column says which is which.

Tool	Capability	Kind	Listed on	Parameters	Description
`list_diagnostics`	`diagnostic.list`	read	All connections	`client_id` `since` `limit` `cursor`	Lists the Diagnostics in the connected Yellowhead account, newest first. Each item has its id, business name, website, status (queued, processing, completed or failed; a run with no result after 15 minutes is reported as failed), client_id, MIDAS score once complete, and created date. Diagnostics are visible across the whole account, not only to the person who ran them. Filters: client_id (one client workspace) and since (created on or after a date and time). An empty page means none were returned for these filters, not that none exist. Fits questions like "what Diagnostics do we have" and "is my Diagnostic ready", and finding two runs to compare.
`get_diagnostic`	`diagnostic.read`	read	All connections	`id*`	Returns one Diagnostic by id: its status, business name, website, client_id, MIDAS score and created date, plus report_id once it has completed. Fits checking whether a particular run has finished; the findings themselves come from get_report.
`get_report`	`report.read`	read	All connections	`id*`	Returns the report of a completed Diagnostic by id: the ten pillar scores as the person rated them (side_a_scores) and as detected (side_b_scores), the MIDAS score, executive summary, blind spots, budget and investment reads, business profile, detected tech stack, brand visibility and sentiment, published apps, and a counts-only summary of the AI connectors found. Internal signals are not included. Some detail depends on the account's plan, as the app shows it: on the Free plan the report carries one blind spot (with that pillar's sub-scores only), the brand visibility and sentiment scores without their findings, the stated and estimated tool spend (on older reports, the estimated total) without the per-pillar breakdown, and no market context; the advertising sub-scores also need Starter or above; the investment roadmap (recommended_investment) and published-app identifiers and links need Pro or above (below Pro, published_apps lists only the platforms). A Diagnostic that has not finished returns report_not_ready. Scores for an unchanged site can move a little between runs, so a small change is not on its own evidence that something changed. The findings are what can be observed from outside.
`list_action_items`	`action_item.list`	read	All connections	`client_id` `source_id` `status` `limit` `cursor`	Lists the action items in the connected account, newest first. Each has its id, title, description, rationale, status, priority, pillar, phase, estimated cost range, suggested tools, remediation guidance, the source it came from (source_type and source_id: a Diagnostic, which get_report reads, or a Citation, Crawlability or Accessibility Scan, which get_citation_scan, get_crawlability_scan or get_accessibility_scan reads), client_id, assignee and due date. Statuses: suggested, queued, in_progress, completed (the person doing it says it is done), confirmed (a second person signed off), verified (a later Diagnostic saw the fix from outside) and dismissed. Filters: client_id, source_id and status. An empty page means none were returned for these filters. Fits "what should we fix first" and progress reviews. Changes to an action item are made in the Yellowhead app, or through a connection an account admin set up there.
`get_action_item`	`action_item.read`	read	All connections	`id*`	Returns one action item by id with its full detail: why it matters (rationale), what to do (description and remediation guidance), the tools involved, its status and dates, and the source it came from (source_type and source_id: a Diagnostic, or a Citation, Crawlability or Accessibility Scan). Fits explaining or planning one fix. Fixes happen on the business's own systems with its own access; an item becomes verified only when a later Diagnostic sees the fix from outside. Changes to an action item are made in the Yellowhead app, or through a connection an account admin set up there.
`get_usage`	`usage.read`	read	All connections	`client_id`	Returns this month's Diagnostic allowance for the connected account: how many included Diagnostics are used (used), the monthly allowance (limit), how many remain (remaining), the plan, whose allowance a run draws on (pool), and the date the allowance resets (resets_on). On the Free plan it carries a note on the first-month allowance. With client_id, it also gives that client workspace's own monthly limit (per_client). Fits questions about how many Diagnostics are left this month and when the allowance resets.
`list_strategic_assessments`	`strategic_assessment.list`	read	All connections	`client_id` `diagnostic_report_id` `limit` `cursor`	Lists the published Strategic Assessments in the connected account, newest first, with their ids, the Diagnostic each was based on, client_id and dates. Only published assessments appear: one that is booked or still being written appears once it is published, so an empty page does not mean none was ordered. Filters: client_id and diagnostic_report_id. A Strategic Assessment is a written walkthrough of a Diagnostic's findings, prepared with the business: which matter and what to fix first.
`get_strategic_assessment`	`strategic_assessment.read`	read	All connections	`id*`	Returns one published Strategic Assessment by id: the deliverable written for the business after its live session. Fits working from its priorities and recommendations.
`list_infrastructure_audits`	`infrastructure_audit.list`	read	All connections	`client_id` `diagnostic_report_id` `limit` `cursor`	Lists the published Infrastructure Audits in the connected account, newest first, with their ids, the Diagnostic each followed, client_id and dates. Only published audits appear: one that is in progress appears once it is published. Filters: client_id and diagnostic_report_id.
`get_infrastructure_audit`	`infrastructure_audit.read`	read	All connections	`id*`	Returns one published Infrastructure Audit by id, as published to the account. Fits working from its findings and recommendations.
`list_citation_scans`	`citation_scan.list`	read	All connections	`client_id` `status` `limit` `cursor`	Lists the Citation Scans in the connected account, newest first. A Citation Scan asks a fixed set of buyer questions in one category and country across several AI answer engines and records which websites the answers cite. Each item has its id, the website scanned (target_domain), category, country, status (pending_payment, paid, running, completed, failed or cancelled), client_id, the Diagnostic it started from (diagnostic_report_id), created and completed dates, and once completed the share of answered cells that cited the website (target_share, 0 to 1) and how many answer cells were filled (populated_cells). Filters: client_id and status. An empty page means none were returned for these filters, not that the account has none or that Yellowhead does not offer the scan.
`get_citation_scan`	`citation_scan.read`	read	All connections	`id*`	Returns one Citation Scan by id: its website, category, country, status and dates, the named competitors (competitor_domains), and once completed its results: the ranking of every domain the answers cited with each one's share of answered cells, the coverage (how many answer cells were filled), each answer cell's question, engine, whether the scanned website was cited and which domains were, and where the scan asked them, the head-to-head questions against named competitors. results is null until the scan completes; on a completed scan whose stored results could not be read, results_unavailable is true and the results are in the Yellowhead app. The citations are what the engines answered when asked; they can differ between runs and are not on their own evidence of why a site was or was not cited. The cited page addresses are in the Yellowhead app.
`list_crawlability_scans`	`crawlability_scan.list`	read	All connections	`client_id` `status` `limit` `cursor`	Lists the Crawlability Scans in the connected account, newest first. A Crawlability Scan checks, URL by URL from the website's sitemap, whether AI crawlers are allowed in by robots.txt and whether pages answer AI crawler identities the way they answer a browser. Each item has its id, the website (target_domain), status (draft, importing, awaiting_review, pending_payment, paid, running, completed, failed or cancelled; the first three are the free sitemap import and page review), whether it is a re-scan of an earlier scan's pages (sample_mode same_as_prior) or a first scan (fresh), the approved and measured page counts, client_id, diagnostic_report_id, and created and completed dates. Filters: client_id and status. An empty page means none were returned for these filters, not that the account has none or that Yellowhead does not offer the scan.
`get_crawlability_scan`	`crawlability_scan.read`	read	All connections	`id*`	Returns one Crawlability Scan by id: its website, sitemap, status, dates and page counts (imported, approved, measured, not measured, dead, stale or missing last-modified dates, duplicates, linked but not in the sitemap), and once completed its run summary (results): whether robots.txt and llms.txt were read, the per-crawler roll-up of what robots.txt allows, how pages answered AI crawler identities compared with a browser, pages linked from the site that the sitemap does not list (up to 25 of each list, with the totals), and why a run stopped early if it did. results is null until the scan completes; on a completed scan whose stored results could not be read, results_unavailable is true and the results are in the Yellowhead app. A robots.txt that could not be read is reported as unknown, not as absent. The per-URL results are in the Yellowhead app.
`list_accessibility_scans`	`accessibility_scan.list`	read	All connections	`client_id` `status` `limit` `cursor`	Lists the Accessibility Scans in the connected account, newest first. An Accessibility Scan measures a sample of the website's pages against automated WCAG 2.x A and AA checks, grouped by page template. Each item has its id, the website (target_domain), status (draft, importing, awaiting_review, pending_payment, paid, running, completed, failed or cancelled; the first three are the free sitemap import and page review), whether it is a re-scan of an earlier scan's pages (sample_mode same_as_prior) or a first scan (fresh), the approved and measured page counts, the number of page templates, client_id, diagnostic_report_id, and created and completed dates. Filters: client_id and status. An empty page means none were returned for these filters, not that the account has none or that Yellowhead does not offer the scan.
`get_accessibility_scan`	`accessibility_scan.read`	read	All connections	`id*`	Returns one Accessibility Scan by id: its website, sitemap, status, dates and page counts, and once completed its results: the run summary (pages measured on both viewports, templates sampled, and the note on what automated checks can and cannot show), the per-template roll-up of failing checks (the 20 largest templates and up to 25 of the most widespread failing checks each, with the totals), and on a re-scan the fix verification against the earlier scan as counts (fixed, still failing or not confirmed). results is null until the scan completes; on a completed scan whose stored results could not be read, results_unavailable is true and the results are in the Yellowhead app. Automated checks cover only part of WCAG, so a page with no failing check is not thereby shown to meet it. The per-page results are in the Yellowhead app.
`get_approval_status`	`action_item.update`	read	App connections only	`approval_id*`	Returns the state of a held request by its approval_id (from update_action_item, add_action_item_comment or run_diagnostic): pending_approval (waiting for an account admin in the Yellowhead app), applying, applied, denied, expired or failed, with the request and decision times and any reason given. Only requests made through this connection are visible.
`update_action_item`	`action_item.update`	write	App connections only	`id*` `status` `assigned_to` `due_date` `resolution_notes`	Requests a change to one action item: its status (queued, in_progress, completed or dismissed), assignee, due date or resolution notes. Available only on a connection an account admin set up in the Yellowhead app and allowed to make this request; a connection made through an assistant's sign-in cannot make it, on any plan. By default the change is held: the result is {status: 'pending_approval', approval_id}, nothing changes until an account admin approves it in the Yellowhead app, and get_approval_status reports the outcome. Only a connection the account has allowed to apply changes directly, and that proves its signing key on each request, applies it at once. Status changes follow the same rules as the app: suggested and verified are set by Yellowhead (verified only when a later Diagnostic sees the fix from outside), and confirmed is a second person's sign-off in the app, so none of the three can be set here. Marking an item completed records that the work was done; it does not verify it.
`add_action_item_comment`	`action_item.comment`	write	App connections only	`id` `body`	Requests a comment on one action item's timeline: what was done, what was found, or what is needed from a person. Available only on a connection an account admin set up in the Yellowhead app and allowed to make this request; a connection made through an assistant's sign-in cannot make it, on any plan. By default the comment is held: the result is {status: 'pending_approval', approval_id}, nothing is posted until an account admin approves it in the Yellowhead app, and get_approval_status reports the outcome. Only a connection the account has allowed to apply changes directly, and that proves its signing key on each request, posts it at once. Comments only add: this cannot edit or delete anything or change the item's status. The same comment sent twice is posted twice.
`run_diagnostic`	`diagnostic.run`	write	App connections only	`prior_diagnostic_id*` `side_a_scores` `budget` `advertising_budget` `advertising_budget_digital` `advertising_platform_fees` `digital_share_pct`	Requests a new Diagnostic of the same website and business as an earlier one (prior_diagnostic_id), reusing that run's answers. Available only on a connection an account admin set up in the Yellowhead app and allowed to make this request; a connection made through an assistant's sign-in cannot make it, on any plan. The website, business and account cannot be changed here. The person's own 1-to-10 pillar ratings (side_a_scores) and the spend figures can optionally be updated: anything not sent keeps the earlier run's value, and the approver sees each change beside the earlier value. A run is always held for an account admin to approve in the Yellowhead app, whatever the connection's settings; the result is {status: 'pending_approval', approval_id}. It uses one of the account's included monthly Diagnostics while any remain (get_usage shows how many). Once those are used, a plan that offers additional Diagnostics pays the published per-run rate from the account's prepaid balance, and any other plan is refused. Which of the two applies is decided when the run is requested and checked again at approval; if it changed in between, the run is refused rather than charged differently. After approval a run takes 5 to 10 minutes: get_approval_status gives the new Diagnostic's id and get_diagnostic its progress. Only accounts enabled for runs requested from an assistant can use this tool.
`describe_yellowhead`	None (no sign-in)	read	All connections	`url` `business_name`	Describes Yellowhead Digital, with no sign-in needed: what it is; the free Diagnostic (the ten pillars it checks, how long it takes, what the Free plan includes, and that an account is needed to run one); every plan with its price and monthly Diagnostics; the paid scans and human services with their prices and public pages; and a link that opens the Diagnostic form with a website and business name filled in. Fits questions about what Yellowhead does or costs, whether it checks something, or how to get started, including before any account exists. The optional url and business_name only fill in that link: nothing is scanned, stored or looked up.
`list_portfolio`	`portfolio.read`	read	All connections	`sort` `search` `status` `tier` `pillar` `min_open_high_priority_items` `client_id` `limit` `cursor`	Lists the client workspaces of the connected team account (brand workspaces on Business Enterprise), one page at a time, with the total so an answer can say how many are shown out of how many. Each row has the client_id, client name and website, the latest Diagnostic (report_id and date; it may still be running or may have failed) and the days since it, the MIDAS score with its tier, its change from the previous scored Diagnostic and whether that change is larger than the usual run-to-run variation, open_action_items (the Portfolio page's own count: items not done and not dismissed, so suggested, queued and in progress), open_high_priority_items (the open items that are critical or high), and the next scheduled Diagnostic. Both item counts cover only work the account owes: items from Diagnostics classified as a competitor, research or a prospect are not counted (list_action_items still lists them). Sorts: name, largest_decline, largest_improvement, lowest_midas, most_open_high_priority, most_open_items, longest_since_last_diagnostic, most_recent_diagnostic and next_scheduled; in the score and date sorts, a client with no Diagnostic or no score comes last. Filters: search (name or website), status, MIDAS tier, client_id, pillar (counts only that pillar's critical and high items) and min_open_high_priority_items. An empty page means no workspace matched these filters, not that the account has none. Included with team accounts on the Agency plans, Business Enterprise and custom plans. Fits "which clients need attention", ranking clients, and finding a client's client_id by name for list_action_items or list_diagnostics.
`get_portfolio_changes`	`portfolio.read`	read	All connections	`since` `direction` `client_id` `limit` `cursor`	Lists the client workspaces whose MIDAS score moved since a date (default: the last 30 days), largest move first. A client appears when its most recent scored Diagnostic is on or after that date and its MIDAS changed, against the scored Diagnostic before it, by more than the usual run-to-run variation; smaller moves are left out, because scores for an unchanged site can move a little between runs. Each item has the client_id and client name, the previous and current MIDAS and the change, both report_ids with their dates for citing (report_id, previous_report_id and previous_report_date are null when that pair cannot be confirmed in this account), and the open items of critical or high priority (only work the account owes: items from Diagnostics classified as a competitor, research or a prospect are not counted). direction narrows the list to declines or improvements; client_id narrows it to one client. An empty list means no client moved by more than that in the window, not that nothing changed. truncated is true when more clients moved by more than that in the window than one call examines (the most recent are examined), so the list may be incomplete. Archived workspaces are not included. Included with team accounts on the Agency plans, Business Enterprise and custom plans. Fits "which of my clients got worse this month" and "who improved since our last review".
`start_diagnostic`	`diagnostic.start`	action	All connections	`url` `business_name` `side_a_scores` `budget` `client_id` `file_as` `prospect_name` `client_name` `earlier_report_id` `confirmation_token`	Starts a Diagnostic of a website for the signed-in person, in two calls. The first call returns a preview and starts nothing: the website, the business name, the ten 1-to-10 self-ratings (which were answered, carried over or entered as 5 for "not sure"), the monthly tools budget, what the run is recorded as and where it is filed, which of the account's included monthly Diagnostics it uses, and a confirmation_token. A second call with that token starts it; any change needs a new preview. It uses only the account's included Diagnostics: when none are left the result is quota_exhausted with the reset date and the plans page, and nothing is charged. A run takes 5 to 10 minutes and a completion email also arrives; get_run_status reports progress. earlier_report_id fills in the website, name, ratings and budget from an earlier report, for a re-check; if that run did not complete and the same person started it, starting it again once for the same website and name does not use another Diagnostic (the preview says whether it applies). file_as says what the run is for, with the same five choices as the app: my_business (the account's own website), client, competitor, research or prospect. A competitor or research run of a website no workspace holds is filed in no workspace and creates none; a website or business name a client or brand workspace holds is filed in that workspace, as in the app. On an account with workspaces (clients, prospects or brands), client_id names the workspace, and needs_client lists the candidates when where the run is filed is not clear. For an owner or admin of an Agency-plan team account, file_as prospect on a website not yet in Prospects creates a new prospect workspace for it (named by prospect_name, else the business name); the preview says so and nothing is created before the confirmation. The same person may ask for a new client workspace for a website no workspace holds: file_as client with client_name (the new workspace's name); without client_name a miss lists the client workspaces instead. Available on connections made through an AI assistant's sign-in.
`get_run_status`	`diagnostic.read`	read	All connections	`diagnostic_id*`	Reports whether a Diagnostic is queued, running, completed or failed, by its id (diagnostic_id, as start_diagnostic and list_diagnostics give it), with when it started and how many minutes have passed. A Diagnostic usually takes 5 to 10 minutes; one taking longer is reported as running with slow set, because it may still finish, and as failed only once it has recorded a failure or 30 minutes have passed. A failed result says whether starting it again from this connection uses another of the month's Diagnostics. Fits "is it ready yet?" at any point in the conversation.

Tools are advertised over MCP via tools/list and invoked via tools/call. The advertised set is fixed per deployment for each kind of connection. Authority is checked at call time, so a connection or grant with fewer capabilities cannot invoke the tools it does not hold.