---
name: cortex-triggers
description: Manage a Ninjo agent's triggers via the cortex-gateway MCP — keyword/comment/ad/all-messages/outgoing/story triggers, bulk keyword sync, audios, and temporary blocks (negative configs). Use when the user wants to add, edit, remove, list, or sync triggers/keywords for an agent.
---

# cortex-triggers — manage triggers (MCP-first)

Inspect and modify what makes an agent fire. Guidance: `knowledge/keyword-playbook.md` and
`knowledge/triggers.md`.

## 1. Inspect
`list_triggers { agent_id }` → returns triggers grouped by type: `keywords`, `all_messages`,
`comments`, `ads`, `outgoing_messages`, `instagram_story` (keyword/ad triggers include `audios`,
and each shows its `negative_config`). Get `agent_id` from `agents/<name>/meta.md` or `list_agents`.

> **Multi-influencer token?** If `get_me` returns `scope: "multi-influencer"`, the connection is **unscoped** — pass `influencer_id` (the **Influencer ID** from `meta.md`; resolve a user's "@handle" via `get_me`'s `influencers` map) on **every** trigger call (`list_triggers`, `create_trigger`, `sync_keyword_triggers`, …). Single-influencer tokens ignore it. See `knowledge/mcp-tool-reference.md` › Ground rules › **Influencer scope**.

## 2. Create / update / delete
`create_trigger { type, agent_id, ... }` — `type` selects which fields apply:
- `keywords` — `keyword`, `match_mode` (`KEYWORD_ONLY` | `ANYWHERE`), `allow_typo`.
- `comments` — `keyword`, `match_mode`, `allow_typo`, `responses` (public reply templates).
- `all-messages` — `keyword` must be `ALL_DM` or `ALL_COMMENTS`; optional `prompt_evaluator`.
- `ads` — `ad_id`. `outgoing-messages` — `keyword`, `assign_unpaused`. `instagram-story` — `story_id`.

`update_trigger` — `keywords` | `outgoing-messages`.
`delete_trigger { type, trigger_id, agent_id }` — all 6 types.

## 3. Bulk keyword sync (preferred for keyword sets)
`sync_keyword_triggers { agent_id, keywords: [{ keyword, match_type }] }` reconciles the whole DM
keyword set with a diff: preserves existing (keeps `created_at`), patches changed `match_mode`,
inserts new, deletes absent. Inputs are lowercased/trimmed/deduped. `match_type`:
`any_mention`/`anywhere` → `ANYWHERE`; `isolated_word`/`keyword_only` → `KEYWORD_ONLY`.

> If you're editing the agent's SDK too, prefer deploying keywords through `deploy_agent_sdk`
> (`keywords` field) — it dual-writes `v5Config.keywords` **and** `trigger_keywords`, keeping them in
> sync. Pass `keywords` as a JSON array (the parsed `keywords.json`), **never as a JSON-encoded
> string** — the gateway normalizes it (a stringified array is auto-parsed; an invalid string 400s;
> see `knowledge/platform-internals.md` §3e). Use `sync_keyword_triggers` for standalone keyword-only changes, and keep
> `agents/<name>/sdk/keywords.json` in sync with whatever you set.

## 4. Audios (keyword / ad triggers)
`list_trigger_audios { type, agent_id, trigger_id }` and `sync_trigger_audios` — `type` is
`keywords` | `ads`. Audios play in rotation when the trigger matches.

> Not the same as **mid-conversation creator resources** — audio/image clips the agent sends *during* a
> chat (not on trigger match). Manage those with `list_creator_resources`, a two-step presigned upload
> (`create_resource_upload_url` → `register_creator_resource`), `update_/delete_creator_resource`, and
> `update_resource_sending` (`knowledge/mcp-tool-reference.md` §Creator resources).

## 5. Temporary blocks (negative configs)
`get_/upsert_/delete_trigger_negative_config { agent_id, trigger_type, trigger_id, ... }` —
`trigger_type` is `keywords` | `all-messages` | `comments` | `ads`. When enabled and `now <
expires_at`, the trigger is suppressed even if it would otherwise match. Use for temporary pauses.

## Notes
- Keyword design (specificity, typo tolerance, overlap) → `knowledge/keyword-playbook.md`.
- After changes, `list_triggers` again to confirm, and reflect the final set in
  `agents/<name>/sdk/keywords.json` + a `changelog.md` note.
- Reel-reply DM keywords can silently fail to fire (ALL_DM consumes the batch — `knowledge/platform-internals.md` §3c). Where reel engagement is common, add a COMMENT_KEYWORD fallback.

## When a tool fails or a capability is missing
Follow `knowledge/self-sufficiency.md`. This is the canonical deflection case (`approval_timeout` on a trigger read → "verificá vos en Ninjo"). Don't do that: read the actual error, retry the read, and triangulate the trigger/Story binding state with alternate tools — `get_agent_config` returns the trigger set, `list_agents` confirms the target, `trigger_fetch_info` inspects the referenced Story/post. There's no single robust binding-repair tool yet; diagnose from what these tools return and report the specific cause + exact next step, never a vague "check it manually".
