Annotation Ops

Create and manage annotations on the Fullstory timeline so you can see how deploys, experiments, and incidents correlate with changes in user behavior.

When This Runs

Invoked automatically when the user asks:

• "Mark the 3pm deploy on the timeline"
• "Add an annotation for the experiment we started yesterday"
• "Tag the incident window from 2-4pm today"
• "Show me annotatons from the last deploy"

The skill is user-invocable: false — it runs when general-analysis or weekly-digest references an annotation, or when the user explicitly asks to mark something.

What Annotations Are

Annotations are labeled time ranges on the Fullstory timeline. They're markers you set so that when viewing metrics, you can see: "Oh, the conversion drop started right when we deployed the new checkout."

Common annotation types:

• Deploy marker: A point in time when code was released
• Experiment start/end: The window an A/B test ran
• Incident window: The time range of a production issue
• Feature flag toggle: When a feature was turned on or off
• Marketing campaign: When an email blast or promotion ran

Workflow

Step 1: Clarify the annotation

When the user says "mark the deploy" or "tag the incident", ask or infer:

• Label: What should it say? (e.g., "v2.3.0 deploy", "Checkout experiment start", "API incident")
• Time: When did it start? (e.g., "3pm today", "yesterday at 2pm", "July 15 10:00 UTC")
• End time: For events with duration (incidents, experiments) — when did it end? For point-in-time events (deploys) — no end time or use start == end.
• Description (optional): Any extra context — what changed, who deployed, incident ticket link.

Step 2: Create the annotation

Call fullstory:create_annotation:

• label: Human-readable name
• start_time: ISO 8601 timestamp
• end_time: ISO 8601 timestamp (omit for point-in-time events)
• description: Optional context

The tool creates the annotation on the Fullstory timeline and returns an annotation ID. Confirm to the user: "Annotation 'v2.3.0 deploy' created at July 15 15:00 UTC."

Step 3: Use in analysis

After creating an annotation, offer to check metrics around that time: "You marked the deploy at 3pm. Want me to check if conversion changed after the deploy?"

When running general-analysis or funnel-doctor near an annotation time, reference it: "Checkout conversion dropped 4 points starting July 15th — coinciding with the 'v2.3.0 deploy' annotation."

Annotation Best Practices

• Be specific in labels: "v2.3.0 deploy" not "deploy". "Checkout experiment v2" not "experiment".
• Include the incident link in the description for incident annotations.
• Use point-in-time (start == end) for deploys and feature toggles. Use duration for experiments and incidents.
• If the user mentions a time relative to now ("3pm today", "yesterday"), convert to the correct date — don't ask them to do it.

Reading Annotations

If the user asks "what annotations exist around this time?", annotations are visible in the Fullstory UI on the timeline. The MCP server doesn't currently have a list_annotations tool — direct the user to the Fullstory app to see them visually alongside their metrics.