From deac102726c057af1681c97629e14a5dc204ff99 Mon Sep 17 00:00:00 2001 From: Rainer Arencibia Date: Tue, 12 May 2026 11:01:01 -0400 Subject: [PATCH] Add Valuein connector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds Valuein as a partner-built plugin providing SEC EDGAR fundamentals, financial ratios, valuation metrics, smart-money intelligence (insider + 13F + 13D/G), and forensic-audit scores for US-listed equities via the hosted MCP server at https://mcp.valuein.biz/mcp. Structure mirrors plugins/partner-built/lseg and plugins/partner-built/ spglobal exactly: plugins/partner-built/valuein/ ├── .claude-plugin/plugin.json # metadata + mcpServers ├── .mcp.json # HTTP MCP endpoint ├── LICENSE # Apache-2.0 ├── README.md # commands + skills + integrations + install ├── CONNECTORS.md # full MCP tool reference, 21 tools by category ├── commands/ │ ├── research-equity.md # equity research snapshot workflow │ ├── forensic-audit.md # earnings-quality red-flag brief │ └── screen-and-shortlist.md # factor screen + forensic gate └── skills/ ├── equity-research/SKILL.md ├── forensic-audit/SKILL.md └── screen-and-shortlist/SKILL.md Each skill includes YAML frontmatter (name + description), domain principles, available MCP tools, tool-chaining workflow, output format, and explicit "what not to do" guidance. Every numerical claim links back to the originating SEC accession via the response's `lineage` envelope (`source_filing` + `source_url`), so a reader can verify any number with one click. The plugin is also registered in .claude-plugin/marketplace.json so it is discoverable alongside lseg and sp-global. Validation: $ python3 scripts/check.py OK — 81 file(s) checked, 0 issues. Live MCP preflight (https://mcp.valuein.biz/mcp): protocolVersion: 2025-06-18 serverInfo: { name: "valuein-sec-edgar", version: "2.0.0" } capabilities: tools.listChanged, prompts.listChanged, resources.listChanged --- .claude-plugin/marketplace.json | 5 + .../valuein/.claude-plugin/plugin.json | 30 +++ plugins/partner-built/valuein/.mcp.json | 8 + plugins/partner-built/valuein/CONNECTORS.md | 107 ++++++++++ plugins/partner-built/valuein/LICENSE | 190 ++++++++++++++++++ plugins/partner-built/valuein/README.md | 63 ++++++ .../valuein/commands/forensic-audit.md | 103 ++++++++++ .../valuein/commands/research-equity.md | 118 +++++++++++ .../valuein/commands/screen-and-shortlist.md | 86 ++++++++ .../valuein/skills/equity-research/SKILL.md | 96 +++++++++ .../valuein/skills/forensic-audit/SKILL.md | 103 ++++++++++ .../skills/screen-and-shortlist/SKILL.md | 98 +++++++++ 12 files changed, 1007 insertions(+) create mode 100644 plugins/partner-built/valuein/.claude-plugin/plugin.json create mode 100644 plugins/partner-built/valuein/.mcp.json create mode 100644 plugins/partner-built/valuein/CONNECTORS.md create mode 100644 plugins/partner-built/valuein/LICENSE create mode 100644 plugins/partner-built/valuein/README.md create mode 100644 plugins/partner-built/valuein/commands/forensic-audit.md create mode 100644 plugins/partner-built/valuein/commands/research-equity.md create mode 100644 plugins/partner-built/valuein/commands/screen-and-shortlist.md create mode 100644 plugins/partner-built/valuein/skills/equity-research/SKILL.md create mode 100644 plugins/partner-built/valuein/skills/forensic-audit/SKILL.md create mode 100644 plugins/partner-built/valuein/skills/screen-and-shortlist/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 82ade411..7d76fbb6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -99,6 +99,11 @@ "source": "./plugins/partner-built/spglobal", "description": "S&P Global - Financial data and analytics skills including company tearsheets, earnings previews, and transaction summaries" }, + { + "name": "valuein", + "source": "./plugins/partner-built/valuein", + "description": "Free + low-cost SEC EDGAR fundamentals, ratios, valuation metrics, smart-money intelligence, and forensic-audit scores for US-listed equities. Point-in-time accurate, survivorship-bias free." + }, { "name": "claude-for-msft-365-install", "source": "./claude-for-msft-365-install", diff --git a/plugins/partner-built/valuein/.claude-plugin/plugin.json b/plugins/partner-built/valuein/.claude-plugin/plugin.json new file mode 100644 index 00000000..76736937 --- /dev/null +++ b/plugins/partner-built/valuein/.claude-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "valuein", + "description": "Free + low-cost SEC EDGAR fundamentals, ratios, valuation metrics, smart-money intelligence, and forensic-audit scores for US-listed equities. Point-in-time accurate, survivorship-bias free.", + "version": "1.0.0", + "author": { + "name": "Valuein", + "email": "support@valuein.biz" + }, + "homepage": "https://valuein.biz", + "repository": "https://github.com/valuein/mcp", + "license": "Apache-2.0", + "keywords": [ + "sec-edgar", + "fundamentals", + "financial-statements", + "valuation", + "forensic-audit", + "smart-money", + "13f", + "insider-transactions", + "ratios", + "us-equities" + ], + "mcpServers": { + "valuein": { + "type": "http", + "url": "https://mcp.valuein.biz/mcp" + } + } +} diff --git a/plugins/partner-built/valuein/.mcp.json b/plugins/partner-built/valuein/.mcp.json new file mode 100644 index 00000000..53d6b85f --- /dev/null +++ b/plugins/partner-built/valuein/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "valuein": { + "type": "http", + "url": "https://mcp.valuein.biz/mcp" + } + } +} diff --git a/plugins/partner-built/valuein/CONNECTORS.md b/plugins/partner-built/valuein/CONNECTORS.md new file mode 100644 index 00000000..a3751003 --- /dev/null +++ b/plugins/partner-built/valuein/CONNECTORS.md @@ -0,0 +1,107 @@ +# Connectors + +This plugin connects to the **Valuein MCP Server** at `https://mcp.valuein.biz/mcp`, which exposes SEC EDGAR fundamentals + ratios + valuation + smart-money intelligence + forensic-audit scores across the full US public-company universe. All tools are served by a single MCP server — no additional connectors required. + +## How Commands Reference Tools + +Commands in this plugin reference MCP tools by their exact tool name (e.g., `get_company_fundamentals`, `forensic_audit`). The tools are organized into the categories below. + +## Tool Categories + +| Category | Tools | Description | +|----------|-------|-------------| +| Discovery | `search_companies`, `get_pit_universe`, `describe_schema` | Resolve tickers/CIKs/SIC codes; build survivorship-bias-free historical universes; introspect the parquet schema. | +| Fundamentals | `get_company_fundamentals`, `compare_periods`, `get_earnings_signals` | Standardized income statement / balance sheet / cash flow rows with lineage; side-by-side period comparisons; TTM-based earnings surprise signals. | +| Ratios | `get_financial_ratios` | 7 categories of pipeline-computed ratios (profitability, liquidity, leverage, efficiency, per-share, owner earnings, valuation). | +| Valuation | `get_valuation_metrics`, `get_peer_comparables`, `compute_dcf` | Merged ratio + DCF metrics per fiscal period; cross-entity peer benchmarking; standalone forward DCF with 5×5 sensitivity grid. | +| Capital Allocation | `get_capital_allocation_profile` | Deployment mix as percent of OCF (capex / R&D / M&A / dividends / buybacks / debt repayment) with red-flag detection. | +| Forensic | `forensic_audit`, `verify_fact_lineage` | Partial Beneish M-Score + Sloan accruals + solvency snapshot + red-flag narrative; fact-by-fact provenance verification against SEC EDGAR. | +| Filings | `get_sec_filing_links` | Filing URLs by ticker + date range + form type (10-K, 10-Q, 8-K, 20-F, 40-F, amendments). | +| Screening | `screen_universe` | Cross-sectional factor-score screening across the full universe with composite-rank output. | +| Smart Money (Institutional) | `get_insider_transactions`, `get_institutional_holdings`, `get_manager_portfolio`, `get_blockholders`, `get_smart_money_flow`, `get_top_holders`, `get_insider_sentiment` | Insider transactions (Forms 3 / 4 / 5 / 144), 13F holdings, manager portfolios with QoQ deltas, SC 13D / 13G blockholders + going-active flags, cross-fund smart-money flow aggregates. | +| Bulk Streaming | `get_compute_ready_stream` | Presigned R2 Parquet URLs for out-of-core analytics in DuckDB / Polars / Pandas. | + +## Complete Tool Reference + +### Discovery Domain + +- **`search_companies`** — Search the US-listed universe by name, ticker, CIK, or SIC code. Returns ticker, name, sector, industry, exchange, and current S&P 500 membership. Use this to resolve a free-text company reference to a stable ticker before calling fundamental tools. +- **`get_pit_universe`** — Construct a survivorship-bias-free historical universe at a specific date (e.g., "S&P 500 members on 2018-06-30"). Uses `index_membership` interval semantics (effective_date → removal_date) for clean backtests. +- **`describe_schema`** — Introspect the Parquet schema available on the caller's plan. Returns table list, column types, and last-snapshot metadata. + +### Fundamentals Domain + +- **`get_company_fundamentals`** — Standardized income statement, balance sheet, and cash-flow rows per fiscal period. Includes a `lineage` envelope with `source_filing` (SEC accession id) + `source_url` (clickable EDGAR link) for one-click verification of every numeric value. Supports `as_of_date` for PIT backtests. +- **`compare_periods`** — Side-by-side comparison of any two fiscal periods for a ticker. Surfaces material-change flags (e.g., revenue swung > X% YoY, leverage doubled). Useful as a discovery aid before deeper analysis. +- **`get_earnings_signals`** — TTM-based EPS trend + YoY revenue surprise per entity per fiscal period. Useful for earnings-call setup and surprise-history backtesting. + +### Ratios Domain + +- **`get_financial_ratios`** — Pipeline-computed ratios from `ratio.parquet`, filterable by category. Categories: `profitability`, `liquidity`, `leverage`, `efficiency`, `per_share`, `owner_earnings`, `valuation`. TTM and FY variants. Pipeline-derived (no `accepted_at` — use period_end for historical cuts). + +### Valuation Domain + +- **`get_valuation_metrics`** — Merged ratio + DCF metrics in a single response. Returns profitability ratios (margins, ROE, ROA, ROIC), leverage (debt-to-equity), FCF + FCF margin, and DCF inputs (WACC, terminal-growth assumption, stage-1 rate, computed value per share, DDM value) when available. +- **`get_peer_comparables`** — Cross-entity benchmarking: subject + N peers (default 10) with ratios across the requested categories. Surfaces relative quality + valuation positioning. +- **`compute_dcf`** — Forward discounted-cash-flow valuation: caller provides growth + WACC + terminal assumptions, returns per-share intrinsic value + 5×5 sensitivity grid across WACC × terminal-growth. Pulls FCF base + shares from R2; caller can override any field. Does not persist results — pair with `create_report` for an authored artifact. + +### Capital Allocation Domain + +- **`get_capital_allocation_profile`** — Detailed cash deployment per fiscal period: capex, R&D, M&A net activity, dividends paid, share repurchases, debt issuance / repayment, plus deployment mix as percent of operating cash flow. Includes red-flag booleans: `buybacks_exceed_fcf`, `total_returns_exceed_fcf`, `debt_funded_distribution`. + +### Forensic Domain + +- **`forensic_audit`** — Deterministic earnings-quality scores: partial Beneish M-Score (SGI + TATA + LVGI factors), Sloan accruals (total accruals / total assets), and a three-ratio solvency snapshot (debt-to-equity, debt-to-assets, ROA). Returns a ranked red-flag narrative — flags above empirical thresholds (M > -2.22, accruals > 7.5%, D/E > 3.0, negative ROA, leverage growth > 1.10). +- **`verify_fact_lineage`** — Trace any numeric fact in the warehouse back to its originating SEC filing. Returns the fact_id, accession, EDGAR URL, accepted_at timestamp, and whether the value has been restated. + +### Filings Domain + +- **`get_sec_filing_links`** — Filing metadata + EDGAR deep links by ticker, date range, and form type. Supports 10-K, 10-Q, 8-K, 20-F, 40-F + amendments. Returns accession, filing date, accepted_at, form type, is_amendment flag, and SEC inline-XBRL viewer URLs. + +### Screening Domain + +- **`screen_universe`** — Cross-sectional factor scoring across the full universe. Each ticker carries percentile ranks for revenue growth, FCF yield, ROIC, etc., plus a composite rank. Useful as the first stage in `/screen-and-shortlist`. + +### Smart Money Domain (Institutional tier) + +- **`get_insider_transactions`** — Form 3 / 4 / 5 / 144 line items per issuer with role + role decoration (Officer / Director / TenPercentOwner), transaction code, shares, price, and notional. Lineage anchors back to the originating SEC accession. +- **`get_institutional_holdings`** — Form 13F top holders per issuer including HHI (Herfindahl-Hirschman concentration index). Filterable by period_end and lineage detail. +- **`get_manager_portfolio`** — Full Form 13F portfolio of a single filer (CIK) at a quarter-end, with QoQ deltas per position: new / increased / decreased / exited / unchanged. Useful for "follow Tiger Cubs" / "follow Berkshire" workflows. +- **`get_blockholders`** — SC 13D + SC 13G beneficial-ownership filings per issuer with first-class `is_activist` and `going_active` flags (the latter fires on 13G → 13D conversions, the strongest activist signal). +- **`get_smart_money_flow`** — Aggregate cross-fund flow across an issuer: net institutional buys, new positions, exits, blockholder activity, and recent insider clusters. One call = "what is the institutional money doing on this name?" +- **`get_top_holders`** — Top N institutional holders per issuer with concentration metrics. Lighter-weight alternative to the full 13F surface. +- **`get_insider_sentiment`** — Insider cluster detection: multiple distinct insiders buying / selling within a lookback window. Surfaces the strongest single-name insider signal (cluster buying historically outperforms isolated buys by a wide margin). + +### Bulk Streaming Domain + +- **`get_compute_ready_stream`** — Returns a 1-hour-expiry presigned R2 URL for the full parquet table at the caller's tier. Use this for out-of-core analytics in DuckDB / Polars / Pandas that the per-entity tool surface can't economically support. + +## Tier Gating + +| Domain | Sample (no signup) | S&P 500 Free | Pro ($49/mo) | Institutional ($499/mo) | +|---|---|---|---|---| +| Discovery + Fundamentals + Ratios + Valuation + Capital Allocation + Forensic + Filings | S&P 500 / 5yr | S&P 500 / full history | Full universe / 30yr | Full universe / 1990+ | +| Smart Money (insider + 13F + 13D/G) | — | — | — | ✅ | +| Bulk Streaming (presigned URLs) | sample bucket | sp500 bucket | pro bucket | full bucket | + +Sample tier is unauthenticated guest access — the `/research-equity` and `/screen-and-shortlist` commands work without signup for evaluation on S&P 500 companies. + +## Authentication + +The MCP client passes the caller's Valuein API token to the server via the standard MCP `Authorization` header (`Bearer <64-hex-token>`). Tokens are provisioned at https://valuein.biz/dashboard after subscription. No token is needed for the Sample tier — the server treats unauthenticated requests as guest access scoped to `R2_SAMPLE`. + +## Lineage and Verification + +Every numeric response from a Valuein tool carries a `lineage` envelope (compact by default, full detail on request via `lineage_detail`): + +```json +{ + "source_filing": "0000320193-25-000123", + "source_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm", + "restated_in_warehouse": false, + "accepted_at": "2025-11-01T20:00:00Z", + "first_filed_at": "2025-11-01T20:00:00Z" +} +``` + +The `source_url` is a clickable EDGAR deep link to the filing index — one click to verify any number against the originating SEC document. Agents should surface this URL whenever they cite a fact. diff --git a/plugins/partner-built/valuein/LICENSE b/plugins/partner-built/valuein/LICENSE new file mode 100644 index 00000000..ad9cc067 --- /dev/null +++ b/plugins/partner-built/valuein/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for describing the origin of the Work and + reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Support. While redistributing the Work or + Derivative Works thereof, You may choose to offer, and charge a + fee for, acceptance of support, warranty, indemnity, or other + liability obligations and/or rights consistent with this License. + However, in accepting such obligations, You may act only on Your + own behalf and on Your sole responsibility, not on behalf of any + other Contributor, and only if You agree to indemnify, defend, + and hold each Contributor harmless for any liability incurred by, + or claims asserted against, such Contributor by reason of your + accepting any such warranty or support. + + END OF TERMS AND CONDITIONS + + Copyright 2026 Valuein, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/plugins/partner-built/valuein/README.md b/plugins/partner-built/valuein/README.md new file mode 100644 index 00000000..3de2981c --- /dev/null +++ b/plugins/partner-built/valuein/README.md @@ -0,0 +1,63 @@ +# Valuein SEC EDGAR Plugin + +SEC EDGAR financial statements, ratios, valuation metrics, smart-money intelligence, and forensic-audit scores — point-in-time accurate, survivorship-bias free, ~105M facts across 17,000+ US-listed entities. + +## What This Plugin Does + +Valuein's MCP server (`mcp.valuein.biz`) packages SEC EDGAR data into a unified analytical surface: standardized financial statements with one-click lineage to source filings, pipeline-computed ratios, DCF and reverse-DCF, forensic-audit scores (partial Beneish + Sloan accruals + solvency), and a smart-money dataset covering insider transactions (Forms 3/4/5/144) plus institutional ownership (13F / 13D / 13G). This plugin orchestrates those tools into 3 high-level workflows so an analyst doesn't have to chain calls manually. + +The data is **point-in-time correct by construction** — every fact carries an `accepted_at` timestamp from SEC acceptance, and the warehouse never overwrites historical values. Backtests filter by date; restatements appear as new rows. + +## Commands + +| Command | Description | +|---------|-------------| +| `/research-equity` | Generate an equity research snapshot — fundamentals, ratios, peer comparables, valuation, and capital allocation context for any US ticker. | +| `/forensic-audit` | Earnings-quality red-flag brief — partial Beneish M-Score, Sloan accruals, solvency snapshot, and restatement history with citations to source filings. | +| `/screen-and-shortlist` | Run a cross-sectional factor screen, forensic-audit the top candidates, and produce a ranked shortlist with citations. | + +## Skills + +Each command is backed by a skill that provides domain knowledge: + +| Skill | Domain Knowledge | +|-------|------------------| +| `equity-research` | Fundamental analysis, ratio interpretation, peer benchmarking, valuation metrics (DCF inputs, reverse-DCF, capital allocation scorecard). | +| `forensic-audit` | Beneish M-Score interpretation, Sloan accruals, restatement detection, leverage growth signals, citation grounding. | +| `screen-and-shortlist` | Factor-score screening, multi-factor ranking, survivorship-bias-free historical universes, forensic gating. | + +## Integrations + +This plugin connects to the **Valuein MCP Server** which provides US public-company financial data across these domains: + +- **Entity & Universe** — Ticker / CIK / SIC resolution, current S&P 500 membership, historical PIT universe construction (survivorship-free). +- **Fundamentals** — Standardized income statement, balance sheet, cash flow rows with `lineage` envelopes that link every numeric value to the source SEC accession (`source_url` is a clickable EDGAR link). +- **Ratios** — Pipeline-computed profitability, liquidity, leverage, efficiency, per-share, owner-earnings, and valuation ratios; TTM and FY variants. +- **Valuation** — Forward DCF, reverse DCF, peer-comparable benchmarks across the full US universe. +- **Capital Allocation** — Deployment mix (capex / R&D / M&A / dividends / buybacks / debt repayment) as percent of operating cash flow with red-flag detection (buybacks-exceed-FCF, debt-funded-distribution). +- **Forensic Audit** — Partial Beneish M-Score (SGI + TATA + LVGI), Sloan accruals, solvency snapshot, ranked red-flag narrative. +- **Smart Money** (Institutional tier) — Insider transactions (Form 3 / 4 / 5 / 144), institutional ownership (13F), blockholders (SC 13D / 13G), manager portfolios with QoQ deltas, cross-fund consensus. +- **Filings** — Direct EDGAR URLs for 10-K, 10-Q, 8-K, 20-F, 40-F, amendments, by date range and form type. +- **Bulk Streaming** — Presigned R2 Parquet URLs for full-universe out-of-core analysis (DuckDB, Polars, Pandas). + +See [CONNECTORS.md](CONNECTORS.md) for the complete tool reference. + +## Installation + +Add the marketplace and install the plugin: + +``` +/plugin marketplace add anthropics/financial-services +/plugin install valuein +``` + +## Requirements + +- A Valuein account. Free tiers are available: + - **Sample** — no signup required, S&P 500 5-year window, public read-only access. + - **S&P 500 (Free)** — free with email signup, full S&P 500 from 1994 → present. + - **Pro** — $49/month, full US universe (17,000+ tickers, active + delisted), 30-year history, full filings + ratios + valuation + capital-allocation surfaces. + - **Institutional** — $499/month, adds the smart-money dataset (insider + 13F + 13D/13G), full history back to 1990, foreign issuers, filing-event webhooks, commercial redistribution license. +- For paid tiers, set your Valuein API token in the MCP authorization header. See the [Valuein quickstart](https://valuein.biz/developers/quickstart) for token provisioning. + +The Sample tier serves a curated S&P 500 slice without authentication, so the `/research-equity` and `/screen-and-shortlist` commands work out of the box on supported tickers for evaluation. diff --git a/plugins/partner-built/valuein/commands/forensic-audit.md b/plugins/partner-built/valuein/commands/forensic-audit.md new file mode 100644 index 00000000..59544048 --- /dev/null +++ b/plugins/partner-built/valuein/commands/forensic-audit.md @@ -0,0 +1,103 @@ +--- +description: Earnings-quality red-flag brief — Beneish M-Score, Sloan accruals, solvency snapshot, and restatement history for a single US ticker +argument-hint: " [include_amendments=true|false]" +--- + +# Forensic Audit + +> This command uses Valuein's `forensic_audit`, fundamentals, filings, and capital-allocation tools. See [CONNECTORS.md](../CONNECTORS.md) for the complete tool reference. + +Generate a forensic earnings-quality brief for a single US ticker. Surfaces partial Beneish M-Score components, Sloan accruals, three-ratio solvency snapshot, and the recent amendment history (10-K/A, 10-Q/A) — every red flag cites a specific SEC accession. + +This command is opinionated about how a forensic analyst reads the output: it never claims "manipulation" without empirical thresholds, and it always pairs a flag with the underlying ratio and the originating filing. + +See the **forensic-audit** skill for domain knowledge on Beneish interpretation, Sloan accruals, and restatement materiality. + +## Workflow + +### 1. Gather Input + +Ask the user for: +- Ticker symbol (required). +- Whether to include amendments (optional, default true) — restatements are the strongest signal but inflate the output for clean names. + +### 2. Forensic Score Baseline + +Call `forensic_audit` with `ticker`. Returns: +- `m_score` (partial Beneish) with components `sgi` (sales growth index), `tata` (total accruals / total assets), `lvgi` (leverage growth index) +- `sloan_accruals` (net income − operating cash flow) / total assets +- `solvency` with `debt_to_equity`, `debt_to_assets`, `roa` +- `red_flags` ranked by severity +- `source_filing` and `sec_url` for the current period + +Preserve the `partial: true` flag in the output — full Beneish (8 factors) needs AR / current assets / PPE / SGA / current liabilities that the standardised fundamentals model doesn't carry. Communicate the caveat clearly to the user. + +### 3. Multi-Period Fundamentals Trend + +Call `get_company_fundamentals` with `ticker`, `period: "annual"` and the last 5 fiscal years. + +Compute growth-vs-margin divergence: revenue rising while gross margin falling (and accruals positive) is the classic earnings-quality risk pattern. + +### 4. Filing History (Amendments) + +If `include_amendments=true`, call `get_sec_filing_links` with `ticker`, `formTypes: ["10-K/A", "10-Q/A", "20-F/A", "40-F/A"]`. + +Each amendment is a restatement candidate. Note the filing date and SEC URL — agents should NOT speculate about content without verifying the amendment text. + +### 5. Capital-Allocation Cross-Check + +Call `get_capital_allocation_profile` with `ticker`. The boolean flags `buybacks_exceed_fcf` and `debt_funded_distribution` are independent earnings-quality signals — companies funding returns with debt while accruals rise are at the higher end of the manipulation-risk distribution. + +### 6. Synthesize the Brief + +Combine into the output below. + +## Output Format + +### Forensic Brief — \ + +**⚠️ Note on Beneish**: Valuein computes a partial M-Score from the components recoverable in standardised fundamentals (SGI + TATA + LVGI). Full Beneish (8 factors) needs balance-sheet line items that aren't in the model. Use the partial score as a directional signal, not a verdict. + +### Red Flags (Most Severe First) + +For each red flag returned by `forensic_audit`: +- **Flag name** (e.g. "Partial M-Score exceeds -2.22 threshold") +- One-sentence what & why (cite empirical threshold) +- Source: `[Accession ID]` → `source_url` + +### Quantitative Scorecard + +| Metric | Value | Empirical Threshold | Status | +|--------|-------|---------------------|--------| +| Partial M-Score | ... | > -2.22 → concern | ✅/🚩 | +| Sloan Accruals | ...% | > 7.5% → concern | ✅/🚩 | +| Debt / Equity | ... | > 3.0 → high leverage | ✅/🚩 | +| Debt / Assets | ... | > 0.6 → high leverage | ✅/🚩 | +| ROA | ...% | < 0 → unprofitable | ✅/🚩 | +| Leverage Growth Index | ... | > 1.10 → debt growing > assets | ✅/🚩 | + +### Restatement History + +If amendments were requested: +| Date | Form | Accession | EDGAR Link | +|------|------|-----------|------------| +| YYYY-MM-DD | 10-K/A | ... | source_url | +| ... | ... | ... | ... | + +For each amendment, note that the agent should verify the amendment text against the original 10-K / 10-Q to confirm material change. + +### Capital-Allocation Cross-Check + +| Signal | Latest Period | Interpretation | +|--------|---------------|-----------------| +| Buybacks exceed FCF | true / false | Companies funding returns above FCF often borrow; check the debt flag. | +| Debt-funded distributions | true / false | Strongest earnings-quality red flag when combined with positive accruals. | +| Net debt change | $... | Direction matters — increases during high-accruals period = elevated risk. | + +### Bottom Line (3 sentences) + +State the empirical evidence for / against earnings-quality concerns. Do NOT use language like "fraud", "manipulation", or "cooking the books" — describe what the data shows and let the user reach a conclusion. Close with the recommendation: continue diligence, deeper forensic review needed, or no obvious red flags. + +### Sources + +Always close with the cited accession list: `[Accession ID]: ` for every fact_id used above. diff --git a/plugins/partner-built/valuein/commands/research-equity.md b/plugins/partner-built/valuein/commands/research-equity.md new file mode 100644 index 00000000..d4fb2603 --- /dev/null +++ b/plugins/partner-built/valuein/commands/research-equity.md @@ -0,0 +1,118 @@ +--- +description: Generate an equity research snapshot — fundamentals, ratios, peer comparables, valuation, and capital allocation for a single US ticker +argument-hint: " [period e.g. annual|quarterly]" +--- + +# Research Equity + +> This command uses Valuein's fundamentals, valuation, ratios, peer-comparable, and capital-allocation tools. See [CONNECTORS.md](../CONNECTORS.md) for the complete tool reference. + +Generate a comprehensive equity research snapshot for a US-listed ticker. Combines standardized financial statements, pipeline-computed ratios, peer benchmarking, valuation metrics, and capital-allocation analysis into a structured research note. Every numeric value is cited to a specific SEC accession via the response's `lineage` envelope. + +See the **equity-research** skill for domain knowledge on fundamental analysis, peer interpretation, and valuation framing. + +## Workflow + +### 1. Gather Input + +Ask the user for: +- Ticker symbol (required) — e.g. AAPL, MSFT, NVDA. Case-insensitive; the tool normalises. +- Period type (optional, default annual) — `annual` or `quarterly`. +- Specific focus areas (optional) — e.g. earnings, margins, balance sheet, capital returns. + +If the user supplies a company name instead of a ticker, call `search_companies` first to resolve. + +### 2. Pull Historical Fundamentals + +Call `get_company_fundamentals` with `ticker`, `period`. Request the last 5 fiscal periods. + +Extract: revenue trajectory, gross / operating / net margins, EPS trend, total assets / liabilities / equity, cash + total debt, operating cash flow, capex (sign-aware). + +Every row carries a `lineage` envelope — preserve the `source_filing` + `source_url` for citation in the output. + +### 3. Pipeline Ratios + +Call `get_financial_ratios` with `ticker`, `categories: ["profitability", "efficiency", "owner_earnings"]`, `fiscal_period: "FY"`, `limit: 5`. + +Extract: ROE, ROIC, gross / operating / net margin trends, FCF yield, owner-earnings per share, days-sales-outstanding, cash conversion cycle. + +### 4. Valuation Metrics + +Call `get_valuation_metrics` with `ticker`. Returns merged fact-table profitability ratios + DCF inputs from `valuation.parquet` (WACC, terminal growth assumption, computed value per share if a DCF has been pre-run). + +### 5. Peer Comparables + +Call `get_peer_comparables` with `ticker`, `categories: ["profitability", "valuation", "leverage"]`, `limit: 10`. + +Returns the subject + N sector peers with side-by-side ratios. Identify the subject's relative quality and valuation positioning. + +### 6. Capital Allocation + +Call `get_capital_allocation_profile` with `ticker`. Returns capex, R&D, M&A, dividends, buybacks, debt issuance / repayment plus deployment-mix percentages and red-flag booleans (`buybacks_exceed_fcf`, `debt_funded_distribution`). + +### 7. Synthesize + +Combine into a structured research note with the output format below. + +## Output Format + +### Investment Thesis (1-2 sentences) +Lead with the one-line summary of where the company is and why it matters. + +### Fundamentals Trajectory +| Metric | FY-4 | FY-3 | FY-2 | FY-1 | FY0 (LTM) | Trend | +|--------|------|------|------|------|-----------|-------| +| Revenue (M) | ... | ... | ... | ... | ... | ... | +| Gross Margin | ...% | ...% | ...% | ...% | ...% | ... | +| Operating Margin | ...% | ...% | ...% | ...% | ...% | ... | +| EPS (diluted) | ... | ... | ... | ... | ... | ... | +| Net Debt / EBITDA | ... | ... | ... | ... | ... | ... | + +Cite the SEC accession for the most recent fiscal year (from the lineage envelope on the FY0 row). + +### Quality Ratios +| Ratio | Current | 5Y Avg | Trend | +|-------|---------|--------|-------| +| ROE | ...% | ...% | ... | +| ROIC | ...% | ...% | ... | +| FCF Yield | ...% | ...% | ... | +| Owner Earnings / Share | ... | ... | ... | +| Cash Conversion Cycle (days) | ... | ... | ... | + +### Peer Comparables +| Metric | Subject | Peer Median | Peer Range | Position | +|--------|---------|-------------|------------|----------| +| Operating Margin | ...% | ...% | ...% – ...% | ... | +| ROIC | ...% | ...% | ...% – ...% | ... | +| Debt / Equity | ... | ... | ... – ... | ... | + +### Capital Allocation Scorecard +| Use of Cash | % of OCF | Flag | +|-------------|----------|------| +| Capex | ...% | ... | +| R&D | ...% | informational | +| M&A | ...% | ... | +| Dividends | ...% | ... | +| Buybacks | ...% | ... | +| Debt Repayment | ...% | ... | + +Surface the red-flag booleans explicitly if any are true: +- ⚠️ **Buybacks exceed FCF** in the latest period +- ⚠️ **Total returns (buybacks + dividends) exceed FCF** +- ⚠️ **Debt-funded distributions** (distributions exceed FCF AND debt was issued in the same period) + +### Valuation Summary +| Metric | Current | Context | +|--------|---------|---------| +| Forward P/E | ... | vs sector / history | +| EV / EBITDA | ... | vs sector / history | +| Computed DCF Value / Share | $... | from valuation.parquet | +| Implied Equity Premium | ...% | (Computed DCF − current price) / current price | + +### Bottom Line +- **Strengths** (2-3 bullets): durable margins, capital-return discipline, etc. +- **Risks** (2-3 bullets): leverage trajectory, peer-relative drift, red flags. +- **Conviction**: high / medium / low, with one-sentence justification. + +### Sources +Always close with a list of cited filings: `[Accession ID]: ` for every fact_id surfaced above. Every number must trace back to a specific 10-K / 10-Q. diff --git a/plugins/partner-built/valuein/commands/screen-and-shortlist.md b/plugins/partner-built/valuein/commands/screen-and-shortlist.md new file mode 100644 index 00000000..8bcf6a65 --- /dev/null +++ b/plugins/partner-built/valuein/commands/screen-and-shortlist.md @@ -0,0 +1,86 @@ +--- +description: Run a factor screen across the US universe, forensic-audit the top candidates, and produce a ranked shortlist with citations +argument-hint: " [max_results=10]" +--- + +# Screen and Shortlist + +> This command uses Valuein's `screen_universe`, `forensic_audit`, `get_company_fundamentals`, and `get_peer_comparables` tools. See [CONNECTORS.md](../CONNECTORS.md) for the complete tool reference. + +Run a cross-sectional factor screen across the US universe, forensic-audit the top candidates, and return a ranked shortlist with citations. Caller provides the criteria description in natural language; the command translates it into factor weights for `screen_universe` and applies a forensic gate before returning the shortlist. + +See the **screen-and-shortlist** skill for domain knowledge on factor design, multi-factor ranking, and forensic gating. + +## Workflow + +### 1. Gather Input + +Ask the user for: +- Criteria description (required). Common shapes: + - `"high-FCF low-debt"` → FCF yield DESC + debt-to-equity ASC + - `"magic formula"` → ROIC DESC + earnings yield DESC + - `"quality momentum"` → ROIC DESC + revenue CAGR (5Y) DESC + - `"value with safety"` → low P/E + low debt-to-equity + positive ROA +- Max results (optional, default 10). + +### 2. Screen the Universe + +Call `screen_universe` with factor weights matching the criteria. The tool reads `factor_scores.parquet` which carries pre-computed percentile ranks for the canonical factor catalogue. + +Take the top ~30 results before the forensic gate (so the post-gate shortlist still has the requested `max_results` survivors). + +### 3. Forensic Gate + +For each of the top ~30 candidates (parallelise reads): +- Call `forensic_audit` with `ticker`. +- Drop candidates where: + - Partial M-Score > -2.22 (manipulation-risk signal), OR + - Sloan accruals > 7.5% (earnings-quality concern), OR + - ROA < 0 (operating at a loss). + +This is the "screen survivors" set — names that scored well on the quantitative factors AND don't trip forensic-quality red flags. + +### 4. Peer-Context Pass + +For each survivor (cap to `max_results`): +- Call `get_peer_comparables` with `categories: ["profitability", "valuation"]`. +- Note where the candidate sits in its sector vs peer median (1-sentence per name). + +### 5. Synthesize the Shortlist + +Combine into the output below. + +## Output Format + +### Shortlist Header + +Display the criteria, factor weights used, screen date, and survivor count. + +### Top \ Survivors (Ranked) + +For each survivor: + +#### #1 — \ — \ + +- **Factor score**: composite_rank \, percentile \th +- **Forensic clean**: M-Score \, Sloan accruals \%, ROA \% +- **Peer context**: 1 sentence on where the name sits vs sector peers +- **Source**: SEC accession id for the latest 10-K (from `forensic_audit` lineage) + +Repeat for #2..#N. + +### Drops (Failed Forensic Gate) + +For each candidate that scored well but failed the forensic check: +- **TICKER** — reason (e.g. "Sloan accruals 9.2% > 7.5% threshold") + +### Methodology Note + +- Screen factors: \ +- Forensic thresholds: M-Score ≤ -2.22, Sloan accruals ≤ 7.5%, ROA ≥ 0 +- Universe: US-listed entities with `factor_scores.parquet` coverage +- Survivorship-free: includes delisted entities (use `get_pit_universe` for as-of-date queries) + +### Sources + +Always close with a list of cited filings: `[Accession ID]: ` for every survivor's `forensic_audit` lineage. The user should be able to one-click any number back to its SEC source. diff --git a/plugins/partner-built/valuein/skills/equity-research/SKILL.md b/plugins/partner-built/valuein/skills/equity-research/SKILL.md new file mode 100644 index 00000000..c1fc08f7 --- /dev/null +++ b/plugins/partner-built/valuein/skills/equity-research/SKILL.md @@ -0,0 +1,96 @@ +--- +name: equity-research +description: Generate equity research snapshots combining standardized SEC fundamentals, pipeline-computed ratios, peer comparables, valuation metrics, and capital-allocation analysis. Use when researching US-listed equities, building investment cases, evaluating earnings quality vs growth narrative, comparing a company to its sector peers, or stress-testing the capital-return story. Pairs with `/research-equity`. +--- + +# Equity Research Analysis + +You are a senior equity analyst. Combine standardized SEC-EDGAR fundamentals, pipeline-computed ratios, peer comparables, valuation metrics, and capital-allocation data from Valuein MCP tools into a structured research snapshot. Route the data into a coherent investment thesis — let the tools provide the data, you synthesize the story. + +## Core Principles + +Every numerical claim in the output must cite a SEC accession id from the response's `lineage` envelope. The `source_url` is a clickable EDGAR link — surface it so the reader can verify any number in one click. This is the differentiator vs. a free-form LLM analysis: every number has provenance. + +The investment question is rarely "is this a good company" — it's "where is consensus wrong, and which fact in the SEC filings supports my view?" Pull fundamentals to assess the business, ratios to assess quality, peers for relative positioning, capital allocation for shareholder discipline, and valuation for the gap between price and intrinsic value. + +## Available MCP Tools + +- **`get_company_fundamentals`** — Standardized income statement / balance sheet / cash-flow rows by fiscal period. Includes `lineage` (source filing + EDGAR URL). +- **`get_financial_ratios`** — 7 categories of pipeline-computed ratios (profitability, liquidity, leverage, efficiency, per-share, owner earnings, valuation). TTM + FY. +- **`get_valuation_metrics`** — Merged fact-table ratios + DCF inputs from `valuation.parquet`. Includes WACC, terminal growth, computed value per share. +- **`get_peer_comparables`** — Subject + N sector peers with side-by-side ratios. Use to identify relative quality + valuation positioning. +- **`get_capital_allocation_profile`** — Deployment mix as % of OCF (capex, R&D, M&A, dividends, buybacks, debt repayment) with red-flag detection (`buybacks_exceed_fcf`, `debt_funded_distribution`). +- **`search_companies`** — Free-text → ticker resolution. Use when the user supplies a company name. + +## Tool Chaining Workflow + +1. **Resolve the ticker** if the user supplied a company name (`search_companies`). +2. **Fundamentals (5 years)**: `get_company_fundamentals` with `period: "annual"`. Compute revenue CAGR, margin trajectory, leverage trajectory, EPS trend. +3. **Ratios**: `get_financial_ratios` with `categories: ["profitability", "efficiency", "owner_earnings"]`. Surface ROIC, FCF yield, owner-earnings per share, cash conversion cycle. +4. **Valuation**: `get_valuation_metrics` for ROE / ROA / ROIC plus DCF inputs if pre-computed. +5. **Peer benchmarking**: `get_peer_comparables` with `categories: ["profitability", "valuation", "leverage"]`. Note where the subject sits in its sector distribution. +6. **Capital allocation**: `get_capital_allocation_profile`. Surface red-flag booleans explicitly. +7. **Synthesize**: route the numbers into the output template below. Every numerical claim must carry a citation. + +## Output Format + +### Investment Thesis (1-2 sentences) +Lead with the one-line summary of where the company is and why it matters now. + +### Fundamentals Trajectory +| Metric | FY-4 | FY-3 | FY-2 | FY-1 | FY0 (LTM) | Trend | +|--------|------|------|------|------|-----------|-------| +| Revenue (M) | ... | ... | ... | ... | ... | accelerating / decelerating | +| Gross Margin | ...% | ...% | ...% | ...% | ...% | expanding / compressing | +| Operating Margin | ...% | ...% | ...% | ...% | ...% | ... | +| EPS (diluted) | ... | ... | ... | ... | ... | ... | +| Net Debt / EBITDA | ... | ... | ... | ... | ... | de-leveraging / re-leveraging | + +Cite the FY0 row's `source_filing` + `source_url`. + +### Quality Ratios +| Ratio | Current | 5Y Avg | Trend | Interpretation | +|-------|---------|--------|-------|----------------| +| ROE | ...% | ...% | ... | ... | +| ROIC | ...% | ...% | ... | ROIC > WACC? | +| FCF Yield | ...% | ...% | ... | ... | +| Owner Earnings / Share | ... | ... | ... | per Buffett definition | +| Cash Conversion Cycle (days) | ... | ... | ... | ... | + +### Peer Positioning +| Metric | Subject | Peer Median | Sector Range | Position | +|--------|---------|-------------|--------------|----------| +| Operating Margin | ...% | ...% | ...% – ...% | top quartile / median / bottom | +| ROIC | ...% | ...% | ...% – ...% | ... | +| Debt / Equity | ... | ... | ... – ... | ... | +| Forward P/E | ... | ... | ... – ... | ... | + +### Capital Allocation Scorecard +| Use of Cash | % of OCF | Flag | +|-------------|----------|------| +| Capex | ...% | ... | +| R&D | ...% | informational only | +| M&A | ...% | ... | +| Dividends | ...% | ... | +| Buybacks | ...% | ... | +| Debt Repayment | ...% | ... | + +Surface red-flag booleans verbatim: +- ⚠️ **Buybacks exceed FCF** — distributions above cash generation. +- ⚠️ **Total returns exceed FCF** — combined buybacks + dividends above cash generation. +- ⚠️ **Debt-funded distributions** — distributions exceed FCF AND debt was issued in the same period. + +### Bottom Line +- **Strengths** (2-3 bullets): durable margins, capital discipline, balance-sheet quality, etc. +- **Risks** (2-3 bullets): leverage trajectory, peer drift, red flags from capital allocation. +- **Conviction**: high / medium / low — one-sentence justification. + +### Sources +List every cited accession: `[Accession ID]: ` so the reader can verify any number in one click. + +## What Not to Do + +- Don't claim a DCF intrinsic value the data didn't compute. If `computed_dcf_value_per_share` is null in the response, say so — don't fabricate a number from the WACC and terminal-growth inputs. +- Don't ignore the red-flag booleans. They're cheap empirical signals; surface them explicitly. +- Don't summarize sector trends without citing a specific filing. "Tech margins are compressing" needs a peer comparable showing it. +- Don't omit the citations block at the end. The plugin's differentiator is verifiable provenance. diff --git a/plugins/partner-built/valuein/skills/forensic-audit/SKILL.md b/plugins/partner-built/valuein/skills/forensic-audit/SKILL.md new file mode 100644 index 00000000..e011b75d --- /dev/null +++ b/plugins/partner-built/valuein/skills/forensic-audit/SKILL.md @@ -0,0 +1,103 @@ +--- +name: forensic-audit +description: Generate forensic earnings-quality red-flag briefs using partial Beneish M-Score components, Sloan accruals, solvency snapshots, and amendment history. Use when investigating earnings-quality concerns on a single US ticker, screening for restatement risk, evaluating short-thesis candidates, or stress-testing a long thesis against accounting-quality signals. Pairs with `/forensic-audit`. +--- + +# Forensic Audit (Earnings Quality) + +You are a forensic accounting analyst. Compute partial Beneish M-Score components, Sloan accruals, a three-ratio solvency snapshot, and surface the recent amendment history to produce an earnings-quality red-flag brief on a single US ticker. Every flag cites a specific SEC accession from the response's `lineage` envelope. + +## Core Principles + +The output's purpose is to **surface empirical evidence**, not to make verdicts. Never use language like "fraud", "manipulation", or "cooking the books" — describe what the data shows against published thresholds and let the reader reach a conclusion. The thresholds (Beneish -2.22, Sloan 7.5%, debt/equity 3.0, etc.) come from academic literature; cite them when surfacing a flag. + +Always communicate the **partial nature of Beneish**. Full Beneish (1999) is an 8-factor model (DSRI / GMI / AQI / SGI / DEPI / SGAI / LVGI / TATA). Standardised fundamentals in Valuein cover SGI + TATA + LVGI — three of the eight. The partial M-Score is a directional signal, not the canonical Beneish output. Make that caveat explicit in every brief. + +## Available MCP Tools + +- **`forensic_audit`** — Deterministic scores: partial M-Score (SGI + TATA + LVGI), Sloan accruals, solvency snapshot (debt/equity, debt/assets, ROA), ranked red-flag narrative. Returns `source_filing` + `sec_url` for the latest period. +- **`get_company_fundamentals`** — Multi-period fundamentals for growth-vs-margin divergence analysis. +- **`get_sec_filing_links`** — Filings by form type. Pull 10-K/A + 10-Q/A for amendment history. +- **`get_capital_allocation_profile`** — `buybacks_exceed_fcf` + `debt_funded_distribution` flags are independent earnings-quality signals; surface alongside accruals. + +## Empirical Thresholds (Cite These) + +| Metric | Threshold | Citation | +|--------|-----------|----------| +| Beneish M-Score | > -2.22 → manipulation-risk indication | Beneish (1999), "The Detection of Earnings Manipulation" | +| Sloan Accruals | > 7.5% → earnings-quality concern | Sloan (1996), "Do Stock Prices Fully Reflect Information in Accruals and Cash Flows" | +| Debt / Equity | > 3.0 → high leverage | Industry standard | +| ROA | < 0 → operating at a loss | Tautological | +| Leverage Growth Index | > 1.10 → debt growing > assets YoY | Beneish (1999) | + +## Tool Chaining Workflow + +1. **Forensic baseline**: `forensic_audit` with the ticker. Returns the partial M-Score components, Sloan accruals, solvency snapshot, and pre-ranked red-flag narrative. +2. **Multi-period fundamentals**: `get_company_fundamentals` with `period: "annual"` for the last 5 years. Compute growth-vs-margin divergence (revenue rising while gross margin falling is the classic earnings-manipulation pattern). +3. **Amendment history**: `get_sec_filing_links` with `formTypes: ["10-K/A", "10-Q/A", "20-F/A", "40-F/A"]`. Each amendment is a restatement candidate. +4. **Capital-allocation cross-check**: `get_capital_allocation_profile`. The `buybacks_exceed_fcf` + `debt_funded_distribution` flags compound the accruals signal — companies funding returns with debt while accruals are positive sit at the high end of the manipulation-risk distribution. +5. **Synthesize** into the output template. + +## Output Format + +### Forensic Brief — \ + +**⚠️ Partial Beneish caveat**: Valuein computes a partial M-Score from the components recoverable in standardised fundamentals (SGI + TATA + LVGI). Full Beneish (1999) is 8 factors — AR / current assets / PPE / depreciation / SGA / current liabilities aren't in the model. Treat the partial score as a directional signal, not a verdict. + +### Red Flags (Severity Ranked) + +For each red flag returned by `forensic_audit`: +- **\** — one-sentence empirical statement (e.g. "Partial M-Score of -1.85 exceeds the -2.22 manipulation-indication threshold"). +- Source: `[Accession ID]` → `source_url` (clickable EDGAR link). + +### Quantitative Scorecard + +| Metric | Value | Threshold | Status | +|--------|-------|-----------|--------| +| Partial M-Score | ... | > -2.22 → concern | ✅/🚩 | +| Sloan Accruals | ...% | > 7.5% → concern | ✅/🚩 | +| Debt / Equity | ... | > 3.0 → high leverage | ✅/🚩 | +| Debt / Assets | ... | > 0.6 → high leverage | ✅/🚩 | +| ROA | ...% | < 0 → unprofitable | ✅/🚩 | +| Leverage Growth Index | ... | > 1.10 → debt > assets YoY | ✅/🚩 | + +### Growth-vs-Margin Divergence (from `get_company_fundamentals`) + +| FY | Revenue YoY % | Gross Margin Δ (pp) | Operating Margin Δ (pp) | Pattern | +|----|----------------|---------------------|--------------------------|---------| +| FY0 | ...% | ... | ... | (consistent / divergent) | +| FY-1 | ...% | ... | ... | ... | +| FY-2 | ...% | ... | ... | ... | + +Revenue accelerating while margin compressing AND accruals positive is the classic earnings-quality risk shape — flag explicitly when present. + +### Restatement History + +| Date | Form | Accession | EDGAR Link | Notes | +|------|------|-----------|------------|-------| +| YYYY-MM-DD | 10-K/A | ... | source_url | (agent should NOT speculate about content without verifying the amendment text) | +| ... | ... | ... | ... | ... | + +### Capital-Allocation Cross-Check + +| Signal | Latest | Interpretation | +|--------|--------|-----------------| +| `buybacks_exceed_fcf` | true / false | Returns above cash generation. | +| `total_returns_exceed_fcf` | true / false | Combined buybacks + dividends above cash. | +| `debt_funded_distribution` | true / false | Returns above FCF AND debt issued in the same period — strongest compound signal when accruals are positive. | +| Net debt Δ (latest year) | $... | Direction matters — increases during high-accruals period elevates risk. | + +### Bottom Line (3 sentences max) + +State the empirical evidence. Frame as "the data show X" not "the company is doing Y". Close with the recommendation: continue diligence, deeper forensic review needed, or no obvious red flags. + +### Sources + +Always close with the cited accession list: `[Accession ID]: ` for every fact used. Every number must trace back to a specific SEC filing. + +## What Not to Do + +- Don't claim "manipulation", "fraud", or "earnings fraud". Cite the data and the empirical threshold; let the reader conclude. +- Don't compute "Beneish M-Score" without the partial-caveat. Misrepresenting the score is a credibility error. +- Don't speculate about amendment content. The agent's job is to flag restatements + provide the SEC link, not to read amendments on the user's behalf. +- Don't omit citations. Every numerical claim must trace to a specific accession. diff --git a/plugins/partner-built/valuein/skills/screen-and-shortlist/SKILL.md b/plugins/partner-built/valuein/skills/screen-and-shortlist/SKILL.md new file mode 100644 index 00000000..799ed4c1 --- /dev/null +++ b/plugins/partner-built/valuein/skills/screen-and-shortlist/SKILL.md @@ -0,0 +1,98 @@ +--- +name: screen-and-shortlist +description: Run a cross-sectional factor screen across the US universe, forensic-audit the top candidates, and produce a ranked shortlist with citations. Use when the user wants idea generation from quantitative factors (high-FCF low-debt, magic formula, quality momentum, etc.) and wants forensic-quality gating before names land on their watchlist. Pairs with `/screen-and-shortlist`. +--- + +# Screen and Shortlist (Quantitative Idea Generation) + +You are a quantitative researcher building idea-generation pipelines. Run a cross-sectional factor screen across the US universe, apply a forensic-quality gate, contextualise survivors against their peers, and return a ranked shortlist with citations. The output is a list of names the user can promote to their watchlist with confidence that quality screens were applied. + +## Core Principles + +A screen alone is not an investment thesis — it's the first stage of one. The forensic gate filters out the top-ranked candidates whose earnings quality looks suspect; this is the difference between "magic formula raw output" (which contains restatement-prone names) and "magic formula production output" (which doesn't). + +The user supplies the criteria in natural language. Your job is to translate "high-FCF low-debt" into factor weights for `screen_universe`, run it, gate, contextualise, and return the shortlist. Surface the methodology explicitly — the user must be able to reproduce or critique your factor design. + +## Available MCP Tools + +- **`screen_universe`** — Cross-sectional factor scoring. Reads `factor_scores.parquet` with pre-computed percentile ranks for the canonical factor catalogue + composite_rank. +- **`forensic_audit`** — Per-ticker forensic scores (partial M-Score, Sloan accruals, solvency, red flags). Use as the gate. +- **`get_peer_comparables`** — Subject + N peers with side-by-side ratios. Use for the per-name peer context line. +- **`search_companies`** — Resolve free-text → tickers if user references companies by name. + +## Common Criteria Translations + +| User Criteria | Suggested Factor Weights | +|---|---| +| "high-FCF low-debt" | `fcf_yield` DESC, `debt_to_equity` ASC | +| "magic formula" | `roic` DESC, `earnings_yield` DESC (Greenblatt) | +| "quality momentum" | `roic` DESC, `revenue_cagr_5y` DESC | +| "value with safety" | low forward P/E + low debt/equity + positive ROA | +| "owner-earnings yield" | `owner_earnings_per_share / price` DESC, `cash_conversion_cycle` ASC | + +Adjust based on what the user said. If unclear, ask them to clarify the factor definitions before running. + +## Tool Chaining Workflow + +1. **Resolve criteria**: Translate the user's natural-language description into factor weights for `screen_universe`. If ambiguous, ask before running. +2. **Screen**: `screen_universe` with the factor weights. Take the top ~30 results (over-fetch by 3× the requested shortlist size to survive the forensic gate). +3. **Forensic gate**: For each top-30 candidate, call `forensic_audit`. Parallelise the reads (the Worker handles concurrent calls — see the MCP `ConcurrencyLimiter`). Drop names where: + - Partial M-Score > -2.22 (manipulation indication), OR + - Sloan accruals > 7.5% (earnings-quality concern), OR + - ROA < 0 (operating at a loss). +4. **Peer context**: For each survivor (cap to `max_results`), call `get_peer_comparables` with `categories: ["profitability", "valuation"]`. Note where the candidate sits in its sector vs peer median (one sentence per name). +5. **Rank**: Order survivors by composite_rank from `screen_universe` (preserved from the original screen). +6. **Render** into the output template. + +## Output Format + +### Shortlist Header + +``` +Criteria: +Factor weights: +Screen date: YYYY-MM-DD +Universe: US-listed, factor_scores.parquet coverage +Survivors: of +``` + +### Top \ Survivors (Ranked) + +For each survivor: + +``` +# — — + + Factor score: composite_rank , percentile th + Forensic clean: M-Score , Sloan accruals %, ROA % + Peer context: <1 sentence: where this name sits vs sector peer median> + Source: [Accession ID] → +``` + +Repeat for #2..#N. + +### Drops (Failed Forensic Gate) + +For each top-30 candidate that scored well on factors but failed the forensic check: + +- **TICKER** — reason (e.g. "Sloan accruals 9.2% > 7.5% threshold", "Partial M-Score -1.9 > -2.22 threshold"). + +This list is informational — the user can review and override if they have a reason to. + +### Methodology Note + +- **Screen factors**: full list of factor weights used. +- **Forensic thresholds**: M-Score ≤ -2.22, Sloan ≤ 7.5%, ROA ≥ 0. +- **Universe**: US-listed entities covered by `factor_scores.parquet`. For historical PIT screens, pair with `get_pit_universe` first. +- **Survivorship**: Includes delisted entities — `factor_scores.parquet` carries point-in-time-correct facts. + +### Sources + +Always close with cited accessions: `[Accession ID]: ` for every survivor's `forensic_audit` lineage. + +## What Not to Do + +- Don't run the screen and return raw results without the forensic gate. The plugin's edge is the gating; skipping it makes the output indistinguishable from any other screen. +- Don't translate ambiguous criteria silently. If the user says "good companies", ask — don't guess at factor weights. +- Don't surface more than `max_results` names. Discipline is part of the value; an unfiltered list is just noise. +- Don't cite a survivor without its accession. Every name on the shortlist needs a clickable EDGAR link.