Morningstar

View saved version →

---
name: datapoint-finder
description: Finds official Morningstar datapoint names using topic-organized buckets. Use when the user asks to find, browse, or name a datapoint — e.g. "what's the datapoint for expense ratio", "find the datapoint name for Sharpe ratio", or "list datapoints for ESG".
metadata:
  author: Morningstar
  version: 1.0.0
  mcp-server: morningstar-mcp
compatibility: Designed for use with the Morningstar MCP server.
---

# Datapoint Finder

Finds official Morningstar datapoint names from topic-organized buckets.

The buckets under `references/buckets/` list datapoint names by topic — use them to find
candidate names.

## Workflow

Open the matching bucket(s) below (up to 3) and build a candidate name list — bucket names
are a starting point, add your own reasonable guesses too.

## Intent → bucket map

### Performance & Returns
| If the user is asking about… | Load bucket |
|---|---|
| Total/trailing/annual/calendar/daily/monthly **return**, YTD/1Y/3Y/5Y/10Y return, return index, growth of $10K | `perf-trailing-periodic` |
| Percentile **rank in category**, % rank vs peers, quartile, # investments in category | `perf-return-rankings` |
| Beta, standard deviation/volatility, R-squared, tracking error, up/down capture, batting average, bear-market rank, strategic beta | `perf-risk-metrics` |
| Alpha, Sharpe, Sortino, information ratio (risk-adjusted) | `perf-risk-adjusted` |

### Morningstar Ratings
| If the user is asking about… | Load bucket |
|---|---|
| Star rating, risk rating, return rating, "X-star" | `rating-star` |
| Medalist Rating, pillars (Parent/People/Process/Price/Performance), fair value per share, brand tenure/retention | `rating-medalist` |
| Quantitative rating, quant fair value, fair value uncertainty | `rating-quant-equity` |
| ESG risk rating / sustainability rating of a fund | `rating-sustainability` |
~~
### Portfolio Analysis
| If the user is asking about… | Load bucket |
|---|---|
| Country/region exposure, geographic breakdown, US vs non-US | `pa-geographic-exposure` |
| Sector/industry weights (equity econ sector, super sector) | `pa-sector-industry` |
| Asset allocation (stock/bond/cash/other %, long/short) | `pa-asset-allocation` |
| Style box, growth/value factors, sustainability/style tilts | `pa-style-factor` |
| Portfolio avg market cap, portfolio P/E·P/B·P/S, avg moat, turnover, duration, credit quality | `pa-statistics` |
| # of holdings, # bond/stock holdings, top-10 weight | `pa-holdings` |
| Target-date **glide path** (allocation by years-to-target), glide path type / landing point | `pa-glide-path` |

### Price & Distribution & Flows
| If the user is asking about… | Load bucket |
|---|---|
| Price, last close, NAV, market price, 52-wk high/low, premium/discount, AUV | `price-prices` |
| Yield (12-mo/SEC/7-day), dividends paid, capital gains, ROC, distributions | `price-distributions` |
| Trading volume, spread, days traded | `price-trading-activity` |
| Estimated net flows | `price-fund-flows` |
| Fund size, AUM, net assets, tier-level/vehicle assets | `price-aum` |

### Expense & Fee
| If the user is asking about… | Load bucket |
|---|---|
| Expense ratio (net/gross/adjusted), management/admin/custodian/advisor fees, ongoing charge | `fee-management-ongoing` |
| Transaction/trading costs, spreads, RG97 T&O costs, borrowing costs | `fee-transaction-trading` |
| Front/deferred load, exit/switching/contribution fee, sales charge | `fee-entry-exit-load` |
| Performance fee, hurdle rate, high-water mark, crystallisation | `fee-performance-based` |
| 12b-1 / distribution & sales / revenue-sharing fee, no-load flag | `fee-distribution-sales` |

### Corporate Financials
| If the user is asking about… | Load bucket |
|---|---|
| A **stock's** P/E·P/B·P/S, ROE/ROA/ROIC, margins, debt/equity, growth, economic moat, growth grade, market cap, quick ratio, tax rate | `cf-financial-ratios-metrics` |
| Income statement: revenue, cost of revenue, gross/operating profit, EBITDA, EPS, interest/tax, net income | `cf-income-statement` |
| Balance sheet: total assets/liabilities/equity, PP&E, goodwill, debt, inventory, receivables/payables, working capital | `cf-balance-sheet` |
| Cash-flow statement: operating/investing/financing cash flows, capex, dividends paid, changes in working capital | `cf-cash-flow` |
| Shares outstanding (basic/diluted/weighted-avg), share counts | `cf-share-data` |

### ESG & Sustainability
| If the user is asking about… | Load bucket |
|---|---|
| EU SFDR / EU Taxonomy disclosure & regulatory flags | `esg-eu-taxonomy` |

### Ownership
| If the user is asking about… | Load bucket |
|---|---|
| Number of shareholders, trustee / ownership facts | `own-statistics` |

### Reference Data & Fund Information
| If the user is asking about… | Load bucket |
|---|---|
| Currency, domicile, inception, status, minimums, flags (index/active, REIT, UCITS), tax transparency, glide-path/data-ready | `ref-operations` |
| Name, ticker, ISIN/CUSIP/WKN, FundId/SecId/CompanyId, share class, fund/branding name | `ref-identification` |
| Manager name/tenure/ownership/education, firm assets, advisor/custodian | `ref-management-org` |
| Morningstar Category / Global Category / theme, investment type, a stock's sector/industry | `ref-classification` |
| Benchmark/index, prospectus benchmark, index family, index selection/weighting | `ref-benchmark-index` |

## Tie-break rules for overlapping terms

- **"market cap"** → a **stock** `ST159` (`cf-financial-ratios-metrics`); portfolio average
  `HS03W` (`pa-statistics`); size breakdown lives in `pa-style-factor`.
- **"economic moat"** → a **stock** `LT181` (`cf-financial-ratios-metrics`); portfolio
  average `HS0D1` (`pa-statistics`).
- **"fair value"** → Morningstar Fair Value per Share `ST202` and Price/Fair Value `OS603`
  (`rating-medalist`); Quantitative Fair Value `QV009` / Fair Value Uncertainty `ST201`
  (`rating-quant-equity`).
- **"P/E", "P/B", "P/S"** → a **stock** (`ST412`/`ST408`/`ST415`) in
  `cf-financial-ratios-metrics`; **portfolio** (TTM, long, e.g. `HS05X`) in `pa-statistics`.
- **"yield" / "dividend yield"** → a **fund** → 12 Mo / SEC / 7-Day Yield in
  `price-distributions`; distributions paid also `price-distributions`.
- **"sector"** → **fund** weights → `pa-sector-industry`; **stock** classification →
  `ref-classification`.
- **"volume"** → trading volume/spread → `price-trading-activity`, not `price-prices`.
- **"expense ratio" / "fee level"** → `fee-management-ongoing`.
- **"rating"** → 1–5 star → `rating-star`; Medalist (Gold/Silver/Bronze) → `rating-medalist`;
  quant → `rating-quant-equity`; ESG/sustainability → `rating-sustainability`.
- **"base currency"** → Base Currency `LS05M` (`ref-operations`), never Minimum Investment.

Referenced files: 39

View saved version →

---
name: fund-comparison
description: Compares exactly 2 funds or ETFs using a structural-first Morningstar analysis. Starts with a Markdown structural snapshot, supports targeted follow-up analysis, and can generate a self-contained HTML report after the user confirms. Use when the user says “compare SPY and QQQ,” “compare two ETFs,” “create a fund comparison report,” or requests a side-by-side Morningstar comparison of two fund tickers.
---

# Fund Comparison

Compare 2 funds using Morningstar MCP tools. Establish what each fund *is* before reporting what it *did*.

## Guardrails

- Compare exactly 2 funds. If more or fewer are provided, ask the user to specify exactly 2.
- Supported types: ETF (FE), open-end fund (FO), closed-end fund (FC). Exclude ST; notify the user.
- Data source: Morningstar MCP tools only. Never infer, estimate, or backfill values.
- Missing field → `N/A`. Tool failure → `N/A` and identify it as a tool failure.
- No investment advice, suitability statements, or performance predictions.
- Do not generate HTML until the user explicitly confirms after seeing the structural snapshot. An initial request for a full report or HTML does not bypass the snapshot.

## Workflow

Read `references/full-workflow.md` once before starting. It is the complete execution contract.

1. Resolve both identifiers.
2. Retrieve the structural snapshot: a narrow shared data-tool call plus `asset_allocation` for each fund, emitted together after IDs resolve.
3. Show the required Markdown snapshot and structural read. State the factual difference most likely to drive performance and risk differences, unless the funds are structurally similar; in that case use a similarity-first read and name the practical distinctions. Then offer targeted analysis or the full HTML report before asking how the user wants to proceed.
4. For a focused question, retrieve only the relevant diagnostic data, answer in Markdown, and offer the full HTML report again.
5. Generate the full report only after explicit post-snapshot confirmation. Reuse the identifiers, snapshot data, allocations, and any relevant follow-up data from this comparison session; retrieve only the remaining report data and required detail. Keep the confirmed-report path direct: retrieve, validate, render, and deliver. Use intermediate planning, status output, or extra steps only when needed to resolve missing data, ambiguity, or an error.

The comparison order is: asset class → Morningstar Category → exposure/universe → implementation → portfolio choices → outcomes. Lead with the first material difference, never performance.

## Examples

- “Compare SPY and VOO.” → Retrieve and show the structural snapshot, then ask how to proceed.
- “Create a fund comparison report for FBND and VOO.” → Show the snapshot first, note the cross-mandate difference, then ask whether to generate HTML.
- “How do SPY and VOO differ by region?” → Show the structural snapshot, then retrieve regional exposure when requested; do not create HTML unless confirmed.
- “Compare SPY, QQQ, and VTI.” → Ask the user to choose exactly 2 funds before calling tools.

## HTML Deliverable

After the user confirms, create one self-contained HTML file: `comparison-[TICKERA]-vs-[TICKERB].html`. Keep the intermediate `D` JSON at a unique path `/tmp/fund-comparison-data-[TICKERA]-[TICKERB]-[RUN-ID].json`; provide it only when the user explicitly asks. Do not create a companion chart or PDF.

When offering it, describe its sections in one compact sentence: fund identity, structure, management, and cost; structural composition and eligible holdings breakdowns; returns and category ranks; risk; ratings; and analyst research with a concise synthesis.

## Post-report Response

Respond with the output HTML path, important data limitations, and one short invitation for questions about the comparison data. Do not mention the intermediate JSON unless asked. Successful validation is an internal delivery gate; report validation only when it fails and prevents delivery.

Referenced files: 5

View saved version →

---
name: fund-screener
description: Use when screening funds or ETFs by Morningstar category, ratings, fees, assets, returns, or risk.
---

# Fund Screener

Screen funds using the connected Morningstar app as the data source.

## Guardrails

- Use only data returned by the Morningstar app in the current session.
- Do not infer missing values, create synthetic scores, predict performance, or give investment advice.
- Show unavailable values as `N/A` and distinguish missing data from tool failure.
- Supported universes are ETFs, open-end funds, and closed-end funds.
- Treat filters as AND logic unless the user explicitly asks for alternatives; run separate passes for OR logic and deduplicate results.

## Workflow

Before running a real screen, read `references/full-workflow.md`. It preserves Morningstar's partner-authored rules for criteria confirmation, normalization, datapoints, result validation, output tables, disclosures, and follow-up suggestions.

1. Collect the screening criteria in one pass: universe, category, medalist rating, star rating, expense ratio, assets, and any user-specified filters.
2. Normalize user terms against Morningstar-supported datapoints and values before screening. If a close match is likely, ask for confirmation before running.
3. Run the screen, targeting a useful result set of roughly 10 to 20 funds.
4. Validate fund status and remove inactive, merged, or liquidated funds.
5. Enrich surviving results with category, active/passive status, benchmark, expense ratio, assets, inception date, medalist rating, star rating, returns, category ranks, and risk metrics when available.
6. Rank results by the user's priority. If no priority is given, sort by assets descending and then expense ratio ascending.

## Output

Use this order:

1. Disclosure banner.
2. Criteria used table, one row per active filter only, including normalized terms.
3. Result count and exclusions.
4. Snapshot table.
5. Performance table.
6. Risk and category-rank table.
7. Three concise, data-backed refinements such as tighter expense ratio, higher rating floor, narrower category, or universe changes.

If the screen returns zero or too few results, identify the likely binding criteria and ask what to relax.

Referenced files: 3

View saved version →

---
name: fund-summarizer
description: Use when summarizing a fund or ETF with Morningstar ratings, returns, risk, holdings, fees, and caveats.
---

# Fund Summarizer

Create a concise fund summary or report using the connected Morningstar app as the data source.

## Guardrails

- Use only data returned by the Morningstar app in the current session.
- Do not infer missing values, add outside research, predict performance, or give investment advice.
- Show unavailable numeric values as `--` and unavailable text as `N/A`. Distinguish missing data from tool failure.
- Supported investment types are ETFs, open-end funds, and closed-end funds. If the user asks for an equity or unsupported security, explain that this skill is fund-focused and ask for a supported fund.
- Preserve Morningstar terminology for ratings, categories, benchmarks, and analyst research.
- Do not read script source files to understand the data schema — use `references/full-workflow.md` instead. You may invoke `scripts/render.py` when the user explicitly requests an HTML report.
- Do not write helper scripts or render wrappers to produce the HTML report — assemble the data dict inline and call `render_report` once.

## Formatting Rules

| Value type | Rule |
|---|---|
| Percentages and ratios | 2 decimal places (e.g. `8.23%`, `1.05`) |
| Category ranks, MPRS | Whole number (e.g. `47`, `82`) |
| Currency amounts | Raw number with commas, no symbol (e.g. `1,234.56`) |
| Large AUM / flows | B/M compact, no symbol (e.g. `1.23B`, `456.70M`) |
| Dates | YYYY-MM-DD |
| Missing numeric | `--` |
| Missing text | `N/A` |

## Workflow

For broad summaries, detailed reports, or any HTML report, read `references/full-workflow.md` before retrieving data. It preserves Morningstar's partner-authored datapoint map, missing-data rules, structured report inputs, and renderer contract.

1. Resolve the fund from ticker, name, or Morningstar identifier. Ask only if the match is ambiguous.
2. Retrieve all fund data in parallel batches — fire these simultaneously, do not wait for one before starting the next:
   - **Core metadata + ratings/IP** in one `morningstar_data_tool` call
   - **Performance, risk, and monthly returns** (HP010, trailing 10 years) in one `morningstar_data_tool` call
   - **Holdings** in one `morningstar_data_tool` call
   - **Analyst research** via `morningstar_analyst_research_tool`
   - **Top holdings** via `morningstar_fund_holdings_tool`
3. Retrieve benchmark data in one `morningstar_data_tool` call: base currency, HP010 monthly returns (trailing 10 years), and trailing/annual returns. Fire this as soon as step 2 batch A returns (you only need the benchmark ID from it).
4. Build the smallest useful deliverable for the user request. Use Markdown by default; create self-contained HTML only if the user explicitly asks for an HTML report or a sharable artifact. 

## HTML Report Support

When creating an HTML report, use `scripts/render.py`. It reads `assets/template.html`, `assets/icons/`, and the Morningstar logo asset, with visual guidance in `references/design_guide.md`. The renderer produces a self-contained HTML file — no PDF export.

## Output

Use this order:

1. Morningstar disclosure: AI-generated analysis using Morningstar data; informational only, not investment advice.
2. Fund snapshot.
3. Ratings and analyst context.
4. Performance and category-rank context.
5. Risk and portfolio context.
6. Fees, flows, and operational details.
7. Data-availability notes and caveats.

Keep the summary factual and skimmable. For broad requests, include the main tables and a short neutral narrative. For narrow questions, answer only the requested metric or section. If the user asks for an HTML report, produce a single file with all sections, tables, and charts. For other requests, use Markdown with tables and bullet points as needed.

Referenced files: 36

View saved version →

---
name: medalist-rating-analyzer
description: Analyzes a fund's Morningstar Medalist Rating using live Morningstar MCP data, including pillar scores, rating history, and analyst research. Use when asked to rate, analyze, or look up a specific fund by ticker, name, or Morningstar ID.
---

# Medalist Rating Analyzer

Analyzes Morningstar Medalist Ratings using the **Morningstar MCP server**.
Includes only two steps:

1. **Search** — resolve a fund name or ticker to a `morningstar_id`
2. **Fetch** — call the MCP server once to get all research/rating data for that fund

Do not call MCP tools if you have already fetched the same data for the same `morningstar_id` in the same session — keep it in context and answer all follow-up questions from that data.
Do not expose Morningstar internal data id values (e.g., `MMR01`) in your final answers — those are for your internal use only when reasoning about which data to pull and how to answer.
Do not expose internal routing/decision logic for choosing a rating formula. Keep that reasoning private unless the user explicitly asks methodology details.

---

## Plugin Domain Rules

Morningstar domain rules for this skill:

- For fund lookups by name/ticker, call `morningstar:morningstar-id-lookup-tool` first.
- When calling `morningstar:morningstar-id-lookup-tool`, pass only the fund identifier text (ticker, exact Morningstar ID, or fund name), not the full user sentence.
- If the user provides a direct Morningstar ID, skip lookup and proceed directly to the fetch workflow with that ID.
- When MCP-backed formatter output contains a "Disclosure" section with separator lines (────), you MUST reproduce that disclosure text EXACTLY AS PROVIDED in the tool output, word-for-word, without paraphrasing, summarizing, or omitting any sentences. **If it appears more than once in the formatter output, reproduce it that many times, in the same positions — never collapse repeated occurrences into one.** The disclosure text is legally required and must be complete and verbatim.
- **Disclosure handling — never add manually.** `fmt.full_report()` and `fmt.fund_header()` handle all disclosure placement automatically based on `data["disclosure_type"]`. Do NOT write or append a disclosure block yourself anywhere in the response. If you find yourself typing the disclosure text, stop — that means the formatter already placed it.
- If the needed fund data is already provided in session context, answer follow-up questions about the same fund directly and do not call Morningstar MCP data tools again unless the user asks about a different fund.
- When presenting historical pillar score output from `morningstar:morningstar-data-tool`, do NOT omit any rating type labels (e.g. `Analyst Assigned`, `Algorithmic`, `Quantitative`). The type labels must appear in your response exactly as they appear in the tool output.
- For comparison requests, fetch each fund, then synthesize a comparison.
- Never invent fund data; rely on tool output and provided context.
- Show complete relevant tool-backed output; do not provide empty sections.
- Avoid fenced code blocks in user-facing answers; write formulas as plain text.
- If a tool explicitly returns an MCP-service-unavailable error, respond exactly: "Sorry, the Morningstar MCP service is not available at this moment. Please try again later."
- Do not infer MCP outage from user text or model assumptions; only use the outage response when a tool call indicates service unavailability.

### Routing logic for fund-specific methodology questions

- Keep formula-routing logic internal unless the user explicitly asks for methodology details.
- This is a deterministic decision, not a judgment call — never re-derive it by reasoning over the flags in prose. Call `select_formula(domicile_country, is_index_fund, is_australian_superannuation_fund)` from `scripts/data_normalizer.py` (also exported as `scripts.select_formula`) and use its return value directly: `"Active"`, `"Passive"`, `"Superannuation"`, or `"clarification_needed"`.
- Use routing flag values injected in the current-fund context block (domicile_country, is_index_fund, is_australian_superannuation_fund) — these come directly from the data tool. Do NOT infer or default missing values before passing them to `select_formula`.
- If the result is `"clarification_needed"`, follow the clarification instruction in the routing flags block (`Formatter.routing_flags()` in `scripts/formatter.py`) — that is the single canonical source for the exact clarification wording.

---

## Data Source — Morningstar APIs

Data comes from Morningstar MCP.

Three MCP tools are used:

| Tool | Purpose |
|------|---------|
| `morningstar:morningstar-id-lookup-tool` | Resolve ticker / name → `morningstar_id` |
| `morningstar:morningstar-analyst-research-tool` | Fetch analyst research, pillar narratives, and Medalist Rating |
| `morningstar:morningstar-data-tool` | Supplement with structured datapoints (current rating/pillars, fees, historical overall + pillar timelines) |

**If the MCP server is unreachable, inform the user.**

---

## Reference Files

Read only the reference required for the request. Every reference below is one hop from this file.

| Situation | Read |
|-----------|------|
| A new fund, a different fund, or no current-fund `data` in session | [references/full-workflow.md](references/full-workflow.md) — lookup, fetch, normalization, current snapshot, and pre-response workflow |
| A standard question about a fetched fund: full report, current rating, price/fees, a current pillar, or fund identity | [references/follow-up-questions.md](references/follow-up-questions.md) — formatter routing and follow-up examples |
| A historical rating/pillar question, a date-bounded question, or an explanation of a rating change | [references/historical-rating-questions.md](references/historical-rating-questions.md) — history IDs, date filtering, and change-explanation rules |
| How a current Parent, People, or Process pillar is calculated | [references/pillar-input-questions.md](references/pillar-input-questions.md) — the input-data retrieval workflow |
| The precise shape or ownership of a normalized `data` field | [references/normalized-data.md](references/normalized-data.md) — complete `data` schema |
| The input datapoint-ID table or `get_pillar_data_id` usage details | [references/pillar_rating_input_data.md](references/pillar_rating_input_data.md) or [references/pillar_data_query_reference.md](references/pillar_data_query_reference.md) |

For a general Medalist Rating methodology question that is not tied to a specific fund, use `morningstar:morningstar-articles-tool` with `content_filter: "methodology"`; do not load a fund workflow reference.

Executable code lives in `scripts/` (`data_normalizer.py`, `formatter.py`, `pillar_data_query.py`) — import and call these, don't read them as documentation; the reference files above are the documentation.

Referenced files: 13