DalalOS

Indian NSE/BSE research data and mechanically-computed ratios; read-only market tools.

От сообществаРаботаетБез входаГлобальныйБесплатноТолько чтение

Что умеет

    Какие данные видит

    Нужен ли аккаунт

    Не нужен: сервер работает без входа

    Indian NSE/BSE research data and mechanically-computed ratios; read-only market tools.

    Список инструментов сервера (60)

    Технические названия из tools/list. Нужны только разработчикам.

    pingDalalOS health check. Returns a success envelope to confirm the server is reachable.
    get_filing_extractGet the cached PDF-extraction for one BSE corporate filing. Accepts NSE symbol, ISIN, or BSE code + a BSE news_id. Obtain the `news_id` from get_stock_events, which lists a security's recent filings each carrying its `news_id`. Returns cached grounded facts + a factual summary extracted from the filing PDF. On a cache miss for any filing that has an attached PDF, calling this tool ENQUEUES on-demand extraction and returns `status="pending", queued=true` — call again in ~1-2 minutes to retrieve the facts (works for ANY filing with a PDF, not a fixed doc-type list) — EXCEPT financial-results filings, which return `not_queued` reason `results_available_via_financials` (+ a `see_instead` pointer) because their figures come from XBRL via get_financials / get_financial_trends, not PDF extraction. Every `pending` response carries a `reason_code` that stays consistent across repeat polls of the same news_id: `on_demand_processing` (this tool's own trigger enqueued it and it is still queued/running — keep polling), `auto_backfill_processing` (in flight via the nightly sweep only, not this tool), or `awaiting_auto_backfill` (not yet queued, but eligible for a future sweep). Other cache-miss statuses: `not_queued` reason `no_document_to_extract` (no PDF), `not_queued` reason `on_demand_quota_exceeded` (authenticated caller hit its per-day on-demand cap — retry tomorrow, or read `attachment_url` directly), or `failed` (retries exhausted; see `error_reason`). Every cache-miss response includes `attachment_url` to read the filing PDF directly. Raw disclosed facts with verbatim source quotes only — no verdicts, targets, or recommendations.
    get_market_fii_dii_flowMarket-wide DAILY FII/DII net cash-flow (Rs crore), NSE cash (Capital Market) segment. NOT the shareholding data: get_shareholding gives per-company QUARTERLY FII/DII holding PERCENTAGES; this gives market-wide DAILY net buy/sell/net value in Rs crore -- e.g. "FIIs net sold Rs 2,340 Cr, DIIs net bought Rs 1,890 Cr" for a given trading day. `from_date`/ `to_date` are optional ISO dates (default: trailing ~30 days); `segment` is "cash" only. For NSE participant-wise F&O positioning, use `get_fo_participant_activity`. Raw exchange- published figures; `net = buy - sell` is the only computation (SEBI-RA line — no direction calls or "smart money" framing). The envelope's `source` reflects actual per-call provenance, not a fixed NSE label: recent dates are NSE-live (`source="nse"`), older dates are Moneycontrol-backfilled (`source="moneycontrol"`, since NSE publishes no bulk cash-history archive), and a query window spanning both returns `source="mixed"` (each row still carries its own accurate `source`). Renamed from `get_fii_dii_flow` (issue #285) so the name itself telegraphs scope (MARKET-wide) against its get_sector_fii_flow/get_stock_fii_flow siblings. `get_fii_dii_flow` is kept as a deprecated back-compat alias for this release.
    get_stock_fii_flowPer-stock DAILY FII/FPI transaction flow (raw Rs) -- daily series + trailing-30d summary. Accepts NSE symbol, ISIN, or BSE code. `days` (1..1825, default 90) bounds the daily `series`; `summary` is always the trailing-30d figure (the SAME single-source helper get_company_profile's compact `fii_activity` field uses). A distinct FII/FPI surface from get_market_fii_dii_flow (market-wide) and get_shareholding (quarterly holding %) -- this is per-STOCK daily transaction flow, aggregated from CDSL's trade-wise disclosure. COVERAGE CAVEAT: CDSL-only (NSDL unreachable, not ingested) -- every response carries a `coverage_note`. `net = buy - sell` is the only computation (SEBI-RA line: no direction calls, no "smart money" framing). Renamed from `get_fii_activity` (issue #285) so the name carries "flow" like its get_sector_fii_flow/get_market_fii_dii_flow siblings ("activity" gave no scope cue). `get_fii_activity` is kept as a deprecated back-compat alias for this release.
    get_watchlistGet the caller's DalalOS watchlist: bare stock symbols, no quantity/cost-basis. Use this whenever the user asks what's on their (DalalOS) watchlist, or before adding/ removing symbols to check current state. This is DalalOS's OWN watchlist, tied to the caller's DalalOS account -- if another connected MCP server also has a watchlist tool, it is a SEPARATE list; do not treat them as interchangeable. Requires an authenticated caller (API key or OAuth session tied to a DalalOS account) -- unauthenticated or auth-disabled deployments get an `unauthorized`/`not_configured` error envelope instead of data. Each entry is decorated with `name`/`sector`/`market_cap` (best effort, via the same lookup `get_company_profile` uses) alongside the bare `symbol` and `added_at`; a symbol that no longer resolves (delisted, renamed) still returns as a bare row rather than failing the whole call.
    add_to_watchlistAdd one or more stocks to the caller's DalalOS watchlist, accepting a pasted list. Use this when the user says "watch X", "track X", "add X to my watchlist", or asks to save stocks they just searched/screened/analyzed via DalalOS for later. This writes to DalalOS's OWN watchlist (tied to the caller's DalalOS account) -- if another connected MCP server also exposes an add-to-watchlist tool, it is a DIFFERENT, non-overlapping list; use this one for anything the user wants tracked specifically through DalalOS. `symbols` accepts a list of strings or a single string, and any entry may itself be a DELIMITED PASTE -- commas, newlines, semicolons, tabs or pipes -- so a screener export can be handed over as-is. Each fragment is resolved by exact identifier (NSE symbol, ISIN, BSE code) first, then by company name, so "Gandhar Oil" becomes GANDHAR. Capped at `watchlist_tool.MAX_WATCHLIST_BATCH` (200) resolved symbols per call. Fragments are never guessed at. The response splits three ways: `watchlist` (added), `unmatched` (no match), and `ambiguous` (two or more plausible matches, returned WITH their candidates so you can ask the user which they meant rather than picking one). Space-separated company names cannot be split reliably -- "GANDHAR OIL SAVITA OIL" is one fragment, not two -- so ask the user for one per line or comma-separated if a paste comes back unmatched. Re-adding a symbol already on the watchlist is a no-op, not an error. Requires an authenticated caller; see `get_watchlist` for the auth error shape.
    remove_from_watchlistRemove one or more stock symbols from the caller's DalalOS watchlist in a single call. Use this when the user says "stop watching X", "remove X from my watchlist", or "clear my watchlist" (call get_watchlist first, then pass every returned symbol here in one call). This is DalalOS's OWN watchlist -- see add_to_watchlist's docstring for why that distinction matters when multiple MCP servers are connected. `symbols` accepts either a list of strings (mirrors `add_to_watchlist`, capped at `watchlist_tool.MAX_WATCHLIST_BATCH`) or a single bare string (kept for one release for backward compatibility with older single-symbol callers). A partial match -- some symbols on the watchlist, some not -- never fails the call: the response reports `{"removed": [...], "not_found": [...]}` so the caller can see exactly which symbols were actually removed. Requires an authenticated caller; see `get_watchlist` for the auth error shape.
    search_stocksFind Indian stocks by company name, NSE symbol, BSE code, or ISIN. Returns matching securities with their ISIN, internal company_id, name, and both exchange codes. Use this first when a ticker is unknown or ambiguous, then pass a returned `nse_symbol` / `isin` / BSE code as the `query` argument to any other per-stock tool. Tolerant matching: a company-name/symbol typo still surfaces a suggestion, a truncated/ partial ISIN or BSE code matches via prefix, and a former/retired name or symbol (e.g. a pre-rename company name) resolves to the security's current identity, with `resolved_via` on the result naming which kind of resolution fired.
    get_stock_quoteGet the latest end-of-day quote (price, OHLC, volume) for an Indian stock. Accepts an NSE symbol, ISIN, or BSE code. Prices are EOD from the NSE bhavcopy. Carries `currency` ("INR") and a mechanically-computed `vwap` (turnover / volume for the latest bar, None when either is missing/zero). P/E and P/B may be null with a `valuation_notes` explanation (e.g. negative shareholders' equity, or a proven loss) rather than a misleading ratio. A `ratios_caveat` field and/or a `week52_adjustments` list appear when a split, bonus, or other corporate action in the trailing 52 weeks affects the comparability of the 52-week range or valuation ratios. `recent_dividends` / `upcoming_dividends` / `dividend_yield` carry realized cash-dividend history and trailing yield. Always check these fields before restating a figure as clean. A `bse_reported` sub-object, when present, carries BSE's OWN published ROE/operating margin/ net margin — a DIFFERENT, BSE-computed figure (not necessarily TTM or the same consolidated/standalone basis) from this project's XBRL-derived ratios elsewhere. It is a cross-check/fallback signal only — never treat it as the same number as a computed `roe`.
    get_batch_quotesGet EOD quotes for up to 20 Indian stocks in one call (peer benchmarking). Each item carries the same fields as get_stock_quote (currency, vwap, bse_reported, any valuation_notes/ratios_caveat/dividend fields) plus `status` and `error` keys, so an unresolved or uncached symbol is reported per-item rather than failing the whole batch.
    get_financialsGet consolidated financials (P&L + balance sheet), TTM, and computed margins. Accepts an NSE symbol, ISIN, or BSE code. `period_type` is "quarterly" (default) or "annual". Banks/NBFCs/insurers return an interest-income template (NII / interest income) instead of Revenue / EBITDA. Returns raw line items and mechanically-computed ratios only — no valuation verdicts. Also includes a `growth` section (annual YoY plus 3y/5y CAGR for revenue / net income / EBITDA / EPS) — a single summary block layered on top of these levels, NOT a per-period series; for a period-by-period QoQ/YoY growth, margin-delta, and reportable-segment trend series instead, see `get_financial_trends`. The `growth` section here is sign-aware (a loss base/endpoint is Not Meaningful rather than a garbage %), EPS share-adjusted across splits/bonuses, with a `base_effect` flag when a tiny prior-year base inflates the YoY. A `null` inside a present growth metric (as opposed to the metric being absent, which means <2 annual periods are cached) means the growth figure is Not Meaningful for that metric this period — most commonly because the prior-year base (or a CAGR endpoint) was a loss, making a percentage change mathematically undefined or misleading; it is not a data gap. When that is the cause, a sibling `*_not_meaningful_reason` field (e.g. `yoy_not_meaningful_reason: "prior_period_loss"`) makes it explicit rather than leaving the `null` to be misread as "no data available". Also carries three multi-period histories (independent of `period_type`/`limit` — always the full annual history): `interest_coverage_history` (per-year interest-coverage trend, general-only, omitted for banks/NBFCs/insurers or a newly-listed filer), `book_value_history` (per-year book value per share plus a P/B "band" against the actual historical price near each period, not general-only), and `working_capital_ratios` (always present: genera
    get_company_profileGet a company profile: identity, sector/industry, market snapshot, and TTM summary. Assembled from cached security master + quotes + financials. Accepts NSE symbol, ISIN, or BSE code. `fundamentals` is None when no financials are cached yet; `market` is None when no quote is cached. When present, `market` carries `currency` ("INR") and, only when a split/bonus fell inside the trailing 52 weeks, `week52_adjustments` — the same treatment get_stock_quote gives its own snapshot. Both `market` and `fundamentals` may carry caveat fields (e.g. `market.valuation_notes`, `fundamentals.ttm.basis_note`, `fundamentals.latest_period_income.non_recurring_items_note`) when a figure is suppressed or driven by a one-off/non-recurring item — always surface these alongside the figure they annotate rather than the bare number. `market.bse_reported`, when present, carries BSE's OWN published ROE/operating margin/net margin — a DIFFERENT, BSE-computed figure (not necessarily the same period or consolidated/standalone basis) from `fundamentals`' XBRL-derived ratios. Cross-check/ fallback signal only — never the same number as the computed `roe`/margins.
    get_company_reportGet a source-linked, read-only canonical company report for one security. Accepts an NSE symbol, ISIN, BSE code, or company name. `days` (1-365, default 90) is the reporting window that selects which recent disclosures are in scope. Returns the validated `company_report_v1` model as the envelope `data`: company identity, source-linked `facts` with `citations`, mechanically-computed `calculations`, evidence-referenced `claims`, materiality-bucketed `events`, and a `coverage` block that names any missing reviewed mapping rather than implying non-disclosure. This is DalalOS's own consolidated report over its cached exchange filings + reviewed exposure/peer mappings; if another connected MCP server exposes a similarly-named "company report" tool it is a DIFFERENT, non-interchangeable source. Read-only: assembled entirely from cache, no upstream fetch and no LLM call. Every number in a claim references the fact/calculation supporting it, and NO verdict, target price, or buy/sell language can appear — the canonical validator rejects such a report before it is ever built (SEBI research-analyst boundary). An unresolvable query (or a required input with nothing cached) returns `reason_code="not_found"`; an out-of-range `days` returns `invalid_argument`.
    get_peer_comparisonCompare a stock against its sector/industry peers on valuation metrics. Auto-identifies the peer group and returns a side-by-side table (Mkt Cap, PE, PB, Revenue TTM, net / EBITDA margin, ROE, ROA, ROCE, interest coverage, D/E, the EV bundle — EV, EV/EBITDA, EV/EBIT and the EV-based earnings yield — plus the cash-flow ratios P/CF, P/FCF and FCF yield), sourced entirely from cache. EBITDA-margin and the EV bundle are DELIBERATELY general-only (None for banks/NBFCs/insurers — an intentional validity- matrix decision: EBIT/EBITDA are not meaningful add-backs for a financial's P&L). Cash-flow ratios are NOT gated that way and populate for any peer disclosing an annual cash flow — including banks/NBFCs/insurers. The one exception is bank capex specifically: P/FCF and FCF yield are structurally unavailable for BANK peers whose only cached annual filing predates the fix for issue #169 (banks tag capex under a different XBRL concept than the general template; the mapping now covers it, but existing cached rows need a backfill re-scrape to pick it up) — P/CF (which doesn't need capex) is unaffected either way. Each row also carries `piotroski_f_score` (0-9, general-only; None for banks/NBFCs/ insurers) and `altman_z_score` (general-only; None for banks/NBFCs/insurers, and for a general filer whenever any of the five classic-formula inputs is undisclosed for that security). The explanatory text for WHY a score is None is never repeated per row — it is deduplicated across the whole peer set and surfaced once at `data.notes.{piotroski_f_score,altman_z_score}` (a list of the distinct reasons actually present in the table). A row with an implausible figure (e.g. a corrupted P/B or a unit-slipped market cap) is marked `valuation_suspect` and excluded from the table-level `peer_medians`; a row within 52 weeks of a rights issue/demerger/merger is marked `ratios_incomplete` (see the table-level
    get_shareholdingGet the promoter / FII / DII / public shareholding-pattern time series for a stock. Accepts an NSE symbol, ISIN, or BSE code. `limit` caps the most-recent quarterly periods (max 12). Returns raw reported ownership percentages — no verdicts. Sourced from cache; returns an empty series with a note when no shareholding data is cached yet. `breakdown` (when the underlying filing's raw payload was cached) carries the full BSE-SHP institutional sub-category split as `breakdown.institutions`, a list of `{"category": ..., "pct": ...}` — e.g. Mutual Funds, Insurance Companies, Alternate Investment Funds, Provident/Pension Funds, Sovereign Wealth Funds, Foreign Portfolio Investors Category I / II — separately from the headline `fii_pct`/`dii_pct` aggregates. Category label strings are BSE's own text as filed (may contain formatting artifacts like a trailing "/" or doubled spaces), not normalized. Omitted entirely for a period whose raw payload wasn't cached. `breakdown.named_institutional_holders` lists individual FII/FPI, insurance, and mutual-fund holders BSE's filing names once they cross the Reg 31 reporting threshold — `{"name": ..., "category": ..., "pct": ...}` per holder — so a caller can see who specifically holds a stake, not just the category total.
    get_price_historyGet the OHLC + volume price-history series for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `days` (1..1825) bounds the lookback window. Set `adjusted=True` for split/bonus-adjusted closes; default is raw close. `interval` is 'daily' (default), 'weekly', or 'monthly' (weekly/monthly resample the adjusted daily series). EOD from the NSE bhavcopy. `currency` is always "INR". Each bar carries `sma_50` and `sma_200`, computed from daily adjusted/raw closes before resampling, plus a mechanically-computed `vwap` (turnover / volume, None when either is missing/zero); vwap is not rescaled by the split/bonus adjustment factor (turnover/volume are raw flow figures, identical in raw and adjusted mode).
    get_valuation_historyGet point-in-time P/E and price-to-sales history for an Indian stock. Each point uses only the TTM filing that was public on that trade date. `days` accepts 1..1825; `interval` is daily, weekly, or monthly. P/S is null where the filing lacks a usable top line or disclosed share count. Cache-only, mechanically computed, no verdicts.
    get_returnsGet mechanical return statistics over standard windows for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. Returns period returns (1W/1M/3M/6M/1Y/YTD/max), CAGR, annualized volatility, max drawdown, and 52-week high/low — all computed from the split/bonus-adjusted close series. A null return is always explained by exactly one of two fields: `incomplete_windows` (not enough price history for that window yet) or `corporate_action_flagged_windows` (a rights issue/demerger/spin-off/merger/bare consolidation fell inside the window, so the window mixes a mechanical value transfer with ordinary price movement and is nulled rather than reported — see `corporate_action_caveat` when present). If the query only resolved via a rename/merger/demerger-successor alias, the envelope carries `resolved_via` naming which kind fired. Descriptive statistics only; no verdicts.
    get_technical_indicatorsGet moving averages, RSI, MACD, Bollinger Bands, beta, and circuit-filter band/hit-days for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. Moving averages (sma_50/sma_100/sma_200), `rsi_14` (Wilder's 14-period RSI), `macd` (12/26/9 EMA line/signal/histogram), `bollinger_bands` (20-day, 2-stdev middle/upper/lower + percent_b), and `beta` (regressed against NSE's own Nifty 50 daily close series over the trailing ~1Y of paired trading days; `beta_benchmark` names it) are all mechanically computed from the split/bonus-adjusted daily close series. `circuit_band_pct`/`circuit_band_as_of`/`circuit_hit_days` use the RAW (unadjusted) close series and are NSE's own per-security circuit-filter data, not derived from bhavcopy. NSE publishes only a CURRENT snapshot with no historical archive, so this pipeline's own daily captures are the only source of band history and only exist from whenever this deployment started capturing them: * `circuit_band_pct` is null for TWO DIFFERENT reasons — check `circuit_band_as_of` to tell them apart. `circuit_band_as_of` present + `circuit_band_pct` null means this security genuinely has NSE's "No Band" designation (no static daily price band applies — typically a large/liquid, F&O-eligible name; this is a complete, real answer, NOT missing data). `circuit_band_as_of` null means no band has been captured for this security AT ALL yet (also named in `insufficient_history`) — do not conflate the two. * `circuit_hit_days` is a list of `{trade_date, close, prev_close, pct_change, band_pct}` for RAW-close days that plausibly touched that day's captured band (a small tolerance absorbs NSE's tick-size rounding of the actual limit price off the raw percentage) — a descriptive flag that trading was likely constrained that day, not a claim about why. An indicator needing more history than is cached yet (e.g. sma_200 on a recently-listed s
    get_delivery_trendsGet the delivery-volume / delivery-percentage trend for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `days` (1..1825) bounds the lookback window. Returns the raw delivery quantity and delivery % time series from the NSE bhavcopy.
    get_dividendsGet the cash-dividend history for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `years` (1..15, default 5) bounds the window. Returns disclosed dividend amounts per share with ex-dates. Raw disclosures only. `annual_totals` (fiscal-year, Apr-Mar buckets) also carries a dividend-YIELD HISTORY: each bucket's `fy_end_price_date`/`fy_end_price` (the closing price on/before that FY's 31 March year-end) and `dividend_yield` (that FY's total dividend / that FY-end close) — None when no price history reaches that far back yet.
    get_brsrGet BRSR (Business Responsibility & Sustainability Report) ESG disclosures for a stock. Accepts NSE symbol, ISIN, or BSE code. `years` (1..10, default 3) caps fiscal years returned, newest first. Each year gives curated KPIs grouped as `emissions` (Scope 1/2 + intensity), `energy`, `water`, `waste`, `social` (female board/KMP %, LTIFR, fatalities, POSH complaints, CSR spend, ...), `governance`, and `meta` — each `{value, unit}`, raw as filed with SEBI. `include_raw=True` also returns the full ~800-concept BRSR map exactly as disclosed. SEBI's mandatory ESG filing for the top 1000 listed companies (LODR Reg 34(2)(f)). Raw disclosed figures only — never an ESG score, rating, or verdict (SEBI-RA line). Coverage starts from whenever the nightly refresh began ingesting the company's BRSR.
    get_bulk_block_dealsGet NSE bulk/block trade disclosures for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `deal_type` optionally narrows to "bulk" or "block" (omitted returns both); `days` (1..1825, default 90) bounds the trailing window; `limit` (1..500, default 100) caps rows returned, newest first. Each row is a raw disclosed (symbol, counter-party, direction) record: `client_name`, `buy_sell` ("BUY"/"SELL"), `quantity`, `price`, and `remarks` (bulk only). NSE's feed reports one row per counter-party + direction, not a matched buyer/seller pair — there is no official "buyer paired with seller" record. Only NSE's most-recently-published trading day is fetched upstream (no reachable historical bulk/block archive), so coverage starts from whenever the nightly refresh job began running, not further back.
    get_derivatives_positioningGet NSE F&O (futures & options) positioning for one underlying. Accepts an NSE symbol, ISIN, or BSE code for a stock, OR a raw F&O underlying/index name (e.g. "NIFTY", "BANKNIFTY") that has no security-master row of its own. Returns the latest trading day's aggregate: `futures_oi`/`futures_oi_change`, `call_oi`/ `put_oi`, `pcr` (put_oi / call_oi — a mechanically-computed ratio, not a signal), `total_volume`, and `in_ban_list`. Raw NSE bhavcopy figures only — no OI-buildup interpretation or bullish/bearish framing (SEBI-RA line).
    get_fo_participant_activityGet NSE participant-wise (FII/DII/Pro/Client) F&O open interest & volume — market-wide. `days` (1..366, default 30) bounds the trailing window. Each row is one (trade_date, client_type) pair with raw long/short contract counts across futures-index, futures-stock, options-index-call/put, and options-stock-call/put, for both `oi` and `volume`. This is a DIFFERENT, derivatives-side signal from `get_market_fii_dii_flow` (market-wide daily CASH-segment net flow) — it is the highest-confidence official substitute for FII/DII derivatives positioning (NSE's cash-market feed does not cover F&O). Raw counts only — no "smart money"/positioning-bias interpretation (SEBI-RA line).
    get_fno_ban_listGet the full NSE F&O securities-in-ban list for the most-recently-published trading day. Market-wide, not per-underlying — no `query` argument. This is the whole-list companion to `get_derivatives_positioning`'s per-symbol `in_ban_list` flag: use this tool when you want everything currently banned in one call, rather than checking symbols one at a time. Returns `ban_date` (the snapshot's date) and `symbols` (one entry per banned name, each with `nse_symbol` and `isin` — None for index names, which carry no security-master row). Raw NSE-published ban list verbatim — no "avoid these" framing or interpretation (SEBI-RA line).
    get_corporate_actionsGet the disclosed corporate-action timeline for ONE STOCK, HISTORICAL (splits, bonuses, dividends, etc.) — the per-stock, backward-looking sibling of get_market_calendar (whole- market, any window, all event types merged) and get_upcoming_results (whole-market, forward- only results convenience). Use this tool, not get_market_calendar, when you want one company's corporate-action history rather than a market-wide view. Accepts NSE symbol, ISIN, or BSE code. `years` (1..20, default 5) bounds the window. `types` optionally filters to a subset of action types. Newest first; raw disclosures.
    get_stock_eventsGet recent BSE corporate announcements (SEBI Reg-30 disclosures) for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `days` (1..365, default 30) bounds the trailing window over filing date; `category` optionally narrows to one BSE category (e.g. "Board Meeting", or "Insider Trading / SAST" for promoter/KMP insider buy-sell and pledge creation/invocation/revocation disclosures). Returns disclosure metadata — subject, headline, category, filing time, and a link to the source PDF on BSE. Metadata only; the filings themselves are not parsed or summarised. Quarterly results aren't here — use get_financials for those. Capped at 200 rows; `truncated: true` means more filings matched the window than were returned (narrow `days`/`category` to see the rest) — `total_scanned` reports the true match count, uncapped. Each event includes a `news_id` (the BSE filing GUID). To read the extracted facts and a factual summary of a specific filing, pass that `news_id` to get_filing_extract.
    search_company_disclosuresSearch this company's already cached official filings, page by page. Use after get_stock_events/get_filing_extract when you need historical context, such as a prior commissioning date, original order announcement, customer, project, or tender. This is cache-only: it never downloads a filing or triggers extraction. Results retain a source page and original BSE attachment URL; `coverage` tells you how much page-preserving history is indexed and explicitly reports parsed legacy filings that cannot be searched reliably yet.
    get_event_contextReturn cached prior-state context for a canonicalized filing event. Use after get_filing_extract for an order, capacity or other supported event. The result retains source quotes and reports only deterministic historical links; it does not infer price correlation, business causality, or an investment conclusion. Cache-only: no fetches, extraction requests, or writes occur on this tool path. ``event_family`` additionally carries the persisted family TIMELINE — every cached filing in this disclosure thread, in filing order — and ``open_questions`` lists the factual follow-ups still unanswered by those filings (e.g. a required contract value the company has not disclosed), each with the filing that raised it and, once answered, the filing that resolved it. Both are raw, source-linked groupings of the company's own disclosures: never a verdict, target, forecast or recommendation.
    get_company_operating_metricsReturn cached, source-grounded operating KPI history for one company. Coverage distinguishes company-disclosed values from ``not_disclosed`` fields. It never infers a current order book from a new order and never fetches or writes on this read path.
    get_company_macro_exposuresReturn cached company macro pathway evidence and eligible official context signals. Signals are emitted only when an active, reviewed, sourced company exposure passes the factor policy against a complete official PPAC Indian Basket or FBIL USD/INR window. This is conditional context only: it never states that a macro move caused or will cause an earnings, price, or investment outcome. Missing evidence is returned as explicit coverage, not inferred.
    get_company_exposuresReturn one company's REVIEWED macro-factor exposures, labelled via the factor catalog. Cache-only, read-only: the company's reviewed ``company_exposures`` rows joined to the ``factor_registry`` catalog, so each exposure carries its factor label/description/dimension alongside the disclosed pathway (directness/direction/lag/mechanism) and source evidence. This is a DIFFERENT tool from ``get_company_macro_exposures`` (two similarly-named tools): this one is the plain, raw per-company evidence listing — no ``as_of_date``/factor filter, no live PPAC/FBIL macro window, no eligibility signals. ``get_company_macro_exposures`` is the signal-eligibility tool that evaluates those exposures against a complete official macro window. Neither ever claims a macro move caused or will cause an earnings/price/investment outcome (SEBI-RA line). A company with no reviewed exposures returns an empty success envelope.
    get_relevant_peersReturn an explainable peer set for operating, financial, or valuation comparison. Uses reviewed, provenance-backed business tags and overrides plus cached factual metrics. The existing get_peer_comparison table remains the broader SEBI-classification comparison. This tool may return fewer peers when business-model evidence is insufficient; it never presents a same-industry label as proof of comparability, and returns no investment conclusion.
    list_announcement_bucketsList the market-wide BSE announcement discovery buckets (id + label). Each bucket groups a real-world disclosure type (e.g. "order-receipts", "fundraise", "credit-rating", "acquisitions", "management-changes") across the WHOLE market — the inverse of get_stock_events, which is scoped to one company. Pass a bucket id to get_announcement_bucket to fetch its recent filings.
    get_announcement_bucketGet every company that filed a matching BSE announcement in a trailing window, market-wide. `bucket` is one of the ids from list_announcement_buckets (e.g. "order-receipts", "fundraise"). `days` (1..90, default 7) bounds the trailing window over filing date. Returns newest first across the WHOLE universe (not one security). Metadata only — the raw disclosed subject/headline plus a link to the source BSE filing; no PDF parsing, no verdicts. Capped at 200 rows; `truncated: true` means more announcements matched the window than were returned (narrow `days` to see the rest) — `total_scanned` reports the true match count, uncapped. Each event carries its `news_id` — pass it to get_filing_extract for that filing's extracted facts.
    screen_stocksScreen the Indian security universe by user-supplied mechanical criteria. All `filters` keys are optional and AND-combined. `sort_by`/`order` order the result set; `limit` (1..100) caps it. Returns matching securities with the screened metrics — data only, no recommendations. An unknown filter key returns a `bad_request` error that lists every accepted key verbatim, so a rejected call is always self-correcting. RANGE filters (take a `_min` and/or `_max` suffix, e.g. `pe_min: 10, pe_max: 20`): market_cap, price, pe, pb, deliv_pct, week52_high, week52_low, turnover, num_trades (quote-level) — deliv_pct is a PERCENTAGE (50 = 50%); week52_high/week52_low are rupee price levels comparable to `price`; turnover is a rupee traded-value, num_trades a count. promoter_pct, pledged_pct — PERCENTAGES (pass 50 for "50%"), from shareholding data. roe, roa, roce, net_margin, dividend_yield, earnings_yield, fcf_yield, ebitda_margin, operating_margin, quarterly_net_margin_delta_yoy — FRACTIONS (pass 0.15 for "15%"). interest_coverage, ev, ev_to_ebitda, ev_to_ebit, price_to_cash_flow, price_to_fcf, debt_to_equity, price_to_sales, piotroski_f_score (0-9) — plain multiples/scores, no unit conversion needed. revenue_growth, net_income_growth, quarterly_revenue_growth_yoy, quarterly_net_income_growth_yoy, return_1d/1w/1m/3m/6m/1y — FRACTIONS (0.20 = 20% growth or return); unlike the margin/yield group above, these may legitimately exceed 1.0 (>100%) for high-growth or multi-bagger names. pct_off_52w_low — derived, FRACTION: (price - week52_low) / week52_low, e.g. `pct_off_52w_low_max=0.05` for "within 5% of its 52-week low". num_shareholders (a count) and promoter/fii/dii/public_holding_change_qoq — PERCENTAGE POINTS between the latest two shareholding filings (50% -> 55% is 5, not 0.10) — plus num_shareholders_change_qoq, a plain count difference. A security with on
    screen_by_queryScreen the Indian security universe with one free-form Screener.in-style expression. Reach for this instead of screen_stocks when the ask needs OR, arithmetic between two metrics, or a comparison screen_stocks' fixed `<metric>_min`/`_max` keys cannot express — e.g. `Return on capital employed > 22% AND (Debt to equity < 0.5 OR Interest Coverage Ratio > 8)`. screen_stocks stays the right tool for a plain AND-combined set of range filters. `dialect` picks the vocabulary and is never guessed: "screener" (default) reads Screener.in ratio names in the units Screener DISPLAYS — `> 22%` against a ratio stored as a fraction, market cap in crore — while "dalalos" reads canonical DalalOS metric ids in the units the cache stores. The metric catalogue for both is GET /v1/ratios; an unrecognised name comes back as an explicit error naming the phrase, never a silent substitution. Operators: AND, OR, = != > < >= <=, + - * /, and COALESCE, IF, LEAST, POWER, ABS, SQRT, LOG. Missing values follow SQL three-valued logic: a bare comparison against an unknown value does NOT match, `COALESCE(<metric>, 0) > x` does, and `A > x OR B > y` can still match on the right side alone. Division by zero is a missing value, not an error. Paging is pinned to one published metrics generation. Each response reports it as `pagination.snapshot_id`; pass that value back as `snapshot_id` on the next page. If a metrics refresh published a new generation in between, the call fails with `snapshot_expired` and the current generation rather than mixing rows from two of them — restart from `offset` 0. `sort_by` is a sortable metric id; ordering puts unknown values last and ends with an ISIN tie-break, so pages never duplicate or skip a row. Returns matching securities with the screened metrics — data only, no recommendations.
    get_sector_overviewGet an aggregate market overview by sector (or a finer SEBI grain). Omit `sector` to list all groups; pass one to drill in. `grain` is "sector" (default), "igroup" (SEBI Industry), or "isubgroup" (SEBI Basic Industry, the finest grain). Returns count, total market cap, and median/mean PE and median PB per group — computed from cached quotes. Aggregates only.
    list_index_constituentsList the constituent stocks of an Indian market index (e.g. NIFTY 50, NIFTY 500). `index` is matched exactly to a known index name — get the valid names from list_indices. `limit` (1..500) caps the returned constituents. Returns the member securities with identifiers (each `nse_symbol`/`isin` can be passed as the `query` to any per-stock tool).
    list_indicesList the market indices for which constituent membership is cached.
    get_market_heatmapGet valuation + multi-horizon returns for the constituents of an Indian market index. `index` is matched exactly to a known index name (e.g. NIFTY 50, NIFTY 500) — get the valid names from list_indices. `limit` (1..500) caps the returned constituents, sorted by market cap desc. Each row carries market_cap/pe/pb plus precomputed 1d/1w/1m/3m/6m/1y returns, and any Tier-C structural-event flags on those returns (`return_flags`) or a lack of price history (`incomplete_windows`) — the two are mutually exclusive and together explain every null return. Mechanical facts only — no rankings.
    get_top_moversRaw ranked gainers/losers/most-active for an index over one completed EOD session. `index` defaults to 'NIFTY 500' — get valid names from list_indices. `metric` picks the raw sort field: 'pct_change' (day % change, default), 'change' (absolute price change, Rs), 'turnover' (traded value, Rs), or 'volume' (traded quantity). `direction` is 'desc' (default — top gainers / most active) or 'asc' (top losers). `limit` (1..100, default 20) caps the rows. This is the same mechanical fact NSE's own top-gainers/losers page publishes — a caller-chosen sort key over already-public EOD numbers, nothing more. Distinct from get_market_heatmap, which is deliberately NOT sortable by return (issue #85) and instead always sorts by market cap — use get_market_heatmap for a valuation+returns snapshot, use this tool when the question is specifically "what moved most today".
    list_preset_screensList the fixed, nightly-precomputed preset screens (name/description/cache freshness). Presets are FIXED mechanical filter combinations (never live-queried, never ranked or labelled as a recommendation) — a discovery starting point a caller can further filter via screen_stocks itself. Use run_preset_screen(name) to fetch one preset's actual results.
    run_preset_screenReturn the last nightly-precomputed result for one registered preset screen. `name` must be one of the names returned by list_preset_screens. A preset that has never been computed yet returns an empty result with reason_code "no_data". Cache-only — this is the stored output of an equivalent screen_stocks(filters=...) call, not a live query.
    get_upcoming_resultsList companies with an upcoming board-meeting / results date — WHOLE-MARKET, FORWARD-ONLY. This is a forward-only, sector-filterable CONVENIENCE view over the same results_calendar data get_market_calendar also reads — equivalent to get_market_calendar(date_from=today, date_to=today+days, types=["results"]) plus the sector narrowing get_market_calendar doesn't offer, not a competing source. Prefer get_market_calendar instead when you need a past window or multiple event types together. For ONE company's historical corporate-action timeline (splits/bonuses/dividends), use get_corporate_actions instead. `days` (1..90, default 14) is the forward window; `sector` optionally filters; `limit` (1..200) caps the results. Each entry carries the meeting date and security identifiers. A disclosed meeting is never dropped just because its bse_code doesn't join cleanly to the securities master; such rows keep the raw bse_code and add a `note` explaining why isin/nse_symbol/name/sector are null.
    get_fii_dii_flowDEPRECATED (issue #285) — renamed to `get_market_fii_dii_flow`; use that instead. Kept as a thin back-compat alias for this release only (no removal date committed yet): delegates to the exact same query function as `get_market_fii_dii_flow`, so the response is byte-for-byte identical for the same arguments. See `get_market_fii_dii_flow`'s docstring for the full parameter/behavior description.
    get_index_valuationNSE's own daily OHLC + P/E + P/B + Div Yield time series for one named index. `index` is matched case-insensitively against NSE's own published index names (e.g. "Nifty 50", "Nifty Bank", "Nifty IT", "Nifty Auto", "Nifty FMCG", "India VIX" — use get_india_vix for a VIX-specific shape). `from_date`/`to_date` are optional ISO dates (default: trailing ~30 days; window capped at 1825 days). Sourced from NSE's own daily `ind_close_all` file, which carries NSE's ALREADY-COMPUTED P/E, P/B, Div Yield for every index it publishes — sector indices (Nifty Bank, Nifty IT, ...) give an official NSE sector-valuation band, a DIFFERENT figure from get_sector_overview's peer-derived median_pe/median_pb (this project's own aggregate over its tracked universe, grouped by a different taxonomy) — the two are independent, neither validates the other. An unrecognized `index` returns `reason_code: "no_data"` with `available_indices_hint` (every index name NSE publishes) — see also list_index_valuations. Raw NSE-published figures only.
    list_index_valuationsList every NSE index name tracked (headline, broad-market, sector/thematic, India VIX). Each entry carries `{index_name, latest_trade_date, latest_close}`. Powers get_index_valuation's `available_indices_hint` and lets you discover NSE's exact index-name spelling before calling it.
    get_india_vixNSE's daily India VIX (volatility index) OHLC time series. `from_date`/`to_date` are optional ISO dates (default: trailing ~30 days; window capped at 1825 days). Each row is `{trade_date, open, high, low, close, points_change, pct_change}` — VIX has no P/E, P/B, dividend yield, volume, or turnover, so those keys are omitted rather than returned null. This is DalalOS's own NSE-sourced VIX series — if another connected MCP server also exposes a similarly-named VIX tool, it is a DIFFERENT, non-interchangeable source; prefer this one for anything joined against DalalOS's own index/sector data.
    get_market_breadthWhole-market advance/decline/unchanged breadth: how many NSE-listed securities moved up/down/flat on a trading day. `from_date`/`to_date` are optional ISO dates (default: trailing ~30 days; window capped at 366 days). Each row is `{trade_date, advances, declines, unchanged, total}`, sourced from NSE's own live market-data feed. NSE publishes no bulk historical archive for this figure, so history only extends as far back as this server has been capturing it — an empty result for a genuinely old date is expected, not a bug. Raw counts only — no "risk-on/risk-off" or breadth-based market-direction commentary (SEBI-RA line).
    get_macro_indicatorsOfficial macro/sector indicators: MOSPI CPI, WPI, IIP (monthly), GDP (annual), and PPAC's Indian Basket crude-oil price (monthly). `dataset` is required: `"cpi"` (headline Consumer Price Index by sector/division), `"wpi"` (headline Wholesale Price Index — overall + food index only), `"iip"` (Index of Industrial Production by category), `"gdp"` (GDP level + growth rate, current/constant prices, one row per published estimate vintage — First/Second Advance, Provisional, Revised), or `"crude_basket"` (PPAC's Indian Basket crude-oil monthly average price, USD/bbl). Any other value is a `bad_request`. `from_period`/`to_period` bound the window (`"YYYY-MM"` for cpi/wpi/iip/crude_basket, the fiscal-year string e.g. `"2024-25"` for gdp); `series_contains` substring-filters `series_key` (e.g. `"Food"`, `"Manufacturing"`, `"GDP Growth Rate"`; a no-op for crude_basket, which has only one series). `limit` (1..2000, default 200) caps the result, newest period first. Raw published index values/growth percentages/commodity prices only (SEBI-RA line) — no directional commentary ("inflation is high", "oil is expensive").
    get_fx_reference_ratesDaily FBIL INR reference rates (USD/GBP/EUR/JPY/AED/IDR against INR). `currency_pair` optionally filters to one pair (e.g. `"USD/INR"`, case-insensitive). `from_date`/`to_date` are optional ISO dates (default: trailing 30 days). Each row is `{rate_date, currency_pair, unit_base, rate, source}` — `rate` is always "INR per `unit_base` units of the foreign currency" (unit_base is 1 for USD/GBP/EUR/AED, 100 for JPY, 10000 for IDR — FBIL's own published denomination, never silently rescaled). FBIL's public feed only serves a rolling ~2-day window with no bulk history archive found, so a fresh deploy accretes this table forward one scheduled refresh at a time — a wide window may legitimately return far fewer rows than the window implies.
    get_sector_fii_flowDaily FII/FPI net flow (raw Rs), aggregated by sector -- the #74 sector-wise breakdown. Scope-keyed alongside its siblings (issue #285): get_market_fii_dii_flow is market-wide with no sector dimension; get_stock_fii_flow is per-stock; get_shareholding is per-company QUARTERLY holding %. This is DAILY, per-sector, TRANSACTION flow, joined from the stock-level fii_fpi_stock_flow table against securities.sector (the same sector field get_company_profile/get_sector_overview use). `from_date`/`to_date` are optional ISO dates (default: trailing ~30 days, capped at 366); `sector` optionally narrows to one sector name. `net = buy - sell` is the only computation (SEBI-RA line). COVERAGE CAVEAT: sourced from CDSL's Trade-Wise Equity Data of FII/FPI ONLY -- NSDL (India's other depository) was confirmed unreachable and is not ingested, so this is a PARTIAL view of FII/FPI activity by sector, not the whole market's figure (every response carries a `coverage_note` saying so). CDSL itself publishes monthly bulk files, not daily/live.
    get_fii_activityDEPRECATED (issue #285) — renamed to `get_stock_fii_flow`; use that instead. Kept as a thin back-compat alias for this release only (no removal date committed yet): delegates to the exact same query function as `get_stock_fii_flow`, so the response is byte-for-byte identical for the same arguments. See `get_stock_fii_flow`'s docstring for the full parameter/behavior description.
    get_market_calendarGet a unified, WHOLE-MARKET calendar of disclosed events across all NSE/BSE securities, over an ARBITRARY window (past or future). Use this instead of get_upcoming_results when you need a past window or multiple event types together; use get_upcoming_results instead when you just want a forward results window with a sector filter (a scoped convenience over the same results data this tool also reads). For ONE company's historical corporate-action timeline, use get_corporate_actions instead — that tool is per-stock; this one is market-wide. `date_from`/`date_to` are ISO dates (YYYY-MM-DD); `date_to` must be on or after `date_from` and the window is capped at 180 days. `types` optionally filters to a subset of `results, dividend, split, bonus, demerger, ipo` (plus the remaining corporate-action disclosure types: consolidation, rights, buyback, spinoff, merger, distribution, other) — an unknown type is a bad_request. Each event is `{date, type, isin, nse_symbol, name, detail}`, merged from results_calendar (results) and corporate_action_events (everything else) and sorted chronologically; `limit` (1..2000, default 500) caps the merged result. `ipo` is a stub — no IPO data source exists yet, so it always returns zero rows with an explanatory note. Raw disclosed facts only — no verdicts, no importance ranking beyond your own type filter.
    get_iposList IPO/public-issue records: upcoming, open, listing pending, or recently listed. `status` optionally filters to `upcoming`, `open`, `listing_pending`, or `listed` (omitted returns all four); an unknown value is a bad_request. Unlike most fields, `status` is derived at READ TIME from dates versus today (IST) and a listed-security match. A passed planned listing date without that evidence is `listing_pending`, never `listed`. `limit` (1..500, default 100) caps the result. Each entry carries price band, face value, lot size, issue size, open/close/listing dates, issue price, listing price (once listed), category-wise subscription x-times (QIB/NII/Retail/Employee) where disclosed, a DRHP/prospectus link, and a mechanically-computed `listing_gain_pct` = (listing_price - issue_price) / issue_price (null pre-listing). Sourced from BSE (api.bseindia.com) and SEBI public-issue filings — official sources only. No Grey Market Premium (GMP) field anywhere: GMP has no official exchange source, so it is deliberately excluded (SEBI-RA line — raw facts and mechanical arithmetic only, never a verdict).
    get_financial_trendsGet multi-period growth and margin trends for an Indian stock. Levels-vs-deltas division: this tool returns a PER-PERIOD time series (QoQ/YoY growth, `net_margin_delta`, `fcf_growth`, and per-period reportable-segment breakdowns, one row per displayed period) — not the latest levels or a summary growth/CAGR block. For the current P&L/balance-sheet levels, TTM, and a single summary `growth` section (annual YoY plus 3y/5y CAGR), see `get_financials` instead. Accepts NSE symbol, ISIN, or BSE code. `period_type` is "quarterly" (default) or "annual"; `limit` (1..12) caps the periods, newest first. Returns level fields plus QoQ/YoY growth and margins — mechanically computed, no verdicts. Each period carries `source` (`"bse-xbrl"` post-listing vs `"drhp"` pre-listing/prospectus-restated for a newly-listed company); the envelope's own `source` is the shared value or `"mixed"`.
    get_pledge_trendGet the promoter share-pledge percentage trend for an Indian stock. Accepts NSE symbol, ISIN, or BSE code. `limit` (1..16) caps the most-recent periods. Returns the reported pledged-percentage time series. Raw disclosures only. Each period carries `pledge_disclosed`: false means this quarter's pledge field wasn't present in the underlying filing (a null `pledged_pct` reads as "not disclosed", not "zero pledge") — a real 0.0 is only reported when `pledge_disclosed` is true.
    get_data_freshnessReport cache freshness: last successful refresh per data domain and overall health. Every scraper-backed domain (including fii_dii and the ipos family) carries a staleness threshold matched to its real refresh cadence, so a domain whose scraper job silently stops running gets flagged stale rather than reporting `max_age_hours: null` forever.