get_kpi_trend
Analyze historical KPI trends for Swedish municipalities to track performance changes over time. Supports gender-specific filtering for detailed trend analysis.
Instructions
Hämta historisk trenddata för ett nyckeltal som visar förändringar över tid. Användbart för att analysera utveckling och identifiera trender. Stöder könsfiltrering (T/M/K).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kpi_id | Yes | KPI-ID att analysera | |
| municipality_id | Yes | Kommun-ID | |
| start_year | Yes | Startår för trendanalysen | |
| end_year | No | Slutår (standard: innevarande år) | |
| gender | No | Könsfilter: T=Totalt, M=Män, K=Kvinnor, all=visa alla | all |
Implementation Reference
- src/tools/data-tools.ts:350-407 (handler)The main handler function that executes the tool logic: fetches historical KPI data over a year range from Kolada API, applies gender filtering, calculates year-over-year percentage changes, logs execution, and returns formatted trend data as JSON.handler: async (args: z.infer<typeof getKpiTrendSchema>): Promise<ToolResult> => { const startTime = Date.now(); const { kpi_id, municipality_id, start_year, end_year, gender } = args; logger.toolCall('get_kpi_trend', { kpi_id, municipality_id, start_year, end_year, gender }); try { const endYr = end_year || new Date().getFullYear(); const years = Array.from({ length: endYr - start_year + 1 }, (_, i) => start_year + i); // Kolada API v3 uses path-based URLs const endpoint = `/data/kpi/${kpi_id}/municipality/${municipality_id}/year/${years.join(',')}`; let data = await koladaClient.fetchAllData<KPIData>(endpoint); // Apply gender filter data = filterByGender(data, gender); // Calculate year-over-year changes if data exists const trend = data.map((d, index) => { const previousValue = index > 0 ? data[index - 1].values[0]?.value : null; const currentValue = d.values[0]?.value; const change = previousValue && currentValue ? ((currentValue - previousValue) / previousValue) * 100 : null; return { ...d, year_over_year_change_percent: change ? parseFloat(change.toFixed(2)) : null, }; }); logger.toolResult('get_kpi_trend', true, Date.now() - startTime); return { content: [ { type: 'text', text: JSON.stringify( { kpi_id, municipality_id, period: `${start_year}-${endYr}`, gender_filter: gender, trend_data: trend, source: 'Kolada - Källa: Kolada', }, null, 2 ), }, ], }; } catch (error) { logger.toolResult('get_kpi_trend', false, Date.now() - startTime); throw error; } },
- src/tools/data-tools.ts:47-53 (schema)Zod schema for input validation of get_kpi_trend tool parameters: kpi_id (required), municipality_id (required), start_year (required), end_year (optional), gender (default 'all').const getKpiTrendSchema = z.object({ kpi_id: z.string().describe('KPI-ID att analysera'), municipality_id: z.string().describe('Kommun-ID'), start_year: z.number().describe('Startår för trendanalysen'), end_year: z.number().optional().describe('Slutår (standard: innevarande år)'), gender: z.enum(['T', 'M', 'K', 'all']).default('all').describe('Könsfilter: T=Totalt, M=Män, K=Kvinnor, all=visa alla'), });
- src/tools/data-tools.ts:346-408 (registration)Tool registration within the exported dataTools object, defining description, input schema reference, annotations, and handler function.get_kpi_trend: { description: 'Hämta historisk trenddata för ett nyckeltal som visar förändringar över tid. Användbart för att analysera utveckling och identifiera trender. Stöder könsfiltrering (T/M/K).', inputSchema: getKpiTrendSchema, annotations: READ_ONLY_ANNOTATIONS, handler: async (args: z.infer<typeof getKpiTrendSchema>): Promise<ToolResult> => { const startTime = Date.now(); const { kpi_id, municipality_id, start_year, end_year, gender } = args; logger.toolCall('get_kpi_trend', { kpi_id, municipality_id, start_year, end_year, gender }); try { const endYr = end_year || new Date().getFullYear(); const years = Array.from({ length: endYr - start_year + 1 }, (_, i) => start_year + i); // Kolada API v3 uses path-based URLs const endpoint = `/data/kpi/${kpi_id}/municipality/${municipality_id}/year/${years.join(',')}`; let data = await koladaClient.fetchAllData<KPIData>(endpoint); // Apply gender filter data = filterByGender(data, gender); // Calculate year-over-year changes if data exists const trend = data.map((d, index) => { const previousValue = index > 0 ? data[index - 1].values[0]?.value : null; const currentValue = d.values[0]?.value; const change = previousValue && currentValue ? ((currentValue - previousValue) / previousValue) * 100 : null; return { ...d, year_over_year_change_percent: change ? parseFloat(change.toFixed(2)) : null, }; }); logger.toolResult('get_kpi_trend', true, Date.now() - startTime); return { content: [ { type: 'text', text: JSON.stringify( { kpi_id, municipality_id, period: `${start_year}-${endYr}`, gender_filter: gender, trend_data: trend, source: 'Kolada - Källa: Kolada', }, null, 2 ), }, ], }; } catch (error) { logger.toolResult('get_kpi_trend', false, Date.now() - startTime); throw error; } }, },
- src/tools/data-tools.ts:58-65 (helper)Helper function to filter KPI data by gender (T/M/K/all), used in the get_kpi_trend handler and other data tools.function filterByGender(data: KPIData[], gender: 'T' | 'M' | 'K' | 'all'): KPIData[] { if (gender === 'all') return data; return data.map(d => ({ ...d, values: d.values.filter(v => v.gender === gender || (!v.gender && gender === 'T')) })).filter(d => d.values.length > 0); }