StockLens

Add one company to the authenticated user's default StockLens portfolio as a company they follow, so its score stays readable here. Call it only when the person has asked for it or agreed to an offer. If the portfolio is already at the limit of the person's current plan, the result says so. After an add the person accepted from a get_market_summary offer, call get_market_summary again to answer their question. Does NOT execute trades, does NOT record a holding or transaction, and does NOT accept more than one ticker per call.

add_to_watchlist

Screen the companies StockLens scores nightly by region, exchange, sector, industry, market-cap band and trading volume, sorted by one of the six StockLens scores or by market cap, volume, popularity or ticker, and return the top or bottom N. This is the only StockLens tool that ranks or compares companies: use it for any top N, best, worst, highest, lowest or filtered request, and never build such a list from get_market_summary or general knowledge. It has no valuation, price-target or growth filter; say so rather than calling a score sort one. status ranked means the requested order was used. browse_substituted means a score order was asked for and market-cap order with scores hidden was returned, so never describe those rows as ranked by score. locked means no companies are named; relay message verbatim. What the caller can sort and how far it reaches is in access_tier and reach_capped_at. Report only the rows returned. It does not trade and gives no personal recommendations.

discover_stocks

Return the progress or result of an analysis started with initiate_analysis, by its analysis_id. Each call returns the current state once and does not wait. While status is in_progress, check again only when the person asks, and no sooner than retry_after_seconds. A failed status is an answer; relay error_message. A complete result carries the composite score and rating word, the evidence word (Full, Core or Low), each domain's score, grade word and contribution (cornerstone, major, supporting or contextual), key strengths and challenges, and for a Plus Analysis a written narrative. Say how much a domain counts only with its contribution word, never as a number or share. It does not accept a ticker and does not rank companies.

fetch_analysis_result

Retrieve the latest StockLens composite analysis summary for a stock ticker. Returns composite score (0-100), an overall rating, per-domain scores and grades, and key strengths and challenges. No account is required for the 600 largest companies StockLens scores. A signed-in caller reaches further (Free the same 600, Pro the top 5,000, Max the whole scored universe) and always reads anything on their own watchlist, however deep it ranks. Outside that surface the call is refused with TIER_INSUFFICIENT, which is NOT a statement that the stock is unscored: do not tell the user StockLens has no analysis for it. Data is derived from the most recent nightly analysis run. Use this to quickly assess a stock before deciding whether to run a full analysis. Does NOT accept more than one ticker and does NOT rank, sort, filter, or list multiple stocks — for any "top N", "best/worst", "highest/lowest scored", or filtered multi-stock request, call discover_stocks instead; never assemble a ranking by calling this tool repeatedly and inventing an order.

get_market_summary

Retrieve StockLens analysis summaries for the authenticated user's watchlist. Returns available composite scores and grades for watchlisted stocks; either value may be absent when no completed score exists. Returns the full watchlist up to the capacity of the person's current plan; tier_limited says whether it was cut short. Use this to give users an overview of their portfolio's analytical health. Does NOT accept a ticker or filter arguments and does NOT rank or screen stocks outside the user's own watchlist; call discover_stocks for a market-wide ranked or filtered list.

get_portfolio_insights

Start a full StockLens analysis of one company, only when the person asks for one. A new run may use one Analysis credit, or one Plus Analysis credit when depth is plus; Plus adds a written narrative and the result says if the person's plan does not include it. It returns an analysis_id at once and finishes asynchronously; fetch the result with fetch_analysis_result when the person asks for it. new_run_started and reused_existing say whether a recent matching analysis was reused. One ticker per call. It does not rank or compare companies, and does not trade or move money.

initiate_analysis

Health check. Returns pong.

ping

Remove one company from the authenticated user's default StockLens portfolio. Does NOT execute trades and does NOT delete a recorded holding or its transactions; a holding with recorded transactions cannot be removed through this tool. Does NOT accept more than one ticker per call.

remove_from_watchlist