Fetch Microsoft Clarity dashboard insights (traffic, scroll depth, engagement time, rage/dead clicks, script errors, etc.) for the last 1-3 days, optionally broken down by up to 3 dimensions. IMPORTANT: Clarity's API only supports a rolling 1-3 day lookback (no custom date ranges), and this project is limited to 10 requests per day total, so batch dimensions thoughtfully rather than making repeated calls. Optional urlFilter applies a case-insensitive substring match on the URL field AFTER Clarity returns its response (post-processing only) — results are still capped at Clarity's 1,000-row response limit, so a very broad urlFilter on a large site can still be affected by rows Clarity already dropped before filtering ever sees them. If urlFilter is set and none of dimension1-3 is 'URL', it's auto-added to the first open slot; if all 3 are already used by other dimensions, the call fails with an error asking you to free a slot.

Capture today's Clarity insights (numOfDays=1, broken down by URL) and save them to a local file (data/YYYY-MM-DD.json, UTC calendar day) so a future get_clarity_historical_insights call can retrieve this day even after it ages out of Clarity's 3-day live window. This must be triggered manually — there is no background schedule — so run it yourself whenever you want today preserved. Uses 1 of your 10 daily Clarity API requests. Safe to re-run any time today: re-running overwrites today's saved file rather than erroring or creating duplicates.

Return locally-captured Clarity snapshots for each day from startDate to endDate (inclusive, YYYY-MM-DD, UTC). This reads ONLY local files previously written by capture_clarity_snapshot — it never calls the Clarity API and cannot retrieve any day that wasn't explicitly captured, because Clarity's own API has no historical endpoint and only ever exposes the last 1-3 days. The result explicitly lists which requested dates were found locally and which are missing, so gaps are visible rather than silently dropped. There is no way to backfill a missing date after the fact. Optional urlFilter post-filters each found day's rows by URL substring, same as on get_clarity_insights. For wide date ranges, passing urlFilter is recommended to avoid returning many uncompressed days at once.