StockLens

Add to Portfolio

add_to_watchlist

Add one company to one of the person's StockLens portfolios as a company they follow, so its score stays readable here. Call it only when the person has asked for it or agreed to an offer. Without portfolio_id or portfolio_name it adds to the default portfolio, and the result names the portfolio that received it. Relay the result's message, which says where the company went. A status other than added is an answer, not an error: relay its message and act on next_step. After an add the person accepted from a get_market_summary offer, call get_market_summary again to answer their question. One ticker per call; for a list of companies, use add_to_watchlist_batch. It does not trade, record a holding or move money.

Input Schema

Name	Required	Description
`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.
`portfolio_id`	No	The id of the portfolio to add to, as get_portfolio_insights lists it. Optional: without it or portfolio_name the company goes to the default portfolio.
`portfolio_name`	No	The name of the portfolio to add to, as the person names it (exact, case does not matter). Optional.

Output Schema

Name	Required	Description	Default
`mode`	No
`scope`	Yes
`status`	Yes
`ticker`	No
`message`	Yes
`exchange`	No
`next_step`	No
`candidates`	No
`is_default`	No
`plan_limit`	No
`portfolios`	No
`company_name`	No
`portfolio_id`	No
`company_count`	No
`portfolio_name`	No
`portfolio_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 20, 2026
- addedOutput schema / properties / candidates / items / properties / scored
```
Added value: +{
+  "type": [
+    "null",
+    "boolean"
+  ]
+}
```

Changed15 schema fields changedOct 17, 2026

addedInput schema / properties / portfolio_id

Added value: +{
+  "description": "The id of the portfolio to add to, as get_portfolio_insights lists it. Optional: without it or portfolio_name the company goes to the default portfolio.",
+  "type": "string"
+}

addedInput schema / properties / portfolio_name

Added value: +{
+  "description": "The name of the portfolio to add to, as the person names it (exact, case does not matter). Optional.",
+  "type": "string"
+}

addedOutput schema / properties / candidates

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "company_name": {
+        "type": "string"
+      },
+      "exchange": {
+        "type": "string"
+      },
+      "ticker": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "ticker",
+      "exchange",
+      "company_name"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / company_count

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

addedOutput schema / properties / is_default

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

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

addedOutput schema / properties / mode

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

addedOutput schema / properties / next_step

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "arguments": {
+      "additionalProperties": false,
+      "properties": {
+        "exchange": {
+          "type": "string"
+        },
+        "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"
+  ]
+}

addedOutput schema / properties / portfolio_count

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

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

addedOutput schema / properties / portfolios

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "company_count": {
+        "type": "integer"
+      },
+      "is_default": {
+        "type": "boolean"
+      },
+      "portfolio_id": {
+        "type": "string"
+      },
+      "portfolio_name": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "portfolio_id",
+      "portfolio_name",
+      "is_default",
+      "company_count"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "added",
+    "already_in_portfolio",
+    "over_capacity",
+    "ambiguous",
+    "not_found",
+    "portfolio_not_found"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / total_holdings
```
Removed value: -{
-  "type": "integer"
-}
```

changedOutput schema / required

Previous value: -[
-  "ticker",
-  "exchange",
-  "total_holdings",
-  "plan_limit",
-  "scope"
-]New value: +[
+  "status",
+  "message",
+  "scope"
+]

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}$"

Changed3 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 / ticker / description

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

Changed1 schema field changedSep 19, 2026

changedInput schema / properties / exchange / description

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

AddedSep 18, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): it discloses the write is gated on user consent, that the result names the portfolio that received the company, that a status other than 'added' is an answer rather than an error (with next_step to act on), and that a follow-up get_market_summary is needed to answer an accepted offer. That is meaningful behavioral context an agent cannot derive from the structured fields.

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-loads the core action and constraint, and each sentence carries operational content. Slight redundancy between 'the result names the portfolio that received it' and the following 'Relay the result's message, which says where the company went', which is the only real waste.

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?

With an output schema present the description needn't explain return shape, yet it usefully explains how to interpret non-success statuses and the follow-up call. Safety profile is covered by annotations and consent gating is covered by the description, leaving nothing an agent needs to call this correctly.

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 schema already documents the default-portfolio fallback for omitted portfolio_id/portfolio_name and the ticker cardinality. The description largely restates these ('Without portfolio_id or portfolio_name it adds to the default portfolio'), adding little beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Add one company to one of the person's StockLens portfolios as a company they follow') and explicitly distinguishes itself from the sibling add_to_watchlist_batch ('One ticker per call'). It also rules out misreading by declaring 'It does not trade, record a holding or move money', which separates it from any trading-adjacent sibling.

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 ('Call it only when the person has asked for it or agreed to an offer'), names the alternative for lists (add_to_watchlist_batch), and states the follow-up call pattern after a get_market_summary offer. The default-portfolio case for omitting portfolio_id/portfolio_name is also covered, so the agent knows when each parameter variant applies.

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?