Opportunities

Opportunities are the core pipeline/deal object in PR Tracker. They represent a pitch, placement, or other PR engagement moving through a defined set of stages.

Pipeline Stages

Opportunities progress through these stages in order:

1. researching -- Identifying the opportunity
2. drafting -- Preparing the pitch
3. pitched -- Pitch sent
4. responded -- Got a response
5. in_progress -- Actively being worked on
6. placed -- Confirmed placement
7. published -- Live/published
8. won -- Terminal success state
9. lost -- Terminal failure state

Priority Levels

• high
• medium
• low

create_opportunity

Create a new opportunity. If no campaign_id is provided, the opportunity is assigned to the default "General" campaign.

Parameters

Parameter	Type	Required	Description
title	string	Yes	Opportunity title
description	string	No	Description
campaign_id	string (UUID)	No	Campaign ID (defaults to General)
channel_id	string (UUID)	No	Target channel
outlet_id	string (UUID)	No	Target outlet
stage	string	No	Initial stage (default: researching)
priority	string	No	high, medium, or low
target_date	string	No	Target date (YYYY-MM-DD)
notes	string	No	Free-form notes
next_action	string	No	Next concrete step needed (e.g. "Send pitch to Sarah", "Follow up Tuesday")
next_action_date	string	No	When the next action is due (YYYY-MM-DD)
next_action_owner	string	No	Name of the team member who owns this action

Example

{
  "name": "create_opportunity",
  "arguments": {
    "title": "TechCrunch feature on v3 launch",
    "outlet_id": "550e8400-e29b-41d4-a716-446655440000",
    "priority": "high",
    "target_date": "2026-05-15",
    "next_action": "Send pitch to Sarah",
    "next_action_date": "2026-04-10",
    "next_action_owner": "Alex"
  }
}

get_opportunity

Get an opportunity by ID with all linked entities (campaign, channel, outlet, contacts, coverage, email threads).

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID

Example

{
  "name": "get_opportunity",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

list_opportunities

List opportunities with optional filters.

Parameters

Parameter	Type	Required	Description
campaign_id	string (UUID)	No	Filter by campaign
stage	string	No	Filter by stage
priority	string	No	Filter by priority: high, medium, low
outlet_id	string (UUID)	No	Filter by outlet
include_archived	boolean	No	Include archived opportunities (default: false)
limit	number	No	Max results (default: 50)
offset	number	No	Offset for pagination (default: 0)

Example

{
  "name": "list_opportunities",
  "arguments": {
    "stage": "pitched",
    "priority": "high"
  }
}

update_opportunity

Update opportunity fields. For stage changes, use set_opportunity_stage or advance_opportunity instead.

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID
title	string	No	Title
description	string	No	Description
campaign_id	string (UUID)	No	Campaign ID
channel_id	string (UUID)	No	Target channel
outlet_id	string (UUID)	No	Target outlet
priority	string	No	high, medium, or low
target_date	string	No	Target date (YYYY-MM-DD)
notes	string	No	Free-form notes
next_action	string	No	Next concrete step needed
next_action_date	string	No	When the next action is due (YYYY-MM-DD)
next_action_owner	string	No	Name of the team member who owns this action

Example

{
  "name": "update_opportunity",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "priority": "high",
    "next_action": "Follow up on pitch",
    "next_action_date": "2026-04-14"
  }
}

set_opportunity_stage

Set an opportunity to any stage. Sends a Slack notification if configured.

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID
stage	string	Yes	New stage

Example

{
  "name": "set_opportunity_stage",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "stage": "placed"
  }
}

advance_opportunity

Move an opportunity to the next stage in the pipeline. Sends a Slack notification if configured. Returns an error if the opportunity is already at a terminal stage (won or lost).

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID

Example

{
  "name": "advance_opportunity",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

list_opportunities_by_stage

Get all active opportunities at a given stage.

Parameters

Parameter	Type	Required	Description
stage	string	Yes	Stage to filter by

Example

{
  "name": "list_opportunities_by_stage",
  "arguments": {
    "stage": "pitched"
  }
}

get_opportunity_pipeline

Full pipeline view with counts and opportunities grouped by stage. Takes no parameters.

Parameters

None.

Example

{
  "name": "get_opportunity_pipeline",
  "arguments": {}
}

Response Shape

Pipeline: researching: 3, drafting: 2, pitched: 5, responded: 1, in_progress: 3, placed: 0, published: 2, won: 1, lost: 0

{
  "researching": [...],
  "drafting": [...],
  ...
}

list_next_actions

List all open opportunities that have a next action defined, grouped by owner. Answers the question: "What needs to happen next across all our opportunities?"

Excludes opportunities in terminal stages (won, lost, published).

Parameters

Parameter	Type	Required	Description
owner	string	No	Filter by action owner name
overdue_only	boolean	No	Only show actions past their due date (default: false)

Example

{
  "name": "list_next_actions",
  "arguments": {
    "overdue_only": true
  }
}

Response Shape

{
  "total_actions": 8,
  "by_owner": {
    "Alex": [{ "id": "...", "title": "...", "next_action": "...", "next_action_date": "..." }],
    "(unassigned)": [...]
  }
}

link_opportunity_contact

Add a contact to an opportunity.

Parameters

Parameter	Type	Required	Description
opportunity_id	string (UUID)	Yes	Opportunity ID
contact_id	string (UUID)	Yes	Contact ID
role	string	No	Their role (e.g. "editor", "pitch target")

Example

{
  "name": "link_opportunity_contact",
  "arguments": {
    "opportunity_id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "660e8400-e29b-41d4-a716-446655440000",
    "role": "pitch target"
  }
}

unlink_opportunity_contact

Remove a contact from an opportunity.

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	opportunity_contact record ID

Example

{
  "name": "unlink_opportunity_contact",
  "arguments": {
    "id": "770e8400-e29b-41d4-a716-446655440000"
  }
}

archive_opportunity

Soft-delete an opportunity.

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID

Example

{
  "name": "archive_opportunity",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

restore_opportunity

Restore an archived opportunity.

Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Opportunity ID

Example

{
  "name": "restore_opportunity",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}