StockLens

Get Portfolio

get_portfolio_insights

Read-onlyIdempotent

Read one of the person's StockLens portfolios: every company in it, each marked holding or watching with its score and rating word, and the portfolio's average score and rating word, its change over 7 and 30 nights, its largest sector share and its biggest movers over 7 nights, each with a driver of its latest reading that points the same way. Without portfolio_id or portfolio_name it reads the default portfolio. portfolios lists every portfolio the person owns and appears only when there is more than one: then name the portfolio you read once and offer the others by name. With one portfolio, never name it. A portfolio the person does not own returns portfolio_not_found with the choices; never guess. Relay message, caption, trust and concentration as written. If a window says insufficient_data, say so; do not estimate a change. config_changed marks a window in which StockLens changed how it scores, so part of that change is the method, not the market. The scores are the ones get_market_summary serves, as of as_of. It does not rank or screen companies outside the portfolio; call discover_stocks for that. It holds no money figures and gives no personal advice.

Input Schema

Name	Required	Description	Default
`portfolio_id`	No	The id of the portfolio to read, as a portfolios list gives it. Optional: without it or portfolio_name the default portfolio is read.
`portfolio_name`	No	The name of the portfolio to read, as the person names it (exact, case does not matter). Optional.

Output Schema

Name	Required	Description	Default
`as_of`	No
`scope`	Yes
`trust`	No
`rating`	No
`status`	Yes
`caption`	No
`message`	No
`companies`	No
`next_step`	No
`fund_count`	No
`is_default`	No
`population`	No
`portfolios`	No
`top_movers`	No
`portfolio_id`	No
`tier_limited`	No
`company_count`	No
`concentration`	No
`movers_window`	No
`window_change`	No
`holdings_count`	No
`portfolio_name`	No
`portfolio_count`	No
`scored_company_count`	No
`scored_holdings_count`	No
`average_composite_score`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 27, 2026
- addedOutput schema / properties / top_movers / items / properties / driver / properties / peer_group
```
Added value: +{
+  "type": [
+    "null",
+    "string"
+  ]
+}
```

Changed30 schema fields changedOct 17, 2026

addedInput schema / properties

Added value: +{
+  "portfolio_id": {
+    "description": "The id of the portfolio to read, as a portfolios list gives it. Optional: without it or portfolio_name the default portfolio is read.",
+    "type": "string"
+  },
+  "portfolio_name": {
+    "description": "The name of the portfolio to read, as the person names it (exact, case does not matter). Optional.",
+    "type": "string"
+  }
+}

removedOutput schema / properties / aggregate_signal

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

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

addedOutput schema / properties / average_composite_score

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

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

addedOutput schema / properties / companies

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "company_name": {
+        "type": "string"
+      },
+      "composite_score": {
+        "type": [
+          "null",
+          "number"
+        ]
+      },
+      "exchange": {
+        "type": "string"
+      },
+      "freshness": {
+        "enum": [
+          "aging",
+          "stale"
+        ],
+        "type": "string"
+      },
+      "instrument": {
+        "enum": [
+          "fund"
+        ],
+        "type": "string"
+      },
+      "last_scored": {
+        "type": "string"
+      },
+      "mode": {
+        "enum": [
+          "holding",
+          "watching"
+        ],
+        "type": "string"
+      },
+      "rating": {
+        "type": "string"
+      },
+      "ticker": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "ticker",
+      "exchange",
+      "mode"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / company_count

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

addedOutput schema / properties / concentration

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "lead": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "sectors": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "companies": {
+            "type": "integer"
+          },
+          "sector": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "sector",
+          "companies"
+        ],
+        "type": "object"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / fund_count
```
Added value: +{
+  "type": "integer"
+}
```
addedOutput schema / properties / holdings_count
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / is_default

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

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

addedOutput schema / properties / movers_window

Added value: +{
+  "enum": [
+    "7_nights"
+  ],
+  "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 / population
```
Added value: +{
+  "type": "string"
+}
```

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 / rating
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / scored_company_count

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

addedOutput schema / properties / scored_holdings_count
```
Added value: +{
+  "type": "integer"
+}
```

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "ok",
+    "empty",
+    "portfolio_not_found"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / tier_limited / type

Previous value: -"boolean"New value: +[
+  "null",
+  "boolean"
+]

addedOutput schema / properties / top_movers

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "change": {
+        "type": "number"
+      },
+      "composite_score": {
+        "type": "number"
+      },
+      "driver": {
+        "additionalProperties": false,
+        "properties": {
+          "context": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "domain": {
+            "type": [
+              "null",
+              "string"
+            ]
+          },
+          "kind": {
+            "enum": [
+              "SUPPORTIVE",
+              "HEADWIND",
+              "MIXED",
+              "COVERAGE_GAP",
+              "NEUTRAL_NOT_MATERIAL"
+            ],
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "metric": {
+            "type": [
+              "null",
+              "string"
+            ]
+          }
+        },
+        "required": [
+          "kind",
+          "label"
+        ],
+        "type": [
+          "null",
+          "object"
+        ]
+      },
+      "mode": {
+        "enum": [
+          "holding",
+          "watching"
+        ],
+        "type": "string"
+      },
+      "rating": {
+        "type": "string"
+      },
+      "ticker": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "ticker",
+      "mode",
+      "change",
+      "composite_score",
+      "rating"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

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

addedOutput schema / properties / trust

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

removedOutput schema / properties / watchlist

Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "analysis_date": {
-        "type": [
-          "null",
-          "string"
-        ]
-      },
-      "company_name": {
-        "type": "string"
-      },
-      "composite_grade": {
-        "type": [
-          "null",
-          "string"
-        ]
-      },
-      "composite_score": {
-        "type": [
-          "null",
-          "number"
-        ]
-      },
-      "exchange": {
-        "type": "string"
-      },
-      "ticker": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "ticker",
-      "company_name",
-      "exchange"
-    ],
-    "type": "object"
-  },
-  "type": [
-    "null",
-    "array"
-  ]
-}

addedOutput schema / properties / window_change

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "1m": {
+      "additionalProperties": false,
+      "properties": {
+        "change": {
+          "type": [
+            "null",
+            "number"
+          ]
+        },
+        "config_changed": {
+          "type": "boolean"
+        },
+        "insufficient_data": {
+          "type": "boolean"
+        }
+      },
+      "type": [
+        "null",
+        "object"
+      ]
+    },
+    "1w": {
+      "additionalProperties": false,
+      "properties": {
+        "change": {
+          "type": [
+            "null",
+            "number"
+          ]
+        },
+        "config_changed": {
+          "type": "boolean"
+        },
+        "insufficient_data": {
+          "type": "boolean"
+        }
+      },
+      "type": [
+        "null",
+        "object"
+      ]
+    }
+  },
+  "type": [
+    "null",
+    "object"
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "watchlist",
-  "total_holdings",
-  "tier_limited",
-  "scope"
-]New value: +[
+  "status",
+  "scope"
+]

Changed2 schema fields changedSep 5, 2026

addedOutput schema / properties / scope

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

changedOutput schema / required

Previous value: -[
-  "watchlist",
-  "total_holdings",
-  "tier_limited"
-]New value: +[
+  "watchlist",
+  "total_holdings",
+  "tier_limited",
+  "scope"
+]

First observedAug 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the portfolio_not_found error contract with choices, the config_changed method-change caveat, insufficient_data handling, and instructions to relay message/caption/trust/concentration verbatim. These are genuine behavioral caveats an agent would otherwise only discover at call time.

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 purpose and return contents before the conditional rules, and every clause carries operational weight. It is dense and runs long, with the scoring-provenance and 'holds no money figures' lines bordering on redundant given the output schema, but nothing is truly wasted.

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?

For a read-only two-param tool with an output schema, the description covers everything needed: defaulting behavior, error handling, data-quality flags, and what fields to relay verbatim. Even though the output schema exists, the description supplies the interpretive guidance that makes the returned values actionable.

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 baseline is 3, but the description adds precedence/default semantics not in the schema: with neither param the default portfolio is read, and the portfolid reference should come from a portfolios list. It does not resolve what happens if both id and name are supplied, leaving a small gap.

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 ('Read one of the person's StockLens portfolios') and enumerates exactly what is returned. It explicitly distinguishes itself from discover_stocks ('does not rank or screen companies outside the portfolio') and references get_market_summary for score provenance, so an agent can separate it from siblings without opening schemas.

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 explicit when-to-use rules (default portfolio when neither id nor name is given; name the portfolio once only when more than one exists; never name it when there is only one) and a named alternative for screening (discover_stocks). Also prescribes behavior on error ('never guess') and on partial data (insufficient_data, config_changed).

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?