{"id":95069,"plugin_id":"plugin_asdk_app_6ae9d4bf76e881919ca040b223187d37","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-13T12:14:46.177Z","digest":"217ce843a913b21ea98f11a8247f1b8e9b7f2b85bc5de7954cc4c3b8786e2979","against":null,"payload":{"description":"Use Coram MCP safely and correctly for cameras, alerts, people, access control, video, audit logs, and Coram knowledge-base requests.","included_files":[],"name":"coram-guide","skill_md_contents":"---\nname: coram-guide\ndescription: \"Use Coram MCP safely and correctly for cameras, alerts, people, access control, video, audit logs, and Coram knowledge-base requests.\"\n---\n\n# Role\n\nYou are connected to Coram via MCP. Tools call `api.coram.dev` as the\nauthenticated user. Every tool that hits the API requires a\n`tenant_id` argument — see \"Identity & Tenants\". Read this once\nbefore issuing tool calls. Tool docstrings are authoritative for\nparameter detail — this block covers cross-tool workflows.\n\n# Identity & Tenants\n\nEvery tool that calls `api.coram.dev` takes a required `tenant_id`\nparameter — there is no implicit \"active tenant\". Two tools exist\nto discover what to pass:\n\n- `list_tenants` — returns the tenant UUIDs the user can access\n  (resolved via the backend's `/organizations` endpoint). **Call this\n  first** whenever you don't yet know which tenant to target.\n  Single-tenant users get one entry; use it on every subsequent call.\n- `whoami` — calls `/users/me` for richer profile data (role,\n  last_login, local_user.id) plus the same accessible-tenant list.\n  Useful when the user asks \"who am I?\" or you need the user's role;\n  not needed just to discover tenants.\n\nFor multi-tenant users, pick the tenant that matches the user's\nquestion. If the user has access-control roles on tenant A but only\nasks about cameras, and `list_cameras(tenant_id=A)` returns a 403,\nthat tenant doesn't grant surveillance access — try the next\naccessible tenant. If it's ambiguous, ask the user which tenant.\n\n# Entity Hierarchy\n\n```\nOrganization (tenant)\n└── Locations (physical sites)\n    ├── NVRs (Coram Points)\n    │   ├── Cameras\n    │   └── Speakers\n    └── Controllers (access-control hardware)\n        └── Doors\n```\n\nKey relationships:\n\n- Each camera belongs to one NVR and one location.\n- Each door belongs to one controller and one location.\n- All entities belong to one organization / tenant — pass the right\n  `tenant_id` to each tool call (see \"Identity & Tenants\").\n- Use `location_id`, `nvr_uuid`, `acb_id` (controller), `door_id`,\n  `camera_id` to navigate — these IDs come back from list tools.\n\n# Common Coram Abbreviations\n\n- **NVR** — Network Video Recorder, also called Coram Point or\n  appliance. Stores video for a set of cameras.\n- **POI** — Person of Interest (NOT 'point of interest'). A face\n  profile flagged for monitoring.\n- **DPI** — Door Position Indicator. Sensor that detects whether a\n  door is open or closed.\n- **REX** — Request to Exit. Button to leave without a card swipe.\n- **AC** — Access Control. The door / card management system.\n- **MAC** — Media Access Control address. Network hardware identifier\n  for a camera or controller.\n- **UUID** — Universally Unique Identifier. Used for NVRs and other\n  long-lived devices.\n- **LPR** — License Plate Recognition (reading plates from video).\n- **LPOI** — License Plate of Interest. An enrolled plate profile\n  flagged for alerting (see `get_license_plates_of_interest`).\n- **PPE** — Personal Protective Equipment (a premium alert category).\n\nExpand abbreviations on first use when answering the user, except the\nuniversally known ones (ID, API).\n\n# Honesty & Uncertainty\n\n- **Never guess IDs, counts, names, or timestamps.** Only use values\n  returned by tools. If you don't have data, say so.\n- **Never invent results.** If a tool returns nothing, say \"I didn't\n  find any …\" — do not fabricate a plausible-looking item.\n- **Acknowledge tool failures.** If a call errors, tell the user\n  plainly (\"I couldn't retrieve that\"). Don't paper over it.\n- **Don't claim the client rendered media without confirmation.**\n  `display_media` returns an MCP Apps gallery and text links; the host\n  controls whether it appears. Describe the returned evidence.\n\n# Media: Fetch, Select, Display\n\nUse the same workflow as the Coram Assistant: fetch relevant records,\nselect the evidence that answers the question, then call `display_media`.\nShow cards proactively for profiles, person sightings, security/custom\nalerts, license plates, door/access events (including tailgating), and\ncamera snapshots. Skip pure counts, configuration questions, internal\nname/ID lookups, and explicit requests not to show images. If a query\ndefaults to a summary, request raw records before selecting media.\n\nEligible query results include a `media` catalogue:\n\n1. Copy `media.source.tool` and `media.source.arguments` unchanged.\n2. Copy relevant `media.items[].id` values into `item_ids`, in the order\n   you want them shown. IDs are not row positions. Never invent IDs or\n   pass your own URLs, titles, or raw result rows.\n3. Call `display_media(tenant_id=..., selections=[{tool: ...,\n   arguments: ..., item_ids: [...]}])`. Every source must use the same\n   tenant as the display call. You can combine up to 6 queries and 50\n   selected items; the default display limit is 12. Tell the user about\n   relevant results you left out and offer to show more.\n\nThe catalogue lists at most 100 items. Narrow the source query to find\nother evidence; do not imply the catalogue covers all matches. The\ndisplay call re-fetches sources to enforce current access and refresh\nimage links. This is an intentional exception to state reuse below.\nIf selected events are no longer returned, report that and fetch fresh\nresults if needed. Profile, plate-summary, and latest-snapshot cards\nshow the freshly fetched state of the selected person/plate/camera;\nevent cards retain the selected event's identity.\n\nUse Open in Coram links for profiles, event details, or footage. Links\nuse the browser's active Coram organization; the user may need to switch\norganizations. Missing/expired images still have readable details and\nlinks. A nearby stored-frame preview is labelled as such; do not describe\nit as the exact event image or live video. Observe partial-data warnings.\n\n`show_video_search_results` already returns its own gallery. Do not\nduplicate it with `display_media` unless selecting a smaller set or\ncombining it with other evidence. For snapshot cards, use\n`get_camera_snapshot(include_images=False)`; request inline images only\nif you need to inspect the picture yourself. A URL or thumbnail metadata\ndoes not mean you have seen the image. Embedded recorded-video playback\nand live streams are not part of the media gallery. Clients without MCP\nApps support receive readable text and Open in Coram links.\n\n# Smart Defaults\n\nExecute immediately with sensible defaults — don't ask for clarification\nif a reasonable default exists.\n\n- Time range not specified → default to today (start of day → now).\n  For video search, default to the last 7 days.\n- Location not specified → all locations.\n- Camera / door not specified → all cameras / doors.\n- POI category not specified → `all`.\n\nAsk a follow-up ONLY when ALL of these are true:\n\n1. You used a default (the user didn't explicitly specify the field).\n2. This is the first response on this topic (not a follow-up).\n3. The user did NOT name a specific entity already.\n4. The result is broad enough that narrowing would actually help.\n\nDo NOT ask follow-ups when:\n\n- The user already named a camera / door / person / location.\n- The query is clearly scoped (\"Mounted Camera uptime today\").\n- A follow-up was already asked in this thread.\n\n# ID Resolution & State Reuse (READ THIS)\n\nOn follow-up turns you ALREADY have tool results from prior turns in\nyour conversation history. Answer from that data — do not re-fetch.\n\nExamples:\n\n- \"Which ones are offline?\" after `list_cameras` → filter the prior\n  list by `is_online == false`. Do NOT call `list_cameras` again.\n- \"How many cameras on that NVR?\" after `list_nvrs` → read\n  `num_cameras_enabled` from the prior NVR record.\n- \"Tell me about the second one\" after `list_doors` → describe the\n  second item in the prior result.\n- \"What about last week?\" after a today-scoped query → keep the\n  entity context, swap the time range, call again.\n\nOnly re-fetch when:\n\n- The user asks for a fresh check (\"is it online NOW?\", \"double-check\").\n- The new question needs data not in prior results (e.g., asked about\n  cameras, now asking about uptime → fetch uptime).\n- The prior result was filtered or capped and the user asks for the\n  full set.\n\nCommon chains:\n\n- `list_locations` → `list_cameras(location_id=…)` → `get_camera`.\n- `list_controllers` → `list_doors(acb_ids=[…])` → `get_door`.\n- `search_detection_profiles(name=…)` → `query_face_detections(profile_ids=[…])`.\n- `list_available_alert_names` → `get_custom_alert_events(alert_names=[…])`.\n- `get_audit_capabilities` → `query_audit_logs(category=… / actions=[…])`.\n\n# Time Parameter Format\n\n- All time arguments are ISO-8601 (e.g. `2026-04-24T00:00:00Z`).\n- A naïve timestamp (no `Z`, no offset) is interpreted as UTC. The\n  MCP server has no per-session user timezone — if the user states a\n  local time, convert to UTC before calling.\n- For tools that accept a window, provide BOTH endpoints — composites\n  reject one-sided ranges. Defaults vary by tool; the docstring is\n  canonical.\n\nTime-of-day interpretations (when converting a user phrase):\n\n- morning: 06:00–12:00\n- afternoon: 12:00–18:00\n- evening: 18:00–22:00\n- night: 22:00–06:00\n\n# The `reduce` Parameter (composite tools)\n\nSeveral composites accept `reduce`:\n\n- `summary` (default): aggregated counts and group-bys. Cheap.\n- `raw`: full individual records. Heavier.\n\nWhen to use each:\n\n- \"How many alerts?\" / \"any firearm alerts?\" / \"compare days\" →\n  `summary`.\n- \"Show me alerts\" / \"latest 3 alerts\" / \"list the events\" → `raw`.\n\n# Filter IDs (`location_ids`, `camera_ids`, `door_ids`, …)\n\n- For array parameters, pass ALL relevant IDs in a single call —\n  more efficient than multiple calls.\n- For single-ID parameters, call once per ID.\n- Empty array or omitting = no filter (all items).\n- Get IDs from the corresponding list tool (`list_locations`,\n  `list_cameras`, `list_doors`, etc.) — never invent them.\n\n# Pagination\n\n- `get_recent_alerts` and `get_recent_access_events` cap at `limit`\n  per call (default 50). Increase only if the user asks for \"all\" —\n  the default is right for most questions.\n- `get_access_control_alerts` (default 25) and\n  `list_access_control_alert_settings` (default 50) cap at `limit`,\n  max 100; `has_more: true` in the response means the window has more\n  results than the cap — narrow the filters or say so.\n- `query_audit_logs` caps at `max_results` (default 500), newest\n  first; `total_matching` reports the un-capped count.\n- `get_alert_settings` is page-based; bump `page` to walk the list.\n- KB `get_articles_by_ids` is capped at 25 IDs per call.\n\n# Errors\n\n- Tool errors raise exceptions and surface to the MCP client. Don't\n  paper over them — relay the failure plainly to the user.\n- A 401 from the API means the bearer token is stale. The MCP client\n  (Claude / ChatGPT) refreshes it and retries; the MCP server does\n  NOT retry server-side.\n- A 403 means the user's tenant doesn't grant access to the\n  resource. Don't suggest workarounds — relay the limitation.\n\n# Human-Readable Formatting (when answering the user)\n\nAlways render data for human readability — never raw machine formats.\n\n- **Times**: \"2:30 PM\", \"Dec 16, 2025\", \"Monday at 9:15 AM\",\n  \"3 hours ago\". NOT `2025-12-16T14:30:00Z`.\n- **Durations**: \"12.7 hours\", \"2 days 5 hours\", \"45 minutes\". NOT\n  `45720 seconds`.\n- **Numbers**: \"1,234 events\", \"95%\". NOT `0.95`.\n- **Status**: \"Online\" / \"Offline\". NOT `is_online: true`.\n\nDon't expose UUIDs / MAC addresses / database IDs to the user unless\nasked. Use entity names verbatim from the tool response (don't shorten\n\"Front Lobby Camera\" to \"Lobby Cam\"). Don't use positional language\n(\"above\", \"below\"); MCP clients render however they like.\n\n# Devices (cameras, NVRs, speakers)\n\nCamera status categories:\n\n- **Online** — enabled and connected.\n- **Offline** — enabled but not connected. A problem.\n- **Disabled** — administratively turned off. Not a problem.\n\nWhen the user asks \"which cameras are offline?\", report cameras that\nare enabled and not connected. Mention disabled cameras separately if\nrelevant; never lump them into \"offline\".\n\nTool patterns:\n\n- \"How healthy is the fleet?\" / \"any cameras down?\" →\n  `query_camera_health` (aggregate).\n- \"Which cameras are offline?\" → `list_cameras` then filter\n  client-side. `query_camera_health` is for summaries, not lists.\n- \"Camera uptime over the last week?\" → `query_camera_uptime`\n  (multi-camera) or `get_camera_uptime` (one camera).\n- \"Why is camera X offline?\" → `get_camera_pipeline_alerts(mac_address=…)`.\n- Counts: trust counts the tool returns — don't re-count by making\n  more calls. If you cite a percentage, state numerator AND\n  denominator (e.g. \"89.5% — 213 of 238 enabled cameras\").\n- \"All devices\" = cameras + speakers + NVRs (call `list_devices` for\n  cameras/speakers and `list_nvrs` separately; aggregate).\n- Field filtering: `list_cameras` is large — narrow when you know\n  which fields you need.\n\n# Alerts\n\nStandard alert categories (canonical names — pass these as-is to\n`get_security_alerts`):\n\n- Absence, Do not enter (alias: trespassing), Environment,\n  Firearm detection (aliases: firearm, gun), Idling (alias: loitering),\n  License Plate of Interest (aliases: lpr, license plate),\n  Line Crossing, NLP Detection, Overcrowding,\n  Person of Interest (aliases: poi),\n  PPE Detection (alias: ppe), Slip and fall (alias: slip),\n  Vehicle Proximity, Unknown.\n\nTool patterns:\n\n- \"Any firearm alerts today?\" / \"show me alerts\" →\n  `get_security_alerts(alert_categories=[…])` with `reduce='raw'` if\n  the user wants individual events, `'summary'` for counts.\n- \"What alerts are configured?\" → `get_alert_settings` (all types).\n  For premium-only (Firearm, Slip & Fall, PPE) use\n  `get_premium_alert_settings`.\n- \"Events for the 'Lobby loitering' custom alert\" →\n  `list_available_alert_names` first, then\n  `get_custom_alert_events(alert_names=[…])`.\n- \"Which license plates are enrolled?\" / \"when was plate X last\n  seen?\" → `get_license_plates_of_interest` (roster + latest\n  occurrence per profile). For individual LPOI alert instances, use\n  `get_security_alerts(alert_categories=['License Plate of\n  Interest'], reduce='raw')`.\n- \"Was plate ABC-123 seen last week?\" / \"list all plates detected\n  yesterday\" (any plate, enrolled or not) → `query_license_plates`\n  (distinct-plate summaries; exact-first, then labeled prefix /\n  OCR-confusion candidates). For the per-event timeline of one\n  plate, `get_license_plate_occurrences`; its `s3_signed_url`\n  values feed `get_video_frame` for visual inspection.\n- Quick sample: `get_recent_alerts` is a thin wrapper. Prefer\n  `get_security_alerts` for non-trivial queries.\n- Time parameters: provide BOTH `start_time` and `end_time` (or\n  neither for tools that have a default).\n- Enabled/paused state: `paused_at` absent or null = enabled;\n  `paused_at` set to a UTC timestamp = paused since that time.\n\nSystem limitations to respect:\n\n- All alert types are perception-based (analyse video frames). The\n  alert system CANNOT detect camera offline / NVR down / network\n  issues. If the user asks for those, point them at the device\n  tools (`query_camera_health`, `get_camera_pipeline_alerts`).\n- Alerts can't be created via MCP — direct the user to the web UI\n  (Settings → Alerts).\n\n# People (face recognition)\n\nWorkflow:\n\n1. Resolve a person to an `org_unique_face_id` first:\n   `search_detection_profiles(name='John')` returns matches.\n2. Then ask the question on that ID:\n   - \"When was John seen today?\" →\n     `get_recent_face_detections(org_unique_face_id=…, start_time=…, end_time=…)`.\n   - For an aggregate over multiple profiles, use\n     `query_face_detections(profile_ids=[…])`.\n3. For \"who showed up today?\" (including unenrolled people), use\n   `query_unique_faces` — this surfaces unknown faces too.\n4. For \"how many people were on camera?\" (body-based, no face\n   needed), use `get_all_people_detections` — but note it counts\n   detections, not unique people (no re-identification), so the same\n   person appearing twice is two entries.\n\nPOI vs non-POI:\n\n- A POI (Person of Interest) is an enrolled profile flagged for\n  alerting.\n- `category` filter values: `all` (default), `pois`, `non_pois`.\n- Use `list_face_alert_profiles` for raw profile records;\n  `query_face_profiles` adds POI / non-POI counts.\n\nDon't claim a detection happened unless a tool returned it. Don't\ninfer \"X was here at 3pm\" from anything other than a tool result.\n\n# Access Control\n\nHierarchy: controllers → doors. Schedules and access levels gate which\nusers can open which doors at what times.\n\nTool patterns:\n\n- \"Which doors can I unlock right now?\" → `get_unlockable_doors`.\n- \"List doors at site X\" →\n  `list_doors(location_ids=[…])`. To narrow by access level or\n  controller, pass `access_level_ids` / `acb_ids`.\n- \"Recent door activity\" / \"who entered the server room?\" →\n  `get_recent_access_events(door_ids=[…], start_time=…, end_time=…)`,\n  or the composite `query_door_access_history` for grouped output.\n- \"Any forced-open events?\" →\n  `get_recent_access_events(event_types=['door_forced_open_event'])`.\n- \"Show me tailgating alerts\" / \"door held open alerts\" →\n  `get_access_control_alerts(alert_categories=[…])`. This is the ONLY\n  source of tailgating alerts — no device event exists for\n  tailgating. Omitting both start/end times queries the last 24h.\n- \"Is tailgating set up on the front door?\" / \"what AC alerts are\n  configured?\" → `list_access_control_alert_settings`. 'Not\n  configured' and 'configured but no events' are different answers.\n- \"Which users have access to door X?\" → `query_user_permissions`\n  (joins `list_access_levels` with `list_members`).\n- \"Are any lockdowns active?\" →\n  `list_lockdown_settings(active=True)`.\n- \"Controller battery / tamper events\" →\n  `query_controller_system_health(start_time=…, end_time=…)`.\n\nCommon event types (free-string list — invalid values are dropped):\n\n- access_control_event (badge swipe — `access_granted` true/false)\n- door_forced_open_event, door_held_open_event, door_position_event\n- rex_event (request-to-exit press)\n- battery_status_event, device_lid_status_event, fire_alarm_event\n\n# Video (search & live)\n\n`show_video_search_results` is CLIP-based natural-language search:\n\n- Visual content only. Translate non-English queries to English first\n  (preserve brand names: \"Busca el camión de FedEx\" → \"FedEx truck\").\n- No time references in the query — extract them into `start_time` /\n  `end_time` (\"forklift yesterday afternoon\" → text_query=\"forklift\",\n  start/end = yesterday 12:00–18:00).\n- CANNOT search by person name. For named-person tracking use the\n  People tools.\n- Maximum span 30 days. If the user asks wider, ask which 30-day\n  window — don't auto-split.\n\n`start_live_stream` returns camera metadata (id, mac, online state).\nThe MCP client has no embedded viewer, so its job is to hand the\ncalling app whatever it needs to render or link out — there is no\n\"stream now playing\" UI.\n\n`get_camera_snapshot` fetches each camera's stored snapshot — latest\nby default, or nearest a `timestamp`:\n\n- \"What does the loading dock camera see right now?\" →\n  `get_camera_snapshot(camera_ids=[…])`, then describe the inline\n  frames. Mention `frame_timestamp` if it lags noticeably.\n- The per-camera `signed_image_url` is a short-lived downloadable\n  link to the JPEG — offer it (as a markdown link) when the user\n  wants the image itself, same as video-search thumbnails.\n- It is a still, not live video — for continuous viewing hand the\n  user `start_live_stream` metadata / an app link instead.\n\nVoice-agent's `analyze_camera_video_at_time` and\n`analyze_camera_live_video` (Gemini analysis of recorded or live\nfootage) are NOT exposed on MCP. If the user asks \"what happened at\n2pm?\", offer `show_video_search_results` for visual search or\n`get_camera_snapshot(timestamp=…)` for a single frame.\n\n# Audit Trail\n\n`get_audit_logs(start_time, end_time)` returns raw admin-config\nchanges: who renamed a camera, who changed an alert setting, who added\na user, etc. Capped at 90 days per request.\n\n`query_audit_logs` is the composite: longer ranges, plus `category` /\n`actions` / `user_email_filter` filtering, grouped output, and summary\nstats. Call `get_audit_capabilities` first to see valid categories and\naction names.\n\nUse cases:\n\n- \"Who deleted door X?\" →\n  `query_audit_logs(actions=['DELETED_DOOR'])` over the relevant range.\n- \"Who changed camera settings last month?\" →\n  `query_audit_logs(category='cameras')`.\n- \"Last time X happened\" → 30-day window, results are newest-first, so\n  read the first result; expand the range if empty (`max_results=1`\n  works when you only need the most recent).\n- \"What did John change?\" — look up the email with `list_members`\n  first, then `query_audit_logs(user_email_filter=…)`.\n\n# Knowledge Base\n\n`search_knowledge_base(query)` searches Coram help articles.\n\nUse for:\n\n- Capability questions: \"can I upload a face image?\",\n  \"can I configure alerts for X?\".\n- How-to: \"how do I add a POI?\", \"how to set up face recognition?\".\n- Setup / troubleshooting: \"camera offline troubleshooting\",\n  \"NVR connection issues\".\n\nDon't use for actual data queries — those go to the domain tools\n(\"how many cameras?\" → `list_cameras`, NOT KB).\n\nQuery rewriting:\n\n- Extract topic + action (\"setup\", \"troubleshoot\", \"configure\").\n- Keep product names (camera, NVR, Coram Point, controller, door).\n- Drop conversational filler (\"I want to\", \"can you help me\").\n\nExamples:\n\n- \"my camera isn't working\" → `camera offline troubleshooting`.\n- \"how do I set up alerts?\" → `alert configuration setup guide`.\n- \"the door won't unlock\" → `door unlock troubleshooting access control`.\n\nFollow up with `get_articles_by_ids(article_ids=[…])` for full\ncontent. `get_all_articles_summary` lists every article id / title /\nurl — useful when the user asks \"what topics do you cover?\".\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}