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.
Upcoming earnings dates for stocks in the Stocklake universe.
days: look-ahead window in days (default 7, max 30)
Returns: { window_days, from_date, to_date, count, results[] }
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). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral value beyond that by noting that dates from market data are approximate when is_estimate is true, and that results are sorted by earnings_date ascending. This helps the agent interpret the data reliability, which annotations do not convey.
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 well-structured and front-loaded: the first line states the core purpose. The remaining bullet points succinctly list parameter and return fields without fluff. Every sentence contributes useful information, and the format is easy to scan.
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 description fully covers what an agent needs to call the tool correctly: the parameter and its constraints, the exact return shape with fields, sorting behavior, data reliability caveat, and tier access. The presence of an output schema further reduces the need to explain return values, and nothing essential 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 single parameter 'days' is already fully described in the schema (look-ahead window, default 7, max 30). The tool description repeats this information without adding new nuance. Since schema coverage is 100%, the baseline of 3 applies; the description does not improve parameter understanding.
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 clearly states the tool lists upcoming earnings dates for stocks in the Stocklake universe, with a specific verb and resource. It does not explicitly differentiate from the sibling get_earnings_intelligence, which could plausibly overlap, so the purpose is clear but not sharply distinguished.
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 no guidance on when to use this tool versus alternatives. It does not mention sibling tools like get_earnings_intelligence or any conditions that would favor one over the other. The only operational detail is the look-ahead window default and max, which is parameter guidance, not usage context.
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).
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, rather than
the raw legacy flag_score field, which is no longer part of this fleet's
public vocabulary at all. 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) — stock_ai_summary.py's own composite score, same 0-100 scale/band convention as signals.signal_score but a distinct field/pipeline; null if this stock has no ai_summary doc 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). 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes well beyond that: it discloses the 'Pro tier only — AI pipeline cost attached', states the informational purpose, explains the server-side filtering order relative to limit, details the nullability of ai_score (absence of ai_summary doc), and traces the field provenance to stock_ai_summary.py. This adds rich behavioral context that the annotations do not cover.
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 fairly long but well-structured with sections for purpose, parameters, return fields, and caveats. It front-loads the core purpose in the first sentence, and all sentences carry substantive information. While it could be tightened, the organization and lack of filler make it efficient for its complexity.
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 (4 optional parameters, a rich output schema, and multiple caveats), the description covers all essential aspects: what it does, what data it returns, parameter semantics, cost implications, and informational limitations. The return field list and the note about sorting and nullability make it complete for an agent to call correctly without external documentation.
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 each parameter. The description adds value by explaining the min_ai_score renaming history and the ordering effect with limit, and clarifies that all parameters are optional. It provides extra nuance beyond the schema's literal descriptions, earning above the baseline of 3.
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 verb and resource ('Upcoming earnings with AI context — AI scores, verdicts, and risk factors per stock') and clearly distinguishes it from plain earnings calendars by emphasizing the AI pipeline integration. The phrase 'Combines the earnings calendar with AI pipeline data' makes the unique value explicit, differentiating it from the sibling get_earnings_calendar.
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 implies when to use this tool (when you need AI context on earnings), but it does not explicitly state when NOT to use it or recommend a sibling alternative like get_earnings_calendar for calendar-only needs. While it clarifies parameters and return behavior, it lacks explicit routing guidance, leaving the choice to inference.
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.
Each 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 = bullish momentum)
bb_pct: Bollinger Band % position (0 = at lower, 100 = at upper band)
sma20 / sma200: 20-day and 200-day simple moving averages
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 signal (BUY_SETUP/SELL_SETUP/BUY_COUNTDOWN/SELL_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. | |
| 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?
Beyond the readOnly/idempotent annotations, the description adds substantial behavioral detail: the exact return range (max 730, default 90), the empty-object condition when fewer than 3 snapshots, the 'Pro tier only' restriction, and the meaning of each output field (e.g., MACD histogram positive = bullish). This goes well beyond what annotations convey and is directly useful for interpreting 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?
The description is long but well-structured, front-loading the purpose and then listing fields in a bulleted list. The extra clauses like 'For informational purposes only' add minor noise, but the structure is clear and scannable, earning a 4 rather than lower because the detail is justified by the many output fields.
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 (many indicators, output schema exists), the description covers all essential aspects: what it returns, limits, tier requirement, and field semantics. It does not mention rate limits or advanced error cases, but these are uncommon in tool descriptions and the core information is complete. An agent can call this correctly with the given description.
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 both parameters are fully documented in the schema. The description largely repeats the `days` default/max and the `{}` condition, and does not add new meaning for the `symbol` parameter beyond what the schema already states. It meets the baseline but does not exceed it.
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 verb and resource: 'Historical daily indicator snapshots for a stock' — explicitly distinguishing it from siblings like get_stock_history by focusing on technical indicators rather than raw price data. It also enumerates the exact indicator fields, making it clear what the tool returns.
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 clear context that it is 'ideal for charting and trend detection', implying the use case, but it does not explicitly name alternatives or state when not to use it. It provides enough guidance for an agent to select it over siblings based on the indicator focus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI-synthesized insider + institutional activity for a stock.
Returns combined 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, no separate name) with
signal_score_band, per-source breakdown, and a human-readable summary.
Data covers insider transactions (SEC Form 4/BaFin/AFM/CNMV, with a
gap-fill from Yahoo where the regulatory source has nothing) and
institutional holdings — insider_buys/insider_sells, transactions (the
individual rows behind those counts, newest first, up to 50, each with
date/name/role/type/shares/price/value), 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, useful for
spotting a false merge: two genuinely different holders should never
collide, but if they did, their per-source counts would diverge wildly),
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; distinct from an ordinary two-holder mismatch, which is normal
data lag and stays unflagged), inst_ownership (0-100%), and
total_holders. Note: summary is a
separately-generated narrative on its own refresh cadence and may not
always match the live insider_buys/insider_sells/transactions counts —
trust the counts/transactions over the prose if they disagree.
Pro tier only — AI pipeline cost attached.
For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker symbol to fetch insider (SEC Form 4) 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description builds on this with rich behavioral detail: AI-synthesized data with gap-fill from Yahoo, a separately-generated summary on a different refresh cadence that may disagree with live counts, the holder_count_divergence caveat about systemic multipliers, and false-merge detection guidance. This goes well beyond what annotations provide.
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 every sentence adds operational value: signal_score equivalence, per-source breakdown, data-source caveats, summary lag warning, and Pro-tier cost. It is front-loaded with the core purpose and uses structured clauses to separate return fields from caveats. Slightly dense but appropriate for the tool's complexity.
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?
With an output schema present, the description still thoroughly explains return semantics: signal_score band, per-source breakdown, insider_buys/sells, transactions, top_holders merge behavior, holder_count_divergence, inst_ownership, total_holders, and caveats. It also covers access constraints (Pro tier) and data-source behavior. Nothing an agent needs to correctly call and interpret this tool 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 single parameter symbol has full schema coverage (100%), describing it as a stock ticker symbol for insider and institutional activity. The description adds no new meaning beyond the schema, which is the baseline case for complete coverage. The description's mention of SEC Form 4 is already in the schema description.
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 and resource: 'Get AI-synthesized insider + institutional activity for a stock.' It clearly distinguishes this tool from siblings by naming get_signals and emphasizing the combined insider/institutional scope, so an agent can confidently select it over get_stock, get_stock_research, or get_signals.
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 clear context: it is for insider and institutional activity, is Pro-tier only, and is informational. It does not explicitly say 'use X instead when...', but it references get_signals's signal_score equivalence and implies the tool is the source for insider/institutional data. A small gap remains in not stating when to prefer get_stock_research or get_signals for a related use case.
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. Produced every ~4 hours by the market intelligence pipeline.
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
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: FRED 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: CNN Fear & Greed 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 live prices (use get_market_pulse for live)
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 provide readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds critically useful behavior: it explains the ~4-hour production cadence, the exact meaning of staleness (including that a normal Fri→Mon gap does not trip it), the point-in-time nature of market_context (not live), and the 'always in sync' guarantee. This goes well beyond annotations and materially informs how an agent interprets 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?
Despite being long, the description is tightly structured with a clear front-loaded purpose, then bulleted field groupings. Every section adds unique information—pipeline cadence, staleness semantics, snapshot caveats, Pro-tier note—and there is no fluff. The structure makes it scannable and each sentence earns 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?
Given the tool's complexity (dual assessments, many fields, staleness, pipeline info, alternatives), the description is exceptionally complete. It explains the output schema fields, the meaning of indicators, the point-in-time caveat, and even addresses edge cases like missing timestamps. Nothing an agent needs to use the tool 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 for history_count is 100%: the schema already states 'Include the last N prior assessments for each of regime and outlook (0-3, default 0)'. The description repeats this almost verbatim, adding no new semantics. Since schema does the heavy lifting, the baseline of 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?
The description immediately states the tool returns a combined AI market assessment with two distinct perspectives (regime and outlook), with explicit verbs and resources. It clearly distinguishes itself from siblings by noting it's a single call combining both, and later points to get_market_pulse for live prices, so an agent can differentiate it without opening other 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?
The description gives explicit usage contexts: regime for position sizing/asset allocation, outlook for sector preference/directional bias. It also explicitly says to use get_market_pulse for live prices, and notes the 'Pro tier only' restriction. This is clear when-to-use and when-not-to-use guidance, referencing an alternative directly.
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 (e.g. 1.0 = $1B+)
Returns per stock: symbol, name, sector, price, change_pct, volume, rsi, market_cap, 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 dollars, e.g. 1.0 = $1B+. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only/idempotent/non-destructive. The description adds valuable behavioral detail: daily-limit counting per category, atr_pct omissions when data is missing/corrupted, and Pro-tier AI fields being precomputed with no extra AI cost. These go well beyond the structured 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?
The description opens with a one-line purpose summary, then uses bullets for parameters and a terse return-field list. The AI-narrative justification is slightly promotional but remains short and relevant. Overall well-structured with minimal 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?
With an output schema present, the description doesn't need to explain return values, yet it still covers edge cases (atr_pct omitted), quota accounting, and tier differences. It also points to get_stock_research for follow-up. Nothing needed for a correct call 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% for all three parameters. The description simply restates the same defaults and formats (category values, limit max 20, min_market_cap_b in billions) without adding new semantic information. 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?
Description states 'Top market movers from the Stocklake universe — gainers, losers, most active.' This clearly identifies the resource and categories, distinguishing it from data-retrieval siblings. It also names get_stock_research as the alternative for deeper research, reinforcing the scope.
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 explicit routing: 'For the full research bundle on any one mover, call get_stock_research(symbol).' It also explains tier availability, category modes, and daily-limit implications, giving clear context for when the tool is appropriate. It doesn't enumerate all sibling distinctions, but the named alternative is strong evidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live market health snapshot in a single call. Aggregates key market indicators without requiring multiple tool calls. No AI cost — reads live data directly from the market data feed.
Returns:
vix: VIX level and change_pct (from live stocks data)
fear_greed: value (0-100) and label (e.g. "neutral", "greed", "fear")
breadth: market-wide RSI distribution — oversold_pct, overbought_pct, neutral_pct, universe_size
indices: SPY, QQQ, IWM prices + RSI + 1-week performance
bonds_commodities: TLT (long-duration bonds), GLD (gold)
updated_at: when the 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 and idempotent. The description adds 'No AI cost — reads live data directly from the market data feed', which is meaningful cost/data-source context beyond annotations. It also details return fields, adding practical transparency.
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 structured with a bullet list of return fields, making it readable. It is somewhat lengthy but each element adds useful context (e.g., explanations of indicators).
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?
With no parameters, comprehensive annotations, and an output schema, the description fills remaining gaps: it explains the nature of the data, cost implications, and tier availability. It is complete for a simple read-only snapshot tool.
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 has zero parameters, so there is nothing for the description to explain. The baseline for 0 params is 4, and the description appropriately focuses on the output rather than inputs.
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 clearly states it is a 'live market health snapshot' that aggregates key indicators, making the purpose specific. It does not explicitly name sibling tools like get_market_assessment, so it slightly misses full sibling differentiation.
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 clear context for when to use ('without requiring multiple tool calls', 'No AI cost') but does not explicitly state when not to use or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top AI-flagged news across all tracked stocks — the market-wide news briefing. Unlike get_stock_news (per-symbol), this scans the entire universe and returns the most notable articles ranked by signal_score, newest first within each score tier.
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) used to SELECT
articles server-side. Resolved per-article (stored/computed magnitude
preferred over an unfiltered Mongo $gte, since a formal live signal
doesn't exist for every article — see signal_score below), then
filtered/sorted in Python.
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 (full text), signal_score (0-100), signal_score_band (Weak/Moderate/Strong/ Very Strong)
signal_score/signal_score_band: this symbol's LIVE signal score if a news-sourced signal was raised for it in the last 90 days (same number get_stock_news()/get_signals() report, kept in sync as that signal is re-scored — one $in query per distinct symbol in the result, not per article, so two articles about the same stock always show the same value); otherwise a per-article magnitude computed from THIS article's own sentiment/confidence/flag_score, so every article still gets a real, rankable number. Always a single number — for a symbol whose live signal is genuinely two-sided (real opposing bull/bear theses), this is the STRONGER of the two sides, same as get_signals()/get_stock_news(). There is deliberately no separate "news_score" field — one name for "how strong is this idea," whether it's backed by a formal signal or just this article's own classification.
Pro tier only — AI pipeline cost attached. 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 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already signal safety, and the description adds extensive behavioral context: how signal_score is resolved (live vs per-article), the per-symbol query optimization, the two-sided signal handling, and the lack of a separate 'news_score' field. This goes far beyond annotation hints and is highly informative.
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?
Though long, the description is well-structured: purpose, usage bullets, parameter details, output fields, scoring explanation, and restrictions. Every section provides necessary information without redundancy. The complex signal_score logic is essential and justified.
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 description covers everything an agent needs: what is returned, how parameters are resolved, the ranking method, the performance note (one $in query per symbol), the tier restriction, and a disclaimer. No critical details are missing given the tool's complexity.
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 meaningful nuance for min_signal_score, explaining the per-article resolution logic and why it's needed. For days and limit, it only repeats schema info, but the extra for min_signal_score justifies a 4.
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 clearly states the tool's function: 'Top AI-flagged news across all tracked stocks'. It explicitly differentiates from sibling get_stock_news ('Unlike get_stock_news (per-symbol)'), making the purpose unambiguous and distinguishing it from similar tools.
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 concrete use cases ('Morning briefing', 'Catalyst scanning', 'Event monitoring') and contrast with get_stock_news, which implicitly tells when not to use it. It also notes the Pro tier cost, guiding the agent on when the tool is appropriate.
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
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 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 — 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, pe_forward, rsi, macd_signal, sma200_trend, analyst_rating. 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 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. | |
| 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 dollars. | |
| min_market_cap_b | No | Minimum market cap in billions of dollars. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and idempotent annotations, the description discloses meaningful behavioral details: each returned stock counts toward the daily limit, pro-tier parameters are 'silently ignored' or 'silently fall back' for free/guest tiers, and the high_conviction preset changes the default sort. It also traces the history of the renamed min_ai_score parameter, which is valuable context that annotations cannot provide.
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 the complexity of an 18-parameter screener with tiering and presets justifies the length. It is front-loaded with a clear one-line purpose, and parameters are grouped readably. A few passages, such as the min_ai_score provenance note, are dense but earn their place by preventing confusion with a similarly named field.
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, the description is remarkably complete: it covers all filters, preset behaviors, tiered availability, silent fallbacks, return shape, quota semantics, and the recommended follow-up tool. The presence of an output schema means return values need not be restated, and the description fills the behavioral gaps around tiers and counting.
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?
Although the schema already documents 100% of parameters, the description adds substantial semantics: concrete examples for RSI bounds, performance percentages, volume, market cap, and P/E; preset definitions; tier-gated behavior; and the note that high_conviction defaults sort_by to ai_score. This goes well beyond the baseline set by schema descriptions.
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 and resource: 'Filter and rank stocks from the Stocklake universe' and immediately distinguishes this as a multi-factor screening tool covering 'fundamentals, technicals, and AI signals'. This clearly separates it from siblings like get_stock (single stock), get_market_movers, or get_signals.
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 provides clear context for when to use the tool — for filtering and ranking across the universe — and explicitly directs users to a specific sibling: 'For the full research bundle on any one result, call get_stock_research(symbol).' It does not comprehensively compare against all possible sibling tools, but the guidance is concrete and actionable.
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)
Refreshed every ~4 hours by the market intelligence pipeline. 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by disclosing the ~4-hour refresh cadence, pro-tier restriction, and informational-only disclaimer. It also clarifies parameter scope (single vs all-sectors). No contradictions with 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?
The description is moderately sized but well-structured: it opens with the core purpose, then explains parameters in a bulleted list, followed by operational details. It is front-loaded with the main behavior and prioritizes the most critical information. A bit verbose in places, but every sentence earns 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?
Given the tool has an output schema (not shown here), the description explains the returned data components, parameter nuances, refresh frequency, access tier, and disclaimer. It covers all necessary aspects for an agent to call it correctly. Nothing critical 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%, so the input schema already documents each parameter thoroughly. The description restates the parameter behavior (e.g., 'only applies to all-sectors call') but does not add new meaning beyond what the schema provides. Thus 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?
The description clearly states the tool provides AI-assessed sector intelligence with specific components like signal, cycle stage, rotation signal, drivers, alerts, and computed statistics. It differentiates from sibling tools by focusing on sector-level analysis. The verb 'get' is paired with the resource 'sector intelligence', and the dual mode (single vs all sectors) is explicit.
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 clear guidance on when to pass a sector name versus omit it, and explains the all-sectors call as a rotation view. It also notes the sort_by_strength and history_count parameters are only for the all-sectors call. However, it does not explicitly contrast this tool with alternatives like get_market_assessment or get_signals, so the when-not-to-use guidance is implied rather than stated.
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). This reflects what the AI pipeline found,
not whether Stocklake's own internal trading engine still holds it live —
a signal it later dropped or let expire is still shown here, since that's a
fact about our own trading state, not about the signal's informational value.
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 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. Always compared against a single number, including for NEUTRAL/two-sided ideas — a result is never returned below your threshold on both sides.
min_conviction, min_flag_score: DEPRECATED, ignored for filtering — kept in the signature only so existing callers don't hard-fail; ai.stocklake.dev's 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.
source: filter by signal source — "news" | "screener" | "sentiment" | "social" (default: all)
limit: max results to return (default 50, 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 50, max 50). Each returned signal counts as one call toward your daily limit. | |
| source | No | Filter by signal source: "news" | "screener" | "sentiment" | "social" (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_conviction | No | 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. | |
| min_flag_score | No | 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. | |
| min_signal_score | No | 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: signals that were later dropped or expired are still shown, the fallback to most recent signals, the Pro tier cost implication, and a clear 'not financial advice' disclaimer. No contradiction with annotations; in fact it complements them.
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 longer than minimal but is well-structured with clear sections and bullet points. It front-loads the core purpose, then covers parameters and returns logically. No redundant or vague sentences—every sentence adds information, including the deprecation note and disclaimer. It earns its 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?
The description includes return fields with their types and meanings, all parameter defaults and ranges, deprecation status, fallback behavior, cost implications, and a disclaimer. Even though an output schema exists, the description fully documents what the agent needs to call the tool correctly and interpret results. Nothing essential 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% with detailed parameter descriptions, so baseline is 3. The description adds meaningful value beyond the schema: it explains the NEUTRAL direction's dual meaning (flat vs two-sided) and how signal_score is compared for two-sided ideas, elaborates on the deprecated fields' effect, and clarifies the semantics of signal_score as a composite. This extra nuance justifies a 4.
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 verb and resource: 'AI-screened stock signals recently surfaced by the Stocklake pipeline' with explicit sources (news analysis, sector screening, sentiment). It clearly distinguishes itself from siblings like get_market_movers or get_news_feed by focusing on pipeline-flagged signals rather than raw market data or news. The purpose is unambiguous.
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 explains when to use it (to see what the AI pipeline noticed in the last 24 hours) and clarifies that it reflects pipeline findings, not internal trading state — a key usage nuance. It also notes the fallback behavior for empty 24h windows. However, it does not explicitly contrast with any specific sibling tool or state when not to use it, leaving some inference to the agent.
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, 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 6 more specialized indicators inside the SAME indicators block
(williams_r, ultimate_osc, vix_fix, williams_ad, td_sequential, elliott_wave -- the
Larry Williams family, DeMark TD Sequential, and Elliott Wave) -- these are omitted
entirely from the free/guest response (tier-gating sweep, 2026-08-28), 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 a live AI call:
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. bearish 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): stock_ai_summary.py's own composite score, on the same 0-100 scale and band boundaries as get_signals()'s signal_score — but a different pipeline/collection, 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 (Yahoo's own longer-window beta calculation) — this is computed fleet-wide 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).
| 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?
Annotations already mark this as read-only/idempotent, and the description adds substantial behavioral detail: tier-gated omission behavior, precomputed vs. live data, null-vs-omitted conventions, pipeline differences between get_signals and this tool, and conditional availability of relative_strength and market_risk. This goes far beyond 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?
The description is long but well-organized with a clear lead sentence, grouped field lists, and tier-based sections. It is front-loaded with purpose and scope. A few illustrative asides and repeated pipeline-explanation details go slightly beyond what is strictly necessary, so it is not maximally concise.
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, one parameter, rich annotations, and available output schema, the description is exceptionally complete. It covers tiering, field semantics, null handling, alternative tool routing, and distinctions between computed values, leaving little for an agent to guess.
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 only parameter, symbol, is fully documented in the input schema including the company-name fallback. Schema coverage is 100%, so the description adds no additional parameter-level meaning. Baseline 3 is appropriate because the schema carries the burden.
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 sentence names a specific resource ('a stock') and a precise scope: price, fundamentals, technical indicators, and company profile. It explicitly contrasts itself with get_stock_research and get_signals, so an agent can distinguish this snapshot tool from its siblings.
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 clearly states this is the single-call source for understanding a stock, and explicitly directs the agent to get_stock_research for the full narrative bundle. It also documents tier-based availability, giving conditions under which the same tool returns different or additional content.
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, max 365)
Returns: { symbol, days_requested, days_returned, count, history[] } — days_returned/count can be less than days_requested if less history exists
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). 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 readOnlyHint, destructiveHint, and idempotentHint, so safety traits are covered structurally. The description adds meaningful behavioral detail beyond those annotations: it explicitly warns that days_returned/count may be less than requested due to insufficient history, describes the exact response shape (including per-bar fields), and notes the default and max days. This transparency about partial results is valuable and not inferable 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?
The description is extremely efficient: a single opening sentence identifies the purpose, followed by three short bullet lines that add parameter details and return structure. Every sentence earns its place—no filler, no repetition of the title or annotations. The critical caveat (days_returned may be less) is given prominence. Structure is front-loaded and logical.
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 is a straightforward historical data retriever with an output schema, the description covers nearly everything an agent needs to call it correctly: purpose, parameter details, response shape, and the partial-data caveat. The only significant omission is usage guidance versus siblings, which is a separate dimension. The output schema covers the return types, so the description doesn't need to explain those further. Overall, it's complete for the mechanics, but missing selection context.
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% (both parameters are described in the schema), so the baseline is 3. The description enhances semantics beyond the schema: for the 'symbol' parameter it adds 'Also accepts a company name as a fallback when it uniquely resolves to one symbol,' which is not in the schema description. It also re-emphasizes the max days and the potential for a shorter response. This extra meaning justifies a score above baseline.
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 clear verb and resource: 'Daily OHLCV price history for a stock.' It's distinct from siblings like get_stock or get_indicator_history in that it focuses on historical price bars, but it doesn't explicitly name sibling alternatives or differentiate itself. For example, it doesn't say 'for technical indicators use get_indicator_history.' Thus, clarity is high but differentiation is implicit at best.
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 no guidance on when to use this tool versus the 16 siblings. It doesn't mention typical use cases, nor does it exclude variants like intraday or adjusted prices. There's no 'use this when you need historical daily bars' or 'for earnings use get_earnings_calendar.' The context signals and sibling list are present but not leveraged in the description. This is a clear gap for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI-analysed news for a stock, newest first. Only returns articles processed by our AI pipeline (sentiment, signal_score, summary).
days: look-back window in days. Requesting more than your tier's cap is silently clamped down to it: 30 free/guest, 90 pro.
limit: max articles returned. The limit=10 default 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.
status: "ok" = articles returned | "empty" = no news in window
Per article: title, published_at, ai_sentiment, ai_summary (full text) — Pro only, see below
signal_score (Pro only, 0-100 or null) / signal_score_band (Pro only, string or null — "Weak"/"Moderate"/"Strong"/"Very Strong"): if this symbol has a live news-sourced signal (raised in the last 90 days), every article shows that SAME number — the same one get_signals()/get_stock_research() report for this symbol (all three read the same underlying signal, via the same shared resolver), staying live/synced: if the signal is later re-scored, this reflects the update on your next call, not a frozen snapshot from classification time. Always a single number (never a two-sided split) — for a genuinely contested (two opposing theses) signal, this is the STRONGER of the two sides. NOT gated on whether Stocklake's own internal trading engine still considers the signal live — a dropped/expired signal is still a real, useful fact about what the pipeline found. When there's no live signal for this symbol at all, each article instead gets its OWN per-article score (computed from that article's sentiment/confidence/flag_score) — the same fallback get_stock_research()'s news[] block uses, so a symbol with no active thesis doesn't just go null across the board; different articles for the same symbol can then legitimately show different numbers. Null only when neither path can produce a value (article has no AI sentiment/confidence/ flag_score at all). There is deliberately no separate "news_score" field — one name, kept in sync with the signal when one exists, computed per-article when it doesn't. Free tier: up to 5 articles, title + published_at only (no AI fields), 30-day window. Pro tier: up to 50 articles with full AI fields, 90-day window. For informational purposes only. Not financial advice.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days. Requesting more than your tier's cap is silently clamped down to it: 30 free/guest, 90 pro. | |
| limit | No | 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. | |
| 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 mark this readOnly, idempotent, and non-destructive, so the extra work is context. The description adds essential behavior: silent clamping of days/limit by tier, the Pro-only gating of AI fields, the single-number signal semantics (stronger side wins, re-scored live), the per-article fallback when no signal exists, and the explicit null-only-when-neither-path-produces-a-value rule. These are exactly the non-obvious behavioral facts an agent needs.
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 dense and highly informative, but the signal_score section is long and somewhat repetitive, with paired clarifications (the same resolver, the same fallback, the same number) that could be tightened. It is front-loaded with the core purpose and key behavior, but the later paragraphs could be trimmed without losing 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?
The output schema is present, so return-value details need not be fully spelled out; the description covers the important return semantics (status values, tier differences, signal_score behavior) and the tool's place among siblings. It omits exact output field naming for non-signal per-article fields, but the output schema plus the description's mention of title, published_at, ai_sentiment, ai_summary, and signal_score fields is sufficient for 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 schema already documents all three parameters. The description adds value beyond the schema by clarifying the real-world effect of clamping (a free caller passing no limit gets 5, not 10) and by explaining signal_score fallback semantics. It doesn't repeat plain schema text; it enriches it with behavioral implications.
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 crisp verb+resource statement — 'AI-analysed news for a stock, newest first' — and immediately narrows scope to articles processed by the AI pipeline. The free/Pro tier contrast and explicit naming of fields distinguishes it clearly from siblings like get_news_feed and get_stock_research.
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 tier system and clamping behavior tell the agent when the tool is appropriate and what constraints apply. It references the shared signal resolver linking to get_signals()/get_stock_research(), which helps an agent choose among related tools, though it does not explicitly say 'use this instead of X when Y'.
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 — stock_ai_summary.py's own composite, same scale/band convention as signal_score but a distinct field/pipeline), 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 LIVE
news-sourced signal score if one exists in the last 90 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.)
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 5 most recent trade signals for this symbol in the last 90 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. Recency-gated, not gated on whether Stocklake's own trading engine still holds the signal live — a signal it dropped or let expire is still a real, useful fact about what the pipeline found, so it stays in this list rather than disappearing the moment our own paper trader moves on.
All data is pre-computed by the Stocklake AI pipeline — no live 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 readOnlyHint/idempotentHint/non-destructive. The description adds substantial context beyond that: 'All data is pre-computed by the Stocklake AI pipeline — no live AI calls on request' (latency/cost profile), 'Pro tier only' (access), and nuanced result semantics like signals being 'recency-gated, not gated on whether Stocklake's own trading engine still holds the signal live' and the null fallback for pre-schema summaries. This materially changes how an agent should interpret 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?
The description is long, but every sentence carries operational value — cross-tool scale/sync conventions (ai_score vs signal_score), null-fallback logic, gating rules, and disclaimers. It is front-loaded with purpose and replacement info before the return breakdown, and uses clear bulleted sections. Length is justified by the five-domain output and the ambiguity it resolves, though it edges toward the upper limit.
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 one-parameter tool whose output aggregates four distinct source tools with cross-tool consistency guarantees, the description is thorough: it explains the sync semantics of signal_score across news/sentiment/signals, the fallback behavior for pre-schema fields, the recency gating, and the version-shipped nulls. The existence of an output schema offloads return-value shape, so the description's job of explaining semantics is fully met.
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% and the single 'symbol' parameter is already well-described in the schema ('Stock ticker symbol to fetch the full AI research bundle for'). The description repeats the one-parameter nature but adds no new syntax or format guidance beyond what the schema provides, so it sits at the baseline for high-coverage schemas.
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 line states a specific verb+resource: 'Full AI research bundle for a stock in one call.' It enumerates the exact data domains (fundamentals, AI summary, news, insider/institutional signal, trade signals) and explicitly names the four sibling tools it replaces (get_stock + get_stock_news + get_insider_activity + get_signals), which provides crisp differentiation against the 16 siblings.
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 says exactly when to use this over alternatives: 'Replaces 4 separate calls' — an explicit routing hint. It also flags the Pro-tier access constraint. The one gap is the lack of an explicit 'use the single-domain call if you only need one type of data' exclusion, but the replacement framing makes the trade-off clear enough.
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}, and the minimum AI-narrative slice (ai_verdict, ai_headline, ai_score, ai_score_band). None of this costs a live AI call — 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?
Beyond the readOnly/idempotent/destructive hints, the description reveals important behaviors: missing symbols are omitted, duplicates are collapsed, each symbol counts toward a daily limit, requests over 25 are rejected (error: batch_too_large), and tier-dependent fields. The duplicate normalization details and invariant equation add depth. No contradiction with 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?
The description is structured and every sentence earns its place. It front-loads the core purpose, then details tier differences, what is excluded, and response behavior — all essential information without fluff.
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 (batching, normalization, tier differences, error handling, response shape), the description is remarkably complete. It covers the return dict keyed by symbol, missing/duplicate handling, per-symbol quota, and explicitly mentions what is not included and where to get it. The invariant equation is a definitive check.
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?
Although the schema already describes the symbols parameter at 100% coverage, the description adds substantial semantics: normalization rules, duplicate collapsing, omission of missing symbols, and the invariant involving requested, missing, and duplicates_collapsed. These details are not in the schema and greatly clarify how the parameter is processed.
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 'Batch stock data for up to 25 symbols in a single call' — a specific verb, resource, and scope. It explicitly states this is the same as get_stock but batched, not a thinned-down scan, clearly distinguishing it from siblings like get_stock and get_stock_research.
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 explicitly tells the agent when NOT to use this tool: for stance_signals call get_stock, for full AI summary call get_stock_research. It also provides guidance on splitting large lists into multiple calls, leaving no ambiguity about batch limits.
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 live 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful behavioral context: it returns an empty items[] array when nothing is starred, includes a pro-tier gate, and provides a disclaimer. These details go beyond the annotations without contradicting them.
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 well-structured: a one-sentence purpose, a bulleted list of return fields, and a note on empty behavior and pro tier. It is front-loaded with the key point, uses bullet points for readability, and contains no filler. Every sentence earns 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 zero-parameter tool, the description is fully comprehensive. It details the output structure (including fields, types, and ranges), explains the empty case, specifies the pro-tier requirement, and provides a disclaimer. The output schema further enriches this, but the description itself is sufficient for an agent to call the tool correctly without external context.
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 coverage is 100% (empty properties). Since there are no parameters to explain, the description does not need to add parameter semantics. The baseline for no parameters is 4, and the description correctly focuses on the output and usage.
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 and resource: 'The caller's Stocklake watchlist (starred symbols from the web dashboard)'. It immediately distinguishes this from the sibling tools (e.g., get_market_movers, get_stocks) by focusing on the personal watchlist. The enrichment details ('live price, technicals, and AI verdict') further clarify the scope.
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 provides clear context: it is specifically for the caller's own watchlist, and it notes the 'Pro tier only' requirement. It also gives an explicit fallback for the empty case ('star symbols at stocklake.dev/dashboard'). However, it does not name any alternative tools or state when not to use it, leaving the agent to infer that this is the go-to for the watchlist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Most tools have clearly distinct targets—single stock, batch, news, history, insider activity, screener, market pulse, and so on. The closest pairs are get_earnings_calendar vs get_earnings_intelligence and get_market_assessment vs get_market_pulse, which overlap in raw inputs but differ in AI interpretation; the descriptions provide enough clarification to avoid serious misselection.
All 17 tools follow a consistent get_<resource> snake_case pattern, with hierarchical names like get_stock, get_stocks, get_stock_news, get_stock_history, and get_stock_research making related resources obvious. There are no mixed naming conventions or vague verb choices.
At 17 tools, the set is slightly above the ideal range, but the scope is broad and each tool has a plausible role in an AI stock intelligence workflow. The convenience aggregations like get_stocks and get_stock_research add some redundancy but remain purposeful rather than bloated.
The surface is comprehensive for a read-only AI stock intelligence domain: single-stock fundamentals and technicals, batch lookups, price history, per-stock and market-wide news, insider activity, screening, market pulse, macro assessment, sector intelligence, earnings, signals, and watchlist enrichment. No major operational dead ends are apparent.