feat(radar): clarify positional mapping for dateRange filter arrays and dimension types

Improve documentation to explain that filter arrays (location, asn,
continent, geoId) map positionally to dateRange arrays. When comparing
time periods for the same location, users must repeat the filter value
for each dateRange element, otherwise unmatched periods default to
worldwide data.
Also adds documentation for dimension types (timeseries, summary,
timeseriesGroups) and includes ASN in filtering options.

Author: andre-j3sus

apps/radar/src/radar.context.ts

@@ -44,17 +44,64 @@ This server provides tools powered by the Cloudflare Radar API for global Intern
 
 ## Making Comparisons
 
-Many tools support **array-based filters** for comparisons. Each array index corresponds to a distinct data series.
-Example: Compare HTTP traffic between Portugal and Spain over the last 7 days:
+Many tools support **array-based filters** for comparisons. Filter arrays (location, asn, continent, geoId) map **positionally** to dateRange arrays - each array index corresponds to a distinct data series.
+
+### Cross-Location Comparison (Same Time Period)
+Compare HTTP traffic between Portugal and Spain over the last 7 days:
 - \`dateRange: ["7d", "7d"]\`
 - \`location: ["PT", "ES"]\`
 
-## Geographic Filtering
+Result: \`summary_0\` = Portugal (7d), \`summary_1\` = Spain (7d)
+
+### Time Period Comparison (Same Location)
+Compare Portugal bandwidth this week vs last week:
+- \`dateRange: ["7d", "7dcontrol"]\`
+- \`location: ["PT", "PT"]\`  *(repeat the location for each dateRange)*
+
+Result: \`summary_0\` = PT (current week), \`summary_1\` = PT (previous week)
+
+### IMPORTANT: Positional Mapping Behavior
+Filter arrays must match the length of dateRange for consistent filtering. If you provide fewer filter values than dateRange values, unmatched periods default to worldwide/unfiltered data.
+
+**Correct** (comparing Portugal across time periods):
+- \`dateRange: ["7d", "7dcontrol"], location: ["PT", "PT"]\`
+
+**Incorrect** (control period will be worldwide, not Portugal):
+- \`dateRange: ["7d", "7dcontrol"], location: ["PT"]\`  *(missing second location)*
+
+This positional mapping applies to all filter arrays: **location**, **asn**, **continent**, and **geoId**.
+
+## Geographic Options
 
 - **location**: Filter by country (alpha-2 codes like "US", "PT")
 - **continent**: Filter by continent (alpha-2 codes like "EU", "NA")
+- **asn**: Filter by Autonomous System Number (e.g., "13335" for Cloudflare, "15169" for Google)
 - **geoId**: Filter by ADM1 region (GeoNames IDs for states/provinces) - available for HTTP and NetFlows
 
+## Dimension Types
+
+Many tools use a \`dimension\` parameter to control the response format:
+
+### timeseries
+Returns data points over time with timestamps and values. Best for line charts showing trends.
+\`\`\`
+{ timestamps: ["2026-01-01T12:00:00Z", ...], values: ["0.735", "0.812", ...] }
+\`\`\`
+
+### summary
+Returns aggregated percentages or values grouped by a category. Best for pie/bar charts.
+\`\`\`
+{ Chrome: "31.44%", ChromeMobile: "27.89%", Safari: "12.27%", ... }
+\`\`\`
+
+### timeseriesGroups
+Combines both: time series data broken down by category. Best for stacked area/line charts.
+\`\`\`
+{ timestamps: [...], Chrome: ["28.15", "27.35", ...], Firefox: ["31.01", "31.23", ...] }
+\`\`\`
+
+Use \`summary/*\` dimensions (e.g., \`summary/browser\`) for snapshots and \`timeseriesGroups/*\` (e.g., \`timeseriesGroups/browser\`) for trends over time.
+
 ## Visualizations
 
 Generate charts when appropriate:

apps/radar/src/types/radar.ts

@@ -68,7 +68,11 @@ export const DateRangeArrayParam: z.ZodType<HTTPTimeseriesParams['dateRange']> =
 	.describe(
 		'Filters results by date range. ' +
 			'For example, use `7d` and `7dcontrol` to compare this week with the previous week. ' +
-			'Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).'
+			'Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters). ' +
+			'IMPORTANT: When using multiple dateRange values for comparison, filter array parameters (location, asn, ' +
+			'continent, geoId) map positionally to each dateRange element. For example, with dateRange: ["7d", "7dcontrol"] ' +
+			'and location: ["PT", "PT"], the first period uses PT and the control period also uses PT. If you only provide ' +
+			'location: ["PT"], only the first period is filtered by PT while the control period defaults to worldwide data.'
 	)
 
 export const DateStartParam = z
@@ -124,7 +128,12 @@ export const LocationArrayParam: z.ZodType<HTTPTimeseriesParams['location']> = z
 	.optional()
 	.describe(
 		'Filters results by location. Provide an array of alpha-2 country codes (e.g., "US", "PT"). ' +
-			'Prefix a code with `-` to exclude it (e.g., ["-US", "PT"] excludes the US and includes Portugal).'
+			'Prefix a code with `-` to exclude it (e.g., ["-US", "PT"] excludes the US and includes Portugal). ' +
+			'IMPORTANT: When using multiple dateRange values (e.g., ["7d", "7dcontrol"]), each array element ' +
+			'maps positionally to each dateRange. To compare the same location across time periods, repeat the ' +
+			'location code (e.g., location: ["PT", "PT"] with dateRange: ["7d", "7dcontrol"]). Using a single ' +
+			'location with multiple dateRange values will filter only the first period, with subsequent periods ' +
+			'defaulting to worldwide data.'
 	)
 
 export const ContinentArrayParam: z.ZodType<HTTPTimeseriesParams['continent']> = z
@@ -136,15 +145,23 @@ export const ContinentArrayParam: z.ZodType<HTTPTimeseriesParams['continent']> =
 	.optional()
 	.describe(
 		'Filters results by continent. Provide an array of alpha-2 continent codes (e.g., "EU", "NA"). ' +
-			'Prefix a code with `-` to exclude it (e.g., ["-EU", "NA"] excludes Europe and includes North America).'
+			'Prefix a code with `-` to exclude it (e.g., ["-EU", "NA"] excludes Europe and includes North America). ' +
+			'IMPORTANT: When using multiple dateRange values, each array element maps positionally to each dateRange. ' +
+			'To compare the same continent across time periods, repeat the continent code (e.g., continent: ["EU", "EU"] ' +
+			'with dateRange: ["7d", "7dcontrol"]). Using a single continent with multiple dateRange values will filter ' +
+			'only the first period, with subsequent periods defaulting to worldwide data.'
 	)
 
 export const AsnArrayParam: z.ZodType<HTTPTimeseriesParams['asn']> = z
 	.array(z.string().refine((val) => val !== '0', { message: 'ASN cannot be 0' }))
 	.optional()
 	.describe(
 		'Filters results by ASN. Provide an array of ASN strings. ' +
-			'Prefix with `-` to exclude (e.g., ["-174", "3356"] excludes AS174 and includes AS3356). '
+			'Prefix with `-` to exclude (e.g., ["-174", "3356"] excludes AS174 and includes AS3356). ' +
+			'IMPORTANT: When using multiple dateRange values, each array element maps positionally to each dateRange. ' +
+			'To compare the same ASN across time periods, repeat the ASN (e.g., asn: ["13335", "13335"] with ' +
+			'dateRange: ["7d", "7dcontrol"]). Using a single ASN with multiple dateRange values will filter only ' +
+			'the first period, with subsequent periods defaulting to all ASNs.'
 	)
 
 export const AsOrderByParam: z.ZodType<ASNListParams['orderBy']> = z
@@ -330,7 +347,11 @@ export const GeoIdArrayParam = z
 	.describe(
 		'Filters results by Geolocation (ADM1 - administrative level 1, e.g., states/provinces). ' +
 			'Provide an array of GeoNames IDs. Prefix with `-` to exclude. ' +
-			'Example: ["2267056", "-360689"] includes Lisbon area but excludes another region.'
+			'Example: ["2267056", "-360689"] includes Lisbon area but excludes another region. ' +
+			'IMPORTANT: When using multiple dateRange values, each array element maps positionally to each dateRange. ' +
+			'To compare the same region across time periods, repeat the GeoID (e.g., geoId: ["2267056", "2267056"] ' +
+			'with dateRange: ["7d", "7dcontrol"]). Using a single geoId with multiple dateRange values will filter ' +
+			'only the first period, with subsequent periods defaulting to all regions.'
 	)
 
 // BGP Parameters