Stocklake — AI Stock Intelligence

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only/idempotent annotations, the description discloses important behavior: released items always have actual values, upcoming items never do, diff is a plain arithmetic difference with no consensus judgment, key_event is only an event-type flag, and sorting is major-economy-first. It also flags Yahoo's reporting lag and source-exposure caveats.

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 but every sentence earns its place: purpose, source rationale, bucket invariants, filter semantics, sorting behavior, and tier restrictions are all covered without repetition. The front-loaded opening gives immediate clarity, and the structured sections make it 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?

Given an output schema exists and all 5 parameters are documented in the schema, the description covers the remaining contextual ground fully: bucket semantics, value guarantees, filtering options, sorting behavior, reporting lag, and source caveats. Nothing an agent needs to safely invoke 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?

Schema coverage is 100%, so the baseline is a 3, but the description adds meaningful semantics beyond the schema: days defines the upcoming window, lookback_days defines the released window with a reporting-lag rationale, limit applies per bucket, and key_events_only/major_only map to described filtering behavior. This helps an agent use the parameters correctly in context.

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 ('get') and resource: upcoming and recently-released macroeconomic events, listing concrete event types like CPI, GDP, PMI, and payrolls. It clearly distinguishes itself from earnings-calendar and other financial-data siblings by focusing on macro/economic events.

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 makes the intended use explicit: retrieving macro/economic event calendars, with filters like key_events_only and major_only for narrower use cases. It also gives clear context about the data source and Pro-tier restriction, though it does not explicitly name when to use a sibling tool instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark readOnly, idempotent, and non-destructive; the description adds substantial behavioral detail beyond that: source collection, daily population, max/default days, empty-response edge case ('Returns {} if fewer than 3 snapshots found'), full-mode behavior, and access restriction ('Pro tier only'). This is rich 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 long but well organized with a front-loaded purpose statement followed by scannable field bullets. Minor redundancies like 'daily' appearing multiple times are acceptable given the valuable field-level semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the essential operational details: parameter behavior, defaults and limits, edge-case return, access tier, and full vs. base mode. With an output schema present for return structure, the description is complete for an agent to call this tool correctly.

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%, but the description adds meaning beyond the schema by interpreting indicator values ('positive = bullish momentum', '0 = at lower, 100 = at upper band'), explaining the difference between base and full mode, and noting that full mode 'roughly double[s] response size' while some fields 'barely change day to day.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Historical daily indicator snapshots for a stock — ideal for charting and trend detection.' The focus on indicator snapshots clearly distinguishes it from sibling price-history or market tools like get_stock_history, even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: 'ideal for charting and trend detection' and notes 'Pro tier only.' It does not explicitly name alternatives or state when not to use this tool, but the intended use case is explicit enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, and the description is fully consistent with them. Beyond annotations it adds rich behavioral context: the ~4x/day weekday-only refresh cadence with an explicit 'dead overnight and on weekends, not a continuous 4-hourly cadence' correction, the >72h stale threshold that deliberately tolerates a normal Fri→Mon gap, the shared-pipeline sync guarantee, macro_score being null on pre-2026-08-26 assessments, and the point-in-time snapshot vs live distinction. This is exactly the kind of context structured fields cannot 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 key usage guidance and staleness caveats are front-loaded before the field reference, and the two-perspective framing is clearly sectioned with bolded bullet groups. However, it is long — effectively a mini API reference covering every field. Given the tool's genuine complexity (two perspectives, many subtly distinct fields like macro_score vs risk_appetite_score), most sentences earn their place, but it could be tightened without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity tool, this is complete. It covers refresh cadence, staleness semantics with the weekend exception, Monday-morning handling, field-by-field meaning, the macro_score/risk_appetite_score distinction, the trend-field rationale, the point-in-time vs live caveat, and the cost tier. An agent has everything needed to call it correctly and interpret results accurately — the output schema handles return structure while the description handles semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage on the single history_count parameter, the baseline is 3. The description adds genuine value beyond the schema: it clarifies 'last N prior assessments for each' (matching the schema's per-assessment semantics) and explains that macro_score_trend is 'computed automatically (no history_count needed)' — resolving a likely confusion about whether history must be requested. That marginal but real clarification 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?

Opens with a specific verb+resource: 'Combined AI market assessment: macro regime + market outlook in a single call.' It explicitly defines the two perspectives returned (REGIME answering 'how much equity risk to take' and OUTLOOK answering 'which direction and sectors to trade'), and later distinguishes itself from get_market_pulse ('not live prices (use get_market_pulse for live)'). An agent cannot confuse this with any of the 18 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?

Gives explicit decision guidance per perspective: use REGIME 'for position sizing and asset allocation decisions' and OUTLOOK 'for sector preference and directional bias.' It states when NOT to treat results as current (stale flags, Monday morning caveat), names the live-prices alternative (get_market_pulse), and flags the Pro-tier/cost constraint. This is actionable routing, not just a tagline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and non-destructive. The description goes well beyond by explaining how signal_score is computed (live signal vs per-article magnitude), the per-article resolution, the 'stronger of two sides' behavior, and the cost attached to the AI pipeline. It also clarifies that there is deliberately no separate news_score field, a nuance an agent needs to interpret results correctly.

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: purpose first, then use cases, then parameters, then deep signal_score explanation. It is verbose but every paragraph adds necessary context (cost, pro-tier, behavioral details). The use of bullet points and section headers aids scanning. It could be tightened, but it is not padded; complexity justifies the 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?

Despite having an output schema (which presumably lists fields), the description explicitly enumerates per-article fields (symbol, title, published_at, ai_sentiment, ai_summary, signal_score, band) and explains all behavioral aspects an agent would need to call it correctly: selection logic, ordering, cost implications, and constraints. Nothing important is omitted; the tool is fully self-contained.

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 depth for min_signal_score, explaining that it is resolved per-article (live signal preferred) and that the server-side selection uses Python filtering rather than a naive $gte. This helps an agent understand the exact ranking and filtering semantics beyond the schema's terse wording. Days and limit are straightforward but still given bounded defaults in the 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 scope: "Top AI-flagged news across all tracked stocks — the market-wide news briefing." It immediately contrasts with get_stock_news (per-symbol), making the distinction explicit. No ambiguity about what this tool does or how it differs from 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?

Lists exact use cases (morning briefing, catalyst scanning, event monitoring) and explicitly contrasts with get_stock_news. It also states the tool is Pro-tier only and for informational purposes — clear constraints on when to use it. No exclusions are left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: refresh cadence (~4x/day weekdays during market hours, not continuous), staleness risk overnight/weekends, pro-tier gating, sector_score semantics (continuous 0-100, comparable across sectors, null pre-2026-08-26), and the explicit 'Not a buy/sell call' disclaimer. 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 long but information-dense and front-loaded: the core purpose and the single-vs-all decision come first, then parameter semantics, then refresh/availability caveats. Every sentence earns its place; the bulleted parameter explanations are scannable. Slightly verbose in the sector_score explanation, but justified given the semantic subtlety.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only intelligence tool with an output schema, the description covers the key operational facts an agent needs: how to request single vs all sectors, how to rank by strength, how to get trend context, refresh cadence, staleness caveats, and access restrictions. The output schema handles return-value details, so 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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it explains that sector_score is a continuous 0-100 read underlying the 5 discrete signal buckets, that sector_score_trend is single-sector-only and distinguishes two sectors with the same score, and that history_count/sort_by_strength are all-sectors-only. It doesn't exhaustively document every output field, but the schema already does that.

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 precise verb+resource statement: 'AI-assessed sector intelligence' enumerating signal, cycle stage, rotation signal, drivers, alerts, and computed statistics. It clearly distinguishes the single-sector call from the all-sectors rotation view, and the sibling list shows no overlapping tool that does sector intelligence, so an agent can select it confidently.

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 explicitly tells the agent when to pass a sector name vs omit it, and frames the all-sectors call as the rotation view with sort_by_strength for LEADING-first ranking. It also states refresh cadence, weekday/market-hours limitations, pro-tier availability, and the caveat to check updated_at — all concrete usage guidance beyond the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it read-only, idempotent, and non-destructive; the description adds substantial behavioral detail: the 24h window with fallback, retention of dropped/expired signals, deprecated parameters ignored and logged, and daily-limit counting. 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 front-loaded with purpose, then organized into clear parameter and return sections. The length is justified by genuinely complex semantics, and every sentence serves a purpose with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all six parameters, output fields, fallback/window semantics, access constraints, deprecation behavior, and disclaimers. With an output schema present and annotations carrying the safety profile, nothing needed to invoke 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?

Even with 100% schema coverage, the description adds real meaning: the NEUTRAL two-sided interpretation, signal_score as the single filter number even for two-sided ideas, deprecation behavior of min_conviction/min_flag_score, and limit's per-call counting. This significantly improves parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: returns AI-screened stock signals surfaced by the Stocklake pipeline, sourced from news analysis, sector screening, and sentiment. The 'last 24 hours' and 'AI pipeline found' framing clearly distinguishes it from sibling tools like get_screener, get_news_feed, and get_market_movers.

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: read-only, Pro-tier, 24-hour recency with fallback, and signals shown even if the internal engine dropped them. It stops short of a 5 by never explicitly naming sibling alternatives or stating when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnly/idempotent annotations by disclosing tier-gating behavior, omission semantics ('these are omitted entirely from the free/guest response... not merely unlabeled'), null conventions ('score: null means genuinely not computable'), and the fact that forensic scores are raw accounting-model output with no trading signal derived. It also distinguishes its computed beta from Yahoo's beta, which prevents misinterpretation.

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 long and contains some redundant or implementation-specific details, such as duplicating the ai_score explanation and including the 'tier-gating sweep, 2026-08-28' note. It is well organized with bullet lists and front-loaded key fields, but it could be trimmed without losing essential guidance.

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 enumerates return fields, distinguishes free vs Pro response shapes, explains omission/null behavior, names the alternative research tool, and clarifies which values are computed differently from other sources. With an output schema reported present, nothing essential is missing for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the only parameter, symbol, is already well described in the schema with ticker and company-name fallback behavior. The description adds no additional parameter-level semantics beyond framing the call as a single-snapshot request, so the baseline of 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?

The description clearly states the tool's purpose: 'Price, fundamentals, technical indicators, and company profile for a stock' and says it 'Returns all data needed to understand a stock in a single call.' It also distinguishes itself from the sibling get_stock_research by explicitly naming that tool as the only one with the complete research bundle.

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 routing guidance: for full AI narrative and cross-source news/insider context, call get_stock_research(symbol) instead. It also clarifies tier availability, noting that free/guest responses get only the basic six indicators while Pro unlocks additional blocks, and it stresses that all five Pro blocks are precomputed with no live AI cost.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: the exact output shape, Yahoo's real period ceilings, missing-line-item semantics (absence means not reported, not an error), and the possibility of quarterly returning null or the entire financials block being absent. This goes well beyond what annotations 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 front-loaded with the core purpose and differentiator, then uses compact paragraphs for shape, period behavior, and caveats. Despite its length, nearly every sentence carries essential operational information, and the structure 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 tool is complex, but the description covers output shape, period limits, per-line-item organization, data-availability caveats, non-equity symbols, and Pro-tier restriction. An agent has all the context needed to decide whether and how to call this tool correctly.

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 further enriches parameter meaning by explaining what 'annual' and 'quarterly' actually return, including real-world ceiling caveats and the behavior of missing periods, which the schema alone does not state.

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: 'Full raw financial statements — balance sheet, income statement, and cash flow line items over multiple periods.' It further differentiates itself from get_stock()'s forensic_scores block, making the tool's unique purpose unmistakable.

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 explicitly names get_stock() as the alternative when derived forensic scores are needed, and clearly states this tool returns the underlying statement data instead. It also provides concrete exclusions: no data for ETFs/crypto/forex/indices, and quarterly may be null for some symbols.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds substantial behavior beyond them: silent clamping of days/limit to tier caps, tier-gated field availability, the live/synced (not frozen snapshot) signal semantics, the no-gating on Stocklake's internal trading engine, the per-article fallback score path, and the deliberate absence of a separate news_score field. No contradiction with annotations; 'For informational purposes only' reinforces the read-only profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is efficiently front-loaded, but the signal_score block is one dense, run-on paragraph with heavy nested parentheticals (last-90-days, shared resolver, internal-engine caveat, fallback path), making it hard to parse. Clamping and tier facts are also restated three times — in the days/limit text and again in the closing 'Free tier/Pro tier' summary — adding redundancy to an already long definition.

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 genuinely complex tool (tier-dependent clamping, shared-signal freshness semantics, per-article fallback), nothing an agent needs to call it correctly is missing — edge cases like null-when-neither-path-produces-value are explicitly handled. Since an output schema exists, the extensive per-article field explanation is a bonus, though slightly over-explains what the schema could carry. Slight over-reach rather than under-specification.

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% — the days/limit descriptions in the schema already carry the exact clamping and tier-cap text the description repeats verbatim. The description adds the status enum ('ok'/'empty') and per-article field narrative, but those concern the return shape, which an output schema exists to cover. On parameters themselves the description is essentially duplicative, placing it at 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 opening line 'AI-analysed news for a stock, newest first' states a specific verb, resource, and distinctive qualifier. The qualifier 'AI-analysed' plus 'Only returns articles processed by our AI pipeline' cleanly separates it from a raw feed like get_news_feed, so an agent can disambiguate 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 implies usage through the 'AI-analysed' framing and explains that signal_score/signal_score_band are the same values get_signals()/get_stock_research() report via a shared resolver, which orients the agent to data relationships. However, there is no explicit when/when-not routing — it never says 'use get_news_feed for raw articles' or 'use get_signals for standalone signal data.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as read-only and idempotent, but the description adds substantial behavioral detail beyond annotations: data is pre-computed with no live AI calls, null and fallback behavior is documented, signals are recency-gated rather than live-position-gated, and specific field semantics are clarified. No contradictions with annotations exist.

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 with a front-loaded summary and clearly delineated return blocks. Most sentences carry meaningful caveats or semantics that would otherwise be missing, though some asides could be tightened without losing value.

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 complex bundle tool with one parameter and an existing output schema, the description is exceptionally complete: it explains return-field semantics, null behavior, score conventions, recency gating, legacy data fallbacks, and access restrictions. An agent has all the context needed to invoke it correctly and interpret its results.

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 schema already fully documents the only parameter, symbol, at 100% coverage. The description refers to fetching for 'a stock' and 'one symbol' but does not add new parameter-level meaning beyond the schema 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 immediately identifies the tool as a comprehensive one-call research bundle for a stock, with a clear verb ('get') and resource ('full AI research bundle'). It explicitly names the four sibling tools it replaces, making differentiation trivial.

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 states this tool replaces get_stock, get_stock_news, get_insider_activity, and get_signals for one symbol, so an agent knows when to prefer it over these alternatives. It does not explicitly state exclusions like 'use the individual tools if you only need one data type,' but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the 'Pro tier only' restriction and the 'For informational purposes only. Not financial advice' disclaimer, plus the personalization to the caller. It also describes the return payload. 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 moderately long but well-structured: a purpose sentence, a 'Returns:' list, an empty-case note, and a tier/disclaimer. No wasted words, though the disclaimer could be considered boilerplate. It is appropriately front-loaded with the core purpose.

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 there are no parameters, the description fully covers what an agent needs: the data source (caller's watchlist), the fields returned, the empty-case behavior, the Pro tier requirement, and the disclaimer. The output schema exists separately, so no need to detail return values further. It is complete.

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 and the input schema is empty, so there is nothing to explain. Per rubric, 0 parameters warrants a baseline of 4. The description compensates by detailing the output structure, which is highly relevant.

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 identifies the resource ('the caller's Stocklake watchlist') and the enrichment ('live price, technicals, and AI verdict'). It is distinct from all 16 siblings, none of which relate to watchlists. The purpose is unambiguous and specific.

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 context is clear: it returns the caller's personal watchlist, which implies use when the user's own watchlist is needed. It notes 'Pro tier only' as a prerequisite but does not explicitly state when not to use or alternatives. Since no sibling offers watchlist data, explicit exclusions are unnecessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.