StockLens

Initiate Analysis

initiate_analysis

Destructive

Start a full StockLens analysis of one company, only when the person asks for one. A new run may use one Analysis credit, or one Plus Analysis credit when depth is plus; Plus adds a written narrative and the result says if the person's plan does not include it. It returns an analysis_id at once and finishes asynchronously; fetch the result with fetch_analysis_result when the person asks for it. new_run_started and reused_existing say whether a recent matching analysis was reused. One ticker per call. It does not rank or compare companies, and does not trade or move money.

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). Exactly one ticker per call.
`exchange`	No	Exchange code (e.g. NASDAQ). Optional. Resolved automatically if omitted.
`time_range`	No	Time horizon. It 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. It 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
`scope`	Yes
`status`	Yes
`analysis_id`	Yes
`credit_type`	Yes
`new_run_started`	Yes
`reused_existing`	Yes
`estimated_seconds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

changedInput schema / properties / ticker / pattern

Previous value: -"^[A-Za-z][A-Za-z.\\-]{0,9}$"New value: +"^[A-Za-z0-9][A-Za-z0-9.\\-]{0,19}$"

Changed5 schema fields changedSep 25, 2026

changedInput schema / properties / exchange / description

Previous value: -"Exchange code (e.g. NASDAQ). Optional - resolved automatically if omitted."New value: +"Exchange code (e.g. NASDAQ). Optional. Resolved automatically if omitted."

addedInput schema / properties / exchange / enum

Added value: +[
+  "NYSE",
+  "NASDAQ",
+  "AMEX",
+  "OTC",
+  "CBOE",
+  "TSX",
+  "TSXV",
+  "CNQ",
+  "NEO",
+  "MEX",
+  "B3",
+  "SANTIAGO",
+  "BUE",
+  "BVC",
+  "LSE",
+  "EURONEXT_PARIS",
+  "EURONEXT_AMSTERDAM",
+  "EURONEXT_BRUSSELS",
+  "EURONEXT_LISBON",
+  "EURONEXT_DUBLIN",
+  "XETRA",
+  "SIX",
+  "BME",
+  "MILAN",
+  "OSLO",
+  "OMX_STOCKHOLM",
+  "OMX_HELSINKI",
+  "OMX_COPENHAGEN",
+  "WSE",
+  "VIE",
+  "ATH",
+  "PRA",
+  "BUD",
+  "IST",
+  "ICE",
+  "RIS",
+  "TAL",
+  "MCX",
+  "TSE",
+  "HKEX",
+  "SHANGHAI",
+  "SHENZHEN",
+  "ASX",
+  "TWSE",
+  "SGX",
+  "NSE",
+  "KRX",
+  "BSE",
+  "KOE",
+  "JKT",
+  "KLS",
+  "SET",
+  "NZE",
+  "HOSE",
+  "TWO",
+  "TADAWUL",
+  "JSE",
+  "TLV",
+  "DFM",
+  "EGX",
+  "DOH",
+  "KUW"
+]

changedInput schema / properties / risk_tolerance / description

Previous value: -"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."New value: +"Analysis focus. It 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."

changedInput schema / properties / ticker / description

Previous value: -"Stock ticker symbol (e.g. AAPL)"New value: +"Stock ticker symbol (e.g. AAPL). Exactly one ticker per call."

changedInput schema / properties / time_range / description

Previous value: -"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."New value: +"Time horizon. It 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."

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / exchange / description

Previous value: -"Exchange code (e.g. NASDAQ). Optional."New value: +"Exchange code (e.g. NASDAQ). Optional - resolved automatically if omitted."

Changed3 schema fields changedSep 5, 2026

addedInput schema / properties / ticker / pattern
```
Added value: +"^[A-Za-z][A-Za-z.\\-]{0,9}$"
```

addedOutput schema / properties / scope

Added value: +{
+  "enum": [
+    "single_analysis_receipt"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "analysis_id",
-  "status",
-  "estimated_seconds",
-  "depth",
-  "credit_type",
-  "new_run_started",
-  "reused_existing"
-]New value: +[
+  "analysis_id",
+  "status",
+  "estimated_seconds",
+  "depth",
+  "credit_type",
+  "new_run_started",
+  "reused_existing",
+  "scope"
+]

Changed1 schema field changedAug 14, 2026

changedInput schema / properties / depth / description

Previous value: -"Analysis depth: standard or plus. Standard uses LENS_AI credit. Plus uses LENS_AI_PLUS credit and may add AI narratives. Default standard."New value: +"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."

First observedAug 3, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The annotations already flag destructiveHint=true and readOnlyHint=false, and the description meaningfully expands on this by disclosing credit consumption, asynchronous execution, immediate return of analysis_id, and the new_run_started/reused_existing reuse semantics. This helps the agent understand side effects and lifecycle without over-relying on structured hints.

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

Conciseness5/5

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

The description is compact but complete: trigger condition, cost implications, async behavior, follow-up instruction, reuse flags, and explicit non-goals. Every sentence earns its place, and the most important operational constraint is front-loaded.

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 (7 params, output schema, destructive/credit side effects), the description covers everything an agent needs: when to invoke it, what it costs, how it behaves asynchronously, how to fetch the result, whether an analysis may be reused, and what it will not do. The output schema covers return values, so no description redundancy is needed.

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 coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by clarifying the ticker constraint ('One ticker per call') and explaining the behavioral consequence of the depth parameter ('Plus adds a written narrative'). These additions enrich the otherwise well-documented schema.

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 opens with a specific verb and resource: 'Start a full StockLens analysis of one company.' It is immediately distinguishable from siblings by stating what it does not do ('does not rank or compare companies, and does not trade or move money') and by referencing its natural counterpart, fetch_analysis_result. An agent can clearly identify the tool's scope.

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

Usage Guidelines5/5

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

It gives an explicit trigger condition ('only when the person asks for one') and explicitly routes the follow-up action ('fetch the result with fetch_analysis_result when the person asks for it'). It also provides when-not context: it does not rank/compare or trade/move money. These are explicit usage directions with clear alternatives.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?