Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Save Investment Thesis

save_thesis

Idempotent

Persist a directional investment thesis (bull / bear / neutral) on a ticker. The thesis becomes part of the caller's private research diary; pair with list_theses + score_thesis_outcome to track conviction-vs-outcome over time. Pass idempotency_key for at-most-once semantics from a retrying agent.

Use this AFTER the agent has finished its analysis, not before — the thesis records the conclusion, not the question. Pair with source_report_id to link the thesis back to a published report so the buyer's thesis-tracking carries provenance.

Tier: all paid + free tiers (sample tier rejected — sample is guest access with no customerId binding). Flat 10,000-thesis anti-abuse cap per account (archiving frees a slot; never a tier limit).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`view`	Yes	Directional view: bull (expect outperformance), bear (under), neutral (mean-revert).
`notes`	No	Free-form rationale, ≤4000 chars. Stored verbatim; trim before submitting.
`ticker`	Yes	US-listed ticker. Case-insensitive — normalised to upper. E.g. 'AAPL'.
`conviction`	Yes	1 = low conviction (gut feel) → 5 = high conviction (deep analysis).
`visibility`	No	Phase 3: 'private' (default) is owner-only; 'unlisted' is visible at a known direct URL; 'public' surfaces on the author's /[handle] profile and contributes to their reputation score.	private
`horizon_days`	Yes	Investment horizon in days. 1 day–5 years (1825d). The grader uses this to pick the as-of period.
`idempotency_key`	No	Optional client-supplied key. If a previous `save_thesis` from the same user used this key, the existing thesis is returned instead of creating a duplicate.
`source_report_id`	No	Optional id of a report (from `create_report` / `publish_report`) that contains the supporting analysis.
`thesis_at_price_cents`	No	Optional snapshot of the ticker's market price (integer cents) at thesis creation. Used by future versions of the grader that mix in price returns; null for now is fine.

Output Schema

TableJSON Schema

Name	Required	Description
`_meta`	Yes	Provenance envelope — data lineage for every MCP response
`thesis`	Yes
`capacity`	Yes
`deduplicated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 18, 2026

changedOutput schema / properties / _meta / properties / fundamentals_as_of / description

Previous value: -"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to."New value: +"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."

Changed2 schema fields changedJul 25, 2026

addedOutput schema / properties / _meta / properties / fundamentals_as_of

Added value: +{
+  "description": "ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to.",
+  "type": "string"
+}

addedOutput schema / properties / _meta / properties / price_as_of

Added value: +{
+  "description": "ISO timestamp when the price surfaces were last refreshed.",
+  "type": "string"
+}

Changed2 schema fields changedJul 7, 2026

addedOutput schema / properties / _meta / properties / cost_usd

Added value: +{
+  "additionalProperties": false,
+  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
+  "properties": {
+    "amount_usd": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "basis": {
+      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
+      "enum": [
+        "payg_charge",
+        "payg_rate_card"
+      ],
+      "type": "string"
+    },
+    "billed": {
+      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "amount_usd",
+    "billed",
+    "basis"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / _meta / properties / latency_ms

Added value: +{
+  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
+  "minimum": 0,
+  "type": "integer"
+}

Changed1 schema field changedJul 3, 2026

addedOutput schema / properties / thesis / properties / outcome_components

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Phase C fundamentals × price breakdown (fundamentals_score, price_score, price_return_pct, legs_used, basis, …). Null when not yet scored or scored without a breakdown; absent entirely on records graded before Phase C shipped — both mean 'no components recorded'."
+}

Changed1 schema field changedJun 18, 2026
- addedOutput schema / properties / _meta / properties / pit_safe / description
```
Added value: +"true iff a zero-look-ahead point-in-time cut was applied to every returned figure"
```

Changed1 schema field changedMay 29, 2026

addedOutput schema / properties / thesis / properties / visibility

Added value: +{
+  "description": "Phase 3 visibility: 'private' (owner-only), 'unlisted' (known URL), 'public' (surfaces on the author's /[handle] profile + reputation).",
+  "enum": [
+    "private",
+    "unlisted",
+    "public"
+  ],
+  "type": "string"
+}

Changed1 schema field changedMay 16, 2026

addedInput schema / properties / visibility

Added value: +{
+  "default": "private",
+  "description": "Phase 3: 'private' (default) is owner-only; 'unlisted' is visible at a known direct URL; 'public' surfaces on the author's /[handle] profile and contributes to their reputation score.",
+  "enum": [
+    "private",
+    "unlisted",
+    "public"
+  ],
+  "type": "string"
+}

AddedMay 12, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds context about the idempotency_key for at-most-once semantics, which aligns with the annotation, and discloses the private diary nature, tier restrictions, and the anti-abuse cap. It does not contradict annotations and provides extra behavioral detail beyond what annotations convey.

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?

The description is three paragraphs and is fairly concise. The main purpose is front-loaded in the first sentence, and the structure logically separates the core functionality, usage timing, and tier restrictions. While the tier details could be trimmed, the overall length is acceptable and well-organized.

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?

The description covers the essential operational context: what the tool does, when to use it, related tools, idempotency semantics, and tier restrictions. With a full schema and an output schema present, the description is comprehensive enough for an agent to invoke the tool correctly. No critical information 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 all parameters are already well-documented in the schema. The description reiterates the idempotency_key and source_report_id purposes but adds no significant new meaning beyond what the schema provides. Thus, it meets the baseline for high coverage but does not elevate it.

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 clearly states the tool's purpose: 'Persist a directional investment thesis (bull / bear / neutral) on a ticker.' It specifies the resource (thesis on a ticker) and the action (persist). It also distinguishes itself from siblings by naming list_theses and score_thesis_outcome, making it clear this is the creation tool, not retrieval or evaluation.

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?

Explicit usage guidance is given: 'Use this AFTER the agent has finished its analysis, not before — the thesis records the conclusion, not the question.' It also advises pairing with list_theses and score_thesis_outcome for tracking and with source_report_id for provenance. This gives clear when-to-use context and implies when not to use (before analysis).

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

All Valuein — SEC EDGAR Fundamentals & Smart-Money Data 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.