Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Reject a staged action by id. Terminal — the underlying tool is NEVER called, and a rejected (or otherwise already-decided) action can never be flipped back by a later approve/reject call; `transitioned` tells you whether THIS call is what moved it to 'rejected' or whether it was already decided. An id belonging to a different customer's token is indistinguishable from an unknown id (returns NOT_FOUND). Tier: sp500+ (sample rejected).

Return a 15-minute presigned download URL for a report in the requested binary format. `format=md` presigns the cached markdown — instant, no compute. `format=docx` returns a branded Word document with a cover page (title as the hero, the named analyst credited directly beneath it, a small 'Built on Valuein' credit linked to valuein.biz) followed by the report body on page 2 (masthead repeating the analyst's name, abstract, sections, citations table with clickable SEC EDGAR links), with a running footer (ticker, page number, a single disclosure line) repeated on every page. The DOCX is cached in R2 alongside the markdown after first build so repeat downloads are instant; pass `force_regenerate: true` to bust the cache (e.g. right after `update_report`). Tier gate mirrors `get_report`: authors always see their own reports; non-authors below the report's required tier get an upgrade prompt.

Undo a soft-delete: restores a thesis, watchlist, alert, claim or report that `delete_*` archived. The record returns to the state it held before the delete — a closed thesis comes back closed, a paused alert comes back paused. When the item was deleted before the server began recording its prior state, `prior_status_known` is false and the response says which default was used. A restored report returns to its prior status AND visibility, so a report that was public comes back public and one that was private stays private; when that state predates the change that began recording it, the report returns private and `prior_status_known` is false rather than guessing at publication. Citation overrides are NOT restorable (that delete removes the row outright) — use the approval flow. Idempotent: restoring a live item succeeds and changes nothing. Tier: paid + free (sample rejected).

A SMALL, BOUNDED, in-Worker sanity-check backtest — NOT a full-universe backtesting engine. Answers a quick question like 'does this factor actually work on these 5 names over the last year' inline, mid-conversation, without leaving MCP. Composes two existing tools (`get_pit_universe` + `get_pit_valuation_ratios`) across up to 10 tickers x 12 rebalance dates (120 cells): for each rebalance date, checks which requested tickers were in the survivorship-free PIT universe on that date (dropping — never erroring on — a ticker not yet listed or already delisted), then pulls each surviving ticker's point-in-time valuation multiples and computes the forward return to the NEXT rebalance date from the raw (unadjusted) close. Returns a flat {rebalance_date, ticker, factor_values, forward_return_pct} grid plus a small factor<->forward-return correlation per requested factor — a quick cross-sectional signal check, NOT a transaction-cost-aware portfolio simulation or a statistically validated backtest result. If the requested grid exceeds 120 cells, this tool does NOT silently truncate — it returns a `stream_fallback` response (signed Parquet download URLs, same shape as `get_compute_ready_stream`) and tells you to use those URLs. For a REAL full-universe, multi-date, survivorship-free backtest, use the Python SDK's AlphaEngine (`pip install valuein-sdk`) looped over `as_of` dates client-side — this tool is explicitly the small complement to that, not a replacement for it. Available on every plan; coverage follows your plan tier same as the two tools it composes.

Resolve a saved workflow by id and return a structured execution plan for a single ticker. Each plan entry names a real MCP tool or SOP plus its ticker-substituted arguments; the calling agent invokes them in order, applying any `skip_if` predicate against the previous step's output. **This tool does NOT execute the steps server-side.** It plans; the agent runs. Iterate through `plan[]` in order, call the named tool/SOP with `args`, accumulate outputs, and apply each step's `skip_if` (skip the step when the previous output's `path` equals `equals`). Workflows are private state owned by the calling user. Sample-tier callers are rejected. Pair with `list_workflows` (frontend) to discover available workflow_ids.

Persist a correction of a citation value. The correction is keyed on the canonical `fact_id` (a stable hash of CIK + accession + concept + period) so it applies to every report that references that same fact — including agent-regenerated reports. Re-saving the same fact_id replaces the prior correction in place (no duplicate row). The `fact_id` is VERIFIED against live SEC data (scoped to `ticker`) before the correction is stored — a fact_id that doesn't resolve to a real fact is rejected with FACT_NOT_FOUND and nothing is persisted. You therefore must supply the `ticker` the fact belongs to. Use this when the user notices an inaccuracy in an AI-generated report and wants the fix to persist. Provide `notes` for the rationale (≤500 chars) and `source_report_id` for provenance. Flat 10,000-override anti-abuse cap per account (deleting frees a slot; never a tier limit).

Persist a single falsifiable, evidence-backed CLAIM — the atomic unit of the research graph. Use this for each discrete assertion an analysis produces (e.g. 'NVDA gross margin stays above 70% through FY2026'), then compose claims into a thesis with `link_claim_to_thesis`. Claims are scored independently of theses, so claim accuracy is tracked as its own track record. Pick `claim_type` by HOW it's judged, not what it's about: `assertion` = true now, checked against data; `prediction` = resolves at `horizon_days` via `verifiable_condition`; `judgment` = qualitative, not auto-scored. Use `tags` for the topic (financial, valuation, macro, …). Set `eval_mode: 'auto'` + a `verifiable_condition` for deterministic grading, else `'agent'`/`'manual'`. Tier: all paid + free tiers (sample rejected — guest has no customerId). Verifiable claims must cite evidence.

Record (or update) the review state of ONE figure inside a report — the durable answer to 'has a human traced this number back to its filing?' Upsert keyed on (report_id, figure_key): re-reviewing a figure REPLACES its prior mark, it never appends, so this is always the figure's current state, never a history. `figure_key` is an opaque id you mint yourself for one figure (common shapes: `fact:{fact_id}` for a dataset-backed figure, `raw:{hash}` for free-text prose) — reuse the exact same key to update that figure's review later. `state`: verified (traced and correct) | corrected (wrong — supply `corrected_value`) | external (legitimately not from Valuein data) | rejected (unsupported, should be removed). `corrected_value` is REQUIRED when state='corrected' and must be omitted otherwise. Owner-scoped — your reviews never leak to or from another user. Tier: sp500+ (sample rejected).

Save free-form markdown (e.g. a chat synthesis) as a DRAFT report you can refine in the editor and export to Word/PDF. Unlike `create_report` (which computes a structured reverse_dcf or thesis report), this accepts raw markdown and splits it into sections. PASS `citations` with the fact_ids behind the figures you wrote — without them every number in the report reads as unsourced and the report can never be signed off. Tier: sample rejected (reports are per-author state). Idempotency-key → stable report id.

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

Upsert a named watchlist with a list of tickers. Replace semantics — the full ticker list is the source of truth for that name. Use this for both creation AND modification (delete + recreate is not required for edits). 500-ticker cap per list. Names are case-insensitive uniqueness.

Defer a follow-up task ("re-check AAPL margin compression in 30 days") for up to 90 days. This is an AGENT-facing primitive — call it mid-conversation/mid-run when you decide something is worth re-checking later; it is NOT a human-authorable "new task" form (use the Workspace's standing-agent scheduler for recurring, human-configured monitoring instead). On wake, an inbox item ALWAYS lands for the owner ("scheduled task due: …"). Optionally pass `context: {managed: true, team_id: "<standing_agent id>"}` to ALSO kick off a managed agent re-run at wake time — this is LIVE: it fires a real run of that standing-agent team, grounded in the saved context. It degrades to the inbox notice alone only if this deploy can't reach the run endpoint (report the actual outcome, never assume). Persisted durably in D1 — never lost on a Worker recycle. Tier: sp500+ (sample rejected).

Resolve a claim's outcome. By default auto-grades an `auto` claim by evaluating its verifiable_condition against SEC fundamentals (confirmed/refuted), or marks it `needs_review` when it can't be resolved deterministically (judgment, antecedent, or missing data). To record a human/agent judgment instead, pass `manual_status` (+ optional score/reason). Idempotent — re-scoring the same resolution is a no-op. Tier: sp500+ (sample rejected).

Find every auto-gradable claim that is due (assertions in open/needs_review/stale; predictions whose horizon has passed) and resolve each against fundamentals. Operates on the caller's OWN claims — omit `customer_id`. Targeting another user's `customer_id` is reserved for Valuein's internal scoring service and is rejected for every plan, including Institutional. Returns a summary + per-claim results. Idempotent — re-calling only re-resolves what changed.

Find every thesis past its horizon with no outcome yet, and grade each via `score_thesis_outcome`. Operates on the caller's OWN theses — omit `customer_id`. Targeting another user's `customer_id` is reserved for Valuein's internal scoring service and is rejected for every plan, including Institutional. Returns a summary + per-thesis results. Idempotent — a re-call only re-grades anything not already graded.

Grade a saved thesis against fundamental momentum since its creation. Pulls revenue / operating-margin / EPS / OCF deltas and aggregates into a score in [-1, +1]. Bull theses are graded by directional alignment, bear by inverse, neutral by closeness-to-flat. The grade is persisted back to the thesis row; re-call to refresh once new fundamentals land. **Note (PR 2)**: scoring is fundamental-only — does NOT yet include market-price returns. Phase 2 will mix in price data via a partner feed; the response shape is stable.

Rank companies by cross-sectional factor scores from factor_scores.parquet. Returns the underlying factors (roe, gross_margin, operating_margin, net_profit_margin, revenue_growth_yoy, fcf_to_assets, debt_to_equity, asset_turnover, current_ratio, piotroski_f_score) plus their percentile ranks (1.0 = best in universe, 0.0 = worst). `composite_rank` (the default sort) is a one-number multi-factor shortcut; sort by a specific *_rank column for a single factor. Two modes: full-universe (omit ticker) or single-entity (ticker set — spot-check ONE company's factor profile). Sector filter is SIC-derived (GICS-aligned, not licensed GICS — see `get_pit_universe`). Use this *instead of* `get_financial_ratios` when you want CROSS-SECTIONAL comparison (rank vs peers); use `get_financial_ratios` when you want one company's ratios over time. Supports survivorship-free POINT-IN-TIME screening via `as_of_date` (see the param). Full-universe screens omit rows that don't join to a company (null symbol); pass `exclude_outliers=true` to also drop shell-company rows with implausible factors. Available on every plan — sample returns the subset covered by the sample bucket.

Search for US public companies by name, ticker symbol, CIK (SEC identifier), or SIC industry code. Returns ticker, company name, sector, industry, exchange, and current S&P 500 membership status. Use this tool to resolve a company name to ticker/CIK before calling `get_company_fundamentals`, `get_valuation_metrics`, or other tools that require a ticker — they do not fuzzy-match company names. **Use this tool — NOT `get_pit_universe` — when the user asks about CURRENT S&P 500 members.** To list current S&P 500 members, call `search_companies({ is_sp500: true })` (the `is_sp500` filter is itself a valid search parameter, so no other input is required). This returns the live snapshot as of query time. Example: "List 5 current S&P 500 members" → call `search_companies({ is_sp500: true, limit: 5 })`. **Use `get_pit_universe` ONLY when the user explicitly needs a survivorship-free historical universe as of a specific past date** (e.g. "S&P 500 members as of March 2018"). If the user says "current," "today," "now," or gives no date, use `search_companies` instead. **Data details:** `sic_code` is the 4-digit SIC; `industry` is the human-readable label. `sector` is SIC-derived with GICS-style labels — NOT licensed GICS, so industrial conglomerates may map differently from official GICS (e.g. 3M → 'Health Care' by SIC vs Industrials by GICS). S&P 500 membership is sourced from index_membership.parquet (current SP500 = `index_name='SP500' AND removal_date IS NULL`). Available on all plans.

Search the catalog of published research reports. All listings are free to read. Filters: free-text (matches title + abstract), ticker, report_type. Sort: `newest` (default) or `oldest`. Tier-gated: callers only see reports their plan tier can read.

Store or update ONE durable memory entry (key → value) for this user so context survives across sessions — preferences, prior conclusions, working context. Replace semantics per key (reusing a key overwrites it). Do NOT store a number you would later cite as a fact: financial figures come from data tools and carry fact_ids; memory values are never treated as verified figures. Caps: 200 entries / 8000 chars per value. Tier: sp500+ (sample rejected).

Request a Valuein compliance certificate for one of the caller's OWN reports — a signed, publicly verifiable attestation at valuein.biz/verify/{id} that every fact the report cited was knowable at the time it was used (absence of lookahead bias). It attests provenance ONLY: it says nothing about whether the report's conclusions are correct or profitable, and must never be presented as though it did. ⚠️ IRREVERSIBLE AND OUTWARD-FACING. A certificate can be revoked (loudly — the URL keeps resolving and says so) but its signature stays cryptographically valid forever; there is no undo. It is classified RED, so a governed client will stage this for a named human to authorize rather than executing it autonomously. Propose it; do not claim to have certified anything yourself. PRECONDITION: every figure in the report must already be reviewed via `save_figure_review` — check with `list_figure_reviews` first. Refusals are PERMANENT outcomes, not transport errors, and name what to fix: `unreviewed_figures` (review them, then retry), `rejected_figures` (fix the report), `no_figures` (a report with nothing to verify is refused, never trivially passed), `unverifiable_citation`, `not_certifiable`. Do not retry a refusal unchanged. Only the report's author may sign it off. Tier: sp500+ (sample rejected).

Propose an MCP tool call for human approval BEFORE running it. Call this — instead of calling the tool directly — whenever an autonomous or unattended caller (a scheduled standing agent, an unattended agent-runner run, or any MCP client operating without a human watching) is about to perform a write it knows or suspects is risky. The target tool's OWN registered risk hints (readOnlyHint/destructiveHint) decide the tier: GREEN (read-only) tools are never staged — this call is then a no-op passthrough (`result: 'not_required'`) and the caller should just invoke the tool directly. AMBER (reversible write to the caller's own state) and RED (destructive or outward-facing) tools ARE staged: this call does NOT execute anything — it only records the proposal and returns a `staged_action_id`. A human (or any client acting on the human's behalf) later calls `approve_staged_action` or `reject_staged_action` to decide it. Tier: sp500+ (sample rejected — guest has no saved state).

File EXPLICIT, structured feedback about a specific artifact you (or the model) produced — a chat message, a report, a thesis, a claim, a tool call, or the schema. Use this (not `submit_feedback`) when you can name WHAT was judged and HOW: pass `target_type` + `target_id` + a `sentiment` (positive/negative/correction), and optionally a structured `reason` (e.g. wrong_number, bad_citation, hallucinated_fact), the `request_id` of the turn, the disputed `fact_id`, and an `expected_value` (the value it SHOULD have been, in your words). Available on EVERY tier including guest/sample. This is a one-way intake channel — it records your assertion, it NEVER computes or validates a number, and `expected_value` is stored verbatim, never trusted as data. Retried submissions of the same judgement on the same `request_id` file exactly once. Returns the recorded feedback id.

File product feedback to the Valuein team — a bug, feature request, experience note, or data-quality issue — directly from the agent surface. Available on EVERY tier including guest/sample (no token required), so an agent can report a rough edge in-band without the human leaving the conversation. Provide a `category` and a `message` (other fields optional — see params). Authenticated callers can pass an `idempotency_key` so a retried submission files exactly once (the same key from the same account); guest/sample callers are never deduplicated. Returns a friendly acknowledgment you can relay to the user. Do NOT use this to query data; it is a one-way report channel.

Fire a synthetic notification through the alert's configured channel. Use this immediately after `create_alert` to verify the channel (email address valid / webhook URL reachable + HMAC verification on the receiver). The synthetic fire is logged as `attempt=1 channel='test'` so it doesn't affect the real fire counter — the next genuine match still fires normally.

Dry-run a rule's condition_expr against a SYNTHETIC trigger payload — reports whether it WOULD have fired, but NEVER dispatches the action (no report generated, no team run, no message sent, no inbox write). Use this immediately after create_rule to sanity-check the condition before it starts evaluating against real events. Pass `sample_payload_override` to test against specific field values (e.g. `{price_change_pct: 12}`).

Remove the link between a claim and a thesis. Idempotent — succeeds whether or not the link existed. The claim and thesis themselves are untouched. Tier: paid + free (sample rejected).

Revert a published claim (public or unlisted) back to `private` — removes it from the author's /[handle] profile and excludes it from the public claim-accuracy aggregate. The inverse of publish_claim. Owner-only, idempotent. Tier: sp500+ (sample rejected).

Revert a published report (listed or unlisted) back to `private` visibility, removing it from the public catalog. Author-only. Idempotent.

Revert a published thesis (public or unlisted) back to `private` — removes it from the author's /[handle] profile and excludes it from the public reputation aggregate. The inverse of publish_thesis. Owner-only, idempotent. Tier: sp500+ (sample rejected).

Replace one or more sections of an existing report owned by the caller. Useful for authoring workflows where the agent's first draft (`create_report`) is refined by additional analysis before publishing. Pass `citations` for figures in the edited prose — they are MERGED into the report's existing set, never replacing it, so omitting them preserves the lineage already recorded. Bumps `version`. Does NOT change price / tier / visibility — use publish_report for those.

Use this tool when the user asks BOTH what a financial figure is AND which filing reported it — e.g. "What was Apple's most recently reported revenue, and which 10-Q filed it?" or "Show me the accession ID for Tesla's latest net income." Returns a single fact plus its complete filing provenance: entity, concept, period, value, accession ID, filing URL, and form type (10-K, 10-Q, etc.). Use this INSTEAD OF `search_companies` when the user already names a company and wants a financial figure with its source filing — `search_companies` only resolves identifiers and returns no financial data. Use this INSTEAD OF `get_company_fundamentals` when the user explicitly wants the filing/form type or the accession ID — `get_company_fundamentals` returns metrics across periods but omits filing provenance. Two lookup modes: (1) by fact_id (deterministic SHA-256 identity) or (2) by concept name plus a ticker (most recently reported fact). Optionally pin a point-in-time cutoff via as_of_date (YYYY-MM-DD) — returns the latest filing accepted by SEC on or before that date (no look-ahead); check `_meta.pit_safe`. DURATION: a single 10-K tags BOTH a 12-month figure and a 3-month Q4 stub at the same period_end; on a tie this returns the longer (headline) window, and every result carries `period_type` and `period_span_days` so a 3-month stub is never mistaken for the annual figure. Provide either fact_id or concept (required). Returns FACT_NOT_FOUND if no matching fact exists. Available on all plans.

Return new SEC filings across the caller's watchlist tickers since a given date. Reads filing.parquet — does not call insider/ratio surfaces (use those tools separately if you need them). Concurrency-bounded; max 50 tickers per call.