# Hand-offs: the tools that enforce or document a plan A schema tool validates types and names. It cannot tell whether `report_generated` fired before the job finished. Keep business-outcome checks in the acceptance tests and use these tools for what they enforce. Every action below that changes a live workspace is a draft for a human to approve. Produce the file, diff or change list, then stop. Nothing under `martech-context/` or `.amplitude/` is written until the user approves the listed files either. ## Contents - Where the plan lives - Segment Protocols - RudderStack tracking plans - Mixpanel Lexicon, Event Approval and Data Standards - Amplitude Data - Amplitude instrumentation context file - GA4 and HubSpot - Translating a contract into a schema ## Where the plan lives - Pick one source of truth and generate the rest from it. Options: the YAML contracts in `martech-context/tracking-plan/`, a two-tab sheet, or a governance tool (Segment Protocols, RudderStack tracking plans, Amplitude Data, or a dedicated tracking-plan tool such as Avo). - Contracts hold things no schema tool stores: trigger, must-not-fire, source of truth, consent routing, acceptance cases. If the team's source of truth is a schema tool, keep the contracts beside it and link each event to its contract. - Two editable copies drift within a release or two. Mark every generated copy as generated, with the date and the source. ## Segment Protocols What it is, checked 2026-10-17: - An add-on available for Business plans only. - A tracking plan defines Track events with properties and can also validate Identify, Page and Group calls, using JSON Schema. Plans live in the workspace and connect to one or more sources. - Plans can be created or updated by CSV upload (under 15 MB, fewer than 100,000 rows, fewer than 2,000 rules) or through the Segment Public API, which Protocols customers can use to list, get, create, update and delete tracking plans. Typewriter generates typed analytics clients from a plan. - Event versions: send the integer `context.protocols.event_version`; events without a valid version are validated against the oldest version. - Schema controls: Block Event for unplanned Track events; Omit Properties for unplanned properties; Block Event or Omit for JSON Schema violations; trait omission (Omit Traits) for unplanned Identify traits. Omit Properties, violation blocking and Omit Traits apply only to cloud-mode and storage destinations; device-mode destinations still receive them. Blocked events are discarded permanently unless forwarded to a separate source. - Twilio's MCP server only searches and retrieves documentation. There is no first-party Segment control-plane MCP, so plan changes go through the app or the Public API. How to hand off: - Generate the CSV or JSON Schema draft from the contracts (see the last section) and give it to the workspace owner to upload. - Keep Identify and Group traits optional. Clients cache traits and send only changed ones, so a required trait rejects legitimate partial updates. - Connect the plan with blocking off. Turn on blocking only after the violations view shows nothing but genuinely unwanted events for at least one full release cycle, and forward blocked events to a quarantine source first so mistakes can be recovered. ## RudderStack tracking plans What it is, checked 2026-10-17: - Tracking plans validate `track`, `identify`, `page`, `screen` and `group` events (not `alias`) for allowed events, required properties and types. Free: 1 plan with 5 events; Growth: unlimited plans, 75 events per plan; Enterprise: unlimited. - Per-source settings on the source's Tracking Plans tab: Drop events with unplanned event names (track only), Drop events with unplanned event properties, Drop events with other violations (type mismatch, missing required fields), and Propagate errors (violations written into the event `context` and forwarded; when off, events with errors are dropped). RudderStack recommends keeping Propagate errors on. - Plans can be managed in the dashboard, through the Data Catalog API, or as YAML with Rudder CLI (public beta; the CLI's YAML schema version has changed between releases, so check the current docs). - The RudderStack MCP server reads tracking plans, violations and the data catalog. It is not read-only: RudderStack states its only write operations are creating or updating transformations and connecting them to destinations, which changes a live pipeline. It does not write tracking plans or the data catalog. - RudderStack's own agent skills (`rudderlabs/rudder-agent-skills`, MIT) include tracking plan, data catalog and Rudder CLI workflow skills. How to hand off: - While planning, call only the MCP read tools. Do not call the transformation write tools without the user's explicit approval for that specific change. - Give the contracts to the RudderStack tracking plan skill or a developer to express as Rudder CLI YAML; review the dry run or diff before anyone applies it. - Start with Propagate errors on and all three drop settings off; switch drops on per source after violations reach zero for planned traffic. ## Mixpanel Lexicon, Event Approval and Data Standards What it is, checked 2026-10-17: - Lexicon is a data dictionary over ingested data: display names, descriptions, tags, hidden status, merges, and Block (formerly Drop). Display names and merges do not change raw data. Lexicon does not validate incoming payloads against a schema. - Block stops storing new data for the event or property and the blocked data cannot be recovered; only project owners can block, unblock and merge. Verified status and event owners are Enterprise features. - Event Approval (Enterprise only; enabled by project admins or owners) hides new events by default and notifies admins, who make approved events visible. It hides; it is not documented as blocking ingestion. - Data Standards (Enterprise only; defined by project admins or owners) checks events against rules such as a naming convention (snake_case or camelCase), a required description, an assigned owner and attached media, and marks each event compliant or not in Lexicon. It is not documented as blocking ingestion. It checks the display name when one is set, otherwise the tracked name, so a tidy display name can make a non-compliant raw name look compliant. - Mixpanel's MCP server has write tools for Lexicon (edit event and property descriptions, display names, tags, visibility, PII classification, bulk edits of up to 50 items, duplicate merges). No read-only mode is documented; changes are attributed to the connected account in the audit log. - Mixpanel's own skills (`mixpanel/ai-plugins`, Apache-2.0) include `manage-lexicon` and `tracking-implementation`. How to hand off: - Use only the MCP read tools (events, properties, issues) during planning. Produce a change list of descriptions, display names and tags from the contracts, and let the user approve it before any write tool runs. - Where the plan is Enterprise, recommend setting Data Standards to the plan's naming rule, description and owner requirements, and turning on Event Approval so unplanned events stay hidden until reviewed. Both are admin settings for a human. - For implementation, Mixpanel's `tracking-implementation` skill implements from a finished spec when the request carries one. The hand-off message includes: - the approved event list with each property's type, required flag and allowed values, taken from the contracts - an explicit instruction not to re-run discovery - the consent decision for each event, because the skill always asks about consent before initialising the SDK - the identity mapping (`$device_id`, `$user_id`) and the derived `message_id` for `$insert_id` - The skill also needs a project token. The user gives it to Mixpanel's skill directly; it never goes into the plan files or the hand-off text. ## Amplitude Data What it is, checked 2026-10-17: - The tracking plan with branches. Settings include a naming convention preset (including snake_case and Title Case), an option to require team reviews for changes to the main branch with up to seven reviewers, and schema settings that mark unplanned events, properties and types as unexpected (ingested, subscribers notified) or reject them (not ingested). - Amplitude's MCP server writes taxonomy: create, update, delete and restore events and properties, and create, merge and review tracking plan branches (`manage_amp_taxonomy` for branches). Read and write are separate RBAC actions, Use MCP (read) and Use MCP (write). Amplitude states that every role grants read and that Member, Manager and Admin also grant write; there is no separate read role. Taxonomy writes also need the Update Tracking Plan permission. Deletes take two calls, the second confirming. The MCP server does not ingest events. - Amplitude's own skills (`amplitude/mcp-marketplace`, MIT) include taxonomy, tracking plan audit, event surface discovery and event instrumentation skills. How to hand off: - While planning, connect with an account whose role on the project grants only Use MCP (read): a Viewer, a custom role, or a role an admin has restricted to read-only on that project. A Member who connects for planning has write access. - When the plan is approved, the agent drafts the change list for a branch. The branch is created only after explicit approval, by a user whose role has Use MCP (write) and Update Tracking Plan, or through Amplitude's own taxonomy skill. Never on main; the required reviewers approve the merge. - Set schema handling to mark unexpected first. Move to reject only after planned traffic produces no unexpected events for a full release cycle. ## Amplitude instrumentation context file Amplitude's instrumentation skills check for an optional `.amplitude/instrumentation-agent-context.md` at the repo root (or the root of the sub-tree being instrumented). They treat its contents as the customer's conventions (naming, property standards, constraints, glossary) and also read repo files it points to. They do not treat it as overriding their own safety rules. - Offer to write it when Amplitude is in the stack and the plan is approved, and write it only after the user approves it. Use `assets/amplitude-instrumentation-agent-context.md`. - Point it at the plan files instead of copying contracts into it, so there is one source of truth. - State the final Amplitude event names explicitly. Amplitude's own example in that skill uses Title Case; without an explicit rule the instrumentation agent may follow it instead of the plan. - The same skills also use `.amplitude/instrumentation-agent.yaml` to map repo paths to Amplitude project IDs. Do not create it with guessed IDs; the user supplies real project IDs. ## GA4 and HubSpot - GA4 has no tracking plan enforcement. The plan's controls are the naming budget, the parameter count and the custom definitions list. Google's GA4 MCP server is read-only and useful for verifying received event names and registered dimensions. Registering custom dimensions and marking key events are admin changes for a human; key events are marked before the release that first sends them. - With `via: gtm`, give the GTM owner the dataLayer push from the contract (event name, keys, once-per-`event_id` guard) and the GA4 event and parameters it maps to. Container changes are theirs to make and publish. - HubSpot custom event definitions are created through the event definitions API or, on eligible subscriptions, in the app. HubSpot's remote MCP server reads and writes CRM records; it is not documented as managing custom event definitions, so treat definitions as a developer task. Property internal names are permanent, so the plan's names must be final before creation. The unique-value match property for derived properties is created before the first sync runs. ## Translating a contract into a schema When drafting a Protocols JSON Schema, a RudderStack YAML plan or an Amplitude Data event: - `type: string` with `allowed_values` becomes `"type": "string", "enum": [...]`. - `required: true` goes into the event's required list. Optional properties that may be null become `"type": ["string", "null"]`. - `unit` and `description` go into the property description; schema tools do not enforce units. - `unknown_value_policy: send_unknown_and_alert` means `unknown` must be in the enum. - Identifiers that travel in the envelope (`userId`, `anonymousId`, `messageId`) are not event properties; do not duplicate them as required properties. `event_id` is a property when companion or renamed events carry it. - Things no schema enforces: trigger, must-not-fire, source of truth, grain, account at event time, PII in free text that matches a permitted type. Those stay in acceptance tests and monitoring.