StockLens

Discover Stocks

discover_stocks

Read-only

Screen the StockLens nightly-analyzed universe by macro region, exchange, sector, industry, market-cap band, and trading volume, then sort by any of the 6 StockLens scores or a non-score signal, returning the top or bottom N matches. This is the only StockLens tool that ranks or compares across multiple stocks — use it for any "top N", "best/worst", "highest/lowest scored", or filtered market-wide request; never fabricate such a list from get_market_summary or general knowledge. Free accounts can browse by market cap, volume, popularity, or ticker (StockLens scores hidden) with reach capped at 100 matches; sorting by a StockLens score returns a locked result naming zero stocks, with a plan message to relay verbatim. Pro and Max plans include full score sort with precise scores; Pro reach is capped at 5,000 matches, Max is unlimited. Does NOT execute trades, does NOT give personalized recommendations, and does NOT return more stocks than the structured result actually contains.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	0-based page of results, 0-500. Default 0.
`limit`	No	Number of matches to return (the N in top/bottom N), 1-100. Default 10.
`sort_by`	No	One of the 6 StockLens scores or a non-score signal to sort by. Default composite_score.
`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

TableJSON Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

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.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds crucial behavior beyond that: it explicitly states the tool does NOT execute trades or give personalized recommendations, and discloses plan-dependent behaviors (free accounts get locked results with zero stocks when sorting by score, with a plan message to relay verbatim). It also promises not to return more stocks than the structured result contains, which is extra safety context.

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?

Although longer than average, every sentence earns its place: the purpose is front-loaded, the alternatives and exclusions are stated early, and plan behaviors are packed efficiently. There is no fluff, redundancy, or tangential information, and the structure flows logically from purpose to constraints.

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 11 parameters, 4 enums, plan differences, and a locked-result edge case, the description covers all essential operational details. It explains the reach caps, the free-account locked behavior, and explicitly rules out trade execution and personalized advice. The output schema exists, so return value explanation is unnecessary. Nothing an agent needs to call 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 baseline is 3. The tool description does not add new semantics beyond what the schema already documents; it only paraphrases the filtering and sorting capabilities. No additional format, syntax, or edge-case details are provided, so it does not elevate beyond the baseline.

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 states a specific verb ('Screen'), a resource ('StockLens nightly-analyzed universe'), and a precise scope (filtering by region/exchange/sector/etc., sorting, and returning top/bottom N). It also differentiates itself from siblings by explicitly naming get_market_summary and stating it is the only ranking/comparison tool. This makes it immediately distinguishable from alternatives.

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?

Explicitly states when to use it ('any top N, best/worst, highest/lowest scored, or filtered market-wide request') and when not to (never fabricate from get_market_summary or general knowledge). It also provides plan-specific usage constraints (free vs Pro/Max reach limits) and the locked-result behavior for free accounts sorting by score.

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?