@cyanheads/secedgar-mcp-server 0.15.14 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +14 -9
- package/CLAUDE.md +14 -9
- package/README.md +21 -16
- package/changelog/0.15.x/0.15.15.md +24 -0
- package/changelog/0.16.x/0.16.0.md +34 -0
- package/dist/config/server-config.d.ts +14 -0
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +38 -13
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +16 -8
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +66 -0
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +24 -13
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +104 -0
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js +21 -11
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +87 -2
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +41 -25
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +92 -0
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +20 -4
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +67 -0
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +61 -31
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +119 -3
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +101 -36
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +108 -0
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.js +19 -9
- package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +91 -0
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +25 -17
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +79 -0
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +34 -18
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +153 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +403 -87
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +70 -0
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js +27 -15
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +594 -544
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/index.js +24 -24
- package/dist/mcp-server/tools/definitions/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +101 -0
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +48 -29
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/fixed-point.d.ts +7 -0
- package/dist/mcp-server/tools/fixed-point.d.ts.map +1 -0
- package/dist/mcp-server/tools/fixed-point.js +28 -0
- package/dist/mcp-server/tools/fixed-point.js.map +1 -0
- package/dist/mcp-server/tools/form-filter.d.ts +13 -0
- package/dist/mcp-server/tools/form-filter.d.ts.map +1 -0
- package/dist/mcp-server/tools/form-filter.js +16 -0
- package/dist/mcp-server/tools/form-filter.js.map +1 -0
- package/dist/mcp-server/tools/limit-clamp.d.ts +65 -0
- package/dist/mcp-server/tools/limit-clamp.d.ts.map +1 -0
- package/dist/mcp-server/tools/limit-clamp.js +78 -0
- package/dist/mcp-server/tools/limit-clamp.js.map +1 -0
- package/dist/services/edgar/concept-series.d.ts.map +1 -1
- package/dist/services/edgar/concept-series.js +5 -1
- package/dist/services/edgar/concept-series.js.map +1 -1
- package/dist/services/edgar/edgar-api-service.d.ts +18 -8
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +149 -32
- package/dist/services/edgar/edgar-api-service.js.map +1 -1
- package/dist/services/edgar/nport-parser.js +1 -1
- package/dist/services/edgar/nport-parser.js.map +1 -1
- package/dist/services/edgar/ownership-parser.d.ts +2 -0
- package/dist/services/edgar/ownership-parser.d.ts.map +1 -1
- package/dist/services/edgar/ownership-parser.js +4 -0
- package/dist/services/edgar/ownership-parser.js.map +1 -1
- package/dist/services/edgar/same-cik.d.ts +7 -0
- package/dist/services/edgar/same-cik.d.ts.map +1 -0
- package/dist/services/edgar/same-cik.js +9 -0
- package/dist/services/edgar/same-cik.js.map +1 -0
- package/dist/services/edgar/types.d.ts +3 -3
- package/package.json +7 -6
- package/server.json +3 -3
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @fileoverview Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR
|
|
3
|
-
* information table XML
|
|
3
|
+
* information table XML, composed with the quarter's 13F-HR/A amendments (#198).
|
|
4
|
+
* Institution lookup only — `company` is the 13F filer.
|
|
4
5
|
* The reverse direction (which institutions hold an issuer) is secedgar_find_holders,
|
|
5
6
|
* which searches the information tables by CUSIP and returns filer CIKs to feed back
|
|
6
7
|
* into this tool (#81).
|
|
@@ -8,10 +9,11 @@
|
|
|
8
9
|
*/
|
|
9
10
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
10
11
|
import { JsonRpcErrorCode, McpError, validationError } from '@cyanheads/mcp-ts-core/errors';
|
|
12
|
+
import { limitClamp, withLimitClamps, } from '../limit-clamp.js';
|
|
11
13
|
import { dataframeGuidance, getCanvasBridge, toDatasetField, } from '../../../services/canvas-bridge/canvas-bridge.js';
|
|
12
14
|
import { CallScope } from '../../../services/edgar/call-scope.js';
|
|
13
15
|
import { getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
|
|
14
|
-
import { parseInfoTableXml, parseThirteenFCoverPage } from '../../../services/edgar/ownership-parser.js';
|
|
16
|
+
import { parseInfoTableXml, parseThirteenFCoverPage, } from '../../../services/edgar/ownership-parser.js';
|
|
15
17
|
import { ARCHIVE_PAGE_SCAN_CAP, SubmissionsArchiveWalk, } from '../../../services/edgar/submissions-archive.js';
|
|
16
18
|
/**
|
|
17
19
|
* Map a quarter string like "2025-Q4" to its calendar quarter-end date (YYYY-MM-DD) — the
|
|
@@ -37,8 +39,9 @@ function addMaybe(a, b) {
|
|
|
37
39
|
/**
|
|
38
40
|
* Collapse info-table sub-lines into distinct positions, keyed by (CUSIP ?? issuer, class,
|
|
39
41
|
* put/call). Sums market value and shares; drops `investment_discretion` — a per-sub-line
|
|
40
|
-
* attribute with no meaning once managers/accounts are rolled up
|
|
41
|
-
* so a
|
|
42
|
+
* attribute with no meaning once managers/accounts are rolled up — and unions the source
|
|
43
|
+
* accessions, so a position merged across an original and its amendment names both. Sorted
|
|
44
|
+
* by value descending, so a small `limit` returns the largest distinct holdings.
|
|
42
45
|
*/
|
|
43
46
|
function consolidatePositions(rows) {
|
|
44
47
|
const byPosition = new Map();
|
|
@@ -48,9 +51,18 @@ function consolidatePositions(rows) {
|
|
|
48
51
|
if (existing) {
|
|
49
52
|
existing.market_value_usd = addMaybe(existing.market_value_usd, r.market_value_usd);
|
|
50
53
|
existing.shares_or_principal_amount = addMaybe(existing.shares_or_principal_amount, r.shares_or_principal_amount);
|
|
54
|
+
for (const accession of r.source_accession_numbers) {
|
|
55
|
+
if (!existing.source_accession_numbers.includes(accession)) {
|
|
56
|
+
existing.source_accession_numbers.push(accession);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
51
59
|
}
|
|
52
60
|
else {
|
|
53
|
-
byPosition.set(key, {
|
|
61
|
+
byPosition.set(key, {
|
|
62
|
+
...r,
|
|
63
|
+
investment_discretion: undefined,
|
|
64
|
+
source_accession_numbers: [...r.source_accession_numbers],
|
|
65
|
+
});
|
|
54
66
|
}
|
|
55
67
|
}
|
|
56
68
|
return [...byPosition.values()].sort((a, b) => (b.market_value_usd ?? 0) - (a.market_value_usd ?? 0));
|
|
@@ -78,6 +90,131 @@ function findInfoTableDocument(items) {
|
|
|
78
90
|
return (candidates.find((it) => /informationtable|infotable|form13f/i.test(it.name))?.name ??
|
|
79
91
|
candidates[0]?.name);
|
|
80
92
|
}
|
|
93
|
+
/**
|
|
94
|
+
* Read a 13F filing's information table: the index, the table document it names, and the
|
|
95
|
+
* parse. Two requests. SEC failures other than a 404 throw from the service.
|
|
96
|
+
*/
|
|
97
|
+
async function readInfoTable(api, cik, accession, scope) {
|
|
98
|
+
const index = await api.tryGetFilingIndex(cik, accession, scope);
|
|
99
|
+
if (!index)
|
|
100
|
+
return { kind: 'no_index' };
|
|
101
|
+
const document = findInfoTableDocument(index.directory.item);
|
|
102
|
+
if (!document)
|
|
103
|
+
return { kind: 'no_document', documents: index.directory.item.map((i) => i.name) };
|
|
104
|
+
const xml = await api.tryGetFilingDocument(cik, accession, document, scope);
|
|
105
|
+
if (!xml)
|
|
106
|
+
return { kind: 'no_table', document };
|
|
107
|
+
try {
|
|
108
|
+
return { kind: 'ok', holdings: parseInfoTableXml(xml).holdings };
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
return { kind: 'unparseable' };
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Normalize one accession's parsed rows to whole USD and tag them with their source. SEC's
|
|
116
|
+
* 2022 Form 13F amendments (effective 2023-01-03) switched Information Table Column 4 from
|
|
117
|
+
* thousands of dollars to whole dollars, and an amendment filed after that date reports whole
|
|
118
|
+
* dollars even for a pre-2023 quarter, so the unit follows each accession's own filing date —
|
|
119
|
+
* the literal compliance boundary, and always present (unlike the cover-page period).
|
|
120
|
+
*/
|
|
121
|
+
function toHoldingRows(holdings, accession, filingDate) {
|
|
122
|
+
const scale = filingDate < '2023-01-03' ? 1000 : 1;
|
|
123
|
+
return holdings.map((h) => ({
|
|
124
|
+
issuer_name: h.issuer_name,
|
|
125
|
+
title_of_class: h.title_of_class,
|
|
126
|
+
cusip: h.cusip,
|
|
127
|
+
market_value_usd: h.value_reported === undefined ? undefined : h.value_reported * scale,
|
|
128
|
+
shares_or_principal_amount: h.shares_or_principal_amount,
|
|
129
|
+
shares_or_principal_type: h.shares_or_principal_type,
|
|
130
|
+
put_call: h.put_call,
|
|
131
|
+
investment_discretion: h.investment_discretion,
|
|
132
|
+
source_accession_numbers: [accession],
|
|
133
|
+
}));
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Identity of a raw row for the NEW HOLDINGS containment test. Value is left out: its unit
|
|
137
|
+
* changed at 2023-01-03, so a resubmitted row filed across that date differs only in scale.
|
|
138
|
+
*/
|
|
139
|
+
const rowIdentity = (r) => `${r.cusip ?? r.issuer_name}|${r.title_of_class ?? ''}|${r.put_call ?? ''}|${r.investment_discretion ?? ''}|${r.shares_or_principal_amount ?? ''}|${r.shares_or_principal_type ?? ''}`;
|
|
140
|
+
/**
|
|
141
|
+
* True when `table` repeats every row of `composed`, counting duplicates. A NEW HOLDINGS
|
|
142
|
+
* amendment should list only the added securities, but some filers resubmit the whole table
|
|
143
|
+
* under that type (First Eagle's 2026-Q2 amendment repeats all 614 original rows plus 2);
|
|
144
|
+
* appending it would double the portfolio, so it is applied as the restatement it is.
|
|
145
|
+
*/
|
|
146
|
+
function repeatsEveryRow(table, composed) {
|
|
147
|
+
if (composed.length === 0)
|
|
148
|
+
return false;
|
|
149
|
+
const counts = new Map();
|
|
150
|
+
for (const r of table)
|
|
151
|
+
counts.set(rowIdentity(r), (counts.get(rowIdentity(r)) ?? 0) + 1);
|
|
152
|
+
for (const r of composed) {
|
|
153
|
+
const left = counts.get(rowIdentity(r)) ?? 0;
|
|
154
|
+
if (left === 0)
|
|
155
|
+
return false;
|
|
156
|
+
counts.set(rowIdentity(r), left - 1);
|
|
157
|
+
}
|
|
158
|
+
return true;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* Compose a quarter's holdings from its original 13F-HR and same-period amendments, in
|
|
162
|
+
* acceptance order. A RESTATEMENT replaces everything composed before it (earlier NEW
|
|
163
|
+
* HOLDINGS included), and the original counts as one: the base is the last restatement whose
|
|
164
|
+
* table reads, walking back to the original, and nothing before it is read (`superseded`).
|
|
165
|
+
* Each NEW HOLDINGS after the base is read and appended — or applied as a restatement when
|
|
166
|
+
* its table repeats every composed row. An amendment whose type or table cannot be read is
|
|
167
|
+
* `not_applied`; `readTable` returns undefined for it.
|
|
168
|
+
*/
|
|
169
|
+
async function composeHoldings(steps, originalRows, readTable) {
|
|
170
|
+
let base = 0;
|
|
171
|
+
let rows = originalRows;
|
|
172
|
+
for (let i = steps.length - 1; i >= 0; i--) {
|
|
173
|
+
const step = steps[i];
|
|
174
|
+
if (step.kind === 'original') {
|
|
175
|
+
base = i;
|
|
176
|
+
break;
|
|
177
|
+
}
|
|
178
|
+
if (step.kind !== 'RESTATEMENT')
|
|
179
|
+
continue;
|
|
180
|
+
const table = await readTable(step);
|
|
181
|
+
if (table) {
|
|
182
|
+
base = i;
|
|
183
|
+
rows = table;
|
|
184
|
+
step.status = 'restatement';
|
|
185
|
+
break;
|
|
186
|
+
}
|
|
187
|
+
step.status = 'not_applied';
|
|
188
|
+
}
|
|
189
|
+
for (const step of steps.slice(0, base))
|
|
190
|
+
if (!step.kind)
|
|
191
|
+
step.status = 'not_applied';
|
|
192
|
+
let applied = [steps[base]];
|
|
193
|
+
for (const step of steps.slice(base + 1)) {
|
|
194
|
+
// A restatement past the base was tried in the backward pass and did not read.
|
|
195
|
+
if (step.kind !== 'NEW HOLDINGS') {
|
|
196
|
+
step.status = 'not_applied';
|
|
197
|
+
continue;
|
|
198
|
+
}
|
|
199
|
+
const table = await readTable(step);
|
|
200
|
+
if (!table)
|
|
201
|
+
step.status = 'not_applied';
|
|
202
|
+
else if (repeatsEveryRow(table, rows)) {
|
|
203
|
+
for (const earlier of applied)
|
|
204
|
+
if (earlier.kind !== 'original')
|
|
205
|
+
earlier.status = 'superseded';
|
|
206
|
+
applied = [step];
|
|
207
|
+
rows = table;
|
|
208
|
+
step.status = 'restatement';
|
|
209
|
+
}
|
|
210
|
+
else {
|
|
211
|
+
applied.push(step);
|
|
212
|
+
rows = [...rows, ...table];
|
|
213
|
+
step.status = 'new_holdings';
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
return { accessions: applied.map((s) => s.accession), rows };
|
|
217
|
+
}
|
|
81
218
|
/**
|
|
82
219
|
* Periodic-report forms that mark an operating company (not an institutional manager).
|
|
83
220
|
* A filer with any of these and no 13F-HR is misrouted here — the caller wants
|
|
@@ -88,8 +225,19 @@ const OPERATING_COMPANY_FORMS = ['10-K', '10-K/A', '10-Q', '10-Q/A', '8-K', '8-K
|
|
|
88
225
|
const HOLDINGS_REPORT_FORM = '13F-HR';
|
|
89
226
|
const NOTICE_FORMS = new Set(['13F-NT', '13F-NT/A']);
|
|
90
227
|
/**
|
|
91
|
-
*
|
|
92
|
-
*
|
|
228
|
+
* Composition order: acceptance time, which separates two amendments filed the same day
|
|
229
|
+
* (Advisors Asset Management's 2020-Q2 restatement and new-holdings amendment, 2026-08-27,
|
|
230
|
+
* a minute apart), then filing date when a block lacks it, then accession. `amendmentNo`
|
|
231
|
+
* is not a key — filers skip numbers.
|
|
232
|
+
*/
|
|
233
|
+
function compositionOrder(a, b) {
|
|
234
|
+
return ((a.acceptanceDateTime || a.filingDate).localeCompare(b.acceptanceDateTime || b.filingDate) ||
|
|
235
|
+
a.filingDate.localeCompare(b.filingDate) ||
|
|
236
|
+
a.accessionNumber.localeCompare(b.accessionNumber));
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* Zip a submissions block (the recent window or an archive page) into its 13F-HR,
|
|
240
|
+
* 13F-HR/A and 13F-NT notice rows, newest filed first. Read off the submissions fetch the
|
|
93
241
|
* tool already holds, which also feeds the 404 handling (#76) and the operating-company
|
|
94
242
|
* classification (#86).
|
|
95
243
|
*/
|
|
@@ -97,9 +245,10 @@ function thirteenFRows(block) {
|
|
|
97
245
|
const out = [];
|
|
98
246
|
for (let i = 0; i < block.form.length; i++) {
|
|
99
247
|
const form = block.form[i] ?? '';
|
|
100
|
-
if (form !== HOLDINGS_REPORT_FORM && !NOTICE_FORMS.has(form))
|
|
248
|
+
if (form !== HOLDINGS_REPORT_FORM && form !== '13F-HR/A' && !NOTICE_FORMS.has(form))
|
|
101
249
|
continue;
|
|
102
250
|
out.push({
|
|
251
|
+
acceptanceDateTime: block.acceptanceDateTime?.[i] ?? '',
|
|
103
252
|
accessionNumber: block.accessionNumber[i] ?? '',
|
|
104
253
|
filingDate: block.filingDate[i] ?? '',
|
|
105
254
|
form,
|
|
@@ -116,9 +265,52 @@ function forPeriod(rows, periodEnd) {
|
|
|
116
265
|
notice: inPeriod.find((r) => NOTICE_FORMS.has(r.form)),
|
|
117
266
|
};
|
|
118
267
|
}
|
|
268
|
+
/** SEC lookup failures that can leave optional disclosure unavailable. */
|
|
269
|
+
function optionalLookupFailure(err) {
|
|
270
|
+
return (err instanceof McpError &&
|
|
271
|
+
[
|
|
272
|
+
JsonRpcErrorCode.ServiceUnavailable,
|
|
273
|
+
JsonRpcErrorCode.Timeout,
|
|
274
|
+
JsonRpcErrorCode.Forbidden,
|
|
275
|
+
JsonRpcErrorCode.RateLimited,
|
|
276
|
+
JsonRpcErrorCode.NotFound,
|
|
277
|
+
].includes(err.code));
|
|
278
|
+
}
|
|
279
|
+
const amendmentIdentity = z.object({
|
|
280
|
+
accession_number: z.string().describe('Accession for secedgar_get_filing.'),
|
|
281
|
+
filing_date: z.string().describe('Filing date (YYYY-MM-DD).'),
|
|
282
|
+
applied_as: z
|
|
283
|
+
.enum(['restatement', 'new_holdings', 'superseded', 'not_applied'])
|
|
284
|
+
.describe('Composition role.'),
|
|
285
|
+
});
|
|
286
|
+
const amendmentSchema = z.discriminatedUnion('amendment_type', [
|
|
287
|
+
amendmentIdentity
|
|
288
|
+
.extend({
|
|
289
|
+
amendment_type: z.enum(['RESTATEMENT', 'NEW HOLDINGS']).describe('Cover-page type.'),
|
|
290
|
+
})
|
|
291
|
+
.describe('Typed amendment.'),
|
|
292
|
+
amendmentIdentity
|
|
293
|
+
.extend({
|
|
294
|
+
amendment_type: z.literal('UNAVAILABLE').describe('Type could not be read.'),
|
|
295
|
+
unavailable_reason: z
|
|
296
|
+
.enum(['missing_header', 'unreadable_header', 'lookup_failed', 'lookup_stopped'])
|
|
297
|
+
.describe('Why the type is unavailable; inspect with secedgar_get_filing.'),
|
|
298
|
+
})
|
|
299
|
+
.describe('Untyped amendment.'),
|
|
300
|
+
]);
|
|
301
|
+
/** `limit`: a page holds at most 500 holdings rows (#197). */
|
|
302
|
+
const holdingsLimit = limitClamp({
|
|
303
|
+
tool: 'secedgar_get_institutional_holdings',
|
|
304
|
+
field: 'limit',
|
|
305
|
+
min: 1,
|
|
306
|
+
cap: 500,
|
|
307
|
+
bound: 1000,
|
|
308
|
+
shape: (n) => n.default(20),
|
|
309
|
+
description: 'Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.',
|
|
310
|
+
});
|
|
119
311
|
export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_holdings', {
|
|
120
312
|
title: 'Get Institutional Holdings',
|
|
121
|
-
description: '
|
|
313
|
+
description: 'Read an institutional manager\'s 13F-HR information table for a quarter. company is the filer: a 10-digit CIK, ticker, or name; names outside the ticker file use EDGAR entity search, and ambiguous names return candidates. For managers holding an issuer, use secedgar_find_holders and pass its filer_cik here. Positions carry issuer, CUSIP, shares, whole-USD market value, option designation, and the accessions they came from. Same-period 13F-HR/A amendments are composed in acceptance order: a RESTATEMENT replaces the rows, a NEW HOLDINGS amendment adds its rows, and each amendment reports how it was applied. By default, sub-lines consolidate into positions sorted by value; consolidate=false preserves raw filing order, each filing\'s rows after the last. Page with limit, offset and returned next_offset. When canvas is available, the full composed positions are staged as df_<id>: inspect with secedgar_dataframe_describe, then aggregate or join on cusip + reporting_period with secedgar_dataframe_query. Managers below $100M in 13(f) securities may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.',
|
|
122
314
|
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
|
|
123
315
|
errors: [
|
|
124
316
|
{
|
|
@@ -171,13 +363,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
171
363
|
.string()
|
|
172
364
|
.optional()
|
|
173
365
|
.describe('Reporting quarter to target, in "YYYY-QN" format (e.g., "2025-Q4"), matched exactly against each 13F-HR\'s period of report. When omitted, returns the most recent 13F-HR in the submissions feed\'s recent window (the last year or 1,000 filings, whichever holds more). Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026. A quarter older than the recent window is looked up in the archive, reading forward from the quarter end up to 10 archive pages. A quarter the manager covered with a 13F-NT notice (holdings reported by other managers) fails naming that notice.'),
|
|
174
|
-
limit:
|
|
175
|
-
.number()
|
|
176
|
-
.int()
|
|
177
|
-
.min(1)
|
|
178
|
-
.max(500)
|
|
179
|
-
.default(20)
|
|
180
|
-
.describe('Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.'),
|
|
366
|
+
limit: holdingsLimit.schema(true),
|
|
181
367
|
offset: z
|
|
182
368
|
.number()
|
|
183
369
|
.int()
|
|
@@ -192,23 +378,33 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
192
378
|
// Other tools' spellings of the company parameter, and this tool's former one (#115).
|
|
193
379
|
inputAliases: { ticker: 'company', cik: 'company', ticker_or_cik: 'company' },
|
|
194
380
|
output: z.object({
|
|
195
|
-
filer_name: z.string().describe('
|
|
381
|
+
filer_name: z.string().describe('Institutional filer name (the 13F submitter).'),
|
|
196
382
|
filer_cik: z.string().describe('CIK of the 13F filer, zero-padded to 10 digits.'),
|
|
197
383
|
reporting_period: z
|
|
198
384
|
.string()
|
|
199
385
|
.optional()
|
|
200
|
-
.describe('
|
|
201
|
-
filing_date: z.string().describe('
|
|
202
|
-
accession_number: z
|
|
203
|
-
|
|
204
|
-
.describe('
|
|
205
|
-
|
|
386
|
+
.describe('Cover-page quarter end (YYYY-MM-DD). Absent if omitted.'),
|
|
387
|
+
filing_date: z.string().describe('Original 13F-HR filing date (YYYY-MM-DD).'),
|
|
388
|
+
accession_number: z.string().describe('Original 13F-HR accession for secedgar_get_filing.'),
|
|
389
|
+
amendments: z
|
|
390
|
+
.array(amendmentSchema.describe('Same-period 13F-HR/A.'))
|
|
391
|
+
.optional()
|
|
392
|
+
.describe('Known amendments, newest filed first. Absent if none.'),
|
|
393
|
+
amendment_search_complete: z
|
|
394
|
+
.boolean()
|
|
395
|
+
.optional()
|
|
396
|
+
.describe('False if archive discovery was bounded or unavailable.'),
|
|
397
|
+
composed_accessions: z
|
|
398
|
+
.array(z.string())
|
|
399
|
+
.describe('Accessions whose rows form holdings, in application order.'),
|
|
400
|
+
total_holdings_in_filing: z.number().describe('Original 13F-HR raw row count.'),
|
|
401
|
+
total_holdings_composed: z
|
|
206
402
|
.number()
|
|
207
|
-
.describe('
|
|
403
|
+
.describe('Composed raw row count before consolidation or paging.'),
|
|
208
404
|
total_positions: z
|
|
209
405
|
.number()
|
|
210
406
|
.optional()
|
|
211
|
-
.describe('Distinct positions
|
|
407
|
+
.describe('Distinct positions before paging. Only with consolidate=true.'),
|
|
212
408
|
offset: z.number().describe('Row the returned page starts at, 0-based.'),
|
|
213
409
|
next_offset: z
|
|
214
410
|
.number()
|
|
@@ -221,23 +417,20 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
221
417
|
title_of_class: z
|
|
222
418
|
.string()
|
|
223
419
|
.optional()
|
|
224
|
-
.describe('Security class (
|
|
225
|
-
cusip: z
|
|
226
|
-
.string()
|
|
227
|
-
.optional()
|
|
228
|
-
.describe('9-digit CUSIP identifier. Absent when omitted by the filer.'),
|
|
420
|
+
.describe('Security class (COM, CL A, ETF). Absent if unreported.'),
|
|
421
|
+
cusip: z.string().optional().describe('CUSIP. Absent if unreported.'),
|
|
229
422
|
market_value_usd: z
|
|
230
423
|
.number()
|
|
231
424
|
.optional()
|
|
232
|
-
.describe('
|
|
425
|
+
.describe('Whole USD at report date; values filed before 2023-01-03 scaled from thousands. Absent if unreported.'),
|
|
233
426
|
shares_or_principal_amount: z
|
|
234
427
|
.number()
|
|
235
428
|
.optional()
|
|
236
|
-
.describe('Shares
|
|
429
|
+
.describe('Shares or debt principal. Absent if unreported.'),
|
|
237
430
|
shares_or_principal_type: z
|
|
238
431
|
.enum(['SH', 'PRN'])
|
|
239
432
|
.optional()
|
|
240
|
-
.describe('SH shares
|
|
433
|
+
.describe('SH shares; PRN debt principal. Absent if unreported.'),
|
|
241
434
|
put_call: z
|
|
242
435
|
.enum(['Put', 'Call'])
|
|
243
436
|
.optional()
|
|
@@ -245,10 +438,13 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
245
438
|
investment_discretion: z
|
|
246
439
|
.enum(['SOLE', 'DFND', 'OTR'])
|
|
247
440
|
.optional()
|
|
248
|
-
.describe('SOLE sole
|
|
441
|
+
.describe('SOLE sole, DFND shared/advised, OTR other. Absent if unreported or consolidated.'),
|
|
442
|
+
source_accession_numbers: z
|
|
443
|
+
.array(z.string())
|
|
444
|
+
.describe('Accessions the row came from, in application order.'),
|
|
249
445
|
})
|
|
250
446
|
.describe('One row from the 13F information table.'))
|
|
251
|
-
.describe('`limit` rows from `offset`: positions by
|
|
447
|
+
.describe('`limit` rows from `offset`: positions by value when consolidate=true, else raw rows in application order.'),
|
|
252
448
|
dataset: z
|
|
253
449
|
.object({
|
|
254
450
|
name: z
|
|
@@ -258,13 +454,13 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
258
454
|
expires_at: z.string().describe('ISO 8601 expiry timestamp.'),
|
|
259
455
|
})
|
|
260
456
|
.optional()
|
|
261
|
-
.describe('
|
|
457
|
+
.describe('Composed positions, shaped by consolidate; join on cusip + reporting_period. Absent without canvas or holdings.'),
|
|
262
458
|
}),
|
|
263
459
|
enrichment: {
|
|
264
460
|
notice: z
|
|
265
461
|
.string()
|
|
266
462
|
.optional()
|
|
267
|
-
.describe('
|
|
463
|
+
.describe('Amendment composition, discovery, paging, and dataframe guidance.'),
|
|
268
464
|
truncated: z
|
|
269
465
|
.boolean()
|
|
270
466
|
.optional()
|
|
@@ -273,6 +469,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
273
469
|
cap: z.number().optional().describe('The limit cap applied.'),
|
|
274
470
|
},
|
|
275
471
|
async handler(input, ctx) {
|
|
472
|
+
const limit = holdingsLimit.apply(input.limit, ctx);
|
|
276
473
|
const api = getEdgarApiService();
|
|
277
474
|
const callScope = new CallScope(ctx.signal);
|
|
278
475
|
// Resolve entity to CIK. Ticker/CIK/name go through the ticker cache first; on a
|
|
@@ -333,6 +530,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
333
530
|
// matched exactly. No quarter → most-recent; with a quarter, a miss is reported,
|
|
334
531
|
// never silently the latest filing.
|
|
335
532
|
const recentRows = thirteenFRows(submissions.filings.recent);
|
|
533
|
+
const discoveredRows = [...recentRows];
|
|
336
534
|
// A 13F-HR or a notice either one marks a 13F manager; only an entity whose rows
|
|
337
535
|
// read hold neither gets the #86 classification below.
|
|
338
536
|
let filesThirteenF = recentRows.length > 0;
|
|
@@ -356,6 +554,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
356
554
|
walk = new SubmissionsArchiveWalk(api, submissions, { filedAfter: periodEnd, order: 'oldest-first' }, callScope);
|
|
357
555
|
for await (const { block } of walk) {
|
|
358
556
|
const rows = thirteenFRows(block);
|
|
557
|
+
discoveredRows.push(...rows);
|
|
359
558
|
filesThirteenF ||= rows.length > 0;
|
|
360
559
|
({ report: filingMeta, notice } = forPeriod(rows, periodEnd));
|
|
361
560
|
if (filingMeta || notice)
|
|
@@ -421,21 +620,22 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
421
620
|
: '';
|
|
422
621
|
throw ctx.fail('no_filings_found', `No 13F-HR filings found for '${input.company}' for quarter "${input.quarter}".${searched}`);
|
|
423
622
|
}
|
|
424
|
-
//
|
|
425
|
-
const
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
623
|
+
// The original's information table is required: a failure here fails the call.
|
|
624
|
+
const originalTable = await readInfoTable(api, match.cik, filingMeta.accessionNumber, callScope);
|
|
625
|
+
switch (originalTable.kind) {
|
|
626
|
+
case 'ok':
|
|
627
|
+
break;
|
|
628
|
+
case 'no_index':
|
|
629
|
+
throw ctx.fail('no_info_table', `Filing ${filingMeta.accessionNumber} index could not be fetched.`);
|
|
630
|
+
case 'no_document':
|
|
631
|
+
throw ctx.fail('no_info_table', `No information table XML found in filing ${filingMeta.accessionNumber}.`, {
|
|
632
|
+
accession_number: filingMeta.accessionNumber,
|
|
633
|
+
available_documents: originalTable.documents,
|
|
634
|
+
});
|
|
635
|
+
case 'no_table':
|
|
636
|
+
throw ctx.fail('no_info_table', `Information table document '${originalTable.document}' could not be fetched.`);
|
|
637
|
+
case 'unparseable':
|
|
638
|
+
throw ctx.fail('no_info_table', `Failed to parse information table XML for filing ${filingMeta.accessionNumber}.`);
|
|
439
639
|
}
|
|
440
640
|
// Pull reporting period and filing-manager name from the primary_doc.xml cover page.
|
|
441
641
|
// The CIK resolver only knows names for ticker-listed entities, but most 13F filers
|
|
@@ -444,30 +644,123 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
444
644
|
const { filerName, reportingPeriod } = primaryXml
|
|
445
645
|
? parseThirteenFCoverPage(primaryXml)
|
|
446
646
|
: { filerName: undefined, reportingPeriod: undefined };
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
647
|
+
const originalRows = toHoldingRows(originalTable.holdings, filingMeta.accessionNumber, filingMeta.filingDate);
|
|
648
|
+
/** Discovery is optional enrichment after the original is readable. Resume an
|
|
649
|
+
* archive walk that found the original so later-filed amendments are included.
|
|
650
|
+
* Every request shares the primary operation's failure budget and cancellation.
|
|
651
|
+
*/
|
|
652
|
+
const amendmentPeriod = filingMeta.reportDate || reportingPeriod;
|
|
653
|
+
let amendmentSearchComplete = Boolean(amendmentPeriod);
|
|
654
|
+
let disclosureBlocked = false;
|
|
655
|
+
if (amendmentPeriod) {
|
|
656
|
+
walk ??= new SubmissionsArchiveWalk(api, submissions, { filedAfter: amendmentPeriod, order: 'oldest-first' }, callScope);
|
|
657
|
+
try {
|
|
658
|
+
for await (const { block } of walk)
|
|
659
|
+
discoveredRows.push(...thirteenFRows(block));
|
|
660
|
+
amendmentSearchComplete = !walk.truncated;
|
|
661
|
+
}
|
|
662
|
+
catch (err) {
|
|
663
|
+
callScope.signal.throwIfAborted();
|
|
664
|
+
if (!optionalLookupFailure(err))
|
|
665
|
+
throw err;
|
|
666
|
+
amendmentSearchComplete = false;
|
|
667
|
+
disclosureBlocked =
|
|
668
|
+
err.code === JsonRpcErrorCode.RateLimited || callScope.remainingMs === 0;
|
|
669
|
+
}
|
|
450
670
|
}
|
|
451
|
-
|
|
452
|
-
|
|
671
|
+
const samePeriod = [
|
|
672
|
+
...new Map(discoveredRows
|
|
673
|
+
.filter((r) => r.form === '13F-HR/A' && amendmentPeriod && r.reportDate === amendmentPeriod)
|
|
674
|
+
.map((r) => [r.accessionNumber, r])).values(),
|
|
675
|
+
].sort((a, b) => b.filingDate.localeCompare(a.filingDate));
|
|
676
|
+
const entries = [];
|
|
677
|
+
for (const amendment of samePeriod) {
|
|
678
|
+
let amendmentType;
|
|
679
|
+
let unavailableReason = 'lookup_stopped';
|
|
680
|
+
if (!disclosureBlocked) {
|
|
681
|
+
try {
|
|
682
|
+
const header = await api.tryGetFilingDocument(match.cik, amendment.accessionNumber, 'primary_doc.xml', callScope);
|
|
683
|
+
if (header)
|
|
684
|
+
amendmentType = parseThirteenFCoverPage(header).amendmentType;
|
|
685
|
+
unavailableReason = header ? 'unreadable_header' : 'missing_header';
|
|
686
|
+
}
|
|
687
|
+
catch (err) {
|
|
688
|
+
callScope.signal.throwIfAborted();
|
|
689
|
+
if (!optionalLookupFailure(err))
|
|
690
|
+
throw err;
|
|
691
|
+
unavailableReason = 'lookup_failed';
|
|
692
|
+
disclosureBlocked =
|
|
693
|
+
err.code === JsonRpcErrorCode.RateLimited || callScope.remainingMs === 0;
|
|
694
|
+
}
|
|
695
|
+
}
|
|
696
|
+
entries.push({
|
|
697
|
+
amendmentType,
|
|
698
|
+
step: {
|
|
699
|
+
accession: amendment.accessionNumber,
|
|
700
|
+
kind: amendmentType,
|
|
701
|
+
row: amendment,
|
|
702
|
+
status: 'superseded',
|
|
703
|
+
},
|
|
704
|
+
unavailableReason,
|
|
705
|
+
});
|
|
453
706
|
}
|
|
454
|
-
//
|
|
455
|
-
//
|
|
456
|
-
//
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
707
|
+
// Compose the quarter. Each amendment table read is two more requests (index and
|
|
708
|
+
// table) on the same CallScope; a 429 or a spent failure budget stops further reads,
|
|
709
|
+
// as it stops the cover reads above, and a caller cancel still fails the call.
|
|
710
|
+
const original = {
|
|
711
|
+
accession: filingMeta.accessionNumber,
|
|
712
|
+
kind: 'original',
|
|
713
|
+
row: filingMeta,
|
|
714
|
+
status: 'superseded',
|
|
715
|
+
};
|
|
716
|
+
const steps = [original, ...entries.map((e) => e.step)].sort((a, b) => compositionOrder(a.row, b.row));
|
|
717
|
+
const composed = await composeHoldings(steps, originalRows, async (step) => {
|
|
718
|
+
if (disclosureBlocked)
|
|
719
|
+
return;
|
|
720
|
+
try {
|
|
721
|
+
const read = await readInfoTable(api, match.cik, step.accession, callScope);
|
|
722
|
+
// An amendment exists to change rows: an empty table is unreadable, never a
|
|
723
|
+
// restatement that blanks the quarter.
|
|
724
|
+
if (read.kind !== 'ok' || read.holdings.length === 0)
|
|
725
|
+
return;
|
|
726
|
+
return toHoldingRows(read.holdings, step.accession, step.row.filingDate);
|
|
727
|
+
}
|
|
728
|
+
catch (err) {
|
|
729
|
+
callScope.signal.throwIfAborted();
|
|
730
|
+
if (!optionalLookupFailure(err))
|
|
731
|
+
throw err;
|
|
732
|
+
disclosureBlocked =
|
|
733
|
+
err.code === JsonRpcErrorCode.RateLimited || callScope.remainingMs === 0;
|
|
734
|
+
return;
|
|
735
|
+
}
|
|
736
|
+
});
|
|
737
|
+
const amendments = entries.map((e) => ({
|
|
738
|
+
accession_number: e.step.accession,
|
|
739
|
+
filing_date: e.step.row.filingDate,
|
|
740
|
+
applied_as: e.step.status,
|
|
741
|
+
...(e.amendmentType
|
|
742
|
+
? { amendment_type: e.amendmentType }
|
|
743
|
+
: { amendment_type: 'UNAVAILABLE', unavailable_reason: e.unavailableReason }),
|
|
469
744
|
}));
|
|
470
|
-
const positions = input.consolidate ? consolidatePositions(rows) : rows;
|
|
745
|
+
const positions = input.consolidate ? consolidatePositions(composed.rows) : composed.rows;
|
|
746
|
+
const notApplied = amendments.filter((a) => a.applied_as === 'not_applied');
|
|
747
|
+
const amendmentNotice = [
|
|
748
|
+
...(amendments.length > 0
|
|
749
|
+
? [
|
|
750
|
+
`Holdings and dataframe compose the original 13F-HR with its same-period amendments, applied in acceptance order: a RESTATEMENT replaces the rows, NEW HOLDINGS adds them. Amendments, newest filed first: ${amendments.map((a) => `${a.accession_number} (filed ${a.filing_date}, ${a.amendment_type}${a.amendment_type === 'UNAVAILABLE' ? `: ${a.unavailable_reason}` : ''}, ${a.applied_as})`).join('; ')}. Rows come from ${composed.accessions.join(', ')}, in that order.`,
|
|
751
|
+
]
|
|
752
|
+
: []),
|
|
753
|
+
...(notApplied.length > 0
|
|
754
|
+
? [
|
|
755
|
+
`Not applied, since the type or information table could not be read: ${notApplied.map((a) => a.accession_number).join(', ')} — inspect with secedgar_get_filing.`,
|
|
756
|
+
]
|
|
757
|
+
: []),
|
|
758
|
+
...(!amendmentSearchComplete
|
|
759
|
+
? [
|
|
760
|
+
`Amendment discovery is incomplete: the submissions archive search was bounded at ${ARCHIVE_PAGE_SCAN_CAP} pages or unavailable, or the report period is missing. Additional amendments may exist.`,
|
|
761
|
+
]
|
|
762
|
+
: []),
|
|
763
|
+
].join(' ');
|
|
471
764
|
// Register the full parsed position set to the canvas (the inline holdings list
|
|
472
765
|
// is a preview capped at `limit`). Denormalize the filer/period metadata onto
|
|
473
766
|
// every row so the dataframe self-joins across quarters and filers on cusip +
|
|
@@ -491,6 +784,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
491
784
|
market_value_usd: p.market_value_usd ?? null,
|
|
492
785
|
put_call: p.put_call ?? null,
|
|
493
786
|
investment_discretion: p.investment_discretion ?? null,
|
|
787
|
+
source_accession_numbers: p.source_accession_numbers,
|
|
494
788
|
})),
|
|
495
789
|
sourceTool: 'secedgar_get_institutional_holdings',
|
|
496
790
|
queryParams: {
|
|
@@ -499,6 +793,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
499
793
|
quarter: input.quarter,
|
|
500
794
|
consolidate: input.consolidate,
|
|
501
795
|
accession_number: filingMeta.accessionNumber,
|
|
796
|
+
composed_accessions: composed.accessions,
|
|
502
797
|
},
|
|
503
798
|
});
|
|
504
799
|
if (registered)
|
|
@@ -507,36 +802,41 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
507
802
|
// Offset paging over the whole ordered position list — the retrieval path for
|
|
508
803
|
// rows past `limit` when no canvas is available to hold the full set (#94). The
|
|
509
804
|
// information table is parsed whole, so slicing it is contiguous and stable.
|
|
510
|
-
const pageEnd = input.offset +
|
|
805
|
+
const pageEnd = input.offset + limit;
|
|
511
806
|
const holdings = positions.slice(input.offset, pageEnd);
|
|
512
807
|
const nextOffset = pageEnd < positions.length ? pageEnd : undefined;
|
|
513
808
|
// One chain, because `notice` is last-wins across notice/truncated: each arm
|
|
514
809
|
// composes the staged-dataframe pointer into its own string rather than
|
|
515
810
|
// emitting a second notice that would clobber the first (#104).
|
|
811
|
+
const notices = amendmentNotice ? [amendmentNotice] : [];
|
|
516
812
|
if (holdings.length === 0 && input.offset > 0) {
|
|
517
|
-
|
|
813
|
+
notices.push(`Offset (${input.offset}) is at or past the ${positions.length} positions in this filing. ` +
|
|
518
814
|
`Lower the offset to page back into the holdings.` +
|
|
519
815
|
(dataset ? ` ${dataframeGuidance(dataset)}` : ''));
|
|
520
816
|
}
|
|
521
817
|
else if (holdings.length === 0) {
|
|
522
|
-
|
|
818
|
+
notices.push(`The information table for this filing contained no holdings rows. ` +
|
|
523
819
|
`This may be a 13F-NT (notice-only) filing or an amendment. ` +
|
|
524
820
|
`Use secedgar_search_filings with forms=["13F-HR"] to find the correct filing.`);
|
|
525
821
|
}
|
|
526
|
-
else if (
|
|
822
|
+
else if (dataset) {
|
|
823
|
+
notices.push(dataframeGuidance(dataset));
|
|
824
|
+
}
|
|
825
|
+
if (holdings.length > 0 && nextOffset !== undefined) {
|
|
527
826
|
ctx.enrich.truncated({
|
|
528
827
|
shown: holdings.length,
|
|
529
|
-
cap:
|
|
530
|
-
...(
|
|
828
|
+
cap: limit,
|
|
829
|
+
...(notices.length > 0 && { guidance: notices.join(' ') }),
|
|
531
830
|
});
|
|
532
831
|
}
|
|
533
|
-
else if (
|
|
534
|
-
ctx.enrich.notice(
|
|
535
|
-
}
|
|
832
|
+
else if (notices.length > 0)
|
|
833
|
+
ctx.enrich.notice(notices.join(' '));
|
|
536
834
|
ctx.log.info('Institutional holdings retrieved', {
|
|
537
835
|
cik: match.cik,
|
|
538
836
|
accessionNumber: filingMeta.accessionNumber,
|
|
539
|
-
totalHoldings:
|
|
837
|
+
totalHoldings: originalRows.length,
|
|
838
|
+
composedRows: composed.rows.length,
|
|
839
|
+
composedAccessions: composed.accessions.length,
|
|
540
840
|
totalPositions: positions.length,
|
|
541
841
|
returned: holdings.length,
|
|
542
842
|
datasetName: dataset?.name,
|
|
@@ -547,7 +847,11 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
547
847
|
reporting_period: reportingPeriod,
|
|
548
848
|
filing_date: filingMeta.filingDate,
|
|
549
849
|
accession_number: filingMeta.accessionNumber,
|
|
550
|
-
|
|
850
|
+
amendments: amendments.length > 0 ? amendments : undefined,
|
|
851
|
+
amendment_search_complete: amendmentSearchComplete,
|
|
852
|
+
composed_accessions: composed.accessions,
|
|
853
|
+
total_holdings_in_filing: originalRows.length,
|
|
854
|
+
total_holdings_composed: composed.rows.length,
|
|
551
855
|
total_positions: input.consolidate ? positions.length : undefined,
|
|
552
856
|
offset: input.offset,
|
|
553
857
|
next_offset: nextOffset,
|
|
@@ -558,14 +862,22 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
558
862
|
format: (result) => {
|
|
559
863
|
const period = result.reporting_period ? ` (period: ${result.reporting_period})` : '';
|
|
560
864
|
const countLine = result.total_positions !== undefined
|
|
561
|
-
? `Showing ${result.holdings.length} of ${result.total_positions} positions (consolidated from ${result.
|
|
562
|
-
: `Showing ${result.holdings.length} of ${result.
|
|
865
|
+
? `Showing ${result.holdings.length} of ${result.total_positions} positions (consolidated from ${result.total_holdings_composed} info-table rows)`
|
|
866
|
+
: `Showing ${result.holdings.length} of ${result.total_holdings_composed} info-table rows`;
|
|
563
867
|
const lines = [
|
|
564
868
|
`**13F-HR Holdings** — ${result.filer_name} (CIK ${result.filer_cik})`,
|
|
565
869
|
`Filed: ${result.filing_date}${period} | Accession: ${result.accession_number}`,
|
|
566
870
|
countLine,
|
|
871
|
+
`Composed from: ${result.composed_accessions.join(', ')} (${result.total_holdings_composed} rows; original 13F-HR: ${result.total_holdings_in_filing})`,
|
|
567
872
|
];
|
|
568
873
|
lines.push(`Page offset: ${result.offset} (${result.holdings.length} shown)`);
|
|
874
|
+
for (const amendment of result.amendments ?? []) {
|
|
875
|
+
lines.push(`Amendment: ${amendment.accession_number}, filed ${amendment.filing_date}, ${amendment.amendment_type}${amendment.amendment_type === 'UNAVAILABLE' ? ` (${amendment.unavailable_reason})` : ''} — applied as ${amendment.applied_as}${amendment.applied_as === 'not_applied' ? '; inspect with secedgar_get_filing' : ''}.`);
|
|
876
|
+
}
|
|
877
|
+
if (result.amendment_search_complete !== undefined)
|
|
878
|
+
lines.push(result.amendment_search_complete
|
|
879
|
+
? 'Amendment discovery complete within submissions coverage.'
|
|
880
|
+
: 'Amendment discovery incomplete; additional amendments may exist.');
|
|
569
881
|
if (result.next_offset !== undefined) {
|
|
570
882
|
lines.push(`Next offset: ${result.next_offset} — pass as offset to read the next page.`);
|
|
571
883
|
}
|
|
@@ -582,7 +894,7 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
582
894
|
const classStr = h.title_of_class ? ` (${h.title_of_class})` : '';
|
|
583
895
|
const discStr = h.investment_discretion ? ` | discretion: ${h.investment_discretion}` : '';
|
|
584
896
|
lines.push(`**${h.issuer_name}**${classStr}${cusipStr}${putCallStr}`);
|
|
585
|
-
lines.push(`${sharesStr} | ${valueStr}${discStr}`);
|
|
897
|
+
lines.push(`${sharesStr} | ${valueStr}${discStr} | source: ${h.source_accession_numbers.join(', ')}`);
|
|
586
898
|
}
|
|
587
899
|
if (result.dataset) {
|
|
588
900
|
const note = result.dataset.row_count > result.holdings.length
|
|
@@ -593,4 +905,8 @@ export const getInstitutionalHoldingsTool = tool('secedgar_get_institutional_hol
|
|
|
593
905
|
return [{ type: 'text', text: lines.join('\n') }];
|
|
594
906
|
},
|
|
595
907
|
});
|
|
908
|
+
/** `secedgar_get_institutional_holdings` as this deployment's `EDGAR_CLAMP_OVERSIZED_LIMITS` builds it. */
|
|
909
|
+
export function createGetInstitutionalHoldingsTool(options) {
|
|
910
|
+
return withLimitClamps(getInstitutionalHoldingsTool, [holdingsLimit], options);
|
|
911
|
+
}
|
|
596
912
|
//# sourceMappingURL=get-institutional-holdings.tool.js.map
|