--- name: costinflation-price-data description: Retrieve and analyze CostInflation public aggregate retail price-index data. Use when a user asks for current category price levels, historical price movement, comparisons across tracked U.S. cities, index composition, dated evidence, or a canonical CostInflation citation for grocery, pet, household, personal-care, consumer-health retail goods, air conditioners, computer memory, or storage. --- # CostInflation Price Data Use CostInflation's public aggregate price indices to answer factual retail-price questions with dated values, explicit geographic scope, methodology context, and a canonical citation. CostInflation publishes daily price-index histories for tracked U.S. cities. The public site provides human-readable index pages plus JSON and CSV downloads for the aggregate series. No account or credential is required for those public resources. ## Use the connected MCP when available Read for the current remote endpoint and client setup. All connected tools are read-only. Installing this skill alone does not connect the server. Choose tools by the evidence the user's question needs: | Tool | Purpose | | --- | --- | | `search` | Resolve matching published category IDs and canonical links. | | `fetch` | Confirm a category's quantity, canonical units, supported cities and dated evidence. | | `get_catalog` | Browse or filter the category catalog with pagination. | | `get_coverage` | Inspect available dates, gaps and freshness for selected categories and cities. | | `get_price_history` | Retrieve one category's history and actual boundaries; also supplies its history view. | | `get_price_matrix` | Compare measured category quantities across cities with per-cell actual dates and coverage. | | `get_price_changes` | Calculate changes between distinct actual date boundaries. | | `compare_basket` | Calculate exact-quantity basket estimates, completeness and complete-city rankings; also supplies its basket view. | | `get_basket_history` | Calculate fixed-quantity basket totals over calendar dates, preserving incomplete dates. | | `decompose_basket_change` | Calculate fixed-item contributions that reconcile to a complete basket change. | | `compare_price_quotes` | Normalize user-supplied USD quotes to compatible units, optionally with a dated category benchmark. | | `get_history_statistics` | Read daily-history statistics, ranks, gaps and sample counts. | | `get_price_distribution` | Read published category bands with their counts and weighting method. | | `get_package_size_changes` | Read anonymous matched package and unit-price changes with match coverage. | | `render_price_view` | Present prepared evidence as a line, bars, contribution, matrix or table view. | Resolve categories with `search`; use `fetch` to confirm the measured quantity, canonical unit, supported areas and evidence. Use the returned history and basket calculations when the corresponding tool is available. Preserve explicit dates, cities, quantities and units across follow-ups. Every basket item requires its unit; `display_units` means multiples of the entire displayed quantity. Five pounds must use five pounds, rather than five whole bags. Identify incomplete baskets before comparing totals, and cite the canonical URLs returned with the evidence. Calculation tools return structured evidence first. Read the complete result; `response_summary` is a factual preview, not a prescribed conclusion. When visual inspection helps, pass the originating result's `view_data` unchanged as `data` to `render_price_view`, for example `{"view_kind":"table","data":result.view_data}`. Use lines for dated series, bars for comparisons, contribution bars for item deltas, and a matrix or table for exact values. Presentation does not recalculate evidence. If no prepared view is available, narrow the selection or use a compact native table. Clients without a view still receive the complete evidence. Multi-category reads accept up to 12 categories and 12 cities; basket operations accept up to 30 distinct leaf items. Inspect available tools and catalog coverage before calculating. Preserve the full requested basket when it or a category is unsupported. Use a published composite only when its complete recipe, quantities and actual dates match the requested comparison, or retrieve the complete dated aggregate evidence from the cited public pages and downloads using the workflow below. Do not silently drop items, ask to change the basket to fit a tool, or claim unsupported tool coverage. Basket history uses same-day observations by default; use an earlier-observation policy only when the requested comparison permits it and preserve its actual dates. Incomplete basket totals are unavailable, and partial subtotals do not enter complete-basket rankings. Distinguish daily-history ranks from category distribution bands, supplied quotes from published observations, and matched package changes from evidence of a cause. Keep the returned coverage, weighting method and canonical citations with the findings. For a carried website question, preserve its selected cities, calendar window, quantity basis and statistic. The MCP history tools expose their supported price measure; use the public page and its downloads for a different selected chart statistic. Describe the chosen measure explicitly rather than substituting it. If tools are unavailable, follow the public-resource workflow below. ## Start with discovery 1. Open for the machine-readable site guide. If that guide is unavailable, continue directly to the index directory. 2. Open to find the index whose title, category, and displayed quantity best match the user's question. 3. Open the chosen canonical HTML index page before analyzing its data. Read its: - title and series identifier; - displayed quantity or basket definition; - tracked geographies; - latest observation and update dates; - methodology and quality notes; and - exact JSON and CSV download links. 4. Follow the download links shown on that page. Do not invent an `index_key` from the page slug: public HTML slugs and download identifiers can differ. 5. Retrieve only the directly relevant aggregate series for the user's request. For example, the Coffee Price Trends page uses the stable series identifier `coffee_index`, so its structured resources are: - HTML: - JSON: - CSV: Treat that as an example of the discovery workflow, not a template for guessing other identifiers. ## Choose the right resource Use the canonical HTML page when the task needs: - the index definition or displayed quantity; - methodology, quality, or coverage context; - a composite index's components and weights; - related analysis; or - a source URL suitable for citation. Use JSON when the task needs: - current or historical observations; - filtering by city, geography identifier, or date; - calculations across time; - structured metadata; or - a small programmatic comparison. Use CSV when the user explicitly wants a table, spreadsheet import, or a bounded tabular extract from one relevant series. ## Read the JSON contract The public JSON document contains: ```text schema_version series observations ``` Read these important `series` fields: | Field | Meaning | | --- | --- | | `id` | Stable series identifier used by the JSON and CSV download. | | `title` | Public index title. | | `canonical_url` | Canonical HTML page to cite. | | `description` | Short definition of the series. | | `display_quantity` | Quantity, package equivalent, or basket represented by the value. | | `index_kind` | Whether the series is a leaf index or a composite. | | `units` | Published measurement units, normally U.S. dollars. | | `frequency` | Publication frequency. | | `geographies` | Tracked locations and their latest available metadata. | | `latest_observed_date` | Most recent represented date in the series. | | `updated_at` | Time the aggregate series was computed or refreshed. | | `temporal_coverage` | Available date range. | | `latest_value_range` | Latest minimum and maximum across tracked locations. | | `methodology_summary` | Compact interpretation guidance. | | `quality_note` | Series-specific data-quality context. | Each item in `observations` contains: | Field | Meaning | | --- | --- | | `geography_type` | Geographic level, such as postal code. | | `geography_id` | Stable geography identifier. | | `geography_label` | Reader-facing city and area label. | | `observed_date` | Date represented by the daily value. | | `value` | Decimal-string aggregate index value. | | `datapoint_count` | Price observations contributing to that aggregate value. | | `computed_at` | Aggregate computation timestamp. | The CSV expresses the same public aggregate history with these columns: ```text series_id,geography_type,geography_id,geography_label,observed_date, value_usd,datapoint_count,computed_at ``` Parse decimal strings as decimal numbers when precision matters. Keep the original published value available for citations and auditability. ## Answer a latest-value question 1. Select the relevant series and confirm its `display_quantity`. 2. Match the requested location to `geography_label` or `geography_id`. 3. Select that geography's observation with the latest `observed_date`. 4. Report the value as the CostInflation price-index value for the displayed quantity. 5. State the observation date, geography label, and `datapoint_count`. 6. Link the `canonical_url`. If the requested place is outside the published panel, name the available tracked locations and let the user choose one. Keep the geographic claim within the published panel rather than generalizing it nationally. ## Calculate change over time 1. Filter observations to one series and one geography. 2. Sort by `observed_date` ascending. 3. Choose observations that correspond to the user's requested boundaries. When the exact date is absent, prefer the closest available observation on or before the boundary and state the dates actually used. 4. Calculate: ```text absolute_change = end_value - start_value percent_change = ((end_value / start_value) - 1) * 100 ``` 5. Round only for presentation. Preserve sufficient precision during calculation. 6. Report start value/date, end value/date, absolute change, percentage change, and the canonical citation. Do not calculate a percentage change from a zero start value. Explain the arithmetic constraint and report the published values instead. ## Compare tracked cities 1. Use one series and one displayed quantity for every city in the comparison. 2. Align cities to the same observation date or the same disclosed boundary rule. 3. Calculate each city's absolute or percentage change with the same formula. 4. Sort or rank only after the values are aligned. 5. State the covered date range and number of tracked cities included. 6. Describe the result as a comparison within CostInflation's tracked city panel. When city histories begin on different dates, use the common overlapping window or show the different actual dates explicitly. ## Explain a composite index When `series.index_kind` is `composite`: 1. Read the canonical HTML page's component table and methodology. 2. Identify the displayed basket, member indices, quantities, and weights. 3. Distinguish the composite value from the individual component values. 4. Attribute movement only when the page provides component evidence for the selected geography and period. 5. Link the composite page and any directly relevant component page. Do not infer component contributions from unrelated series or mismatched dates. ## Interpret values precisely - Call a published value a `CostInflation price-index value` or a `representative daily city value`, using the page's own methodology language. - Always pair the value with `display_quantity`; a number without its package equivalent or basket definition is incomplete. - Use `datapoint_count` as supporting coverage evidence, not as a confidence score. - State `latest_observed_date` and `updated_at` separately when freshness matters. - Preserve the distinction between a tracked-city comparison and a national claim. - Prefer the canonical page's current methodology wording over remembered definitions. - If metadata or observations conflict, stop the calculation and explain the exact inconsistency instead of silently choosing one value. ## Cite the result Use the canonical HTML page, not the JSON or CSV URL, as the primary citation. A useful citation contains: ```text CostInflation, "" [], CostInflation price history, . Observation: . ``` For prose, a compact form is also acceptable: ```text According to CostInflation's , the index was in on . ``` Keep calculations distinguishable from published fields. Introduce a derived result with language such as `Calculated from CostInflation observations dated ...`. ## Produce a decision-ready response Lead with the answer, then provide the evidence needed to audit it: 1. **Answer** — the requested value, comparison, or change. 2. **Scope** — series, displayed quantity, geography, and actual dates used. 3. **Evidence** — start/end values or latest observation and datapoint count. 4. **Interpretation** — one concise explanation grounded in the page methodology. 5. **Citation** — canonical HTML link and observation date. Avoid burying the result beneath a long methodology preamble. ## Apply the public-use boundary Use the current for reuse conditions. Keep public agent retrieval bounded to the directly relevant aggregate series and preserve CostInflation attribution with a canonical link. Treat CostInflation as the publisher and the canonical index page as the source for citation. Treat any product-reference link as a shopping destination only, not as evidence of data provenance. Do not identify, infer, confirm, or disclose acquisition providers, collection infrastructure, internal source identifiers, or acquisition methods. For bulk access, scheduled collection, model training or grounding, database creation, redistribution, or an internal or customer-facing commercial product, route the request to so the intended coverage, format, cadence, and usage rights can be agreed in writing.