> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Projects
> Understand the Projects tools available through Profound MCP
Profound MCP gives AI assistants tools to read, generate, and manage Projects and their tasks. To connect your MCP client to the hosted server, refer to the [Connection guides](/mcp/common-mcp-clients).
Learn more about Projects in [Profound Help Center](https://help.tryprofound.com/articles/8581387448-about-projects).
## How the tools work together
Projects are scoped to a category, so before doing anything with Projects, the assistant resolves the category with [`list_categories`](/mcp/capabilities/discovery-tools#list-categories).
Ask what work exists in a category. The assistant lists its Projects with [`list_projects`](#list-projects), narrowing to active or archived work when you ask for it.
Ask about one Project. The assistant reads the goal, the resolved identity, and the full task list with [`get_project`](#get-project).
Ask for a new Project. The assistant previews the generation plan with [`new_project`](#new-project), starts generation once you confirm, and follows progress with [`get_project_status`](#get-project-status). Generation runs for around 10 minutes.
Ask to add, edit, or progress tasks. The assistant uses [`create_project_task`](#create-project-task), [`update_project_task`](#update-project-task), and [`set_project_task_status`](#set-project-task-status). When a Project is finished or no longer relevant, ask to archive it: [`archive_project`](#archive-project) sets it aside without deleting it.
## Behavior and safety
### Behaviors
Every write tool except `delete_project_task` defaults to preview mode: the assistant receives a plan of the change first, shows it to you, and applies the change only after you confirm it.
| Behavior | What it means |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Preview before apply | Write tools return a plan of the change and change nothing until the assistant applies it |
| Archive over delete | `archive_project` marks a Project `retired` and preserves its history |
| Full-replace briefs | A `brief` passed to `update_project_task` replaces the existing brief instead of merging into it |
| Destructive deletes | `delete_project_task` permanently deletes a task, with no preview and no undo |
| Clear text writes | The tools that take text reject raw metrics, so assistants replace them with human-readable values, for example `33%` instead of `0.33` for a Visibility Score. The saved task wording can differ from the text you provided |
| Live data | Tools read from the Profound API, so results reflect your current access and data |
### MCP hints
The read tools (`list_projects`, `get_project`, and `get_project_status`) are marked `readOnlyHint: true` and `idempotentHint: true`: they only read data and are safe to retry. The following MCP hints are set on the write tools:
| Tool | Hints | What it means |
| ------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
| `new_project` | `destructiveHint: false`, `idempotentHint: false` | Applying twice starts two generations and creates two Projects |
| `archive_project` | `destructiveHint: false`, `idempotentHint: true` | Archiving an already-retired Project changes nothing |
| `create_project_task` | `destructiveHint: false`, `idempotentHint: false` | Applying twice adds the task twice |
| `update_project_task` | `destructiveHint: false`, `idempotentHint: true` | Applying the same change again leaves the task as it is |
| `set_project_task_status` | `destructiveHint: false`, `idempotentHint: true` | Setting the same status again changes nothing |
| `delete_project_task` | `destructiveHint: true`, `idempotentHint: true` | The delete is permanent, and a repeat call has nothing left to delete |
Every write tool also sets `openWorldHint: true`, which tells your MCP client that the writes land in the live, shared environment, so the client may ask you to confirm before running them.
## Projects tools
| Tool | Usage |
| ------------------------- | ------------------------------------------------------ |
| `list_projects` | List a category's Projects |
| `get_project` | Read one Project with its goal and full task list |
| `get_project_status` | Check a Project's lifecycle and live generation status |
| `new_project` | Generate a new Project in a category |
| `archive_project` | Retire a Project without deleting it |
| `create_project_task` | Add a task to a Project |
| `update_project_task` | Update fields on an existing task |
| `set_project_task_status` | Change a task's status |
| `delete_project_task` | Permanently delete a task |
Lists a category's Projects and their details, including title, number of tasks, and the last updated date.
**Example prompts**:
* "What projects do we have in the Banking category?"
* "Show me the projects we're actively tracking."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| `category_id` | Yes | - | The Profound category, from `list_categories` |
| `status` | No | `null` | Filter to `suggested`, `tracked`, or `retired`. Leaving it blank returns all Projects |
| `limit` | No | `20` | Maximum Projects to return |
| `offset` | No | `0` | Offset for pagination |
**Notes**
* The tool doesn't return a total Project count.
Reads one Project, including the title, the goal, the description, and the tasks.
**Example prompts**:
* "Walk me through the 'Rank top three on savings accounts' project."
* "What tasks are still open on that project?"
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------ |
| `project_id` | Yes | - | The Project ID, from `list_projects` |
| `category_id` | Yes | - | The category of the Project |
Ask your assistant to compare live metrics against the Project target. The data `get_project` returns pairs well with the [analytics tools](/mcp/capabilities/analytics-capabilities).
Gets a Project's lifecycle status:
* `suggested` for proposed work
* `tracked` for active work measured against the goal
* `retired` for archived work
For Projects that were recently generated or are currently being generated, this tool also returns the `live_generation` state: `queued`, `running`, `completed`, or `failed`.
**Example prompts**:
* "Is the project you started generating ready yet?"
* "Did that project generation finish or fail?"
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | -------------------------------------------------------------------------------- |
| `project_id` | Yes | - | The Project ID, from `list_projects` or `new_project`. Not a generation `run_id` |
| `category_id` | Yes | - | The category of the Project |
Starts generating a Project. The preview shows the generation plan, and once you confirm it, Profound builds the Project in the background and returns a link to it. Building takes around 10 minutes, and the assistant can check whether it's done with `get_project_status`.
**Example prompts**:
* "Create a project to improve our visibility on savings accounts prompts."
* "Generate a project for earned media on the checking topic, focused on the US market."
**Inputs**
| Input | Required | Default | Description |
| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `category_id` | Yes | - | The category to generate in, from `list_categories` |
| `focus` | Yes | - | One concrete sentence naming the Project to generate |
| `topics` | No | `null` | Topic names the Project should focus on |
| `project_name` | No | `null` | Title for the Project. If left blank, Profound generates the name |
| `work_types` | No | `null` | Kind of work to produce: `publish`, `refresh`, `earned`, `creative`, or `social` |
| `date_range` | No | `null` | Time period the generated work should cover |
| `platforms` | No | `null` | Platforms or channels to prioritize |
| `regions` | No | `null` | Markets or regions to prioritize |
| `tags` | No | `null` | Category tags to guide what gets generated |
| `context` | No | `null` | Extra detail to guide what gets generated: objective, audience, competitors, evidence, desired output, and constraints |
| `preview` | No | `true` | When `true`, show the plan without creating anything; when `false`, start generation |
Archives a Project, which sets it aside without deleting it. The Project and its history are preserved and marked `retired`, so the change is reversible.
**Example prompts**:
* "Archive the holiday campaign project, it's done."
* "Retire the projects we're no longer working on."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | --------------------------------------------------------------------------------------- |
| `project_id` | Yes | - | The Project ID |
| `category_id` | Yes | - | The category of the Project |
| `reason` | No | `null` | Short reason for archiving, for example no longer relevant, already done, or superseded |
| `preview` | No | `true` | When `true`, return the plan without changing the Project; when `false`, apply |
Adds a task to a Project.
**Example prompts**:
* "Add a task to refresh the pricing page to the savings project."
* "Add a task to the 'Rank top three on savings accounts' project: promote the new rates announcement on LinkedIn. Mark it high impact."
**Inputs**
| Input | Required | Default | Description |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| `project_id` | Yes | - | The Project to add the task to |
| `category_id` | Yes | - | The category of the Project |
| `title` | Yes | - | The task title, 5–12 words |
| `summary` | No | `null` | The task's summary |
| `brief` | No | `null` | The task's working instructions, sent as a structured brief object |
| `type` | No | `null` | Task type: `publish`, `refresh`, `earned`, `competitor_copy`, `creative`, or `social` |
| `topic` | No | `null` | The topic this task targets |
| `impact` | No | `null` | Impact score, 1–5, where 5 is the highest |
| `reference_url` | No | `null` | A supporting link, such as the page to work on or a source to draw from |
| `reference_label` | No | `null` | Display name for the reference link |
| `position` | No | `null` | The task's position in the Project's task list |
| `preview` | No | `true` | When `true`, show the planned task without creating it; when `false`, create it |
Updates the fields on an existing task.
**Example prompts**:
* "Update the pricing page task: the new rates page is live now, link it as the reference."
* "Reword the summary of the LinkedIn task so it focuses on the new savings rates."
**Inputs**
| Input | Required | Default | Description |
| ----------------- | -------- | ------- | ---------------------------------------------------------- |
| `project_id` | Yes | - | The Project ID |
| `task_id` | Yes | - | The task ID, from `get_project`'s task list |
| `category_id` | Yes | - | The category of the Project |
| `title` | No | `null` | New title |
| `summary` | No | `null` | New summary paragraph |
| `brief` | No | `null` | New task instructions, sent as a structured brief object |
| `type` | No | `null` | New task type |
| `topic` | No | `null` | New target topic |
| `impact` | No | `null` | New impact score, 1–5 |
| `reference_url` | No | `null` | New supporting link for the task |
| `reference_label` | No | `null` | New display name for that link |
| `preview` | No | `true` | When `true`, show the planned changes; when `false`, apply |
**Notes**:
* A new `brief` replaces the old one entirely, so the assistant submits the complete brief even for a small change.
Changes a task's status. The status options are `not_started`, `in_progress`, `done`, and `abandoned`. The `abandoned` status doesn't delete tasks.
**Example prompts**:
* "Mark the pricing refresh task as done."
* "We're pausing the earned media task, shelve it."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | ------------------------------------------------------------------- |
| `project_id` | Yes | - | The Project ID |
| `task_id` | Yes | - | The task ID |
| `category_id` | Yes | - | The category of the Project |
| `status` | Yes | - | The new task status |
| `note` | No | `null` | Note recorded with the status change |
| `preview` | No | `true` | When `true`, return the proposed status change; when `false`, apply |
Permanently deletes a task from a Project. Destructive and irreversible, with no preview step.
To archive a task without losing it, ask to change its status to `abandoned` instead.
**Example prompts**:
* "Delete the duplicate task you just added."
* "Remove that test task for good."
**Inputs**
| Input | Required | Default | Description |
| ------------- | -------- | ------- | --------------------------- |
| `project_id` | Yes | - | The Project ID |
| `task_id` | Yes | - | The task ID to delete |
| `category_id` | Yes | - | The category of the Project |
## Resources
| Resource URI | Use it for |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file:///profound/projects-guide` | The Projects playbook: goals and measurement, the resolved identity block, task types and brief schemas, the impact rubric, and the `new_project` interview |
| `file:///profound/projects-guide/brief-examples` | Complete examples of a Project brief and a task brief |