start_project_research
Sends Heimdall to research a project's domain, so a conversation that opened a project can ask for the industry's expectations without leaving the panel.
Start a research sweep on a project by project_id. Heimdall reads the project's brief and record, searches the web for what products of this kind are expected to do, the regulations and compliance they meet, the integrations clients ask for and the accessibility and security baselines, and files what it found as research notes and as suggestions on the review queue. The run is queued through the same action the project dashboard runs and research.started goes out; one run at a time per project.
Read list_research_notes once the status is ready. The call spends the team's AI budget. A staff token with import:create on the project is needed.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
project_id*stringUUID of the project to research.
What it returns
{ "data": { "id": "c5d6e7f8-a9b0-4c1d-8e2f-3a4b5c6d7e8f", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "status": "queued", "note_count": 0, "suggestion_count": 0, "provider": null, "model": null, "usage_id": null, "failure_reason": null, "created_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "creator_name": "Bea Analyst", "started_at": null, "finished_at": null, "created_at": "2026-10-28T11:50:00+00:00" }}How it fails
VALIDATION_FAILEDa sweep is already queued or running on the project.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, the holder's role on the project does not carry import:create, or the project's assists are off.
TOKEN_MISSING_ABILITYtoken lacks import:create.
How is this guide?
Last updated on