StockLens

Discover Stocks

discover_stocks

Read-only

Screen the companies StockLens scores nightly by region, exchange, sector, industry, market-cap band and trading volume, sorted by one of the six StockLens scores or by market cap, volume or ticker, and return the top or bottom N. Popularity ordering is unavailable: analysis_volume and user_volume are retired and return VALIDATION_ERROR without running a screen. For a popularity request, ask the person to choose a supported ordering. Use it for any top N, best, worst, highest, lowest or filtered request across the companies StockLens scores, and never build such a list from get_market_summary or general knowledge; to compare only companies the person names, call get_market_summary for each instead. It has no valuation, price-target or growth filter; say so rather than calling a score sort one. status ranked means the requested order was used. When a ranked result carries message, relay it; it states what the ranking covers, so never present the rows as a ranking of more than that. browse_substituted means a score order was asked for and market-cap order with scores hidden was returned, so never describe those rows as ranked by score. locked means no companies are named; relay message verbatim. What the caller can sort and how far it reaches is in access_tier and reach_capped_at; signed_in_as names the account they belong to. Report only the rows returned. It does not trade and gives no personal recommendations.

Input Schema

Name	Required	Description
`page`	No	0-based page of results, 0 to 500. Default 0.
`limit`	No	Number of matches to return (the N in top/bottom N), 1 to 100. Default 10.
`sort_by`	No	One of the 6 StockLens scores, market_cap, volume or ticker. Default composite_score. Popularity ordering is unavailable.
`macro_in`	No	Restrict to these macro regions. Omitted = no restriction.
`direction`	No	top = highest first, bottom = lowest first. Default top.
`sector_in`	No	Restrict to these GICS sectors. Omitted = no restriction.
`exchange_in`	No	Restrict to these exchanges. Omitted = no restriction.
`industry_in`	No	Restrict to these GICS industries. Omitted = no restriction.
`search_text`	No	Free-text company name/ticker search, up to 80 characters.
`volume_floor`	No	Minimum average trading volume. Omitted = no floor.
`market_cap_band`	No	Restrict to this market-cap band. Omitted = no cap restriction.

Output Schema

Name	Required	Description	Default
`rows`	Yes
`scope`	Yes
`status`	Yes
`message`	No
`next_step`	No
`as_of_date`	No
`access_tier`	Yes
`data_source`	Yes
`hard_locked`	Yes
`signed_in_as`	No
`rows_returned`	Yes
`scores_locked`	Yes
`total_matches`	No
`config_context`	Yes
`effective_sort`	Yes
`reach_capped_at`	No
`sort_substituted`	No
`effective_direction`	Yes
`quota_remaining_today`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 17, 2026
- addedOutput schema / properties / next_step / properties / arguments / properties / exchange
```
Added value: +{
+  "type": "string"
+}
```

Changed3 schema fields changedOct 15, 2026

changedInput schema / properties / sort_by / description

Previous value: -"One of the 6 StockLens scores or a non-score signal to sort by. Default composite_score."New value: +"One of the 6 StockLens scores, market_cap, volume or ticker. Default composite_score. Popularity ordering is unavailable."

changedInput schema / properties / sort_by / enum

Previous value: -[
-  "composite_score",
-  "fundamental_score",
-  "technical_score",
-  "risk_score",
-  "sentiment_score",
-  "macro_score",
-  "analysis_volume",
-  "user_volume",
-  "ticker",
-  "market_cap",
-  "volume"
-]New value: +[
+  "composite_score",
+  "fundamental_score",
+  "technical_score",
+  "risk_score",
+  "sentiment_score",
+  "macro_score",
+  "ticker",
+  "market_cap",
+  "volume"
+]

addedOutput schema / properties / signed_in_as
```
Added value: +{
+  "type": "string"
+}
```

Changed12 schema fields changedSep 25, 2026

changedInput schema / properties / limit / description

Previous value: -"Number of matches to return (the N in top/bottom N), 1-100. Default 10."New value: +"Number of matches to return (the N in top/bottom N), 1 to 100. Default 10."

addedInput schema / properties / limit / maximum
```
Added value: +100
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

changedInput schema / properties / page / description

Previous value: -"0-based page of results, 0-500. Default 0."New value: +"0-based page of results, 0 to 500. Default 0."

addedInput schema / properties / page / maximum
```
Added value: +500
```
addedInput schema / properties / page / minimum
```
Added value: +0
```

addedOutput schema / properties / message

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

addedOutput schema / properties / next_step

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "arguments": {
+      "additionalProperties": false,
+      "properties": {
+        "ticker": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ticker"
+      ],
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "description": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "call_tool",
+        "ask_user",
+        "human_action"
+      ],
+      "type": "string"
+    },
+    "options": {
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / properties / rows / items / properties / macro_code / description

Previous value: -"Listing geography of the exchange (US, CA, EU, CH, GB, JP, or GLOBAL when unmapped) — the same value macro_in filters on."New value: +"Listing geography of the exchange (US, CA, EU, CH, GB, JP, or GLOBAL when unmapped), the same value macro_in filters on."

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "ranked",
+    "browse_substituted",
+    "locked"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / upgrade_message

Removed value: -{
-  "type": [
-    "null",
-    "string"
-  ]
-}

changedOutput schema / required

Previous value: -[
-  "rows",
-  "scores_locked",
-  "hard_locked",
-  "access_tier",
-  "rows_returned",
-  "effective_sort",
-  "effective_direction",
-  "config_context",
-  "data_source",
-  "scope"
-]New value: +[
+  "status",
+  "rows",
+  "scores_locked",
+  "hard_locked",
+  "access_tier",
+  "rows_returned",
+  "effective_sort",
+  "effective_direction",
+  "config_context",
+  "data_source",
+  "scope"
+]

Changed1 schema field changedSep 22, 2026
- addedOutput schema / properties / sort_substituted
```
Added value: +{
+  "type": "boolean"
+}
```

Changed2 schema fields changedSep 19, 2026

addedOutput schema / properties / hard_locked
```
Added value: +{
+  "type": "boolean"
+}
```

changedOutput schema / required

Previous value: -[
-  "rows",
-  "scores_locked",
-  "access_tier",
-  "rows_returned",
-  "effective_sort",
-  "effective_direction",
-  "config_context",
-  "data_source",
-  "scope"
-]New value: +[
+  "rows",
+  "scores_locked",
+  "hard_locked",
+  "access_tier",
+  "rows_returned",
+  "effective_sort",
+  "effective_direction",
+  "config_context",
+  "data_source",
+  "scope"
+]

AddedSep 5, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare the safety profile (readOnly, non-destructive, non-idempotent, closed-world), so the description carries the operational burden and does so richly: popularity ordering returns VALIDATION_ERROR without running a screen, and the status values ranked, browse_substituted and locked each carry distinct semantics and required agent behavior. It also flags the absence of valuation/price-target/growth filters and warns against mislabeling a score sort.

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?

Purpose, filters, sort and return shape are front-loaded before the operational caveats, and nearly every sentence earns its place by changing agent behavior. It is nonetheless long and dense, and the popularity-unavailable point is restated in the sort_by schema, so it falls just short of fully tight.

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, so return values need not be spelled out, yet the description still supplies the status/message/access_tier/reach_capped_at interpretation an agent needs to relay results faithfully. Combined with the usage and error guidance, nothing required to call or report this tool correctly 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%, so the schema already documents all 11 parameters including enums and defaults. The description reinforces the sort and filter semantics and the popularity exclusion, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate 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.

Purpose5/5

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

The opening sentence gives a specific verb (screen), a precise resource (the companies StockLens scores nightly), the full filter surface (region, exchange, sector, industry, cap band, volume), the sort options, and the return shape (top/bottom N). It explicitly differentiates from get_market_summary, which is the closest sibling. An agent can pick this tool 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.

Usage Guidelines5/5

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

It states when to use it ('any top N, best, worst, highest, lowest or filtered request'), when not to (never build such a list from get_market_summary or general knowledge), and names the alternative for the named-company case ('call get_market_summary for each instead'). It also handles the popularity edge case by instructing the agent to ask the person to pick a supported ordering.

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?