Real-time stock prices, fundamentals, technical indicators, and AI-analysed news for 1000+ stocks. Includes macro regime, market outlook, sector intelligence, insider sentiment, and earnings calendar. 12 MCP-native tools over Streamable HTTP. Free tier available, no credit card.
Scored across 22 tools
Most tools have clearly distinct purposes, and the descriptions actively cross-reference related tools (e.g. get_stock_activity vs get_stock_news/get_stock_filings, get_news_feed vs get_signals). There is still some overlap among get_stock, get_stocks, get_stock_research, and get_stock_activity, but the descriptions make the boundaries workable.
Every tool follows the same snake_case get_<resource> pattern: get_stock, get_stocks, get_watchlist, get_sector_intelligence, etc. No mixed conventions or vague verbs appear.
22 tools is on the heavy side, but the server covers a broad stock-intelligence domain spanning quotes, financials, news, filings, calendars, AI research, market overview, and watchlists. Each major surface has a plausible reason to exist, though a few could arguably be consolidated.
Coverage is strong across single-stock data, batch retrieval, research, news, filings, financials, price/indicator history, analyst trends, insider activity, calendars, market pulse, movers, sector intelligence, screening, signals, and watchlists. Minor gaps remain, such as a symbol-search/discovery tool or portfolio/alert management, but core workflows are covered.
How analyst consensus on a stock has moved over time - the trajectory of the rating and price targets, not just today's value. Answers "are analysts getting more or less positive on this name?", which get_stock's single current analyst_rating / analyst_target cannot.
Returns one row per day, oldest to newest, up to days (max 365, default 90):
date: YYYY-MM-DD
analyst_rating: consensus label (strong_buy/buy/hold/underperform/sell/strong_sell) or null
analyst_rating_score: numeric consensus, 1.0 (strong buy) to 5.0 (sell)
LOWER is more positive. The same scale as get_stock's analyst_rating_score.
analyst_count: number of analysts contributing
analyst_target: mean price target
analyst_target_high / analyst_target_low / analyst_target_median: target spread
price: the stock's price on the snapshot date, so the target can be read against where the stock actually traded
Snapshots are taken once per weekday, so a 90-day window is roughly 60 rows.
A field is null on a day where the source reported none - analyst_rating in
particular can be null on a day when the price targets are present. A weekday
can be missing entirely if the daily snapshot did not run; such days are not
reconstructed, the date is simply absent. Coverage: most of the
tracked universe has a usable history; a symbol with fewer than 2 snapshots
returns an empty snapshots list with a note rather than a single stranded point.
History begins July 2026 and grows daily.
For the current analyst view alone, get_stock is enough. For price/indicator history, see get_indicator_history - this tool is analyst consensus only.
Pro tier only. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days of daily analyst snapshots to return (max 365, default 90). Returns an empty list with a note if fewer than 2 snapshots exist in the window. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral facts: weekday-only snapshots (~60 rows per 90 days), null semantics per field, missing weekdays never reconstructed, fewer than 2 snapshots returns an empty list with a note, and history starting July 2026. It also notes the inverted 1.0=strong buy / 5.0=sell scale, which prevents a serious misreading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core question and sibling routing, then a scannable field list. The field enumeration partly duplicates the output schema, and the trailing disclaimer adds length, but almost every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers cadence, sparsity, null handling, minimum-history cutoff, coverage caveats, tier gating, and the numeric scale convention. For a read-only history tool with an output schema in place, nothing an agent needs before calling is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the lower-is-more-positive direction of analyst_rating_score, the ~60-rows-per-90-days density, and the null-per-field behavior that tells the agent how to interpret the `days` window's output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('how analyst consensus on a stock has moved over time') and frames it as the trajectory rather than a snapshot. It explicitly distinguishes itself from get_stock ('get_stock's single current analyst_rating / analyst_target cannot') and from get_indicator_history ('this tool is analyst consensus only').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the exact question the tool answers ('are analysts getting more or less positive on this name?') and gives explicit routing rules: use get_stock for the current view alone, get_indicator_history for price/indicator history. It also flags the Pro-tier prerequisite, which is a real usage gate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upcoming earnings dates for stocks in the Stocklake universe.
days: look-ahead window in days (default 7, max 30)
limit: max companies to return. Free and guest get at most 5, whatever limit says: the companies with the largest market cap, listed by date, each counted as one call toward your daily limit. Pro gets up to 500 companies per call (default 100) for one call. A window can hold 1,000+ reporters; page with offset, or narrow with symbols / min_market_cap / a smaller days.
offset: Pro only. Skips that many companies (sorted by date). Pass the response's next_offset to get the next page.
symbols: only these tickers (up to 50). Applied before limit.
min_market_cap: only companies with at least this market cap in USD.
Returns: { window_days, from_date, to_date, count, total_in_window, offset, next_offset, results[] }. total_in_window counts the companies that match your filters, before limit/offset; next_offset is null on the last page (Free and guest: always null).
Each result: symbol, name, sector, market_cap, price, rsi, earnings_date (ISO UTC), is_estimate, eps_trailing, eps_forward
Sorted by earnings_date ascending.
Dates sourced from market data - treat is_estimate=true dates as approximate. Available to all tiers.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-ahead window in days (default 7, max 30). | |
| limit | No | Max companies to return. Free and guest: at most 5 (the largest by market cap), each counted as one call toward your daily limit. Pro: up to 500 per call (default 100), one call each. | |
| offset | No | Pro only: skip this many companies (by date) to page through a long window. Use next_offset from the previous response. Ignored for Free and guest. | |
| symbols | No | Only these tickers (up to 50), e.g. your holdings. Applied before limit. | |
| min_market_cap | No | Only companies with a market cap of at least this many US dollars (e.g. 10000000000 for $10B). Applied before limit. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/non-destructive, and the description layers on genuinely non-obvious behavior: Free and guest are capped at 5 companies 'whatever limit says', each call counts toward a daily quota, Pro allows 500/call, offset is ignored for Free/guest. It also flags that dates are market-data-sourced and is_estimate=true should be treated as approximate — a real caveat not captured by schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line purpose followed by a per-parameter bullet list, then return shape and sort order. Every bullet carries decision-relevant information (tier caps, precedence, paging), and the redundancy with schema descriptions is small relative to the density of added semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though an output schema exists, the description's return-shape sketch adds the meaning of total_in_window vs count and the null-on-last-page rule for next_offset, plus sort order and Free-tier next_offset always being null. For a 5-param, tier-gated, paginated tool, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining evaluation order ('applied before limit' for symbols and min_market_cap), tier-conditional enforcement of limit and offset, and the next_offset paging contract. Much of it restates the schema text verbatim, which caps it below a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'Upcoming earnings dates for stocks in the Stocklake universe', which is clearly distinct from price/news/financials siblings. It does not, however, differentiate itself from the closest neighbors (get_earnings_intelligence, get_economic_calendar), so an agent must infer the boundary rather than read it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong operational guidance: it tells the agent to page with offset, or to narrow with symbols / min_market_cap / a smaller days when a window holds 1,000+ reporters, and warns that offset is Pro-only. Missing is explicit routing guidance vs. sibling tools such as get_earnings_intelligence, so the 'when to use this instead' half of the equation is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upcoming earnings with AI context - AI scores, verdicts, and risk factors per stock. Combines the earnings calendar with AI pipeline data to surface which upcoming earnings events are worth monitoring.
Parameters:
days_ahead: look-ahead window in days (default 14, max 30)
sector: filter to one sector (e.g. "Technology")
min_ai_score: only return stocks with AI score >= this value, 0-100 (optional).
Gates on the same ai_score field the response returns. Applied server-side before limit truncates the
result - a stock with a qualifying score always counts against limit ahead
of one without, rather than being cut off first for reporting later in the
earnings window.
limit: max results to return (default 25, max 25). Each returned ticker counts as one call toward your daily limit - see the docs' rate-limit section.
Returns per stock (sorted by earnings_date ascending):
earnings_date: ISO UTC timestamp · is_estimate: whether date is estimated
symbol, name, sector, price, rsi, market_cap
eps_trailing, eps_forward (earnings expectations context)
ai_verdict (positive/neutral/negative, from nightly AI pipeline)
ai_score (0-100) / ai_score_band (Weak/Moderate/Strong/Very Strong) - the AI research composite score, same 0-100 scale and bands as signal_score but a separate score; null if this stock has no AI summary yet.
ai_risks: top 2 AI-identified risk factors
analyst_rating, analyst_target
Pro tier only - AI pipeline cost attached. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 25, max 25). Each returned ticker counts as one call toward your daily limit. | |
| sector | No | Filter to one sector, e.g. "Technology". | |
| days_ahead | No | Look-ahead window in days (default 14, max 30). | |
| min_ai_score | No | Only return stocks with AI score >= this value, 0-100 (optional). Gates on the same ai_score field the response returns. Applied server-side before limit truncates the result, so a qualifying stock always counts against limit ahead of one without. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (which only cover the read-only/idempotent safety profile) by disclosing tier gating ('Pro tier only'), cost implications ('AI pipeline cost attached'), and a rate-limit interaction ('each returned ticker counts as one call toward your daily limit'). It also explains the server-side ordering of min_ai_score vs limit truncation, which is genuinely non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a clear purpose statement, but the parameter and return-value lists duplicate the input schema and the existing output schema, making the description longer than necessary. The structure is readable but not economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter read tool with an output schema, the description supplies everything an agent needs: tier restriction, cost, rate-limit accounting, filtering semantics, and sort order. The return-field enumeration is redundant given the output schema but not harmful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented in the schema and the description largely restates them (days_ahead, sector, min_ai_score, limit). It adds only marginal nuance about ai_score gating and limit interaction, which the schema also captures, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and differentiator: 'Upcoming earnings with AI context - AI scores, verdicts, and risk factors per stock.' The second sentence explicitly says it 'combines the earnings calendar with AI pipeline data,' which lets an agent distinguish it from the plain get_earnings_calendar sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use it ('surface which upcoming earnings events are worth monitoring') but never names an alternative or exclusion, even though get_earnings_calendar is an obvious sibling. An agent must infer that this tool is the AI-enriched superset rather than being told directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upcoming and recently-released macro/economic events -- interest rate decisions, CPI, GDP, PMI, unemployment, payrolls, retail sales, and more.
Two buckets:
released_recent: events with a real reported value, within the last
lookback_days days. Every item here carries a real actual value
(never blank) plus diff (actual minus previous -- a plain arithmetic
difference, never a beat/miss or consensus judgment; point-in-time
consensus is not available).
upcoming: not-yet-released events within days. No item here ever
carries an actual value.
Every item in both buckets carries key_event: true for the handful of
event types that reliably move markets on their own (rate decisions, CPI,
GDP, headline Non-Farm Payrolls) -- an event-TYPE flag only, never a
beat/miss or directional judgment on the number itself. Set
key_events_only=true to filter to just these, or major_only=true to
restrict to the 8 largest economies.
Both buckets sort major-economy-first, then by recency -- truncating to
limit should never lose a US/EU/UK/JP/CN/DE/FR/CA print to an older or
thinner-economy one.
All tiers. Guest and free: days max 1 (default 1), lookback_days max 2, limit max 20.
Pro: days max 14 (default 3), lookback_days max 7, limit max 50. When a guest/free
value is above its cap, the response is served at the cap and carries
capped ({param: {requested, served}}) plus a pro_unlocks note.
For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-ahead window in days for upcoming events. Default 1 for guest and free, 3 for Pro. Max 1 for guest and free, 14 for Pro. | |
| limit | No | Max results per bucket, released_recent and upcoming each capped independently (default 20). Max 20 for guest and free, 50 for Pro. | |
| major_only | No | Restrict to the 8 largest economies (United States, Euro Area, United Kingdom, Japan, China, Germany, France, Canada). Default false returns all countries. | |
| lookback_days | No | Look-back window in days for recently-released events (default 2). Max 2 for guest and free, 7 for Pro. Actual values arrive with about a 1-day reporting lag, so a same-day-only window misses real releases -- keep this at 2+ to reliably see them. | |
| key_events_only | No | Restrict to the small subset of event types that reliably move markets on their own: interest rate/rate decisions, CPI, GDP, and headline Non-Farm Payrolls. Default false returns every event matching the broader base filter (also includes PMI, unemployment, other payrolls components, retail sales, ADP, inflation). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent, non-destructive annotations, the description discloses important behavior: released items always carry a real actual value, diff is arithmetic rather than a beat/miss judgment, upcoming items never carry actual, and limit truncation preserves major-economy prints. It also explains guest/free versus Pro caps and the capping response with pro_unlocks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well front-loaded and organized around the two buckets, flags, and tier limits. Some tier and parameter details repeat the schema, but most of the length carries non-obvious semantic distinctions that matter for correct use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, five optional parameters, rich annotations, and an output schema, the description is complete enough to call it correctly. It covers bucket semantics, actual/diff meaning, key_event interpretation, sorting/truncation behavior, and tier-based capping.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema, especially that limit applies independently per bucket and that truncation should not drop major-economy releases, and it reinforces the lag rationale for lookback_days and the event-type meaning of key_events_only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: upcoming and recently released macro/economic events such as rate decisions, CPI, GDP, PMI, and payrolls. It clearly distinguishes this from company-level siblings like get_earnings_calendar by framing the tool as macro/economic events, and it explains the two returned buckets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context by defining the released_recent and upcoming buckets, and it explains when to use filters such as key_events_only=true and major_only=true. It does not explicitly name alternative sibling tools or state when not to use this one, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical daily indicator snapshots for a stock - ideal for charting and trend detection.
Returns up to days days of data (max 730, default 90) from the stock_indicator_snapshots
collection which is populated daily by the indicator pipeline.
Every snapshot row contains:
recorded_at: ISO date string
price: closing price at snapshot time
rsi: RSI(14) value (0-100)
macd_histogram: MACD histogram value (positive = upward momentum)
bb_pct: Bollinger Band % position (0 = at lower, 100 = at upper band)
sma20 / sma200: 20-day and 200-day simple moving averages
With full=true, each row also gets:
williams_r: Williams %R (0 to -100; >-20 overbought, <-80 oversold)
ultimate_osc: Ultimate Oscillator (0-100; >70 overbought, <30 oversold)
vix_fix_value: Williams VIX Fix synthetic fear gauge (higher = more fear)
williams_ad_trend: Accumulation/Distribution trend (rising/falling/flat)
td_signal: DeMark TD Sequential count, named for the move that is running out (DOWNTREND_EXHAUSTION_SETUP / UPTREND_EXHAUSTION_SETUP / DOWNTREND_EXHAUSTION_COUNTDOWN / UPTREND_EXHAUSTION_COUNTDOWN / null)
td_phase: DeMark phase (setup_active/setup_complete/countdown_active/countdown_done/null)
analyst_rating: analyst consensus (buy/outperform/hold/underperform/sell or null)
analyst_target: mean analyst price target or null
Returns {} if fewer than 3 snapshots found. Pro tier only. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days of historical daily indicator snapshots to return (max 730, default 90). Returns {} if fewer than 3 snapshots are found in the window. | |
| full | No | False (default) returns only recorded_at/price/rsi/macd_histogram/bb_pct/sma20/sma200 per day - enough for most charting/trend use. True adds the specialized indicators (williams_r, ultimate_osc, vix_fix_value, williams_ad_trend, td_signal, td_phase) plus analyst_rating/analyst_target, which barely change day to day and roughly double response size over a long window. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 730/90 limits, the empty-object return when fewer than 3 snapshots exist, the Pro-tier requirement, and the fact that the pipeline populates it daily.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and constraints are front-loaded, but the long field-by-field enumeration of return values duplicates the output schema, which already exists, so a significant portion of the text does not earn its place against structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a pro-tier, read-only snapshot tool with a rich output schema, the description covers the operational essentials an agent needs: the empty-result condition, the size cap, the cost of full=true, and the daily refresh cadence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so days, full and symbol are already documented in the schema; the description largely restates those semantics (max 730, default 90, what full adds). Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Historical daily indicator snapshots for a stock') and frames the use case ('charting and trend detection'). It is distinguishable from price-history siblings like get_stock_history, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'ideal for charting and trend detection' implies a context but gives no when-to-use vs when-not guidance and does not tell the agent how this differs from get_stock_history or get_signals, which an agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get insider transactions (regulatory insider filings for the US and several European markets) and, on Pro, the AI read plus institutional holdings for a stock.
Every tier (guest/free/pro) gets the filing facts: insider_buys and insider_sells over the window (echoed as window_days), transactions (the individual rows behind those counts, newest first, each with date/name/role/type/shares/price/value), summary (a one-line factual readout computed from those same rows -- counts, dollar totals, date range -- so it can never disagree with them), source/source_name (which filing feed was used), and updated_at (when the filings were last fetched).
Free/guest: a 90-day window (a larger days is capped at 90, see
days_note), the 5 most recent rows (transactions_note says how many more
there are), and pro_unlocks describing what Pro adds. No AI fields and no
institutional holders.
Pro: days up to 365, up to 50 rows, plus signal (POSITIVE/NEGATIVE/
NEUTRAL etc.), signal_score (0-100, higher = stronger/more notable - the
exact same field, formula, scale and bands as get_signals()'s
signal_score) with signal_score_band, insider_signal/inst_signal,
ai_commentary (a separately-generated AI narrative on its own refresh
cadence, with ai_commentary_as_of - it can lag the transactions; trust
summary/the rows if they disagree), top_holders (a union of multiple
data sources, up to 15, each with name/shares/pct_held/sources/
share_counts_by_source - the last two show which source(s) contributed
to a merged row and each one's own reported share count), holder_count_
divergence (null unless every matched holder disagrees by the same
systemic multiplier across sources - e.g. an unrecorded reverse split -
a signal top_holders.shares may be unreliable for this symbol),
inst_ownership (0-100%), and total_holders.
For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Insider-transaction window in days (default 90, max 365 on Pro; free/guest calls are capped at 90). Applies to transactions, insider_buys and insider_sells. | |
| symbol | Yes | Stock ticker symbol to fetch insider-filing and institutional-holdings activity for. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (read-only, idempotent, non-destructive), and the description adds substantial context beyond them: free/guest caps at 90 days and 5 rows, ai_commentary runs on a separate cadence and 'can lag the transactions', and holder_count_divergence is null unless all matched holders disagree by a systemic multiplier that may make top_holders.shares unreliable. It also explains that summary is computed from the same rows so it cannot disagree.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core capability and tier split are front-loaded in the first sentence, and the tier breakdown is logically ordered. It is dense and somewhat over-packed with parenthetical asides (e.g. 'echoed as window_days', footnote pointers like days_note/transactions_note), but given the tool's complexity most sentences carry real information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema that already documents return fields, the description fully characterizes what varies by tier and which fields are conditional (signal, holders, divergence). An agent has everything needed to call it correctly and interpret results; nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: `days` is capped at 90 for free/guest (referencing days_note) and extends to 365 on Pro, and it clarifies that the value is echoed back as window_days. That is genuine added meaning over the schema's own text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Get insider transactions... regulatory insider filings') and scopes it geographically (US and several European markets). It also explicitly ties its signal_score to get_signals()'s field, letting an agent distinguish it from that sibling without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear tier-based context (guest/free gets a 90-day window with no AI or holders; Pro gets 365 days, signals, commentary, and holders) so an agent understands what it will receive. However it never states when to prefer this tool over siblings like get_signals or get_stock, and offers no exclusions or routing criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combined AI market assessment: macro regime + market outlook in a single call. Refreshed ~4x/day, weekdays only, during market hours (~2h apart) - dead overnight and on weekends, not a continuous 4-hourly cadence. Check regime_stale/outlook_stale below (which already account for the weekend gap) before treating either as current, especially on a Monday morning.
Two distinct perspectives returned together:
REGIME (RISK_OFF/CAUTIOUS/NEUTRAL/AGGRESSIVE): answers "how much equity risk to take" → use for position sizing and asset allocation decisions
OUTLOOK (POSITIVE/NEUTRAL/NEGATIVE): answers "which direction and sectors to trade" → use for sector preference and directional bias
Both share the same pipeline run so they are always in sync.
history_count: include last N prior assessments for each (0-3, default 0)
regime_*: risk posture fields - regime, risk_appetite_score (0-100 re-expression of regime, higher = current conditions support more risk-taking), regime_bias, regime_bias_note (plain sentence on whether current conditions favor long or short setups, or neither), regime_confidence, regime_rationale, key_risks, watch_for, vix_at_assessment, regime_updated_at, regime_stale
macro_score / regime_strength: macro_score is a real, continuous 0-100 read on how
much risk the current environment supports (0=RISK_OFF/capital preservation,
100=AGGRESSIVE/risk-on) - the same underlying number regime buckets into 4
discrete categories, blending arithmetic inputs (VIX level, breadth
oversold/overbought skew, SKEW-vs-VIX divergence, TD-exhaustion ratio) with
regime_strength, the AI's own 1-10 read of regime conviction. Distinct from
risk_appetite_score (a coarse 4-value lookup on regime alone) - macro_score is
the real underlying number. Null on a pre-2026-08-26 assessment that predates
this field. Not a call on any one stock.
macro_score_trend: {change_7d, change_30d, direction} - whether macro_score itself is improving/deteriorating/stable over the trailing 7/30 days, computed automatically (no history_count needed). A bare 33 doesn't tell you whether the environment is getting worse or just stabilized after a worse reading; this does. Either leg is null without enough history yet.
regime_stale / outlook_stale: true if that assessment is >72h old (the pipeline runs weekdays only, so a normal Fri→Mon gap does not trip this - only a genuinely broken/stuck pipeline does). null if the timestamp itself is missing.
indicators.macro_data: macro data (yield curve, Fed funds, cpi_index, unemployment, M2)
indicators.volatility_term_structure: VIX spot/3M/6M term structure + contango signal
indicators.market_sentiment: Fear & Greed index value and label
market_context: price/RSI/SMA200/perf snapshot of SPY/QQQ/IWM/TLT/GLD/VIX/TNX + sectors NOTE: point-in-time snapshot recorded when AI ran - not current prices (use get_market_pulse for the latest)
outlook_*: directional fields - outlook, outlook_conviction, equity_view, preferred_sectors, avoided_sectors, catalyst, outlook_key_risk, outlook_rationale, outlook_updated_at, outlook_stale
Pro tier only - AI pipeline cost attached. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| history_count | No | Include the last N prior assessments for each of regime and outlook (0-3, default 0). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/idempotent safety, yet the description adds substantial non-structured context: a ~4x/day weekday-only refresh cadence with dead weekends, the exact >72h staleness rule and why a Fri→Mon gap does not trip it, null semantics for missing timestamps, the Pro-tier cost attachment, and the caveat that market_context is a frozen snapshot. These are exactly the operational facts an agent needs and none are derivable from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Content is front-loaded: cadence and staleness caveats come before field enumeration, and the regime/outlook split is visually separated. It is long and has minor redundancy — staleness is explained once in the header and again in the field list, and macro_score is re-explained across two bullets — which costs it a point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity composite tool with an output schema, the description covers cadence, staleness, tier gating, field-level meaning including the subtle macro_score vs risk_appetite_score distinction, and honest disclaimers. An agent can call and interpret this tool without opening the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one optional parameter at 100% schema coverage, the baseline would be 3; the description earns an extra point by restating the 0-3/default-0 bound and, more usefully, clarifying that macro_score_trend computes automatically without history_count — a non-obvious interaction the schema cannot express.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Combined AI market assessment: macro regime + market outlook') and immediately splits it into two named perspectives with distinct decision uses. It also distinguishes itself from get_market_pulse by explicitly scoping market_context as a point-in-time snapshot rather than live prices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing for each half — regime for position sizing/allocation, outlook for sector preference and directional bias — and tells the agent to check regime_stale/outlook_stale before treating values as current. It names one sibling alternative (get_market_pulse for latest prices) but offers no guidance on when not to call this tool at all (e.g., non-Pro tier, or topics better served by get_signals/get_sector_intelligence).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top market movers from the Stocklake universe - gainers, losers, most active.
category: "gainers" | "losers" | "most_active" | "all" (default "all" = all 3 categories)
limit: results per category (default 10, max 20). Each returned stock counts as one call toward your daily limit - a symbol appearing in more than one category (e.g. both "gainers" and "most_active") counts once per category it appears in.
min_market_cap_b: filter to stocks above this market cap in billions of US dollars (e.g. 1.0 = $1B+), compared against market_cap_usd
Returns per stock: symbol, name, sector, price, change_pct, volume, rsi, market_cap (listing currency), market_cap_usd, currency, analyst_rating, atr_pct (atr_pct omitted when the underlying volatility reading is missing or corrupted). Available to all tiers.
Pro tier adds the minimum AI-narrative slice (ai_verdict, ai_headline, ai_score 0-100, ai_score_band) - precomputed, no extra AI cost. A big mover's price/volume/RSI alone doesn't say whether the move matters; the one-line headline does. For the full research bundle on any one mover, call get_stock_research(symbol).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per category (default 10, max 20). Each returned stock counts as one call toward your daily limit - a symbol appearing in more than one category (e.g. both "gainers" and "most_active") counts once per category it appears in. | |
| category | No | Which movers category to return: "gainers" | "losers" | "most_active" | "all" (default "all" = all 3 categories). | all |
| min_market_cap_b | No | Filter to stocks above this market cap in billions of US dollars, e.g. 1.0 = $1B+ (compared against market_cap_usd). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that each returned stock consumes one call against the daily limit (and that cross-category duplicates count once per category), tier gating (all tiers vs Pro-only AI fields), and a data-quality caveat that atr_pct is omitted when the volatility reading is missing or corrupted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the one-line definition followed by a well-structured bulleted parameter list; the Pro-tier paragraph slightly over-explains ('A big mover's price/volume/RSI alone doesn't say whether the move matters') but each element is relevant. Some return-field enumeration duplicates the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param, zero-required read tool with an output schema, the description covers everything an agent needs: category values and defaults, limits, market-cap filtering semantics, quota accounting, tier availability, and a hand-off to get_stock_research.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the same quota/default/cap explanation appears verbatim in the schema for limit, category, and min_market_cap_b, so the description adds no semantics the schema does not already carry. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb+resource+scope ('Top market movers from the Stocklake universe - gainers, losers, most active') and enumerates the exact category values, which cleanly separates it from siblings like get_screener, get_market_pulse, or get_stocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames the scenario (surfacing big gainers/losers/most-active) and routes to the right next step for depth: 'For the full research bundle on any one mover, call get_stock_research(symbol).' It does not, however, state when to prefer a sibling scanner (e.g. get_screener) or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Market health snapshot in a single call. Aggregates key market indicators without requiring multiple tool calls. No AI cost. Index and bond/commodity prices are the latest available, delayed about 15 minutes; vix, fear_greed and breadth come from the latest market snapshot (see updated_at).
Returns:
vix: VIX level (a number) as of that snapshot
fear_greed: {value (0-100), description ("extreme fear" | "fear" | "neutral" | "greed" | "extreme greed"), last_update}
breadth: market-wide RSI distribution - oversold_pct, overbought_pct, neutral_pct (with their counts), universe_size
indices: spy, qqq, iwm, each {price, change_pct (today, in percent), rsi}
bonds_commodities: tlt (long-duration bonds), gld (gold), same shape as indices
updated_at: when the vix/breadth/fear_greed snapshot was last recorded Available to all tiers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely non-structured facts: ~15-minute delay on index and bond/commodity prices, snapshot-sourced vix/fear_greed/breadth, no AI cost, and universal tier availability. Data freshness and cost are exactly the traits an agent cannot infer from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded well: purpose, then cost/freshness, then detail. However, roughly half the text is a bulleted return-value enumeration that substantially duplicates the existing output schema, which is padding against this rubric.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Freshness semantics, snapshot source for derived fields, tier availability, and cost are all covered, which is what an agent needs to decide whether the data is stale or accessible. The return-value block is redundant given the output schema, but nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema is closed, so there is nothing to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter guidance for a parameterless call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb+resource framing ('Market health snapshot in a single call') and states it aggregates indicators that would otherwise need multiple calls, which separates it from per-stock siblings like get_stock. It does not distinguish itself from the closest neighbor, get_market_assessment, so an agent still has to guess between those two.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'without requiring multiple tool calls' implies the aggregation use case, and 'Available to all tiers' removes an access precondition. But there is no explicit when-to-use vs get_market_assessment / get_market_movers / get_signals, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most notable recent news across all tracked stocks: a market-wide briefing. Unlike get_stock_news (one symbol), this scans every tracked stock and returns articles ranked by signal_score, newest first within each score.
Use this for:
Morning briefing: "what happened in the market this week?"
Catalyst scanning: "what news is driving moves right now?"
Event monitoring: "which stocks have high-impact news today?"
min_signal_score: minimum signal_score (0-100, default 60).
days: look-back window in days (default 3, max 10).
limit: max articles returned (default 10, max 25).
Per article: symbol, title, published_at, ai_sentiment, ai_summary, signal_score (0-100), signal_score_band (Weak/Moderate/Strong/Very Strong).
signal_score is the symbol's current news-based signal score when one was raised in the last 90 days (the same number get_stock_news() and get_signals() report), otherwise a score computed from the article's own classification. It is always a single number.
collapsed_count: present when several articles reported the same event;
only the highest-ranked one is returned and this says how many were
merged into it. limit counts distinct events.
Articles are published by third parties; titles and summaries describe what those articles say. Requires a Pro account. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days (default 3, max 10). | |
| limit | No | Max articles returned (default 10, max 25). | |
| min_signal_score | No | Minimum signal_score, 0-100 (default 60). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds valuable context beyond that: a Pro account requirement, third-party content provenance ('articles are published by third parties'), and a disclaimer, plus dedup behavior via collapsed_count.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded summary sentence followed by clearly sectioned use cases and field notes; efficient overall, though the parameter bullets partly duplicate the schema and add some length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers routing, auth requirement, output field meanings, dedup semantics, and content provenance; an output schema exists so return-value detail is not strictly required. Nothing essential for correct invocation is missing, though the signal_score discussion overlaps with structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters; the description's parameter bullets restate defaults and ranges (0-100, default 60, max 10/25) without adding syntax or format detail. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Most notable recent news across all tracked stocks: a market-wide briefing') and explicitly contrasts with the sibling get_stock_news ('one symbol'), so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides three concrete when-to-use scenarios with example queries (morning briefing, catalyst scanning, event monitoring) and explicitly names the alternative tool get_stock_news along with the condition (one symbol) that routes to it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter and rank stocks from the Stocklake universe - fundamentals, technicals, and AI signals in one tool.
Parameters:
sector: e.g. "Technology", "Healthcare", "Financial Services"
country: e.g. "United States", "Germany"
min_rsi / max_rsi: exact RSI bounds (e.g. max_rsi=30 = oversold, min_rsi=70 = overbought)
sma_trend: "above_200" (price above 200-day MA) | "below_200"
macd_signal: "positive" (MACD line above signal) | "negative"
min_perf_1d / max_perf_1d: 1-day performance % (e.g. min_perf_1d=2.0 = up 2%+ today)
min_volume: minimum daily volume (e.g. 1000000)
min_market_cap_b / max_market_cap_b: market cap in billions of US dollars, compared against market_cap_usd (stocks with no FX rate for their currency are excluded when either bound is set)
max_pe_forward: maximum forward P/E (e.g. 20 = value screen)
analyst_rating: "strong_buy" | "buy" | "hold" | "sell" | "strong_sell"
min_ai_score: minimum AI score 0-100 (pro tier only - silently ignored for free). Gates on the AI research composite ai_score - same 0-100 scale and bands as signal_score, but a separate score (per-stock AI summary strength, not a directional signal). Renamed 2026-08-24 from the retired 0-10 min_flag_score - the raw flag_score field it used to gate on is no longer part of this fleet's public vocabulary at all (see ai_score below).
preset: "oversold" | "overbought" | "momentum" | "high_conviction" (pro only) oversold = RSI≤35 + above SMA200 · overbought = RSI≥65 momentum = RSI 50-70, above SMA200, up 0.5%+ today · high_conviction = ai_score≥70
sort_by: "market_cap" | "rsi" | "perf_1d" | "volume" | "analyst_rating" | "rating" | "ai_score" (pro). Defaults to "market_cap", except the "high_conviction" preset defaults to "ai_score" (the dimension it's filtering by) unless you explicitly pass a different sort_by.
sort_dir: "asc" | "desc" (default "desc")
limit: 1-25 (default 20). Each returned stock counts as one call toward your daily limit.
Returns: { count, preset, filters, results[] } - each result includes symbol, name, sector, industry, country, price, change_pct, volume, market_cap, market_cap_usd, currency, pe_forward, rsi, macd_signal, sma200_trend, analyst_rating. market_cap is in the listing's own currency (the currency field; for a listing quoted in pence or cents, GBp/ZAc/ILA, it is in the major unit and market_cap_currency says which); market_cap_usd is converted to US dollars and is what the market_cap sort and cap filters use. Pro tier adds rating (0-10 composite score) + ai_verdict + ai_headline + ai_score (0-100) + ai_score_band to every result row (the headline is the "why" - a bare verdict alone isn't enough to act on), enables min_ai_score filter, high_conviction preset, and sorting by rating/ai_score (sort_by silently falls back to market_cap on free/guest for both). All other filters available to all tiers. For the full research bundle on any one result, call get_stock_research(symbol).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return, 1-25 (default 20). Each returned stock counts as one call toward your daily limit. | |
| preset | No | "oversold" | "overbought" | "momentum" | "high_conviction" (pro only). oversold = RSI<=35 + above SMA200; overbought = RSI>=65; momentum = RSI 50-70, above SMA200, up 0.5%+ today; high_conviction = ai_score>=70. | |
| sector | No | Filter by sector, e.g. "Technology", "Healthcare", "Financial Services". | |
| country | No | Filter by country, e.g. "United States", "Germany". | |
| max_rsi | No | Maximum RSI bound (e.g. max_rsi=30 = oversold). | |
| min_rsi | No | Minimum RSI bound (e.g. min_rsi=70 = overbought). | |
| sort_by | No | "market_cap" | "rsi" | "perf_1d" | "volume" | "analyst_rating" | "rating" | "ai_score" (pro). Defaults to "market_cap", except the "high_conviction" preset defaults to "ai_score" (the dimension it's filtering by) unless you explicitly pass a different sort_by. Sorting by rating/ai_score silently falls back to market_cap on free/guest. | |
| sort_dir | No | Sort direction: "asc" | "desc" (default "desc"). | desc |
| sma_trend | No | "above_200" (price above 200-day MA) | "below_200". | |
| min_volume | No | Minimum daily volume, e.g. 1000000. | |
| macd_signal | No | "positive" (MACD line above signal) | "negative". | |
| max_perf_1d | No | Maximum 1-day performance %. | |
| min_perf_1d | No | Minimum 1-day performance %, e.g. min_perf_1d=2.0 = up 2%+ today. | |
| min_ai_score | No | Minimum AI score, 0-100 - pro tier only (silently ignored for free). Gates on the AI research composite ai_score, same 0-100 scale and bands as signal_score but a separate score (per-stock AI summary strength, not a directional signal). | |
| analyst_rating | No | Filter by analyst consensus rating: "strong_buy" | "buy" | "hold" | "sell" | "strong_sell". | |
| max_pe_forward | No | Maximum forward P/E, e.g. 20 for a value screen. | |
| max_market_cap_b | No | Maximum market cap in billions of US dollars (compared against market_cap_usd). | |
| min_market_cap_b | No | Minimum market cap in billions of US dollars (compared against market_cap_usd, so non-USD listings are converted first). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only safety, but the description adds substantial non-obvious behavior: min_ai_score is "silently ignored for free", sort_by "silently falls back to market_cap on free/guest", each returned stock counts against the daily call limit, and cap filters exclude stocks with no FX rate. It also discloses that preset choice changes the default sort dimension, which an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded and scannable as a parameter list, but it carries dead weight: the min_ai_score entry includes changelog archaeology ("Renamed 2026-08-24 from the retired 0-10 min_flag_score...") that no agent needs to invoke the tool, and a long Returns section despite an output schema existing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter screener with tier-gated behavior, the description covers everything material: filter semantics, defaults, preset interactions, tier fallbacks, currency handling, call-cost implications, and cross-tool routing. Combined with the output schema and annotations, an agent has no ambiguity left before calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and much of the parameter list restates schema text. The description earns above baseline by clarifying semantics the schema leaves ambiguous: the market_cap vs market_cap_usd distinction, the market_cap_currency field for GBp/ZAc/ILA listings, the high_conviction sort_by default, and the FX-driven exclusion rule for cap bounds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ("Filter and rank stocks from the Stocklake universe") and enumerates the three data families it screens on (fundamentals, technicals, AI signals). It is clearly distinguishable from screening siblings like get_signals or get_market_movers, though it never explicitly names a sibling it supersedes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage context through worked examples ("max_rsi=30 = oversold", "e.g. 20 = value screen") and named presets that encode common screens, plus a clear handoff: "For the full research bundle on any one result, call get_stock_research(symbol)". It lacks an explicit negative case (e.g. when to use get_stocks instead of screening), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI-assessed sector intelligence: signal, cycle stage, rotation signal, drivers, alerts, and computed statistics per sector (RSI distribution, breadth, performance 1W/1M, top/bottom movers, historical percentiles). Pass a sector name for a single sector, or omit the parameter (or pass None) to get the latest assessment for all 11 sectors - the all-sectors call doubles as the rotation view: use sort_by_strength to rank LEADING-first for finding leading vs lagging sectors, and history_count for prior signal states per sector.
sort_by_strength: sort all-sectors output LEADING→LAGGING instead of alphabetical (all-sectors call only; ignored when a single sector is requested)
history_count: include last N prior signal states per sector, 0-3 (default 0; all-sectors call only)
sector_score / strength_score: sector_score is a real, continuous 0-100 read on
this sector's relative strength/leadership (0=LAGGING, 100=LEADING) - the same
underlying number signal buckets into 5 discrete categories, blending
arithmetic inputs (RSI/perf percentiles, top-5 concentration, SMA200 breadth)
with strength_score, the AI's own 1-10 read. Comparable across all 11 sectors on
one absolute scale (not per-sector-relative). Null on a pre-2026-08-26 assessment
that predates this field. Not a buy/sell call.
sector_score_trend: {change_7d, change_30d, direction} - whether this sector's score is improving/deteriorating/stable over the trailing 7/30 days, computed automatically. Single-sector calls only - this is the only trend view available for one sector at all (history_count only applies to the all-sectors call). Two sectors both reading STRONG/68 can be in opposite motion; this tells them apart. Either leg is null without enough history yet.
Refreshed ~4x/day, weekdays only, during market hours (~2h apart) - dead overnight and on weekends, not a continuous 4-hourly cadence. Check the returned updated_at before treating this as current, especially on a Monday morning or after a holiday. Available to pro tier only (AI pipeline costs). For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| sector | No | Pass a sector name for a single sector's assessment, or omit (None) to get the latest assessment for all 11 sectors at once - the all-sectors call doubles as the rotation view. | |
| history_count | No | Include the last N prior signal states per sector, 0-3 (default 0). Only applies to the all-sectors call. | |
| sort_by_strength | No | Sort all-sectors output LEADING→LAGGING instead of alphabetical, for finding leading vs lagging sectors. Only applies to the all-sectors call; ignored when a single sector is requested. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (which already declare readOnly/idempotent/non-destructive) with refresh cadence ('~4x/day, weekdays only, dead overnight and on weekends'), a staleness warning to check updated_at, a pro-tier access restriction, and null semantics for assessments predating 2026-08-26. It also frames sector_score as 'not a buy/sell call', setting expectations about interpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then a tight bulleted parameter section, then operational caveats — a good structure. It is long and carries minor redundancy ('For informational purposes only. Not financial advice.' alongside 'Not a buy/sell call'), and the sector_score paragraph could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three optional parameters, an output schema, and rich annotations, the description covers everything an agent needs: mode selection, parameter interactions, data freshness, tier gating, and null/edge cases. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is already 100%, so the schema documents all three parameters; the description largely restates their behavior (all-sectors-only, ignored for single sector). Where it adds real value is the distinction between sector_score (continuous 0-100, absolute cross-sector scale) and strength_score (AI's 1-10 read), plus the trend object shape — though those are output fields rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('AI-assessed sector intelligence') and enumerates exactly what it returns (signal, cycle stage, rotation signal, drivers, alerts, computed stats), so an agent can distinguish it from get_market_assessment or get_signals without opening a schema. The dual single-sector/all-sectors scope is stated up front.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to pass a sector name for one sector and omit/None for all 11, and names the intended use of each mode ('the all-sectors call doubles as the rotation view'). It also states the exact conditions for sort_by_strength, history_count, and sector_score_trend, including that the trend view exists only for single-sector calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI-screened stock signals recently surfaced by the Stocklake pipeline - sourced from news analysis, sector screening, and sentiment signals.
Shows what the pipeline noticed in the last 24 hours (falling back to the most recent signals regardless of age if nothing has fired in that window
see window in the response). Signals stay listed for their recency window
even after they expire.
This is the market-wide queue across all stocks. For the history of one stock (news, filings, insider, earnings, analyst events and its setups over 90 days) use get_stock_activity.
Parameters:
direction: "POSITIVE" | "NEGATIVE" | "NEUTRAL" (default: all). NEUTRAL
covers both a flat/undecided read AND a genuinely two-sided idea (real
opposing bull/bear theses on the same symbol) - in the latter case
signal_score is the STRONGER of the two sides (see signal_score below),
so a high score alongside NEUTRAL means "real conviction here, just no
directional consensus," not "nothing going on." The two-sided detail is
in rationale.
min_signal_score: minimum signal score 0-100 (default 60) - mainly how stretched the stock is in the signal's direction. This is the field to filter on. Always compared against a single number, including for NEUTRAL/two-sided ideas - a result is never returned below your threshold on both sides.
source: filter by signal source - "news" | "screener" | "sentiment" (default: all)
limit: max results to return (default 25, max 50). Each returned signal counts as one call toward your daily limit.
Returns:
count: number of signals returned
window: "24h" (fresh activity found) or a fallback note when the last 24h had nothing and the response instead shows the most recent signals overall
signals[]: each with symbol, direction, signal_score (0-100), signal_score_band (human-readable label - "Weak"/"Moderate"/"Strong"/"Very Strong"), source, rationale, expires, flagged_at
Pro tier only - AI pipeline cost attached. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 25, max 50). Each returned signal counts as one call toward your daily limit. | |
| source | No | Filter by signal source: "news" | "screener" | "sentiment" (default: all). | |
| direction | No | Filter by direction: "POSITIVE" | "NEGATIVE" | "NEUTRAL" (default: all). NEUTRAL covers both a flat/undecided read and a genuinely two-sided idea (see signal_score below). | |
| min_signal_score | No | Minimum signal score, 0-100 (default 60) - mainly how stretched the stock is in the signal's direction. This is the field to filter on. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 24h recency window with a documented fallback to older signals, the fact that expired signals remain listed for their window, a per-result cost against a daily call limit, and a Pro-tier gating note. These are exactly the operational facts an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and routing, then clearly sectioned into Parameters and Returns, with zero wasted sentences. Slight redundancy: the limit and source parameter lines restate the schema descriptions almost verbatim, adding length without new meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, four-param, zero-required list tool with an output schema, the description covers everything material: scope, recency semantics, fallback behavior, cost, tier gating, and the tricky NEUTRAL scoring case. Nothing an agent needs to invoke or interpret it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what NEUTRAL actually means (flat read vs. genuinely two-sided thesis, with signal_score being the stronger side), which the schema only gestures at with 'see signal_score below'. It also clarifies that min_signal_score is compared against a single number even for two-sided ideas, resolving a real filtering ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (AI-screened stock signals from the Stocklake pipeline) plus its provenance (news analysis, sector screening, sentiment). It also explicitly distinguishes itself from the nearest sibling: 'This is the market-wide queue across all stocks. For the history of one stock ... use get_stock_activity.' An agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative tool and the condition that selects it (single-stock history vs market-wide queue), which is the main routing ambiguity among 20+ siblings. It does not address other plausible-looking siblings such as get_screener or get_news_feed, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price, fundamentals, technical indicators, and company profile for a stock. Returns all data needed to understand a stock in a single call.
Key fields:
price, change_pct, prev_close, week52_high/low, volume, avg_volume
market_cap, enterprise_value, beta
pe_trailing, pe_forward, price_to_book, dividend_yield, dividend_rate
debt_to_equity, profit_margins, operating_margins, gross_margins, return_on_equity, free_cashflow
revenue_growth, earnings_growth, revenue_ttm, gross_profit_ttm
analyst_rating: "strong_buy"|"buy"|"hold"|"sell"|"strong_sell" (analyst consensus)
analyst_rating_score: 1.0-5.0 mean analyst recommendation (1=strong_buy, 5=strong_sell)
analyst_target: mean analyst price target
analyst_count: number of analyst opinions
indicators: raw RSI, MACD, Bollinger Bands, SMA20/SMA200 (the canonical 50/200-day averages -- no separate top-level ma_50/ma_200 field), EMA20/EMA200, ATR
description: company business description
website, employees, officers (top 5: name, title, total_pay)
updated_at: last data sync timestamp Available to all tiers (raw indicator numbers, no interpretation). This basic six (RSI/MACD/Bollinger/SMA/EMA/ATR) is standard, widely-available technical analysis.
Pro tier also unlocks the specialized indicators inside the SAME indicators block:
williams_r, ultimate_osc, vix_fix, williams_ad (the Larry Williams family),
td_sequential (DeMark), elliott_wave, adx {adx, plus_di, minus_di}, ichimoku
{tenkan, kijun, cloud_top, cloud_bot, above_cloud, below_cloud}, squeeze
{squeeze_on, hist}, and rs_rank (relative-strength rank 1-99, stocks only: the past
year's return with the latest quarter counted double, ranked against every tracked
stock; 99 = strongest; absent with under a year of history). These are omitted
entirely from the free/guest response, not merely unlabeled; free/guest calls get
indicators with only the basic six populated.
Pro tier adds four interpreted blocks computed from the same indicators, no extra AI cost, plus a minimum AI-narrative slice - all five below are precomputed, none cost an AI call on your request:
ai_verdict / ai_headline / ai_score / ai_score_band: the minimum useful AI-narrative slice, shared by every pro-tier stock-returning tool. A bare verdict alone isn't actionable (e.g. negative while up 8% on the day with a strong_buy analyst rating is genuinely ambiguous) - the one-line headline is the "why", ai_score is the 0-100 composite (same scale/band convention as get_signals' signal_score, distinct pipeline). For the full text (summary/key_points/risks/near_term/longer_term) and cross-source news/insider context, call get_stock_research(symbol) instead - that's the only tool with the complete bundle.
ai_score (0-100) / ai_score_band (Weak/Moderate/Strong/Very Strong): the AI research composite score, on the same 0-100 scale and band boundaries as get_signals()'s signal_score - but a separate score, never the same number for the same symbol by coincidence alone.
rating: {score 0-10, direction POSITIVE/NEUTRAL/NEGATIVE, signals per-indicator breakdown}
composite technical score
signals: flat labeled signals (rsi/macd/bollinger/sma200/sma50/williams_r/ultimate_osc/ vix_fix/williams_ad/td_sequential/elliott_wave, each with a value + plain-English label)
same indicators as 'indicators', pre-interpreted for programmatic use without parsing raw numbers
stance_signals: unified list of per-source directional calls (technical rating, AI summary near_term/longer_term, insider/institutional sentiment, analyst consensus, active screener signals) - each entry {stance POSITIVE/NEGATIVE/NEUTRAL, conviction 0-10, horizon INTRADAY/SWING/POSITION/LONG_TERM, edge_quality PROVEN/OBSERVATION/UNKNOWN (per-source signal_backtest track record), source, raw_label, as_of}. Same canonical shape used on the stock detail page - a source with missing/stale data is simply omitted, not nulled out.
relative_strength: {windows: {5d/20d/60d/120d/12m -> {stock_return_pct, rs_vs_spy, rs_vs_qqq, rs_vs_sector}}, verdict: one-line plain-language read (e.g. "Laggard - weak near- and long-term")}
stock's own return minus each benchmark's return (percentage points, not a ratio) per window. rs_vs_sector uses the stock's GICS sector SPDR ETF (Vanguard backup if the primary lacks history); omitted for stocks with no resolvable sector (crypto, FX, indices). Windows/ benchmarks with insufficient history are omitted rather than null. null if not precomputed yet.
market_risk: {beta_spy_1y, corr_spy_1y} - 1-year daily-return beta and correlation vs SPY. Distinct from quote.beta (a longer-window beta) - this is computed from the same daily bars as relative_strength. Both fields null if not yet precomputed for this symbol (populates on the next scheduled indicators run).
forensic_scores: {altman_z, piotroski_f, beneish_m, computed_at} - three classic forensic-
accounting formulas (Altman 1968 bankruptcy-risk, Piotroski 2000 fundamental-strength,
Beneish 1999 earnings-manipulation-likelihood), computed from balance sheet/income
statement/cash flow data, refreshed on each company's own filing cadence (roughly annual).
Each sub-block is {score, note, ...} - altman_z adds zone (safe/grey/distress),
piotroski_f adds strength (strong/moderate/weak, 0-9 scale), beneish_m adds
likely_manipulator (bool, score > -1.78). note explains what the score measures and
its known caveats (e.g. Altman Z is not meaningful for banks/insurers and can flag REITs/
client-float businesses as "distress" by design) - always read alongside the score, not in
isolation. score: null means genuinely not computable for this company (common for
financial-sector names), not an error. No trading signal is derived from these scores
anywhere in this API today - treat as raw accounting-model output for your own research.
sector_context: where this stock's fundamentals sit versus the other tracked equities in
its own sector - {sector, revenue_growth, gross_margin, operating_margin, as_of}, each
metric {value, sector_median, percentile 0-100, n}. Purely descriptive positioning (e.g.
"revenue growth is in the 80th percentile of its sector"), no interpretation or direction.
A metric is omitted when the stock has no value for it or the sector has fewer than 15
peers with data; the whole block is omitted when nothing is computable. Baseline refreshed
daily; sectors are pooled globally across all tracked equities.
get_stock also returns trend: {period: "quarterly", points: [{period_end, revenue_growth /
gross_margin / operating_margin: {value, sector_median, n}}]}, oldest first - the same three
metrics for the last few quarters (revenue_growth is year-over-year) beside the sector
median for each quarter, so you can see whether the stock is gaining or losing ground on its
peers. Off-cycle fiscal quarters are matched to the nearest calendar quarter. A quarter or
metric is left out where either side lacks data. get_stocks omits trend to keep batch rows
small.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback (e.g. "Apple") when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the readOnly/idempotent annotations: discloses tier gating (Pro-only indicators are omitted entirely from free/guest responses, not merely unlabeled), null/omission semantics ('omitted rather than null', 'populates on the next scheduled indicators run'), refresh cadence (forensic scores on filing cadence, sector baseline daily), and caveats like Altman Z not being meaningful for banks. This is exactly the context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Roughly 700 words for a one-parameter read tool, with visible redundancy: ai_score/ai_score_band are described twice in adjacent bullets, and the `trend` block is appended mid-section after sector_context rather than front-loaded. Because an output schema exists, the exhaustive field-by-field enumeration largely duplicates structured data rather than earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a rich, gated, multi-block read tool, the description covers everything needed to call and interpret it: tier-dependent shape, which blocks may be absent and why, how `signals`/`indicators`/`stance_signals` differ, and where to go for the fuller research bundle. No material gap remains for an agent deciding and invoking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and the schema already documents it at 100% coverage, including the company-name fallback. The description never mentions the `symbol` argument or its resolution behavior, so it adds nothing here and the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: 'Price, fundamentals, technical indicators, and company profile for a stock... all data needed to understand a stock in a single call.' It also explicitly differentiates from siblings by naming get_stock_research for the full narrative bundle and noting get_stocks omits `trend`, so an agent can pick correctly without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear routing signals exist: 'For the full text ... call get_stock_research(symbol) instead - that's the only tool with the complete bundle' and 'get_stocks omits `trend` to keep batch rows small.' What's missing is an explicit statement of when NOT to use this tool (e.g. historical series -> get_stock_history, signals -> get_signals), leaving some sibling selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything that happened to one stock over the last 90 days, in one timeline, newest first: news, SEC 8-K filings, insider clusters and large single trades, earnings dates and reported results, analyst target and rating changes, and screener setups. Answers "what has been going on with this stock?" in one call instead of five.
Each item has a type (news | filing | insider | earnings | analyst | setup), an
ISO timestamp, a plain headline and a type-specific extra object. With no
types the timeline is the "All" view: very weak news is left out and upcoming
earnings within 30 days are returned separately under upcoming; with types you
get just those kinds, news included in full (for Pro; see below for Free). counts is how many items of each kind
exist in the window, whatever the page or filter; with no types its sum can exceed total, because the
all-types list leaves out very weak news, shows a reported quarter once and lists upcoming dates separately.
What each type is:
news: an article about the company (third-party reporting; the headline is the article's own).
filing: an SEC 8-K, with its item labels. Earnings coverage that repeats a results
filing is folded into it (extra.related_news). Filings are recorded for US-listed
companies in USD with a market cap of about $1 billion or more.
insider: a cluster of 3 or more insiders buying or selling within 30 days, with the amount in the headline.
earnings: a reporting date (extra.date, extra.upcoming, extra.estimate), or a
reported quarter. Where its EPS can be matched to the analysts' estimate, the headline
says whether EPS beat, missed or was in line with estimates; Pro's content adds the
figures. A stock with no estimate data keeps its row as it was.
analyst: the consensus target or rating moved by 5% or more; consecutive steps in one direction are one item.
setup: a screener setup flagged on the stock (Pro).
Every account gets the facts: all types except setups over the 90 days, with the plain
headline in full and the same page size. Three allowances match the other Free tools: Free
returns the 5 newest articles of the last 30 days (as get_stock_news does; news_note says
so), the 5 most recent SEC 8-K filings (as get_stock_filings does; filings_note says so),
an analyst item names the direction only, and so does an EPS beat or miss on a reported
quarter (never the estimate or a percentage). Pro adds related news and filings, and these fields:
tone (Positive/Negative/Neutral, describing
the news for the company, not a price call), number with its number_label (a 0-100
score for news and setups, relevance for filings), a short summary, the model's own
filing headline, fuller extra fields (analyst target and rating levels, insider total value and trades), and the
setup items themselves (everyone else is told only that the stock has some, under
locked_types; the number is not sent).
Not the same as get_signals, which is the market-wide queue of freshly screened ideas across all stocks (Pro, last 24 hours, ranked by signal_score). A setup here is one such idea for this stock, one item among six kinds in its history. For articles alone use get_stock_news; for filings alone, get_stock_filings.
If a source could not be read just now, status is "partial" and unavailable lists the
kinds left out (of those you asked for): an empty list for them does not mean nothing
happened. Call again shortly.
For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days (default 90, max 90). | |
| page | No | Page number, starting at 1. `pages` in the response says how many there are. | |
| limit | No | Items per page (default 25, max 50). The whole call counts as one call toward your daily limit. | |
| types | No | Which kinds of items to return: any of "news", "filing", "insider", "earnings", "analyst", "setup" (default: all). Unknown names are an error that lists the valid ones. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only safety profile, yet the description adds far more: `status: "partial"` with an `unavailable` list and the warning that an empty list there does not mean nothing happened, call-again guidance, the Free/Pro split with named note fields (`news_note`, `filings_note`, `locked_types`), and coverage limits (8-Ks only for US-listed USD companies above ~$1B cap).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a one-line summary, then cleanly sectioned into per-type definitions, tier differences, alternatives and failure modes — all of which carry load given six item types. It is dense rather than padded, but the Free-allowances sentence ('Three allowances match the other Free tools: ... and so does an EPS beat or miss') is garbled and enumerates four things under a count of three, and 'see below for Free' is a forward reference that could be inline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-source, tiered, paginated aggregation tool this covers everything an agent needs: what each `type` contains via its `extra` fields, the upcoming-earnings edge case, pagination/counts semantics, degraded-source handling, and Free-vs-Pro field gating. The output schema exists so return shapes needn't be described, yet the description still tells the agent which fields appear conditionally.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description meaningfully deepens `types`: omitting it yields the 'All' view that drops very weak news and separates upcoming earnings under `upcoming`, while specifying it returns those kinds with news in full — plus why `counts` can sum above `total`. That is behavioral semantics the schema's 'Which kinds of items to return' does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with explicit scope: 'Everything that happened to one stock over the last 90 days, in one timeline, newest first,' and enumerates the six item kinds. It also names the sibling tools it is not (get_signals, get_stock_news, get_stock_filings), so an agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use framing ('Answers "what has been going on with this stock?" in one call instead of five') plus when-not: 'For articles alone use get_stock_news; for filings alone, get_stock_filings,' and a full paragraph distinguishing the setup item from get_signals' market-wide queue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The latest SEC 8-K filings of one company, newest first: when each was filed, what it reports and, on Pro, what it says. 8-Ks are how a US-listed company announces results, deals, financings, leadership changes and other material events.
Free returns the 5 most recent filings (items_note says so when more exist); Pro up
to 25. Per filing, for every account:
filed_at (ISO 8601 with the New York offset), date, time (New York time) and session (before open / during trading / after close)
items: what the filing covers, as plain labels (for example "Results of operations", "Director or officer change", "Material agreement")
company, symbol and the SEC accession number
Pro adds headline (one line on what it says), summary (two or three sentences),
sentiment (Positive/Negative/Neutral, the tone of the news for the company, not a
price call) and relevance (0-100, how material the filing looks; routine filings are
left out for everyone). A filing with no usable text has no summary.
Coverage: US-listed companies in USD with a market cap of about $1 billion or more. Filings are recorded in the morning, before the US open and after the close, so one filed minutes ago may not be there yet. For the filing together with news, insider and analyst activity in one timeline, use get_stock_activity. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max filings returned (default 10, max 25; Free returns up to 5). The whole call counts as one call toward your daily limit. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: Free returns 5 with an `items_note` truncation signal, Pro up to 25, routine filings are suppressed for all tiers, filings lacking usable text have no summary, and recording happens only pre-open and post-close so recent filings may be missing. It even disambiguates `sentiment` as news tone rather than a price call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then tiering, then field semantics, then coverage and alternatives — a logical order with bulleted structure. It is slightly over-long because it enumerates every returned field even though an output schema exists, making part of that list redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema and full annotation coverage, the description fills the remaining gaps an agent needs: tier-dependent result counts, universe restrictions, ingestion latency, suppression of routine filings, and the sibling to use for a combined timeline. Nothing material is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds marginal value by explaining the practical consequence of `limit` — the tier caps and the `items_note` flag that appears when more filings exist than were returned — which is not in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: 'latest SEC 8-K filings of one company, newest first,' and defines what an 8-K is. It is clearly distinguishable from siblings like get_stock_news and get_stock_activity, which are named as different cuts of related data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'For the filing together with news, insider and analyst activity in one timeline, use get_stock_activity.' It also states eligibility boundaries (US-listed, USD, ~$1B+ market cap) and freshness caveats, so an agent knows when this tool will and will not return data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw financial statements - balance sheet, income statement, and cash flow line items. This is the underlying statement data itself, not a derived summary - for the forensic-accounting scores computed FROM these statements (Altman Z / Piotroski F / Beneish M), see get_stock()'s forensic_scores block instead.
Each returned statement is shaped {line_item_name: {period_end_iso: value}}
e.g. income_stmt["Total Revenue"]["2025-12-31"] - so a caller can compute its own trends/deltas/CAGRs, not just read the latest value. Values are in the company's reporting currency (financial_currency).
Tiers:
Free and guest: the LATEST fiscal year only. Every line item's
{period_end: value} map has one entry and periods lists one date.
All three statements and the statement filter work. period=
"quarterly"/"both" returns that latest annual year with
quarterly=null plus a pro_unlocks note (not an error).
annual_periods_available says how many years Pro would return.
Pro: period="annual" (default) returns up to 5 fiscal years; some symbols return fewer. period="quarterly" returns up to roughly 7-8 of the most recent quarters. period="both" returns both blocks in one call.
~50-60 curated line items per statement (not a raw dump of every reported row): balance sheet structure (assets/liabilities/equity/debt/ working capital), income statement (revenue through EPS), and cash flow (operating/investing/financing, free cash flow, buybacks, stock-based comp). Coverage genuinely varies by symbol and sector - a bank has no "Inventory" line, a company with no buyback program has no "Repurchase Of Capital Stock" entry. A missing line item means it is not reported for this company, not a fetch error.
quarterly can come back null (with a quarterly_note) for a symbol whose real quarterly data isn't available. annual/quarterly can both be entirely absent (with a note) if this symbol hasn't yet been through the financials sync, or if it's not an equity (no data for ETFs/crypto/ forex/indices) - these states read the same for every tier.
For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | 'annual' (default; Pro: up to 5 fiscal years, free: the latest fiscal year), 'quarterly' (Pro: up to ~7-8 most recent quarters), or 'both' (Pro). Free/guest asking for 'quarterly' or 'both' gets the latest annual year plus a pro_unlocks note, not an error. | annual |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. | |
| statement | No | 'all' (default), 'balance_sheet', 'income_stmt', or 'cash_flow' - restricts which statement(s) are returned. | all |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them: tier-based availability limits, that free/guest quarterly requests return a pro_unlocks note rather than an error, that null quarterly comes with a quarterly_note, that missing line items mean 'not reported' not 'fetch error', and that values are in financial_currency. This is unusually rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the most important distinction (raw data vs derived scores) and uses a labeled Tiers block that is easy to scan. It is somewhat long and repeats tier/period rules already in the schema, costing it a point, but no sentence is purely filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the description covers every edge case an agent would need: coverage variance by sector, null/absent statement states, non-equity symbols, and tier gating. Nothing required to call or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's tier/period/statement detail largely restates what the schema already documents (the period tier behavior appears near-verbatim in both). It adds the response shape {line_item: {period: value}} and currency semantics, but those are return-value concerns rather than parameter meaning, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (raw balance sheet / income statement / cash flow line items) and explicitly distinguishes itself from the sibling get_stock by naming its forensic_scores block as the alternative for derived metrics. An agent can tell exactly what this returns without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use-this vs when-to-use-that routing rule: use this for raw statement data, use get_stock().forensic_scores for Altman Z / Piotroski F / Beneish M. It also frames the caller's intent (compute own trends/deltas/CAGRs) which clarifies the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily OHLCV price history for a stock.
days: number of trading days to return (default 90). Guest/free: max 365. Pro: full history, up to 20,000 trading days (most established names go back decades; a full pull can be ~10,000+ bars, so request only what you need).
Returns: { symbol, days_requested, days_returned, count, history[],
history_available: { bars, earliest_date } } -
days_returned/count can be less than days_requested if less history exists.
When a guest/free caller asks for more than 365 days the response is capped
at 365 and carries a pro_unlocks note saying what Pro adds.
Per bar: date, open, high, low, close, volume
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of trading days of daily OHLCV history to return (default 90). Max 365 for guest and free; Pro can request the full history (up to 20,000 trading days). A full-history call can be ~10,000+ bars - prefer a narrower window unless you need it all. days_returned/count in the response can be less than this if less history exists. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further and discloses non-obvious behavior: guest/free callers are capped at 365 days with a `pro_unlocks` note, and days_returned/count may be less than requested when history is short. That is meaningful edge-case context an agent could not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Bulleted, front-loaded, and every bullet maps to a distinct concern (parameter, response shape, per-bar fields). It loses a point because the 'days' bullet and the return-shape bullet substantially duplicate the schema parameter description and the existing output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with full schema coverage and an output schema, the description covers everything needed to invoke it correctly: the data granularity, tier-based caps, short-history behavior, and bar fields. No gap remains that would cause a wrong call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema's `days` description already carries the default, the 365/20,000 tier limits, and the days_returned caveat. The description largely restates that same tier and default information, adding little semantic meaning beyond the structured fields. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line gives a specific verb+resource: 'Daily OHLCV price history for a stock,' which clearly separates it from get_stock, get_stock_financials, and get_indicator_history by naming the exact data product (daily OHLCV bars). It stops short of explicitly naming a sibling to prefer or avoid, so it is clear but not sibling-differentiated to the top standard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives real guidance on the 'days' parameter ('request only what you need,' 'a full pull can be ~10,000+ bars'), which is genuinely useful scoping advice. However, it never states when to use this tool instead of the adjacent get_indicator_history or get_stock, so tool-selection guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent news articles for one stock, newest first.
symbol: ticker, e.g. "AAPL" or "SAP.DE".
days: look-back window in days. Values above the account's maximum are lowered to it (30 or 90 days, depending on the account).
limit: max articles returned. Values above the account's maximum are lowered to it (5 or 50 articles, depending on the account).
status: "ok" = articles returned | "empty" = no news in the window.
Per article: title, published_at. Depending on the account, also ai_sentiment, ai_summary, signal_score (0-100 or null) and signal_score_band ("Weak"/"Moderate"/"Strong"/"Very Strong" or null).
signal_score is the same number get_signals() and get_stock_research() report for this symbol when a news-based signal was raised in the last 90 days; otherwise it is computed per article from that article's own classification. It is always a single number.
collapsed_count: present when several articles reported the same event
(for example one analyst's target change carried by several outlets);
only the newest is returned and this says how many were merged into it.
limit counts distinct events.
Articles are published by third parties; titles and summaries describe what those articles say. For news together with filings, insider, earnings and analyst events in one timeline, use get_stock_activity. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days (default 30). Values above the account's maximum (30 or 90) are lowered to it. | |
| limit | No | Max articles returned (default 10). Values above the account's maximum (5 or 50) are lowered to it. | |
| symbol | Yes | Stock ticker symbol. Also accepts a company name as a fallback when it uniquely resolves to one symbol. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/open-world, but the description adds substantive behavior an agent could not infer: days and limit are silently clamped to account-specific maxima (30/90 and 5/50), status can return 'empty', results are deduplicated by event with collapsed_count, and content is third-party sourced. These are the operational facts that change how an agent interprets and reports results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded lead sentence followed by a scannable bullet list, with each bullet carrying a distinct operational fact. It runs long and spends several lines describing per-article return fields that the output schema likely already covers, which is the only waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read tool with an output schema, this covers everything: request semantics, clamping, empty-result handling, dedup behavior, the ambiguous signal_score inheritance rule, and a provenance disclaimer. Nothing an agent needs in order to call it and interpret the response is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: concrete ticker examples including a non-US format ('SAP.DE'), restated clamping behavior, and the non-obvious note that 'limit counts distinct events' rather than raw articles. That last point materially affects how an agent sizes its request and is absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: 'Recent news articles for one stock, newest first.' The sibling routing line to get_stock_activity makes the boundary explicit, so an agent can distinguish this from get_stock_activity and get_news_feed without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative for the adjacent use case ('For news together with filings, insider, earnings and analyst events in one timeline, use get_stock_activity'), which is exactly the routing decision an agent faces. It does not address when to prefer get_news_feed over this per-symbol tool, so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full AI research bundle for a stock in one call - fundamentals, AI-generated summary, recent AI-classified news, insider/institutional signal, and recent trade signal history. Replaces 4 separate calls: get_stock + get_stock_news + get_insider_activity + get_signals (for one symbol).
Returns:
stock: price, name, sector, rsi, pe_forward, market_cap, 52-week range, analyst data
ai_summary: verdict, ai_score (0-100)/ai_score_band (Weak/Moderate/Strong/ Very Strong - the AI research composite, same scale and bands as signal_score but a separate score), full summary, key_points, risks, price_at_generation, generated_at, headline (one-sentence plain-language take), near_term (stance/confidence over <4 weeks - technicals/momentum-weighted), longer_term (stance/confidence over a multi-month horizon - fundamentals/analyst/institutional-flow-weighted). headline/near_term/longer_term are null on summaries generated before this schema shipped - until that symbol's next regeneration, fall back to verdict/ai_score.
news: last 3 high-relevance articles (title, published_at, ai_sentiment,
ai_summary, signal_score [0-100]/signal_score_band - this symbol's current
news-sourced signal score if one exists in the last 30 days [same number
as the signals list below and get_signals()/get_stock_news(), kept in
sync as it's re-scored], else a per-article magnitude computed from that
article's own classification. One name, no separate "news_score" field.
The 3 are distinct events: an article carries collapsed_count when
several articles about the same event were merged into it.)
filings[]: the latest SEC 8-K filings of the last 30 days, up to 3 (date, title, headline, summary, sentiment, items, sec_url). Empty when none in the window; get_stock_filings has the full list.
earnings: {next, last_reported}. next = the coming report date (estimated_date says whether the date can still move) with the consensus; last_reported = the newest reported quarter in the last 100 days with revenue, EPS and, where available, the beat or miss (eps_surprise). null when neither is known.
analyst_change: how consensus moved over the last 30 days - rating and mean target at the start and end, rating_score_change, direction (upgrading / downgrading / steady), target_change_pct, analyst_count_change. null with fewer than two analyst snapshots in the window; get_analyst_trend has the daily series.
sentiment: signal, signal_score (0-100)/signal_score_band - one name, no separate "insider_score" field, same as the news block above - insider_trend (buying/selling/neutral, or null with no transactions in the window), institutional_pct
signals[]: up to the 3 most recent trade signals for this symbol in the last 30 days (direction, rationale, signal_score [0-100], signal_score_band [human-readable label - "Weak"/"Moderate"/"Strong"/"Very Strong" - or null alongside a null signal_score], source, expires, flagged_at). Empty if nothing in that window. Signals stay listed for the full window even after they expire.
forensic_scores: {altman_z, piotroski_f, beneish_m, computed_at} - three classic
forensic-accounting formulas (Z-Score bankruptcy risk / F-Score fundamental
quality / M-Score earnings-manipulation risk), computed from stocks.financials
(GH #107). Omitted entirely if this symbol has no forensic_scores doc yet - not
every symbol qualifies (financial-sector companies mostly return null on all
three by construction, see the field's own note text). A withheld individual
score always surfaces as {"score": null, "note": ""} -
never a bare 0, never silently dropped from its own sub-block. Same shape
get_stock()/get_stocks() already return.
All data is pre-computed by the Stocklake AI pipeline - no AI calls on request. Pro tier only. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker symbol to fetch the full AI research bundle for. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/closed-world, and the description goes well beyond them: data is pre-computed with no AI call on request, results are windowed to 30/100 days, expired signals remain listed, and a stale-schema fallback is spelled out (headline/near_term/longer_term are null on older summaries — fall back to verdict/ai_score). It also discloses null/empty semantics per block and the 'never a bare 0, never silently dropped' contract for withheld forensic scores.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and sibling routing are correctly front-loaded in the opening sentences, and the sub-block breakdown is scannable. However, the bulk of the description re-enumerates return fields (price, rsi, pe_forward, direction, rationale, expires…) that the output schema already defines, making it far longer than an agent needs for tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex — nine heterogeneous sub-blocks with windowing, nullability, and sync relationships — and the description covers every one of them, including the non-obvious cross-references (the news block's signal_score is the same number as the signals list and get_signals/get_stock_news). Nothing needed to call or interpret it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single required parameter at 100% schema coverage, so the schema already carries the documentation burden. The description adds only the loose framing 'for one symbol' and the implication that the symbol scopes every returned block; it adds no syntax, format, or validation detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first clause gives a specific verb+resource+scope: a full pre-computed AI research bundle for one stock symbol, in one call. It further distinguishes itself from siblings by naming exactly which four calls it consolidates (get_stock, get_stock_news, get_insider_activity, get_signals). An agent can place this tool in the catalog without reading any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing is stated: it replaces four named sibling calls for a single symbol, and it points to get_stock_filings and get_analyst_trend for the exhaustive versions of two sub-blocks. It also states a hard eligibility constraint (Pro tier only) that governs whether the agent should call it at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch stock data for up to 25 symbols in a single call - the same fields get_stock returns for the same key/symbol, so this is a true batch version, not a thinned-down scan. Returns a dict keyed by symbol. Missing symbols are omitted from the result. Each symbol in the batch counts as one call toward the daily limit. A request over 25 symbols is rejected outright (error: batch_too_large) rather than silently served on just the first 25 - split a larger list into multiple calls. Available to all tiers (fundamentals/indicators/company profile, free).
Pro tier adds, per symbol, the same precomputed blocks get_stock adds - rating {score, direction, signals}, signals (per-indicator breakdown), relative_strength, market_risk {beta_spy_1y, corr_spy_1y}, sector_context (revenue growth/margins vs sector median - see get_stock), and the minimum AI-narrative slice (ai_verdict, ai_headline, ai_score, ai_score_band). None of this costs an AI call on your request - it's all precomputed and just needs projecting.
NOT included, even on pro - call get_stock(symbol) for stance_signals, or get_stock_research(symbol) for the full ai_summary text (summary/key_points/ risks/near_term/longer_term) plus cross-source news/insider/signal context.
Response also carries duplicates_collapsed: how many input symbols
normalized (case-folding, share-class aliasing e.g. "BRK.B"->"BRK-B") or
literally repeated onto a symbol already counted elsewhere in this batch.
requested - len(missing or []) - duplicates_collapsed == count always holds.
| Name | Required | Description | Default |
|---|---|---|---|
| symbols | Yes | List of stock ticker symbols, up to 25 per call. Each symbol counts as one call toward the daily limit. A request over 25 symbols is rejected outright (error: batch_too_large) rather than silently served on just the first 25 - split a larger list into multiple calls. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (which only cover read-only/idempotent safety) by disclosing quota costs ('each symbol counts as one call toward the daily limit'), hard rejection over 25 symbols with the exact error code batch_too_large, omission of missing symbols, and dedup/normalization behavior. It also notes pro-tier blocks are precomputed and cost no AI call, which is material for cost planning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the key constraints, but the tier-content enumeration is dense and partly duplicates the schema's 25-symbol rule. The closing sentence is garbled and truncated ('requested - len(missing or []) - duplicates_collapsed == count always holds'), which costs clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description needn't explain return shape, yet it helpfully lists the tier-dependent fields and the duplicates_collapsed key. The only real hole is the malformed invariant sentence, which leaves the accounting rule ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the 25-symbol limit and per-call cost are already documented; the description largely restates them. It does add genuine meaning beyond the schema by describing symbol normalization (case-folding, share-class aliasing like BRK.B -> BRK-B) and the duplicates_collapsed accounting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('batch stock data for up to 25 symbols') and explicitly positions itself as a true batch of get_stock, not a thinned-down scan. It also names the siblings that cover what it does not: get_stock for stance_signals and get_stock_research for full ai_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance (batch up to 25, split larger lists) and explicit routing for out-of-scope data ('call get_stock(symbol) for stance_signals, or get_stock_research(symbol) for the full ai_summary text'). Tier availability (free vs pro) is stated so an agent knows what it can expect from its plan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The caller's Stocklake watchlist (starred symbols from the web dashboard), enriched with latest price, technicals, and AI verdict.
Returns:
count: number of symbols on the watchlist
items[]: each with symbol, name, sector, price, change_pct, rsi, market_cap, analyst_rating, atr_pct, ai_verdict, ai_headline, ai_score (0-100), ai_score_band (Weak/Moderate/Strong/Very Strong), added_at, price_at_add
empty items[] if nothing is starred yet - star symbols at stocklake.dev/dashboard
Pro tier only. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: it is Pro tier only, it returns an empty items[] rather than erroring when nothing is starred, and the result is informational and not financial advice. Missing auth/failure-mode detail keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence and each subsequent line earns its place (empty-state behavior, tier gating, disclaimer). The multi-line Returns block partly duplicates the existing output schema, which is mild redundancy but also usefully explains field meaning like the ai_score_band ordering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool with a published output schema and full annotation coverage, the description supplies the remaining pieces an agent needs: entitlement (Pro tier), empty-state handling, and result interpretation. The only gap is the lack of explicit differentiation guidance versus similar read siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly signals the no-argument nature by describing a caller-scoped, implicit-scope retrieval.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource: retrieves the caller's Stocklake watchlist, defined as starred symbols from the web dashboard, plus the enrichments applied. This clearly distinguishes it from list-style siblings such as get_stocks and from per-symbol siblings like get_stock, so an agent can pick it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: it is the watchlist of the calling user, and the description notes that starring happens on the web dashboard, plus what happens when nothing is starred. There is no explicit when-to-use-this-instead-of guidance against siblings like get_stocks or get_signals, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_earnings_calendar4 fields changedInput schema / properties / limitAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Max companies to return. Free and guest: at most 5 (the largest by market cap), each counted as one call toward your daily limit. Pro: up to 500 per call (default 100), one call each."
+}Input schema / properties / min_market_capAdded value: +{
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Only companies with a market cap of at least this many US dollars (e.g. 10000000000 for $10B). Applied before limit."
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Pro only: skip this many companies (by date) to page through a long window. Use next_offset from the previous response. Ignored for Free and guest.",
+ "type": "integer"
+}Input schema / properties / symbolsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Only these tickers (up to 50), e.g. your holdings. Applied before limit."
+}get_economic_calendar4 fields changedInput schema / properties / days / anyOfAdded value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / days / defaultPrevious value: -3New value: +nullInput schema / properties / days / descriptionPrevious value: -"Look-ahead window in days for upcoming events (default 3). Max 7 for guest and free, 14 for Pro."New value: +"Look-ahead window in days for upcoming events. Default 1 for guest and free, 3 for Pro. Max 1 for guest and free, 14 for Pro."Input schema / properties / days / typeRemoved value: -"integer"get_stock_activityget_stock_filingsget_signals1 field changedInput schema / properties / min_signal_score / descriptionPrevious value: -"Minimum composite signal score, 0-100 (default 60) - a blend of conviction/confidence/flag_score, source track record, and real technical factors. This is the field to filter on."New value: +"Minimum signal score, 0-100 (default 60) - mainly how stretched the stock is in the signal's direction. This is the field to filter on."get_news_feed1 field changedInput schema / properties / min_signal_score / descriptionPrevious value: -"Minimum signal_score used to SELECT articles server-side, 0-100 (default 60). Resolved per-article (this symbol's live signal_score if one exists, else a per-article magnitude computed from sentiment/confidence/flag_score) since a live signal doesn't exist for every article."New value: +"Minimum signal_score, 0-100 (default 60)."get_stock_news2 fields changedInput schema / properties / days / descriptionPrevious value: -"Look-back window in days. Requesting more than your tier's cap is silently clamped down to it: 30 free/guest, 90 pro."New value: +"Look-back window in days (default 30). Values above the account's maximum (30 or 90) are lowered to it."Input schema / properties / limit / descriptionPrevious value: -"Max articles returned. Default 10 is a Pro-tier-shaped value - on free/guest it's silently clamped down to that tier's cap (5), so a free caller passing no limit effectively gets 5, not 10. Requesting more than your tier's cap (5 free/guest, 50 pro) is likewise clamped down."New value: +"Max articles returned (default 10). Values above the account's maximum (5 or 50) are lowered to it."get_analyst_trendget_earnings_intelligence1 field changedInput schema / properties / min_ai_score / descriptionPrevious value: -"Only return stocks with AI score >= this value, 0-100 (optional). Renamed 2026-08-24 from the retired 0-10 min_flag_score — gates on the same stock_ai_summary.py ai_score field the response already returns. Applied server-side before limit truncates the result, so a qualifying stock always counts against limit ahead of one without."New value: +"Only return stocks with AI score >= this value, 0-100 (optional). Gates on the same ai_score field the response returns. Applied server-side before limit truncates the result, so a qualifying stock always counts against limit ahead of one without."get_economic_calendar3 fields changedInput schema / properties / days / descriptionPrevious value: -"Look-ahead window in days for upcoming events (default 3, max 14)."New value: +"Look-ahead window in days for upcoming events (default 3). Max 7 for guest and free, 14 for Pro."Input schema / properties / limit / descriptionPrevious value: -"Max results per bucket, released_recent and upcoming each capped independently (default 20, max 50)."New value: +"Max results per bucket, released_recent and upcoming each capped independently (default 20). Max 20 for guest and free, 50 for Pro."Input schema / properties / lookback_days / descriptionPrevious value: -"Look-back window in days for recently-released events (default 2, max 7). Yahoo's own actual value has a confirmed ~1-day reporting lag, so a same-day-only window misses real releases -- keep this at 2+ to reliably see them."New value: +"Look-back window in days for recently-released events (default 2). Max 2 for guest and free, 7 for Pro. Actual values arrive with about a 1-day reporting lag, so a same-day-only window misses real releases -- keep this at 2+ to reliably see them."get_indicator_history1 field changedInput schema / properties / full / descriptionPrevious value: -"False (default) returns only recorded_at/price/rsi/macd_histogram/bb_pct/sma20/sma200 per day — enough for most charting/trend use. True adds the specialized indicators (williams_r, ultimate_osc, vix_fix_value, williams_ad_trend, td_signal, td_phase) plus analyst_rating/analyst_target, which barely change day to day and roughly double response size over a long window."New value: +"False (default) returns only recorded_at/price/rsi/macd_histogram/bb_pct/sma20/sma200 per day - enough for most charting/trend use. True adds the specialized indicators (williams_r, ultimate_osc, vix_fix_value, williams_ad_trend, td_signal, td_phase) plus analyst_rating/analyst_target, which barely change day to day and roughly double response size over a long window."get_insider_activity2 fields changedInput schema / properties / daysAdded value: +{
+ "default": 90,
+ "description": "Insider-transaction window in days (default 90, max 365 on Pro; free/guest calls are capped at 90). Applies to transactions, insider_buys and insider_sells.",
+ "maximum": 365,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / symbol / descriptionPrevious value: -"Stock ticker symbol to fetch insider (SEC Form 4) and institutional-holdings activity for."New value: +"Stock ticker symbol to fetch insider-filing and institutional-holdings activity for."get_market_movers1 field changedInput schema / properties / limit / descriptionPrevious value: -"Results per category (default 10, max 20). Each returned stock counts as one call toward your daily limit — a symbol appearing in more than one category (e.g. both \"gainers\" and \"most_active\") counts once per category it appears in."New value: +"Results per category (default 10, max 20). Each returned stock counts as one call toward your daily limit - a symbol appearing in more than one category (e.g. both \"gainers\" and \"most_active\") counts once per category it appears in."get_screener1 field changedInput schema / properties / min_ai_score / descriptionPrevious value: -"Minimum AI score, 0-100 — pro tier only (silently ignored for free). Gates on stock_ai_summary.py's own composite ai_score, same 0-100 scale/band convention as signals.signal_score but a distinct field/pipeline (per-stock AI summary confidence, not a directional trade idea). Renamed 2026-08-24 from the retired 0-10 min_flag_score."New value: +"Minimum AI score, 0-100 - pro tier only (silently ignored for free). Gates on the AI research composite ai_score, same 0-100 scale and bands as signal_score but a separate score (per-stock AI summary strength, not a directional signal)."get_sector_intelligence1 field changedInput schema / properties / sector / descriptionPrevious value: -"Pass a sector name for a single sector's assessment, or omit (None) to get the latest assessment for all 11 sectors at once — the all-sectors call doubles as the rotation view."New value: +"Pass a sector name for a single sector's assessment, or omit (None) to get the latest assessment for all 11 sectors at once - the all-sectors call doubles as the rotation view."get_signals1 field changedInput schema / properties / min_signal_score / descriptionPrevious value: -"Minimum composite signal score, 0-100 (default 60) — a blend of conviction/confidence/flag_score, source track record, and real technical factors. This is the field to filter on."New value: +"Minimum composite signal score, 0-100 (default 60) - a blend of conviction/confidence/flag_score, source track record, and real technical factors. This is the field to filter on."get_stock_financials2 fields changedInput schema / properties / period / descriptionPrevious value: -"'annual' (up to 5 fiscal years, default), 'quarterly' (up to ~7-8 most recent quarters), or 'both'."New value: +"'annual' (default; Pro: up to 5 fiscal years, free: the latest fiscal year), 'quarterly' (Pro: up to ~7-8 most recent quarters), or 'both' (Pro). Free/guest asking for 'quarterly' or 'both' gets the latest annual year plus a pro_unlocks note, not an error."Input schema / properties / statement / descriptionPrevious value: -"'all' (default), 'balance_sheet', 'income_stmt', or 'cash_flow' — restricts which statement(s) are returned."New value: +"'all' (default), 'balance_sheet', 'income_stmt', or 'cash_flow' - restricts which statement(s) are returned."get_stock_history1 field changedInput schema / properties / days / descriptionPrevious value: -"Number of trading days of daily OHLCV history to return (default 90, max 365). days_returned/count in the response can be less than this if less history exists."New value: +"Number of trading days of daily OHLCV history to return (default 90). Max 365 for guest and free; Pro can request the full history (up to 20,000 trading days). A full-history call can be ~10,000+ bars - prefer a narrower window unless you need it all. days_returned/count in the response can be less than this if less history exists."get_stock_news1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max articles returned. Default 10 is a Pro-tier-shaped value — on free/guest it's silently clamped down to that tier's cap (5), so a free caller passing no limit effectively gets 5, not 10. Requesting more than your tier's cap (5 free/guest, 50 pro) is likewise clamped down."New value: +"Max articles returned. Default 10 is a Pro-tier-shaped value - on free/guest it's silently clamped down to that tier's cap (5), so a free caller passing no limit effectively gets 5, not 10. Requesting more than your tier's cap (5 free/guest, 50 pro) is likewise clamped down."get_stocks1 field changedInput schema / properties / symbols / descriptionPrevious value: -"List of stock ticker symbols, up to 25 per call. Each symbol counts as one call toward the daily limit. A request over 25 symbols is rejected outright (error: batch_too_large) rather than silently served on just the first 25 — split a larger list into multiple calls."New value: +"List of stock ticker symbols, up to 25 per call. Each symbol counts as one call toward the daily limit. A request over 25 symbols is rejected outright (error: batch_too_large) rather than silently served on just the first 25 - split a larger list into multiple calls."get_signals2 fields changedInput schema / properties / min_convictionRemoved value: -{
- "default": 7,
- "description": "DEPRECATED, ignored for filtering — kept in the signature only so existing callers don't hard-fail; internal scoring retired the raw conviction/confidence/flag_score triad in favor of signal_score. Passing a non-default value here has no effect and is logged for a planned removal.",
- "type": "integer"
-}Input schema / properties / min_flag_scoreRemoved value: -{
- "default": 8,
- "description": "DEPRECATED, ignored for filtering — kept in the signature only so existing callers don't hard-fail; internal scoring retired the raw conviction/confidence/flag_score triad in favor of signal_score. Passing a non-default value here has no effect and is logged for a planned removal.",
- "type": "integer"
-}get_market_movers1 field changedInput schema / properties / min_market_cap_b / descriptionPrevious value: -"Filter to stocks above this market cap in billions of dollars, e.g. 1.0 = $1B+."New value: +"Filter to stocks above this market cap in billions of US dollars, e.g. 1.0 = $1B+ (compared against market_cap_usd)."get_screener2 fields changedInput schema / properties / max_market_cap_b / descriptionPrevious value: -"Maximum market cap in billions of dollars."New value: +"Maximum market cap in billions of US dollars (compared against market_cap_usd)."Input schema / properties / min_market_cap_b / descriptionPrevious value: -"Minimum market cap in billions of dollars."New value: +"Minimum market cap in billions of US dollars (compared against market_cap_usd, so non-USD listings are converted first)."get_signals1 field changedInput schema / properties / source / descriptionPrevious value: -"Filter by signal source: \"news\" | \"screener\" | \"sentiment\" | \"social\" (default: all)."New value: +"Filter by signal source: \"news\" | \"screener\" | \"sentiment\" (default: all)."get_stock_financialsget_economic_calendarget_indicator_history1 field changedInput schema / properties / fullAdded value: +{
+ "default": false,
+ "description": "False (default) returns only recorded_at/price/rsi/macd_histogram/bb_pct/sma20/sma200 per day — enough for most charting/trend use. True adds the specialized indicators (williams_r, ultimate_osc, vix_fix_value, williams_ad_trend, td_signal, td_phase) plus analyst_rating/analyst_target, which barely change day to day and roughly double response size over a long window.",
+ "type": "boolean"
+}get_signals2 fields changedInput schema / properties / limit / defaultPrevious value: -50New value: +25Input schema / properties / limit / descriptionPrevious value: -"Max results to return (default 50, max 50). Each returned signal counts as one call toward your daily limit."New value: +"Max results to return (default 25, max 50). Each returned signal counts as one call toward your daily limit."
Add one secure layer between your agents and this server.