{"id":102926,"plugin_id":"plugin_asdk_app_6ad5d33159f48191b299a28716a21f47","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:17:08.267Z","digest":"39e52ac92b59bcfc316862c725e58fdad6ed54fb5b552f05649e50948a6c3be0","against":null,"payload":{"description":"Analyze Reteno contact profiles and audiences with count_segment_contacts, or messaging performance and event volume with analytics exports. Count people matching fields, events, activity, time windows, and exclusions; explain population shares and supported breakdowns without saving segments.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":233},{"relative_path":"references/audience-counts.md","size_in_bytes":6901},{"relative_path":"scripts/shard_exports.py","size_in_bytes":4360}],"name":"reteno-analytics","skill_md_contents":"---\nname: reteno-analytics\ndescription: Analyze Reteno contact profiles and audiences with count_segment_contacts, or messaging performance and event volume with analytics exports. Count people matching fields, events, activity, time windows, and exclusions; explain population shares and supported breakdowns without saving segments.\n---\n\n# Reteno Analytics\n\n## Overview\n\nUse this skill for Reteno profile statistics, audience sizes, field completeness, country/language breakdowns, event-qualified contact counts, audience overlaps, or population shares, as well as campaign performance, workflow rankings, delivery/conversion rates, event volume, and event type lookup.\n\nThis skill does not modify contacts or save segments. Audience calculations return inline counts; analytics exports require downloading and inspecting their rows with `<plugin-root>/scripts/transfer.py`.\n\nDefault to a concise summary. Return exported files only when requested.\n\n## Workflow\n\n1. Identify the analytics question and choose the smallest Reteno MCP query that answers it.\n   - Use `count_segment_contacts(schema)` for **contacts matching conditions**: profile/custom fields, missing values, events or activity (including occurrence thresholds and periods), AND/OR combinations, exclusions, and intersections supported by live definitions. Read `references/audience-counts.md` and use `$segment-designer` in `--mode count`; never create a segment merely to count it.\n   - Use `get_segment_contacts(segment_id, limit=1, offset=0)` for the active-contact count of an already saved segment, after resolving its exact ID.\n   - Use `get_messaging_analytics(group_by, date_from?, date_to?, workflow_ids?, message_ids?, media_types?, conversion_event?, order_by?)` for send, delivery, open, click, bounce, spam, unsubscribe, revenue, channel, media-type, or conversion metrics.\n   - Use `get_events_analytics(date_from?, date_to?, event_type_ids?)` for event-count denominators or event-volume breakdowns.\n   - Use `get_event_types(event_type_ids?, event_key?, search?)` first when the user provides an event name/key and you need to resolve the exact event type identifier before running analytics.\n   - Event volume and matching-contact counts answer different questions. A contact with ten purchases contributes one contact to an audience count; it can contribute ten occurrences to event analytics. Do not infer one metric from the other.\n2. Call the relevant MCP tool with the selected organization only.\n   - Avoid exploratory loops. `get_messaging_analytics` and `get_events_analytics` are limited to 10 calls per 60 seconds per MCP client/tool.\n   - Prefer one precise analytics query, then do filtering, ranking, and aggregation from the downloaded CSV.\n3. If the tool returns a manifest with signed artifact URLs instead of inline rows, download the export through `python3 <plugin-root>/scripts/transfer.py download --url <ticket> --output <file>`.\n   - Resolve `<plugin-root>` from this installed skill directory; use the transfer helper for signed tickets.\n4. Save downloaded artifacts under `output/reteno-analytics/`.\n   - Messaging exports: `output/reteno-analytics/messaging_<group_by>_<date_from>_<date_to>.csv`\n   - Events exports: `output/reteno-analytics/events_<date_from>_<date_to>.csv`\n   - If the export is JSON instead of CSV, keep the same basename and use `.json`.\n5. Inspect the local file and answer from the downloaded rows.\n   - Quote the exact `dateFrom`/`dateTo` resolved by the tool.\n   - Reflect the manifest `timeRange` and `dataAvailability` in the answer when freshness, timezone, same-day data, or datetime precision matters.\n   - Same-day analytics are available but values can change as new events arrive.\n   - If the user asked for rankings, compute them from the local rows rather than from the manifest metadata.\n6. Keep the response concise and clear.\n   - Return files only when explicitly requested.\n   - Do not move analytics exports into `saved/` unless the user later asks to keep them for reuse.\n\n## Time Range Behavior\n\nThese export defaults do not apply to profile counts. Profile fields describe the current state; event/activity periods in an audience schema must express the requested window explicitly.\n\n- `date_from` and `date_to` accept `YYYY-MM-DD` dates or ISO datetime strings.\n- Date-only values cover the full organization-local day.\n- Timezone-less datetimes are interpreted in the organization timezone.\n- Timezone-aware datetimes use their explicit instant and are reported back in the organization timezone.\n- When dates are omitted, the live API default is the last seven organization-local days, including today.\n- A single `get_messaging_analytics` or `get_events_analytics` call must not exceed 185 days.\n\n## Messaging Analytics Behavior\n\n- `group_by` must be `organization`, `workflow`, or `message`.\n- Allowed `media_types` are `email`, `sms`, `mobilepush`, `appinbox`, and `webpush`.\n- When `media_types` is omitted, the MCP default is `email` and `mobilepush`; confirm the resolved channels from `filters.mediaTypes`.\n- Every CSV row is separated by `media_type`; never merge channel rows unless the user explicitly asks for a cross-channel total and you label it as computed.\n- `organization` rows include `media_type`, core metrics, `reach`, `frequency`, delivery/open/click/conversion rates, and `revenue`.\n- `workflow` rows add `workflow_id`, `workflow_name`, and `launches`.\n- `message` rows add `workflow_id`, `workflow_name`, `callout_id`, `callout_name`, `message_id`, and `message_subject`.\n- Use `group_by=\"workflow\"` for workflow totals and rankings. Message/callout rows describe\n  message performance and are not additive workflow totals. Do not sum them to reconstruct\n  workflow counts, even when their workflow IDs match. Read `metricScope.countsSource` when\n  present and retain its meaning; compare like groupings, sources, channels and date windows.\n- If `open_rate` is blank but same-row `opened` and `delivered` are valid nonnegative numbers\n  with `delivered > 0`, calculate `100 * opened / delivered` and label it **derived open rate**.\n  Preserve a supplied native rate. Missing counts or a zero denominator mean unavailable,\n  not zero. Do not average row percentages or silently substitute message totals for workflow\n  counts. Flag inconsistent counts instead of presenting an implausible rate as reliable.\n- `spam`, `bounced`, and `unsubscribed` are message-level only.\n- `conversions` is present only when `conversion_event` is supplied. `conversion_event` can be an integer `EventTypeID` or an exact case-insensitive event key/name match.\n- Pass a supplied numeric conversion-event ID directly; resolve names through `get_event_types`.\n  A lookup failure or unavailable event metadata does not prove the ID is invalid. Preserve the\n  exact MCP error and report existence as unverified; do not guess another event or silently\n  remove the conversion filter.\n- `order_by` may use `sent`, `delivered`, `opened`, or `clicked` for all groups. `spam`, `bounced`, and `unsubscribed` are valid only for `group_by=\"message\"`. `conversions` requires `conversion_event`.\n- The finest available grouping level is callout/message. Recipient-domain, mailbox-provider, ISP, bounce-reason, recipient-level delivery errors, raw logs, and date-bucket splits are not available from this MCP analytics tool.\n- Large `group_by=\"message\"` exports can fail upstream for high-volume organizations. If a message-level export returns a 5xx/internal server error, do not keep retrying the same full-range call. Retry with smaller non-overlapping organization-local date shards, download each successful shard, and compute the requested result from local rows. For \"unique message IDs and sends\" over the last 7 days, use one shard per date, union non-empty `message_id` values for the unique count, and sum the CSV send metric (`sent`/`sends`, whichever column the export provides) across shards. Respect the 10 calls per 60 seconds limit. If any shard still fails, report a partial result and list the failed date shard(s).\n\n## Event Analytics Behavior\n\n- `get_events_analytics` groups only by event type.\n- Do not pass or invent `split_by_date` or `source`; those filters are not available on the live API-backed tool.\n- Event analytics CSV columns are `event_type_id`, `event_key`, `event_name`, `count`, `launched_workflows`, `stopped_workflows`, `contact_not_found`, and `parameter_errors`.\n- Rows are ordered by `count` descending.\n- Use `get_event_types` to resolve event keys, event names, conversion candidates, or event type IDs before querying analytics when the user provides a name rather than an ID.\n- `get_event_types` returns metadata only. It does not return counts, trends, delivery metrics, or failure diagnostics.\n\n## Active workflow count limitation\n\nMCP `list_workflows` status alone does not establish the exact business count of active,\nnot-paused workflows with a valid launch condition. Report any available inventory as an\ninventory/status count with that limitation. Do not infer missing launch-condition evidence,\nuse internal warehouse tables, or present an approximate count as exact. Individual workflow\nexports can support inspection of named workflows but do not by themselves prove the complete\norganization-wide business metric.\n\n## Output Behavior\n\n- Default: a concise summary\n- Optional: provide CSV or JSON exports only when the user explicitly asks for the file\n- Intermediate analytics artifacts stay under `output/reteno-analytics/`\n\n## Constraints\n\n- Read-only only; do not create, update, or delete Reteno entities.\n- Stay within the selected organization unless the user explicitly asks for cross-organization comparison.\n- Inspect the local downloaded artifact before answering whenever the MCP tool returns only an export manifest.\n\n## Resources\n\n- Read `references/audience-counts.md` for population semantics, safe calculation budgets, exact ranking requirements, and count reporting.\n- Use the bundled helper `python3 <plugin-root>/scripts/transfer.py download --url <ticket> --output <file>` for every signed Reteno export download.\n\n## Local export recovery\n\nUse `<skill-dir>/scripts/shard_exports.py plan --from YYYY-MM-DD --to YYYY-MM-DD --output <manifest>` to plan non-overlapping inclusive date shards. Fetch sequentially within MCP limits; record each shard as `complete` with its local CSV `path`, or `failed` with a short error. Run `shard_exports.py summarize --manifest <manifest>` to union nonempty message IDs and sum additive `sent`/`sends`. Missing, pending or failed windows produce an explicit partial result. Do not sum unique reach, distinct users, rates or overlapping audience counts across shards. Keep organization/timezone, requested dates and excluded shards in the response. Viber and Telegram are unavailable in Reteno.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}