Stocklake — AI Stock Intelligence

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral facts: weekday-only snapshots (~60 rows per 90 days), null semantics per field, missing weekdays never reconstructed, fewer than 2 snapshots returns an empty list with a note, and history starting July 2026. It also notes the inverted 1.0=strong buy / 5.0=sell scale, which prevents a serious misreading.

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

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

Front-loaded with the core question and sibling routing, then a scannable field list. The field enumeration partly duplicates the output schema, and the trailing disclaimer adds length, but almost every sentence carries actionable information.

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

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

Covers cadence, sparsity, null handling, minimum-history cutoff, coverage caveats, tier gating, and the numeric scale convention. For a read-only history tool with an output schema in place, nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the lower-is-more-positive direction of analyst_rating_score, the ~60-rows-per-90-days density, and the null-per-field behavior that tells the agent how to interpret the `days` window's output.

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

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

The description names a specific verb and resource ('how analyst consensus on a stock has moved over time') and frames it as the trajectory rather than a snapshot. It explicitly distinguishes itself from get_stock ('get_stock's single current analyst_rating / analyst_target cannot') and from get_indicator_history ('this tool is analyst consensus only').

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

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

It states the exact question the tool answers ('are analysts getting more or less positive on this name?') and gives explicit routing rules: use get_stock for the current view alone, get_indicator_history for price/indicator history. It also flags the Pro-tier prerequisite, which is a real usage gate.

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

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

Annotations already cover read-only, idempotent, closed-world, non-destructive semantics, so the bar is lower. The description still adds real behavioral context: dates are market-data sourced, is_estimate=true entries should be treated as approximate, results are sorted by earnings_date ascending, and the tool is available to all tiers (an access constraint not visible in 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?

Front-loads the one-line purpose, then uses short bullets for the parameter, return shape, sort order, and caveat – easy to scan. The per-field enumeration of results[] overlaps with the existing output schema, which is mild redundancy, but the bullets are compact and nothing is padded.

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 and full annotations already present, the description covers the remaining gaps an agent needs: the estimate caveat, sort order, tier availability, and window bounds. Only the absence of routing guidance relative to the other earnings/calendar siblings keeps it from a 5.

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 single 'days' parameter is fully documented in the schema (default 7, max 30). The description only restates that same default/max, adding no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('upcoming earnings dates for stocks') with scope (the Stocklake universe), so an agent can tell what it returns without opening the schema. It doesn't explicitly distinguish itself from the nearby sibling get_earnings_intelligence or get_economic_calendar, which keeps it short of a 5.

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

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

Usage is implied by the look-ahead window framing ('days: look-ahead window in days, default 7, max 30'), which tells the agent the tool answers forward-looking calendar questions. There is no explicit when-to-use/when-not or routing to the earnings-related alternatives, so guidance stays at the implied level.

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?

Goes well beyond the annotations (which only cover the read-only/idempotent safety profile) by disclosing tier gating ('Pro tier only'), cost implications ('AI pipeline cost attached'), and a rate-limit interaction ('each returned ticker counts as one call toward your daily limit'). It also explains the server-side ordering of min_ai_score vs limit truncation, which is genuinely non-obvious behavior.

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

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

Front-loaded with a clear purpose statement, but the parameter and return-value lists duplicate the input schema and the existing output schema, making the description longer than necessary. The structure is readable but not economical.

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

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

For a four-parameter read tool with an output schema, the description supplies everything an agent needs: tier restriction, cost, rate-limit accounting, filtering semantics, and sort order. The return-field enumeration is redundant given the output schema but not harmful.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema and the description largely restates them (days_ahead, sector, min_ai_score, limit). It adds only marginal nuance about ai_score gating and limit interaction, which the schema also captures, so baseline 3 applies.

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

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

States a specific resource and differentiator: 'Upcoming earnings with AI context - AI scores, verdicts, and risk factors per stock.' The second sentence explicitly says it 'combines the earnings calendar with AI pipeline data,' which lets an agent distinguish it from the plain get_earnings_calendar sibling without opening a schema.

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

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

Implies when to use it ('surface which upcoming earnings events are worth monitoring') but never names an alternative or exclusion, even though get_earnings_calendar is an obvious sibling. An agent must infer that this tool is the AI-enriched superset rather than being told directly.

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

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

Despite already-rich annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: the released_recent vs upcoming split, the guarantee that upcoming items never carry actual values, the meaning of diff, the key_event flag, major-economy-first sorting, and tier-cap/capped-response behavior.

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

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

The description is long but well-structured and front-loaded, with bullets separating bucket semantics, filtering flags, sorting, and tier limits. Most sentences earn their place, though some schema-level details are repeated.

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 calendar tool with five optional parameters and an output schema, the description covers the key behavioral and filtering nuances an agent needs. It explains the returned buckets and flags even though the output schema exists.

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

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

Schema description coverage is 100%, so the input schema already documents each parameter thoroughly. The description reinforces defaults and caps but adds little parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific resource (upcoming and recently-released macro/economic events) and enumerates concrete event types, clearly distinguishing this calendar from earnings or corporate-event siblings.

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

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

It defines the two buckets and filter behavior, which implies when to use the tool, but it never names an alternative tool or explicitly says when not to use this one. Routing to siblings such as get_earnings_calendar is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 730/90 limits, the empty-object return when fewer than 3 snapshots exist, the Pro-tier requirement, and the fact that the pipeline populates it daily.

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

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

Purpose and constraints are front-loaded, but the long field-by-field enumeration of return values duplicates the output schema, which already exists, so a significant portion of the text does not earn its place against structured data.

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

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

For a pro-tier, read-only snapshot tool with a rich output schema, the description covers the operational essentials an agent needs: the empty-result condition, the size cap, the cost of full=true, and the daily refresh cadence.

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

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

Schema description coverage is 100%, so days, full and symbol are already documented in the schema; the description largely restates those semantics (max 730, default 90, what full adds). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Historical daily indicator snapshots for a stock') and frames the use case ('charting and trend detection'). It is distinguishable from price-history siblings like get_stock_history, though it never names an alternative explicitly.

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

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

The phrase 'ideal for charting and trend detection' implies a context but gives no when-to-use vs when-not guidance and does not tell the agent how this differs from get_stock_history or get_signals, which an agent must infer.

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

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

Annotations cover the safety profile (read-only, idempotent, non-destructive), and the description adds substantial context beyond them: free/guest caps at 90 days and 5 rows, ai_commentary runs on a separate cadence and 'can lag the transactions', and holder_count_divergence is null unless all matched holders disagree by a systemic multiplier that may make top_holders.shares unreliable. It also explains that summary is computed from the same rows so it cannot disagree.

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

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

The core capability and tier split are front-loaded in the first sentence, and the tier breakdown is logically ordered. It is dense and somewhat over-packed with parenthetical asides (e.g. 'echoed as window_days', footnote pointers like days_note/transactions_note), but given the tool's complexity most sentences carry real information.

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

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

Despite an output schema that already documents return fields, the description fully characterizes what varies by tier and which fields are conditional (signal, holders, divergence). An agent has everything needed to call it correctly and interpret results; nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: `days` is capped at 90 for free/guest (referencing days_note) and extends to 365 on Pro, and it clarifies that the value is echoed back as window_days. That is genuine added meaning over the schema's own text.

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

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

Names a specific verb and resource ('Get insider transactions... regulatory insider filings') and scopes it geographically (US and several European markets). It also explicitly ties its signal_score to get_signals()'s field, letting an agent distinguish it from that sibling without opening either schema.

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

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

Gives clear tier-based context (guest/free gets a 90-day window with no AI or holders; Pro gets 365 days, signals, commentary, and holders) so an agent understands what it will receive. However it never states when to prefer this tool over siblings like get_signals or get_stock, and offers no exclusions or routing criteria.

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

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

Annotations already establish read-only/idempotent safety, yet the description adds substantial non-structured context: a ~4x/day weekday-only refresh cadence with dead weekends, the exact >72h staleness rule and why a Fri→Mon gap does not trip it, null semantics for missing timestamps, the Pro-tier cost attachment, and the caveat that market_context is a frozen snapshot. These are exactly the operational facts an agent needs and none are derivable from the annotations.

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

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

Content is front-loaded: cadence and staleness caveats come before field enumeration, and the regime/outlook split is visually separated. It is long and has minor redundancy — staleness is explained once in the header and again in the field list, and macro_score is re-explained across two bullets — which costs it a point.

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

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

For a high-complexity composite tool with an output schema, the description covers cadence, staleness, tier gating, field-level meaning including the subtle macro_score vs risk_appetite_score distinction, and honest disclaimers. An agent can call and interpret this tool without opening the output schema.

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

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

With only one optional parameter at 100% schema coverage, the baseline would be 3; the description earns an extra point by restating the 0-3/default-0 bound and, more usefully, clarifying that macro_score_trend computes automatically without history_count — a non-obvious interaction the schema cannot express.

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

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

The description opens with a specific verb+resource ('Combined AI market assessment: macro regime + market outlook') and immediately splits it into two named perspectives with distinct decision uses. It also distinguishes itself from get_market_pulse by explicitly scoping market_context as a point-in-time snapshot rather than live prices.

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

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

It gives explicit routing for each half — regime for position sizing/allocation, outlook for sector preference and directional bias — and tells the agent to check regime_stale/outlook_stale before treating values as current. It names one sibling alternative (get_market_pulse for latest prices) but offers no guidance on when not to call this tool at all (e.g., non-Pro tier, or topics better served by get_signals/get_sector_intelligence).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses that each returned stock consumes one call against the daily limit (and that cross-category duplicates count once per category), tier gating (all tiers vs Pro-only AI fields), and a data-quality caveat that atr_pct is omitted when the volatility reading is missing or corrupted.

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

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

Front-loaded with the one-line definition followed by a well-structured bulleted parameter list; the Pro-tier paragraph slightly over-explains ('A big mover's price/volume/RSI alone doesn't say whether the move matters') but each element is relevant. Some return-field enumeration duplicates the output schema.

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

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

For a 3-param, zero-required read tool with an output schema, the description covers everything an agent needs: category values and defaults, limits, market-cap filtering semantics, quota accounting, tier availability, and a hand-off to get_stock_research.

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

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

Schema description coverage is 100% and the same quota/default/cap explanation appears verbatim in the schema for limit, category, and min_market_cap_b, so the description adds no semantics the schema does not already carry. Baseline 3 applies when the schema does the heavy lifting.

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

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

Opens with a concrete verb+resource+scope ('Top market movers from the Stocklake universe - gainers, losers, most active') and enumerates the exact category values, which cleanly separates it from siblings like get_screener, get_market_pulse, or get_stocks.

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

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

Clearly frames the scenario (surfacing big gainers/losers/most-active) and routes to the right next step for depth: 'For the full research bundle on any one mover, call get_stock_research(symbol).' It does not, however, state when to prefer a sibling scanner (e.g. get_screener) or exclusion conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely non-structured facts: ~15-minute delay on index and bond/commodity prices, snapshot-sourced vix/fear_greed/breadth, no AI cost, and universal tier availability. Data freshness and cost are exactly the traits an agent cannot infer from annotations or schema.

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

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

Front-loaded well: purpose, then cost/freshness, then detail. However, roughly half the text is a bulleted return-value enumeration that substantially duplicates the existing output schema, which is padding against this rubric.

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

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

Freshness semantics, snapshot source for derived fields, tier availability, and cost are all covered, which is what an agent needs to decide whether the data is stale or accessible. The return-value block is redundant given the output schema, but nothing important is missing.

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

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

The tool takes zero parameters and the schema is closed, so there is nothing to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter guidance for a parameterless call.

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

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

Opens with a concrete verb+resource framing ('Market health snapshot in a single call') and states it aggregates indicators that would otherwise need multiple calls, which separates it from per-stock siblings like get_stock. It does not distinguish itself from the closest neighbor, get_market_assessment, so an agent still has to guess between those two.

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

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

'without requiring multiple tool calls' implies the aggregation use case, and 'Available to all tiers' removes an access precondition. But there is no explicit when-to-use vs get_market_assessment / get_market_movers / get_signals, so the routing decision is left to inference.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds valuable context beyond that: a Pro account requirement, third-party content provenance ('articles are published by third parties'), and a disclaimer, plus dedup behavior via collapsed_count.

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

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

Front-loaded summary sentence followed by clearly sectioned use cases and field notes; efficient overall, though the parameter bullets partly duplicate the schema and add some length.

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

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

Covers routing, auth requirement, output field meanings, dedup semantics, and content provenance; an output schema exists so return-value detail is not strictly required. Nothing essential for correct invocation is missing, though the signal_score discussion overlaps with structured fields.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters; the description's parameter bullets restate defaults and ranges (0-100, default 60, max 10/25) without adding syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource ('Most notable recent news across all tracked stocks: a market-wide briefing') and explicitly contrasts with the sibling get_stock_news ('one symbol'), so an agent can distinguish the two without opening either schema.

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

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

Provides three concrete when-to-use scenarios with example queries (morning briefing, catalyst scanning, event monitoring) and explicitly names the alternative tool get_stock_news along with the condition (one symbol) that routes to it.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial non-obvious behavior: min_ai_score is silently ignored on free tier, sort_by silently falls back to market_cap for free/guest on rating/ai_score, limit counts each returned stock against a daily quota, and non-USD listings without an FX rate are excluded when cap bounds are set. It also covers sort_by default overrides per preset and the naming history of min_ai_score/flag_score.

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

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

Well front-loaded and sectioned (purpose, parameters, returns, tier notes), but it restates essentially every one of the 18 parameter descriptions nearly verbatim from a schema that already has 100% coverage, which bloats the definition considerably. The genuinely additive material (tier gating, preset/sort interaction, FX caveat) is buried among redundant restatement.

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 18-parameter, tier-gated tool with many interacting options, the description covers filter semantics, defaults, preset compositions, tier limitations, the return shape and its per-tier fields, and the follow-up tool for single-symbol depth. Despite an output schema existing, the tier-conditioned return differences are helpful to state. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema in meaningful ways: the market_cap vs market_cap_usd distinction and the FX-exclusion side effect of cap bounds, the preset-driven sort_by default, and the ai_score vs signal_score distinction with the retired flag_score rename. Duplicated filter examples add less, but the extra semantics are real.

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

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

States a specific verb+resource+scope: "Filter and rank stocks from the Stocklake universe - fundamentals, technicals, and AI signals in one tool." An agent immediately understands this is a screening/ranking tool rather than a lookup. It never explicitly contrasts itself with the closest siblings (get_stocks, get_signals), so it stops short of a 5.

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 operational context: preset definitions and what each preset filters on, tier availability, and an explicit hand-off ("For the full research bundle on any one result, call get_stock_research(symbol)"). It does not state when to prefer this tool over get_stocks or get_signals, so the routing guidance is incomplete.

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?

Goes well beyond the annotations (which already declare readOnly/idempotent/non-destructive) with refresh cadence ('~4x/day, weekdays only, dead overnight and on weekends'), a staleness warning to check updated_at, a pro-tier access restriction, and null semantics for assessments predating 2026-08-26. It also frames sector_score as 'not a buy/sell call', setting expectations about interpretation.

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

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

Front-loaded with purpose, then a tight bulleted parameter section, then operational caveats — a good structure. It is long and carries minor redundancy ('For informational purposes only. Not financial advice.' alongside 'Not a buy/sell call'), and the sector_score paragraph could be trimmed.

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

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

Given three optional parameters, an output schema, and rich annotations, the description covers everything an agent needs: mode selection, parameter interactions, data freshness, tier gating, and null/edge cases. Nothing material is missing for correct invocation.

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

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

Schema description coverage is already 100%, so the schema documents all three parameters; the description largely restates their behavior (all-sectors-only, ignored for single sector). Where it adds real value is the distinction between sector_score (continuous 0-100, absolute cross-sector scale) and strength_score (AI's 1-10 read), plus the trend object shape — though those are output fields rather than parameters.

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

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

States a specific verb+resource ('AI-assessed sector intelligence') and enumerates exactly what it returns (signal, cycle stage, rotation signal, drivers, alerts, computed stats), so an agent can distinguish it from get_market_assessment or get_signals without opening a schema. The dual single-sector/all-sectors scope is stated up front.

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

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

Explicitly says to pass a sector name for one sector and omit/None for all 11, and names the intended use of each mode ('the all-sectors call doubles as the rotation view'). It also states the exact conditions for sort_by_strength, history_count, and sector_score_trend, including that the trend view exists only for single-sector calls.

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

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

Beyond the readOnly/idempotent annotations, it discloses the freshness window and fallback semantics, that expired signals remain listed for their recency window, that each returned signal consumes a daily call quota, and that the tool is Pro-tier only with an AI pipeline cost attached. These are exactly the operational facts an agent cannot infer from structured fields.

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

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

Front-loaded with purpose and the key 24h/fallback behaviour, then cleanly sectioned into Parameters and Returns. It runs long and repeats parameter text that also appears in the schema, but no sentence is pure filler.

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

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

Despite having an output schema, it spells out the response shape (count, window, signals with score bands and expiry), the tier gate, and the quota cost. An agent has everything needed to call this correctly and interpret the result.

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 baseline would be 3, but the description adds real semantics: NEUTRAL spans both a flat read and a genuinely two-sided thesis, signal_score reflects the stronger side, and min_signal_score is explicitly named as the field to filter on with a never-below-threshold-on-both-sides guarantee. Much of this is mirrored in the schema descriptions, which caps it below 5.

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

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

States a specific verb and resource — AI-screened stock signals surfaced by the Stocklake pipeline — and names the three contributing sources (news analysis, sector screening, sentiment). It is distinguishable from feed-style siblings like get_news_feed or get_screener, but never explicitly contrasts itself with 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?

Provides useful operating context: a 24h recency window with fallback behaviour and a Pro-tier restriction. However, it never says when to prefer this over get_screener, get_news_feed, or get_market_movers, and gives no explicit when-not 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?

Goes far beyond the readOnly/idempotent annotations: discloses tier gating (Pro-only indicators are omitted entirely from free/guest responses, not merely unlabeled), null/omission semantics ('omitted rather than null', 'populates on the next scheduled indicators run'), refresh cadence (forensic scores on filing cadence, sector baseline daily), and caveats like Altman Z not being meaningful for banks. This is exactly the context annotations cannot carry.

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

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

Roughly 700 words for a one-parameter read tool, with visible redundancy: ai_score/ai_score_band are described twice in adjacent bullets, and the `trend` block is appended mid-section after sector_context rather than front-loaded. Because an output schema exists, the exhaustive field-by-field enumeration largely duplicates structured data rather than earning its place.

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

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

For a rich, gated, multi-block read tool, the description covers everything needed to call and interpret it: tier-dependent shape, which blocks may be absent and why, how `signals`/`indicators`/`stance_signals` differ, and where to go for the fuller research bundle. No material gap remains for an agent deciding and invoking.

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

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

Only one parameter and the schema already documents it at 100% coverage, including the company-name fallback. The description never mentions the `symbol` argument or its resolution behavior, so it adds nothing here and the baseline 3 applies.

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

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

Opens with a specific verb+resource+scope: 'Price, fundamentals, technical indicators, and company profile for a stock... all data needed to understand a stock in a single call.' It also explicitly differentiates from siblings by naming get_stock_research for the full narrative bundle and noting get_stocks omits `trend`, so an agent can pick correctly without opening schemas.

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

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

Clear routing signals exist: 'For the full text ... call get_stock_research(symbol) instead - that's the only tool with the complete bundle' and 'get_stocks omits `trend` to keep batch rows small.' What's missing is an explicit statement of when NOT to use this tool (e.g. historical series -> get_stock_history, signals -> get_signals), leaving some sibling selection to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them: tier-based availability limits, that free/guest quarterly requests return a pro_unlocks note rather than an error, that null quarterly comes with a quarterly_note, that missing line items mean 'not reported' not 'fetch error', and that values are in financial_currency. This is unusually rich behavioral disclosure.

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

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

Front-loads the most important distinction (raw data vs derived scores) and uses a labeled Tiers block that is easy to scan. It is somewhat long and repeats tier/period rules already in the schema, costing it a point, but no sentence is purely filler.

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

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

Despite an output schema existing, the description covers every edge case an agent would need: coverage variance by sector, null/absent statement states, non-equity symbols, and tier gating. Nothing required to call or interpret the result is missing.

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

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

Schema description coverage is 100%, and the description's tier/period/statement detail largely restates what the schema already documents (the period tier behavior appears near-verbatim in both). It adds the response shape {line_item: {period: value}} and currency semantics, but those are return-value concerns rather than parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific resource (raw balance sheet / income statement / cash flow line items) and explicitly distinguishes itself from the sibling get_stock by naming its forensic_scores block as the alternative for derived metrics. An agent can tell exactly what this returns without opening the schema.

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

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

Gives an explicit when-to-use-this vs when-to-use-that routing rule: use this for raw statement data, use get_stock().forensic_scores for Altman Z / Piotroski F / Beneish M. It also frames the caller's intent (compute own trends/deltas/CAGRs) which clarifies the use case.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further and discloses non-obvious behavior: guest/free callers are capped at 365 days with a `pro_unlocks` note, and days_returned/count may be less than requested when history is short. That is meaningful edge-case context an agent could not infer from annotations alone.

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

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

Bulleted, front-loaded, and every bullet maps to a distinct concern (parameter, response shape, per-bar fields). It loses a point because the 'days' bullet and the return-shape bullet substantially duplicate the schema parameter description and the existing output schema.

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

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

For a two-parameter read tool with full schema coverage and an output schema, the description covers everything needed to invoke it correctly: the data granularity, tier-based caps, short-history behavior, and bar fields. No gap remains that would cause a wrong call.

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

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

Schema description coverage is 100% and the schema's `days` description already carries the default, the 365/20,000 tier limits, and the days_returned caveat. The description largely restates that same tier and default information, adding little semantic meaning beyond the structured fields. Baseline 3 applies when the schema does the heavy lifting.

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

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

The opening line gives a specific verb+resource: 'Daily OHLCV price history for a stock,' which clearly separates it from get_stock, get_stock_financials, and get_indicator_history by naming the exact data product (daily OHLCV bars). It stops short of explicitly naming a sibling to prefer or avoid, so it is clear but not sibling-differentiated to the top standard.

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

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

The description gives real guidance on the 'days' parameter ('request only what you need,' 'a full pull can be ~10,000+ bars'), which is genuinely useful scoping advice. However, it never states when to use this tool instead of the adjacent get_indicator_history or get_stock, so tool-selection guidance is only implied.

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

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

Annotations declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), and the description adds genuinely new behavior: days/limit are clamped to an account maximum, status can be 'ok' or 'empty', duplicate events are merged with collapsed_count and limit counts distinct events, and articles are third-party content. This is unusually rich disclosure beyond the structured fields.

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

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

Bulleted, front-loaded with the one-line purpose, and each block is scannable. It is somewhat long, and the per-article field listing partially duplicates the existing output schema, though the signal_score provenance note earns its space.

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, return-value explanation was optional, yet the description still clarifies the non-obvious parts (signal_score tie-in to get_signals/get_stock_research, collapsed_count semantics) while covering params, clamping, and status. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, and the description largely repeats it (defaults, clamping rules). The only added value is ticker format examples ('AAPL', 'SAP.DE') versus the schema's company-name fallback note, which is marginal. Baseline 3 is correct.

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

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

States a specific verb and resource with scope: 'Recent news articles for one stock, newest first.' The 'for one stock' qualifier implicitly separates it from the market-wide sibling get_news_feed, but no sibling is named explicitly, so an agent must infer the boundary.

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 never states when to choose this tool over get_news_feed, get_stock_research, or get_signals — it only mentions those siblings to explain provenance of signal_score. There are no explicit conditions, prerequisites, or exclusions for invocation.

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 read-only/idempotent/closed-world safety, and the description adds genuinely new behavior: all data is pre-computed with no AI calls on request (latency and cost implication), Pro-tier gating, sync semantics between the news signal_score and get_signals, and the null/omission rules for headline, near_term, longer_term and forensic_scores. These are real operational disclosures beyond the structured fields, though they are buried in dense return-value prose rather than surfaced up front.

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

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

The purpose line is correctly front-loaded and the Returns section is bulleted, but the block runs roughly 450 words for a one-parameter tool, with nested parentheticals about score naming and field provenance that read as schema commentary. Since an output schema already exists, much of the Returns enumeration is redundant and dilutes the operative content.

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 a single-symbol read tool with an output schema, the definition covers everything an agent needs: scope, tier gating, pre-computation, null-handling, and the multi-symbol alternative path. It slightly overshoots by re-documenting return fields the output schema already exposes, so it is complete but not efficiently so.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already tells the agent everything about `symbol`. The description adds only a light scoping note ('for one symbol'), never stating single-symbol-only behavior in isolation (i.e. no batch or comma-separated input). 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 first sentence names a specific verb+resource (a composite research bundle for a single stock) and enumerates the five data blocks it returns. It then explicitly names the four sibling tools it consolidates (get_stock, get_stock_news, get_insider_activity, get_signals) 'for one symbol', which makes it distinguishable from every sibling at a glance.

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

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

Usage is pinned down as 'one call replaces these 4 calls for one symbol', which scopes it to single-symbol aggregation versus the granular tools, and 'Pro tier only' plus 'not financial advice' set invocation prerequisites. An agent knows both the selecting condition and the access constraint without 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?

Goes well past the annotations (which only cover read-only/idempotent safety) by disclosing quota costs ('each symbol counts as one call toward the daily limit'), hard rejection over 25 symbols with the exact error code batch_too_large, omission of missing symbols, and dedup/normalization behavior. It also notes pro-tier blocks are precomputed and cost no AI call, which is material for cost planning.

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

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

Front-loaded with the key constraints, but the tier-content enumeration is dense and partly duplicates the schema's 25-symbol rule. The closing sentence is garbled and truncated ('requested - len(missing or []) - duplicates_collapsed == count always holds'), which costs clarity.

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

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

Given an output schema exists, the description needn't explain return shape, yet it helpfully lists the tier-dependent fields and the duplicates_collapsed key. The only real hole is the malformed invariant sentence, which leaves the accounting rule ambiguous.

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

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

Schema coverage is 100%, so the 25-symbol limit and per-call cost are already documented; the description largely restates them. It does add genuine meaning beyond the schema by describing symbol normalization (case-folding, share-class aliasing like BRK.B -> BRK-B) and the duplicates_collapsed accounting.

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

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

States a specific verb and resource ('batch stock data for up to 25 symbols') and explicitly positions itself as a true batch of get_stock, not a thinned-down scan. It also names the siblings that cover what it does not: get_stock for stance_signals and get_stock_research for full ai_summary.

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

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

Gives concrete when-to-use guidance (batch up to 25, split larger lists) and explicit routing for out-of-scope data ('call get_stock(symbol) for stance_signals, or get_stock_research(symbol) for the full ai_summary text'). Tier availability (free vs pro) is stated so an agent knows what it can expect from its plan.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: it is Pro tier only, it returns an empty items[] rather than erroring when nothing is starred, and the result is informational and not financial advice. Missing auth/failure-mode detail keeps it short of a 5.

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

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

The purpose is front-loaded in the first sentence and each subsequent line earns its place (empty-state behavior, tier gating, disclaimer). The multi-line Returns block partly duplicates the existing output schema, which is mild redundancy but also usefully explains field meaning like the ai_score_band ordering.

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

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

For a parameterless, read-only tool with a published output schema and full annotation coverage, the description supplies the remaining pieces an agent needs: entitlement (Pro tier), empty-state handling, and result interpretation. The only gap is the lack of explicit differentiation guidance versus similar read siblings.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly signals the no-argument nature by describing a caller-scoped, implicit-scope retrieval.

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

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

States a concrete verb+resource: retrieves the caller's Stocklake watchlist, defined as starred symbols from the web dashboard, plus the enrichments applied. This clearly distinguishes it from list-style siblings such as get_stocks and from per-symbol siblings like get_stock, so an agent can pick it without opening any schema.

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

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

Usage is only implied: it is the watchlist of the calling user, and the description notes that starring happens on the web dashboard, plus what happens when nothing is starred. There is no explicit when-to-use-this-instead-of guidance against siblings like get_stocks or get_signals, and no exclusions.

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