StockLens

Initiate Analysis

initiate_analysis

Destructive

Initiate a full StockLens AI analysis for a specific stock. Starting a new run may consume one Analysis credit (LENS_AI) or one Plus Analysis credit (LENS_AI_PLUS, which may add AI narratives). Returns an analysis_id immediately — completion is asynchronous. Retrieve status or results with a separate fetch_analysis_result call when the user asks for them. A recent matching analysis may be reused; the receipt explicitly reports new_run_started and reused_existing without claiming an asynchronous credit charge has completed. Concurrent identical initiations receive retry guidance. Free supports the standard Analysis only; Pro and Max unlock Plus Analysis.

Input Schema

TableJSON Schema

Name	Required	Description
`depth`	No	Analysis depth: standard or plus. Standard consumes an Analysis credit (LENS_AI). Plus consumes a Plus Analysis credit (LENS_AI_PLUS) and may add AI narratives. Default standard.
`ticker`	Yes	Stock ticker symbol (e.g. AAPL)
`exchange`	No	Exchange code (e.g. NASDAQ). Optional.
`time_range`	No	Time horizon — shapes which signals the analysis weighs most (shorter horizons favor price action, momentum and news; longer favor fundamentals and quality). Not a price forecast. One window per calibrated band: short_2_wk (Short-term), medium_1_mo (Medium-term), long_1_yr (Long-term). Default medium_1_mo. The legacy medium_2_mo and long_2_yr aliases are still accepted and resolve to medium_1_mo and long_1_yr respectively.
`risk_tolerance`	No	Analysis focus — reweights how much the analysis weighs downside/quality risk vs. growth/fundamentals. NOT a personal risk or suitability assessment, and it never changes the company's underlying facts. low=Defensive, medium=Balanced, high=Growth. Default medium.
`analysis_emphasis`	No	Optional. RISK_EMPHASIS \| BALANCED \| FUNDAMENTAL_GROWTH_EMPHASIS. Must agree with the emphasis implied by risk_tolerance (low->RISK_EMPHASIS, medium->BALANCED, high->FUNDAMENTAL_GROWTH_EMPHASIS); a mismatch is rejected as a validation error before any credit is consumed.
`evidence_history_family`	No	Optional. SHORT_HISTORY \| MEDIUM_HISTORY \| LONG_HISTORY. Must agree with the family implied by time_range (short_2_wk->SHORT_HISTORY, medium_1_mo/medium_2_mo->MEDIUM_HISTORY, long_1_yr/long_2_yr->LONG_HISTORY); a mismatch is rejected as a validation error before any credit is consumed. Does not select a representative range on its own.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`depth`	Yes
`status`	Yes
`analysis_id`	Yes
`credit_type`	Yes
`new_run_started`	Yes
`reused_existing`	Yes
`estimated_seconds`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

The description goes well beyond the annotations, disclosing asynchronous behavior, credit consumption (with the nuance that the receipt does not claim a charge has completed), reuse possibility, receipt fields (new_run_started, reused_existing), retry guidance for concurrent identical requests, and plan-based limitations (Free vs Pro/Max). This is rich behavioral context that the annotations (readOnlyHint=false, destructiveHint=true) do not provide.

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

Conciseness4/5

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

The description is fairly long (around 150 words) and covers many aspects, but it is front-loaded with the primary purpose and then logically progresses through behavior, reuse, receipt, retry, and plan limitations. Every sentence adds substantive information; it is more detailed than a typical description but justified by the tool's complexity. It is not overly redundant.

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

Completeness5/5

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

Given the tool's complexity (asynchronous, credit-consuming, potential reuse), the description covers all key aspects: immediate return of analysis_id, asynchronous completion, how to retrieve results (fetch_analysis_result), reuse behavior, receipt contents, retry guidance for concurrency, and plan-based depth restrictions. It also aligns with the output schema (analysis_id) without needing to repeat return details. The description is fully complete for an agent to select and invoke the tool correctly.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying plan restrictions: 'Free supports the standard Analysis only; Pro and Max unlock Plus Analysis.' This is not present in the schema for the depth parameter and gives practical guidance. The description also reinforces the asynchronous nature of credit consumption, but the schema already describes the credit roles. Overall, it adds enough extra meaning to warrant a 4.

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

Purpose5/5

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

The description begins with 'Initiate a full StockLens AI analysis for a specific stock,' which clearly states the verb (initiate), resource (analysis), and scope (specific stock). It differentiates from siblings by explicitly mentioning that results are retrieved via fetch_analysis_result, and other siblings (get_market_summary, get_portfolio_insights) are not about initiating per-stock analysis.

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

Usage Guidelines4/5

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

The description provides clear context: returns an analysis_id immediately, completion is asynchronous, and results are retrieved via fetch_analysis_result. It also notes that a recent matching analysis may be reused, which guides when initiation might avoid new work. However, it does not explicitly state 'when not to use' this tool beyond implying reuse, but the mention of fetch_analysis_result as the retrieval alternative is a strong usage signal.

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

All StockLens tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.2/5.0

Disambiguation4/5

Each tool has a distinct function: initiate_analysis starts an async job, fetch_analysis_result retrieves that job's status/result, get_market_summary returns the latest pre-computed score, and get_portfolio_insights covers multiple tickers. The only mild overlap is between fetch_analysis_result and get_market_summary, but descriptions make the difference clear.

Naming Consistency4/5

Tool names mostly follow a verb_noun pattern (fetch, get, get, initiate), with only 'ping' breaking the convention. The mix of 'fetch' and 'get' is a minor inconsistency but doesn't obscure meaning.

Tool Count5/5

Five tools is well-scoped for a stock analysis server. Each tool covers a distinct part of the workflow: initiating analysis, fetching results, getting summaries, portfolio overview, and a health check. No bloat or excessive granularity.

Completeness4/5

The analysis lifecycle is covered end-to-end: initiate, fetch, and get latest summary, plus portfolio-level insights. The only notable gap is lack of a 'list analyses' or 'cancel analysis' tool, but that's not critical for the core purpose.

Resources

Need Help?