Skip to main content
Glama
Sign In

StockLens

by com.stocklens
OverviewDiscussionsAdmin

Initiate Analysis

initiate_analysis
Destructive

Start a fresh StockLens analysis of one company, only when the person asks for one or agrees to an offer of one in a get_market_summary result. A new run may use one Analysis credit, or one Plus Analysis credit when depth is plus; the result says if the person's plan does not include it. Use it for a requested evidence gap beyond the nightly snapshot, such as factor values, peer context or ranked contributors. Both depths include written domain summaries and synthesis when produced; Plus adds deeper synthesis and extra web cards where available. The assistant result is condensed; the saved web report has the factor cards and Explain views. 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

NameRequiredDescriptionDefault
depthNoAnalysis depth: standard or plus. Both include written domain summaries and synthesis when produced. Plus uses deeper synthesis and adds extra cards in the web report where available. Standard uses an Analysis credit (LENS_AI); Plus uses a Plus Analysis credit (LENS_AI_PLUS). Default standard.
tickerYesStock ticker symbol (e.g. AAPL). Exactly one ticker per call.
exchangeNoExchange code (e.g. NASDAQ). Optional. Resolved automatically if omitted.
time_rangeNoTime 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_toleranceNoAnalysis 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_emphasisNoOptional. 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_familyNoOptional. 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

NameRequiredDescriptionDefault
depthYes
scopeYes
statusYes
analysis_idYes
credit_typeYes
new_run_startedYes
reused_existingYes
estimated_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / depth / description
      Previous 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."New value: +"Analysis depth: standard or plus. Both include written domain summaries and synthesis when produced. Plus uses deeper synthesis and adds extra cards in the web report where available. Standard uses an Analysis credit (LENS_AI); Plus uses a Plus Analysis credit (LENS_AI_PLUS). Default standard."
  2. Changed1 schema field changed
    • 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}$"
  3. Changed5 schema fields changed
    • 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."
  4. Changed1 schema field changed
    • 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."
  5. Changed3 schema fields changed
    • 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"
+]
  6. Changed1 schema field changed
    • 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."
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only flag it as non-read-only, non-idempotent and destructive; the description explains why — it consumes one Analysis or Plus Analysis credit, is plan-gated ('the result says if the person's plan does not include it'), and is asynchronous (returns analysis_id at once, completes in background). It further discloses reuse semantics via new_run_started/reused_existing and the condensed assistant result vs. the fuller saved web report.

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?

Front-loaded with the trigger condition and use case before the credit/async mechanics, and almost every sentence carries operational value. Minor redundancy: the depth tiers and 'one ticker per call' are restated from the schema, and the credit/plan sentences could be tightened.

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?

An output schema exists, yet the description still supplies the workflow-level context an agent needs: asynchronous execution, the analysis_id handoff to fetch_analysis_result, the reuse fields, and the difference between the condensed assistant payload and the saved report. Nothing needed to call this correctly against a 7-parameter tool is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the parameter docs are already rich (depth, exchange resolution, time_range bands, risk_tolerance reweighting, cross-field agreement rules), so the baseline is 3. The description restates the credit implication of depth and the 'one ticker per call' constraint but adds little parameter meaning beyond the 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?

Opens with a specific verb+resource and scope: 'Start a fresh StockLens analysis of one company,' immediately narrowing to a single-ticker, single-company operation. It explicitly disambiguates from siblings by naming fetch_analysis_result for retrieval and by stating it 'does not rank or compare companies' (discover_stocks/get_market_summary territory).

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?

Gives an explicit precondition ('only when the person asks for one or agrees to an offer of one in a get_market_summary result') plus a positive use case (requested evidence gap beyond the nightly snapshot: factor values, peer context, ranked contributors). It also routes the follow-up step to fetch_analysis_result 'when the person asks for it' and names exclusions (no ranking/comparison, no trading).

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

All StockLens toolsInspect
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