DalalOS: Indian Stock Market Research (NSE/BSE)

Use this when the user asks how an Indian stock's return compared with an index such as Nifty 50 over a period. One stock's return beside an NSE index's over the same window. `symbol` is an NSE equity symbol, `index` an NSE index name (default "Nifty 50"). Window: `days` (default 365, max 1825) or `from_date`/`to_date`. Returns each side's return %, annualised volatility, max drawdown, best and worst day, and `difference_pct` (stock minus index, percentage points). The stock's return compounds NSE's own close/prev_close, so splits and bonuses do not break it. Price returns, no dividends. Arithmetic only.

Use this when the user asks for moving averages, RSI, MACD, Bollinger Bands, beta or circuit-limit data for an Indian stock. Get 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 tha…

Use this when the user asks which Indian stocks gained or lost the most, or traded the most, in the last completed session. Raw 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 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".

Use this when the user asks which Indian companies report results soon, optionally by sector. For a past window or other event types use get_market_calendar. List 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.

Use this when the user asks how an Indian stock's PE or price-to-sales ratio has changed over time. Get 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.

Use this when the user asks what is on their DalalOS watchlist, a saved list of stock symbols (not brokerage holdings). Get 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. 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.

Use this when the user wants to browse market-wide disclosure types, such as order receipts or fundraises, before calling get_announcement_bucket. List 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.

Use this when the user asks which stocks are in an Indian index such as NIFTY 50 or NIFTY Bank. List 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).

Use this when the user needs the names of Indian indices that have PE, PB and dividend-yield history. List 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.

Use this when the user needs the list of Indian market indices DalalOS covers. List the market indices for which constituent membership is cached.

Use this when the user asks what ready-made screens are available, before calling run_preset_screen. List 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.

Use this only to confirm the DalalOS connection is working. DalalOS health check. Returns a success envelope to confirm the server is reachable.

Use this when the user asks to remove stocks from their DalalOS watchlist. Changes only the user's own saved list. Remove 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, tied to the caller's DalalOS account. `symbols` accepts either a list of strings (mirrors `add_to_watchlist`, capped at 200 symbols per call) 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.

Use this when the user wants the latest result of a named ready-made screen from list_preset_screens. Return 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.

Use this when the user's screen needs OR logic, arithmetic between two metrics or a screen expression that screen_stocks filters cannot express. Screen the Indian security universe with one free-form DalalOS screen 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 common screener ratio names in the units a screener page 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. Query syntax and metric names: https://dalalos.in/docs/screener and https://dalalos.in/docs/screener/ratios. 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 la…

Use this when the user asks for Indian stocks matching numeric criteria such as PE, PB, market cap, ROE, margins or debt, optionally within an index such as NIFTY 50. For OR logic or arithmetic between metrics use screen_by_query. Screen 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…

Use this when the user needs historical detail from an Indian company's earlier filings, for example a prior order value or commissioning date. Search 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.

Use this when the user names an Indian company, NSE symbol, BSE code or ISIN and you need to identify the listed security before calling another tool. Not for US or other non-Indian stocks. Find 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.

Use this when the user asks to report a problem with DalalOS data or tools, or to request a feature, or agrees after you offer to report a likely DalalOS issue. Not for questions about a company; it sends a report to the DalalOS team and does not change any data. Submit a user-approved report about DalalOS data, tools, documentation, or a feature request. Use this when the user asks to report feedback or agrees after you offer. Include only details needed to understand the issue; do not send full conversations, credentials, account information, contact details, portfolio holdings, or unrelated private data. Clearly distinguish a suspected issue from a verified fact: a reported discrepancy is stored as a claim, since units, periods or source timing may explain it. Never report a failure of this feedback tool itself, and do not offer to report the same issue twice in one conversation. Fields: `category` (data_inaccurate, data_outdated, data_missing, tool_error, unexpected_result, feature_request, documentation, other), `summary` (max 160 chars), `details` (what happened or what is needed, max 2000 chars) and `request_id` (a fresh UUID you generate per report; reuse it only to retry the same report) are required. Optional context: `related_tool` (the DalalOS tool involved), `security_identifier` with `security_identifier_type` (nse_symbol, bse_code or isin; give both or neither), `metric`, `observed_value` and `expected_value` (with units, max 200 chars each), `as_of_date` (date or reporting period), `source_reference` (a short citation or URL; it is stored, never fetched). No source, exact value or identifier is required. Requires an authenticated caller. Feedback is free and does not use monthly credits. On success returns `report_id` and `status` "received" (the report was saved; it has not been verified, prioritised or fixed). Tell the user the report supports future improvements, that the team will not reply to individual reports for now, and give them the rep…