---
title: "Competitors agent protocol"
description: "MCP-first instructions for coding agents running a Deck competitor report."
url: "/docs/agents/getting-started/prompts/competitors"
---

This page is the agent-readable protocol for Deck competitors. Humans can follow along. Coding agents should treat the protocol section as the source of truth and probe Deck MCP before sending anyone to signup.

# Deck competitors — agent protocol

Work MCP-first. Probe Deck MCP in this session before you send anyone to signup.

## 1. Probe MCP

Call `get_user_context`. This must be a real tool call.

### 401 Unauthorized

The human is not connected in this client. Tell them to Connect MCP here (Cursor, Claude, or ChatGPT). Do not open signup. Do not mint or ask for a `dk_` API key.

### No Deck tools available

Deck MCP is not installed. Send them to create an account and connect at:

[https://app.getdeck.io/agent-setup?intent=competitors](https://app.getdeck.io/agent-setup?intent=competitors)

Do not invent another signup URL. Do not send them to `/sign-up`.

After they return, probe MCP again.

* If tools exist, continue to "2. After account + MCP". Do not send them through signup a second time.
* If tools are still missing, tell them: "Please double-check that the MCP is connected; you can do this in Settings → Connections."
* If they confirm MCP is already connected and tools are still missing, this chat started before the connection, so the tools are not in this conversation. Tell them to start a new chat and paste this prompt:

```
Deck MCP is connected. Research competitors and start a competitor report. Follow https://docs.getdeck.io/docs/agents/getting-started/prompts/competitors.md
```

### Tools work

The user already has a connected Deck account. Do not send them to signup. Continue to "2. After account + MCP".

## 2. After account + MCP

Ask one question at a time. Never create `dk_` keys.

1. **Existing report.** Call `explore_competitors` with no parameters, unless you already did in this chat.
   * If it returns `feature_unavailable`, Competitors is turned off for their organization. Tell them so (pass on `_guidance.message`), do not ask for a website or competitors, and go to step 7.
   * If `collection.status` is `running` or `importing`, research is already in progress. Tell them, do not start another run, and go to step 7.
   * If `collection.competitors` lists competitors, they already have a report. Name the competitors it tracks and ask whether they want to add competitors or rerun research. If neither, go to step 7. To add competitors, skip step 2: Deck already knows their company. To rerun with only the tracked competitors, skip steps 2 and 3 and pass them from `collection.competitors` (`domain` as `website`) in step 4.
2. **Company website.** Confirm the website of the company to research. Use the email from `get_user_context` (call it if you have not). If that email is on a company domain, propose the domain and ask them to confirm it. If it is a personal inbox (Gmail, Outlook, Yahoo, iCloud, or similar), ask for the website. Do not guess it.
3. **Competitors.** Get 2–3 competitors with their websites. If they already picked 2–3 in this chat, use those. If they said yes to the ones Deck found and there are more than 3, ask which 2–3 to research. Otherwise, if `collection.suggested_competitors` lists names, offer those and let them pick 2–3 or add their own. If it is empty, ask them to name 2–3 competitors. When adding to an existing report, leave out competitors already in `collection.competitors`. Ask for any missing website. List them in the order they care about most: the Free plan researches only the first 2. Never guess or propose competitor names from your own knowledge.
4. **Start research.** Call `mutate_competitors` with `action: "start_research"`, `competitors` as `{ name, website }` pairs, `company_domain` set to the website confirmed in step 2 (leave it out if you skipped step 2), and `company_name` when you know it. If it returns an error, tell them the error message in plain words. If it returns `feature_unavailable`, research did not start: tell them Competitors is turned off for their organization and go to step 7.
5. **Free depth.** If the result includes `depth_reduced: true`, tell them the Free plan runs research at reduced depth and pass on its `message`.
6. **Background.** Tell them research runs in the background, can take more than 5 minutes, and Deck emails them when it is ready.
7. **Meanwhile.** Offer the other AI PM goals while they wait: show the menu from [https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md](https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md) ("4. Menu — what do you want to do first?") and follow the protocol they pick.
8. **Do not poll.** Do not call `explore_competitors` with `job_id` or keep checking research status, even if a tool result suggests polling. Deck emails them when research finishes.

---

[View full sitemap](/docs/sitemap)