What inputs does save_thesis accept?

ticker (string, required): US-listed ticker. Case-insensitive — normalised to upper. E.g. 'AAPL'. view ("bull" | "bear" | "neutral", required): Directional view: bull (expect outperformance), bear (under), neutral (mean-revert). conviction (integer, required): 1 = low conviction (gut feel) → 5 = high conviction (deep analysis). horizon_days (integer, required): Investment horizon in days. 1 day–5 years (1825d). The grader uses this to pick the as-of period. notes (string, optional): Free-form rationale, ≤4000 chars. Stored verbatim; trim before submitting. thesis_at_price_cents (integer, optional): 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. source_report_id (string, optional): Optional id of a report (from `create_report` / `publish_report`) that contains the supporting analysis. idempotency_key (string, optional): 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. visibility ("private" | "unlisted" | "public", optional, default "private"): 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.

Which Valuein plans include save_thesis?

Available on the free tier (token required) and on Pro and Institutional. Not point-in-time safe.

state

Save Investment Thesis

save_thesis

Benchmark and above

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 seman...

Example Call

example_call.pypython

# Using the Valuein MCP server from Python (via MCP SDK)# Or call directly from Claude / Cursor after setup result = await client.call_tool(    "save_thesis",    arguments={    "ticker": "EXAMPLE",    "view": "bull",    "conviction": 10,    "horizon_days": 10})print(result)

Direct tool call:save_thesis(...)

Inputs

Parameter	Type	Required	Description
`ticker`	string	required	US-listed ticker. Case-insensitive — normalised to upper. E.g. 'AAPL'.
`view`	"bull" \| "bear" \| "neutral"	required	Directional view: bull (expect outperformance), bear (under), neutral (mean-revert).
`conviction`	integer	required	1 = low conviction (gut feel) → 5 = high conviction (deep analysis).
`horizon_days`	integer	required	Investment horizon in days. 1 day–5 years (1825d). The grader uses this to pick the as-of period.
`notes`	string	optional	Free-form rationale, ≤4000 chars. Stored verbatim; trim before submitting.
`thesis_at_price_cents`	integer	optional	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.
`source_report_id`	string	optional	Optional id of a report (from `create_report` / `publish_report`) that contains the supporting analysis.
`idempotency_key`	string	optional	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.
`visibility`	"private" \| "unlisted" \| "public"	optional	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.Default: `"private"`

Output Fields

thesisdeduplicatedcapacity

Example Response

Illustrative

response.jsonjson

{  "thesis": null,  "deduplicated": null,  "capacity": null}

Shape only — field names match the live schema; values are placeholders, not real filings. See MCP server for the structured response shape.

Notes

Available from the Benchmark plan and above.

Try this tool

Get token All tools

Categorystate

PIT-safeNo

Min planBenchmark

Inputs9 (4 required)

Plan Access

Sample (guest)

Not included

Benchmark (token)

Available

Pro

Available

Institutional

Available

Related Tools

search_companies

Search Companies

get_company_fundamentals

Company Fundamentals

get_valuation_metrics

Valuation Metrics

get_financial_ratios

Financial Ratios

Resources

Point-in-Time methodology →Parquet schema reference →Bulk Data API reference →Python SDK guide →

Index names are trademarks of their owners; Valuein is not affiliated with or endorsed by any index provider.