Stocklake — AI Stock Intelligence

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

Annotations already signal read-only and idempotent behavior, and the description adds meaningful operational context: results are sorted by earnings_date ascending, and is_estimate=true dates should be treated as approximate due to market data sourcing. This goes beyond the annotations and helps the agent 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 tightly organized as a bullet-point spec with the core purpose first, followed by parameter and return details. Every line adds useful information, and there is no filler or redundant 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?

The description covers the parameter, the exact return envelope, field meanings, sorting order, and the reliability caveat for estimated dates. It also mentions availability. Given the provided output schema and annotations, nothing important is missing for an agent to invoke this tool and interpret its response.

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 describes days fully, including its default and maximum, so the description adds little to parameter understanding. The description repeats the same semantics rather than enriching beyond the JSON Schema. A baseline 3 is appropriate because schema coverage is complete.

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 exactly what the tool returns: 'Upcoming earnings dates for stocks in the Stocklake universe.' It adds a detailed return shape, making the resource and outcome unambiguous. This clearly distinguishes it from the sibling get_earnings_intelligence, which sounds like analysis rather than a date 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 establishes clear context for when to use this tool: any time an agent needs upcoming earnings dates within a configurable look-ahead window. The days parameter is explained with defaults and limits. It does not explicitly name alternatives or state when-not-to-use, so it misses the 5-grade bar.

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 and idempotent; the description goes further by explaining server-side filtering before truncation, per-result call counting against rate limits, Pro-tier availability, null behavior when no AI summary exists, sorting order, and the non-financial-advice disclaimer. This is rich behavior disclosure 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 front-loaded with a clear purpose and then uses structured sections for parameters and return values. It is somewhat long and partially duplicates schema parameter descriptions, but every section contributes useful information and no filler is present.

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 covers defaults, max values, filtering behavior, output content, sorting, disclaimer, rate-limit accounting, and tier requirements. An AI agent has enough context to call and interpret results correctly, especially with the output schema also available.

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 carries the core parameter definitions. The description still adds meaningful context beyond the schema for min_ai_score, including the legacy min_flag_score rename, the precise field it gates on, and the ordering nuance between filter application and limit truncation. Most other parameters are redundant with the schema, so a 5 is not warranted.

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: it combines the earnings calendar with AI pipeline data to surface upcoming earnings events with AI scores, verdicts, and risk factors. This distinguishes it from the raw get_earnings_calendar sibling and makes the resource and value proposition 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 implies when to use this tool: when an agent needs AI-contextualized earnings, such as scores, verdicts, and risk factors, rather than a plain earnings calendar. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for 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 cover readOnlyHint, idempotentHint, and destructiveHint, and the description substantially adds context: maximum/default days, empty-result behavior, that data comes from a daily pipeline, and Pro-tier restriction. Each row's field semantics are explained, which goes well beyond what annotations alone 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 structure is logical and front-loaded: purpose first, data-window and sourcing second, then a row-level column reference. The bulk of the length is a compact field list with inline interpretation, which is genuinely useful for an agent interpreting output rather than 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?

For a tool of this complexity with 15+ indicator fields, the description covers purpose, data source, window semantics, empty-result behavior, output field meanings, Pro-tier restriction, and a disclaimer. Combined with a 100%-coverage schema and output schema, nothing an agent needs to call or 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?

Schema coverage is 100%, but the description adds value by explaining the meaning and behavior around the `days` parameter (default, max, and the empty-result rule) and by clarifying that `symbol` also accepts a company-name fallback. The field-level breakdown is output semantics, yet it helps an agent reason about which parameters affect the result.

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 ('Historical daily indicator snapshots for a stock') and an explicit use case ('ideal for charting and trend detection'). It clearly separates this tool from price-history siblings by emphasizing indicator snapshots, and lists a rich set of indicators so an agent knows exactly what to expect.

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 when it is appropriate ('Historical daily indicator snapshots for a stock — ideal for charting and trend detection') and sets expectations around the date window and data population. It does not explicitly name which sibling tool to use for simple price history, so it does not fully reach a 5 on exclusion guidance.

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 far beyond the readOnly/idempotent/destructive annotations. It discloses source gap-fill behavior, the merged top_holders semantics and false-merge detection, the special meaning of holder_count_divergence, and that the summary narrative runs on a separate cadence and may disagree with live counts. These are exactly the non-obvious behavioral traits 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 long, but nearly every sentence adds unique operational or interpretation detail that justifies its length. It is front-loaded with the core purpose and signal semantics. It could be improved with clearer paragraph or bullet separation, but it is not padded or redundant.

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

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

Despite the presence of an output schema, the description explains the nuanced parts of the response that a schema alone cannot: source merging, the systemic-multiplier condition behind holder_count_divergence, and the trust hierarchy when summary disagrees with counts. It also flags Pro-tier cost. For a single-parameter, read-only data tool, this 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?

Schema description coverage is 100%, so the single `symbol` parameter is already fully documented by the schema. The description does not add validation, format, or syntax details beyond 'for a stock.' Baseline 3 is appropriate because the schema carries the parameter documentation burden and the description adds no meaningful input semantics.

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 delimits the tool's scope from sibling market-data tools by describing the combined insider/holdings signal and its exact output components. The purpose is unambiguous and distinct even without comparing against sibling names.

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: use this when you need insider transactions, institutional holdings, and a combined signal for a single stock. It also adds operational guidance like 'Pro tier only — AI pipeline cost attached.' It does not explicitly name alternatives or state when not to use it, but the context is strong enough to imply appropriate usage.

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?

Although annotations already say the call is read-only and idempotent, the description adds meaningful behavioral context: it is not produced every 4 hour, stale is tripped only after >72h with weekday-only pipeline details, and all market_context values are point-in-time snapshots of a specific execution run. These details go well beyond the annotations and materially affect 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 longer than typical descriptions, but its length is justified by the two distinct analyses, the many key output fields, and the important caveats. It is well orgized and puts the core purpose first. Some disclaimerminal lines (For informational purposes only) are less actionable for an agent, so it does not get a perfect score.

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 when to use each perspective, how staleness works, the cost/tier caveat, the difference between live and point-in-time data, and gives meaning for each major result field. There is also an output schema, so the response format is available elsewhere. This is complete for safe and correct invocation.

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

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

The only parameter is history_count, and the input schema already provides a clear default, a range, and a human-readable description. The tool description repeats this same information but does not add any deeper parameter behavior e.g., navg except the schema already covers it. Baseline 3, as 100% of the schema is described.

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 says this is a combined AI market assessment returning both macro regime and market outlook, which is a specific and distinct resource. It also breaks down the two perspectives into the questions they answer, making the tool's purpose unambiguous and able to be selected from a list.

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 direct usage guidance: the REGIME perspective is for position sizing and asset allocation, and the OUTLOOK perspective is for sector preference and directional bias. It also explicitly says to use get_market_pulse for live data instead of the point-in-time snapshot here, which is a clear when-not/alternative instruction.

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 this as read-only, idempotent, and non-destructive, so the description needs less safety disclosure. The description adds valuable behavioral details: the per-category counting toward the daily API limit, omission of atr_pct when underlying data is missing/corrupted, and the precomputed Pro-tier AI messages with no extra AI cost. It clearly states what is returned and notes absent data. This is a good example of adding context beyond the schema. Minor lack: no explicit note about rate limits beyond the daily call counting, but most relevant behavior is transparent.

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-organized: a scope line, a pagination/limit note, a filter note, return fields, and a Pro tier explanation and pointer to a sibling. It is a little long, and the Pro tier narration ('A big mover's...' uses colorful language) adds length but also explanatory value. It front-loads the core purpose immediately and presents parameters in the same order as the schema. The slight extra length and marketing tone prevent a perfect 5.

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 has a rich output schema and a clear list of returned per-stock fields, so the description doesn't need to repeat the full return shape. The input schema covers all three parameters with 100% coverage. The description covers the daily-limit accounting, the Pro-tier optional fields, and the alternative for full research; there is no major gap an agent needs to guess. For a list/read tool of moderate complexity, this 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?

Schema description coverage is 100%, so each parameter already has a rich description in the schema. The tool description adds the default for category and limit, the valid enum values, and a concrete example for min_market_cap_b. It also adds the critical interpretation that a symbol appearing in multiple categories counts once per category toward the daily limit, which clarifies exactly how limit/quota accounting works. This is a strong baseline 3 with meaningful added value, so a 4 is justified.

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 and resource: 'Top market movers from the Stocklake universe — gainers, losers, most active.' It clearly identifies the tool's function as listing market movers, and explicitly differentiates its output categories. The context that it returns a per-stock summary and points to the sibling get_stock_research for deeper research further distinguishes it from other 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 states when to use the tool: it provides top movers and notes that Pro tier adds predefined AI narratives. It explicitly names the alternative get_stock_research(symbol) for full research on a single mover. It also gives selection guidance by showing the category and limit parameters. It does not explicitly mention when not to use it, but the guidance is strong overall.

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. The description adds valuable context by stating it 'reads live data directly from the market data feed' and 'No AI cost', and explains the meaning and freshness of returned fields. This goes 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 concise opening sentence followed by a clear bulleted list of return fields. Every sentence adds value, avoids redundancy, and the format makes 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 this is a zero-parameter tool, the description comprehensively explains the output fields, including their meanings. With an output schema present, the description fully covers what an agent needs to know to invoke and interpret the 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 schema coverage is 100% by definition. With no parameters to document, the description is not required to add parameter details; the baseline score of 4 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?

Description clearly states it provides a 'Live market health snapshot in a single call' and enumerates the aggregated indicators (VIX, fear/greed, breadth, indices, bonds). This goes beyond the name by specifying the resource and scope, and differentiates it from sibling tools by emphasizing that it aggregates data without requiring multiple calls.

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 the tool is for quickly obtaining a market-wide health overview in one call, and notes 'No AI cost' and 'Available to all tiers', which are useful usage considerations. It does not explicitly list exclusions or name alternative tools for when more detail is needed, but the single-call aggregation message provides clear 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 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?

Annotations declare read-only/idempotent/non-destructive behavior, and the description adds substantial extra context: pro-tier gating, silent ignores and fallbacks on free/guest tiers, daily-limit counting, the AI-score field provenance, as well exactly which fields each tier receives. No statement contradicts 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?

Well structured and front-loaded: purpose, parameters, returns, tier behavior, and next-step routing. It is long, but the tool is complex. It loses the top score because it repeats a good deal of what the input schema already spells out and includes internal implementation details like stock_ai_summary.py and the retired flag_score renaming that could be trimmed.

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

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

For a complex, tiered, filter-heavy tool with 18 optional parameters, the description covers what is returned, what counts against quotas, pro/free differences, silent resource fallbacks, and which sibling tool to call next. An agent has everything needed to invoke it correctly, and the output schema covers the remaining return-shape details.

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 carries most parameter meaning. The description still adds value by grouping the filter dimensions into conceptual families, providing practical worked examples for RSI, performance, P/E, and volume screens, and explaining cross-parameter behaviors like presets influencing default sort_by. This is a step 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 opening sentence uses a concrete verb-resource pair — "Filter and rank stocks" — and scopes the tool to the Stocklake universe. The stated dimensions (fundamentals, technicals, AI signals) and the follow-up to get_stock_research make it clear this is the screening/ranking tool, not the single-stock or news/history sibling.

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 clearly defines when this tool is used: screen and rank the broad universe with filters/presets, with pro-tier behaviors explicitly called out. It also tells the agent to call get_stock_research for deeper per-result research. It does not fully contrast against siblings like get_stocks, get_market_movers, or get_signals, so it stops just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's safety burden is low. It adds non-obvious context: refresh cadence (~4 hours), pro-tier availability, and the fact that the all-sectors call serves as the rotation view. 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 well-structured with a concise summary followed by parameter bullets and context bullets. It is longer than minimal, but each sentence adds useful information such as refresh cadence, access tier, and parameter constraints. The 'not financial advice' disclaimer is boilerplate but not distracting.

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 output schema exists, annotations cover safety, and the description explains both call modes plus parameter restrictions, the tool is sufficiently complete for an agent to select and invoke it correctly. A minor gap is the lack of explicit guidance for when to choose this tool over related siblings like get_market_assessment or get_signals.

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 and their defaults. The description's bullets recap this information (history_count 0-3, default 0; sort_by_strength ignored for single sector) without substantially extending schema semantics, so 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 opens with a specific verb and resource ('Get Sector Intelligence') and enumerates the concrete outputs: signal, cycle stage, rotation signal, drivers, alerts, and computed statistics. It also explains the dual all-sectors/rotation view, which distinguishes it from the sibling market and earnings 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 clearly states when to pass a sector name versus when to omit it, and explains that the all-sectors call doubles as the rotation view. It provides usage guidance for sort_by_strength and history_count, though it does not explicitly contrast this tool with named siblings.

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 readOnlyHint and idempotentHint annotations, the description adds critical behavioral details: the fallback to older signals when nothing fires in 24 hours, the fact that dropped or expired signals are still shown, and the 'Pro tier only — AI pipeline cost attached' warning. 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 lengthy but every sentence carries useful information—parameter semantics, edge cases, return structure, and cost. It's well-organized with clear sections and front-loaded with the core purpose, so the length is fully 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?

Given the tool's complexity, the description is comprehensive: it covers all parameters, return fields (count, window, signals), fallback behavior, deprecation, and the Pro tier cost. It complements the existing output schema by explaining the nuances of signal_score_band and the window field, so nothing an agent needs to call it correctly is missing.

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

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

The description goes far beyond the input schema: it explains that NEUTRAL covers both flat and two-sided ideas, that signal_score reflects the stronger side for two-sided ideas, that min_signal_score is always compared against a single number, and that min_conviction/min_flag_score are deprecated and ignored. This is essential for correct filtering.

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 that the tool returns 'AI-screened stock signals' from the Stocklake pipeline, sourced from news analysis, sector screening, and sentiment signals. It distinguishes itself from siblings like get_news_feed or get_market_movers by focusing on the pipeline's processed signals rather than raw data, so an agent can tell exactly what it does.

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 provides useful context on the 24-hour window and fallback behavior, and clarifies that signals reflect AI findings rather than the trading engine's current state. However, it does not explicitly name alternative tools or state when to prefer this over get_screener or get_news_feed, so the agent must infer usage from the description.

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, establishing the tool's safety profile. The description goes far beyond that, explaining tier-based availability (free vs pro), that missing data is omitted rather than nulled, the distinction between ai_score and get_signals' signal_score (different pipeline, same scale), how relative_strength computes percentage-point differences, and that some fields may be null if not precomputed. This is rich behavioral context that an agent could not infer from annotations alone. No contradictions found.

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 extensive yet well-structured, using bullet points and clear sections. It front-loads the core purpose and then expands into field lists, tier differences, and related-tool pointers. While long, every section serves a purpose given the tool's complexity (e.g., explaining pro-tier additions, null behavior, and the relationship to get_stock_research). It does not waste words, though a more concise summary of the basic fields could be trimmed without loss of 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?

The description covers the full scope of the tool: all return fields, nested object structures (indicators, signals, stance_signals, relative_strength, market_risk), tier differences, null-handling conventions, and explicit pointers to the only alternative for fuller research. It also explains numerical scales (analyst_rating_score, ai_score) and how they relate to other tools (signal_score). Given the richness of the output and the annotation baseline, nothing an agent needs to call this 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?

The schema defines the only parameter, symbol, with a clear description: 'Stock ticker symbol. Also accepts a company name as a fallback (e.g. "Apple") when it uniquely resolves to one symbol.' The tool description does not add additional parameter semantics beyond what the schema already provides. Since schema description coverage is 100%, a baseline of 3 is appropriate; the description does not need to compensate for any gap.

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 clear statement: 'Price, fundamentals, technical indicators, and company profile for a stock.' and reinforces with 'Returns all data needed to understand a stock in a single call.' It explicitly lists the categories of data and distinguishes the tool from get_stock_research, which is referenced as the only tool with the full AI narrative bundle. This gives an agent a precise mental model of what the tool does and how it relates to 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 explicitly directs users to get_stock_research for full narrative and cross-source context: 'For the full text... call get_stock_research(symbol) instead — that's the only tool with the complete bundle.' It also mentions that the base tool is available to all tiers and that pro tier adds specialized indicators and interpreted blocks. However, it does not explicitly compare against other siblings like get_stocks (plural) or get_stock_history, leaving some ambiguity about when those would be preferred. Still, the guidance for the primary alternative is clear.

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 no annotations are present, so it carries the transparency burden. It discloses the default and maximum `days`, that `days_returned` may be lower than requested, and the exact per-bar fields. It does not explicitly state no-side-effect behavior, but the get/returns language plus the clarity of the operation make this a strong, non-hidden contract.

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 compact and organized as a short first line for the tool's purpose plus concise bullets for parameter and return semantics. Every sentence carries meaningful information and no filler or redundant material exists.

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, combined with the complete input schema and returned-val format, leaves no essential invocation behavioral detail unresolved: argument defaults, maximums, partial-history case, and bar fields are all present. This is fully sufficient for an agent to call 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%, including `days`' default/max and `symbol`' ticker-plus-company-name behavior, so the added description value is limited. The description does clarify the effect of `days` beyond a single schema phrase and defines the return shape, but this goes beyond parameter semantics and the description says the schema already says.

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-resource pairing: it returns daily OHLCV price history for a stock. This makes the tool's function obvious and distinguishes it from earnings, indicators, news, and screener siblings that provide different data types.

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 clearly establishes when this tool should be used: when a caller needs daily stock price bars rather than news or fundamentals. It does not explicitly name alternative tools or exclusion conditions, but the clear data scope provides enough contextual guidance 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/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 declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds significant operational context: no live AI calls, pre-computed pipeline data, recency-gated trade signals that persist even if the internal trader dropped them, null fallback for pre-schema summaries, and explicit score-field naming/sync conventions. 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-structured: a front-loaded summary, a clear replacement statement, detailed labeled return blocks, and explicit edge cases. Every sentence contributes operational or selection-relevant information, and the bulleted layout makes the complexity scannable.

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?

This is a composite tool with multiple return blocks, score band conventions, null cases, sync behavior, and signal retention nuances. The description documents all of these clearly. With an output schema also present, an agent has everything needed to call the tool 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 input schema already covers the single symbol parameter with 100% description coverage. The tool description reinforces that symbol is a stock ticker for the research bundle but does not add new parameter semantics. Baseline 3 is appropriate because the schema carries the full weight.

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

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

The description opens with a specific verb+resource: 'Full AI research bundle for a stock in one call' and enumerates exactly what it returns: fundamentals, AI summary, news, insider/institutional signal, and trade signal history. It explicitly names the four sibling tools it replaces, so an agent can immediately distinguish it from get_stock, get_stock_news, get_insider_activity, and 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 explicitly says it replaces get_stock + get_stock_news + get_insider_activity + get_signals for one symbol, giving a clear selection rule versus alternatives. It also notes the Pro tier restriction and that data is pre-computed, which helps an agent decide when this tool is appropriate.

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 annotations, the description reveals multiple non-obvious behaviors: missing symbols are omitted, each symbol counts toward a daily limit, over-25 requests are rejected outright with batch_too_large, duplicates are collapsed through normalization, and Pro-tier data is 'precomputed' with no live AI cost. It even provides a response invariant formula, which is far more behavioral detail than annotations supply.

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 clear paragraphs and front-loaded purpose; every section covers a distinct operational concern (main semantics, tier details, exclusions, and the duplicates invariant). It repeats the over-25 rejection that already lives in the schema, which is a small efficiency loss, but the structure and packaging is strong.

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 batch endpoint with tier differences, daily limits, normalization behavior, and output shape quirks, this description leaves nothing an agent needs to infer. It enumerates what's included, explicitly lists what is NOT included and which sibling to call instead, and even describes output-level invariants. The presence of an output schema lowers the burden on explaining return values, but the description still covers the non-obvious delivery 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?

The schema already covers the basic limits and rejection behavior for the symbols parameter, so baseline is at 3. The description adds meaningful symbolic semantics: how duplicates are collapsed via 'case-folding, share-class aliasing e.g. BRK.B->BRK-B' and how requested/missing/duplicates relate in the invariant. That adds real value beyond the schema.

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

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

The description opens with a precise verb constraint: 'Batch stock data for up to 25 symbols in a single call', and immediately distinguishes itself from get_stock by clarifying it returns 'the same fields get_stock returns' and is 'a true batch version, not a thinned-down scan.' It also names its result shape, so an agent knows exactly what this tool is and what it produces.

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 when-to-use and when-not-to-use guidance: if you need more than 25 symbols, 'split a larger list into multiple calls; if you need stance_signals, get_stock(symbol); if you need full AI text/news context, get_stock_research(symbol).' It also notes tier availability, making the routing decision complete.

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.