@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.
Files changed (97) hide show
  1. package/AGENTS.md +14 -9
  2. package/CLAUDE.md +14 -9
  3. package/README.md +21 -16
  4. package/changelog/0.15.x/0.15.15.md +24 -0
  5. package/changelog/0.16.x/0.16.0.md +34 -0
  6. package/dist/config/server-config.d.ts +14 -0
  7. package/dist/config/server-config.d.ts.map +1 -1
  8. package/dist/config/server-config.js +38 -13
  9. package/dist/config/server-config.js.map +1 -1
  10. package/dist/index.js +16 -8
  11. package/dist/index.js.map +1 -1
  12. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +66 -0
  13. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  14. package/dist/mcp-server/tools/definitions/company-search.tool.js +24 -13
  15. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +104 -0
  17. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +21 -11
  19. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +87 -2
  21. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +41 -25
  23. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +92 -0
  25. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  26. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +20 -4
  27. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  28. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +67 -0
  29. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/find-holders.tool.js +61 -31
  31. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +119 -3
  33. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +101 -36
  35. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +108 -0
  37. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-filing.tool.js +19 -9
  39. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-financials.tool.js +1 -1
  41. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +91 -0
  43. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +25 -17
  45. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +79 -0
  47. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  48. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +34 -18
  49. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  50. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +153 -1
  51. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +403 -87
  53. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +70 -0
  55. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  56. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +27 -15
  57. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  58. package/dist/mcp-server/tools/definitions/index.d.ts +594 -544
  59. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  60. package/dist/mcp-server/tools/definitions/index.js +24 -24
  61. package/dist/mcp-server/tools/definitions/index.js.map +1 -1
  62. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +101 -0
  63. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  64. package/dist/mcp-server/tools/definitions/search-filings.tool.js +48 -29
  65. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  66. package/dist/mcp-server/tools/fixed-point.d.ts +7 -0
  67. package/dist/mcp-server/tools/fixed-point.d.ts.map +1 -0
  68. package/dist/mcp-server/tools/fixed-point.js +28 -0
  69. package/dist/mcp-server/tools/fixed-point.js.map +1 -0
  70. package/dist/mcp-server/tools/form-filter.d.ts +13 -0
  71. package/dist/mcp-server/tools/form-filter.d.ts.map +1 -0
  72. package/dist/mcp-server/tools/form-filter.js +16 -0
  73. package/dist/mcp-server/tools/form-filter.js.map +1 -0
  74. package/dist/mcp-server/tools/limit-clamp.d.ts +65 -0
  75. package/dist/mcp-server/tools/limit-clamp.d.ts.map +1 -0
  76. package/dist/mcp-server/tools/limit-clamp.js +78 -0
  77. package/dist/mcp-server/tools/limit-clamp.js.map +1 -0
  78. package/dist/services/edgar/concept-series.d.ts.map +1 -1
  79. package/dist/services/edgar/concept-series.js +5 -1
  80. package/dist/services/edgar/concept-series.js.map +1 -1
  81. package/dist/services/edgar/edgar-api-service.d.ts +18 -8
  82. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  83. package/dist/services/edgar/edgar-api-service.js +149 -32
  84. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  85. package/dist/services/edgar/nport-parser.js +1 -1
  86. package/dist/services/edgar/nport-parser.js.map +1 -1
  87. package/dist/services/edgar/ownership-parser.d.ts +2 -0
  88. package/dist/services/edgar/ownership-parser.d.ts.map +1 -1
  89. package/dist/services/edgar/ownership-parser.js +4 -0
  90. package/dist/services/edgar/ownership-parser.js.map +1 -1
  91. package/dist/services/edgar/same-cik.d.ts +7 -0
  92. package/dist/services/edgar/same-cik.d.ts.map +1 -0
  93. package/dist/services/edgar/same-cik.js +9 -0
  94. package/dist/services/edgar/same-cik.js.map +1 -0
  95. package/dist/services/edgar/types.d.ts +3 -3
  96. package/package.json +7 -6
  97. 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. Institution lookup only — `company` is the 13F filer.
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. Sorted by value descending,
41
- * so a small `limit` returns the largest distinct holdings.
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, { ...r, investment_discretion: undefined });
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
- * Zip a submissions block (the recent window or an archive page) into its 13F-HR and
92
- * 13F-NT rows, in block order — newest filed first. Read off the submissions fetch the
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: 'Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML. company is the institutional filer — its 10-digit CIK (e.g. 0000102909), a ticker, or an entity name (names outside EDGAR\'s ticker file resolve through EDGAR entity search) — and the tool returns what that institution holds. A name that matches several EDGAR filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK, rather than guessing. For the reverse direction — which institutions hold a given portfolio company — use secedgar_find_holders, whose filer_cik results feed straight back into this tool. The 13F information table lists each position: issuer name, CUSIP, shares held, market value (in whole USD), and put/call designation for options. Sub-lines for the same security are consolidated into distinct positions sorted by value by default (set consolidate=false for raw filing rows). The inline holdings list is one page of limit rows starting at offset — pass the returned next_offset to walk further down a large information table. The full parsed holdings set is also materialized as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate the whole filing or self-join across quarters on cusip + reporting_period. Institutions with less than $100M in 13(f) securities are exempt and may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.',
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: z
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('Name of the institutional filer (the 13F submitter).'),
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('Calendar-quarter end this 13F covers (YYYY-MM-DD), from the cover page. Absent when the filing omits it.'),
201
- filing_date: z.string().describe('Date the 13F was submitted (YYYY-MM-DD).'),
202
- accession_number: z
203
- .string()
204
- .describe('Accession number of this 13F-HR — pass to secedgar_get_filing.'),
205
- total_holdings_in_filing: z
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('Raw information-table rows in this filing, before consolidation and limit.'),
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 after consolidating sub-lines, before limit. Present only when consolidate=true.'),
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 (e.g., "COM", "CL A", "ETF"). Absent when not reported.'),
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('Market value in whole USD at the reporting date; values from filings before 2023-01-03, reported in thousands, are scaled to whole USD. Absent when not reported.'),
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 (equities) or principal amount (debt). Absent when not reported.'),
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, PRN principal amount (bonds, notes). Absent when not reported.'),
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 discretion, DFND defined (shared or advised), OTR other. Absent when not reported, and on consolidated positions.'),
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 market value when consolidate=true, else raw rows in filing order.'),
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('Dataframe of every position, shaped by consolidate; rows carry the filer keys and join across quarters on cusip + reporting_period. Absent when canvas is unavailable or there are no holdings.'),
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('Guidance when no filing was found or the result is empty, with alternatives.'),
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
- // Get the filing index to find the information table document
425
- const filingIndex = await api.tryGetFilingIndex(match.cik, filingMeta.accessionNumber, callScope);
426
- if (!filingIndex) {
427
- throw ctx.fail('no_info_table', `Filing ${filingMeta.accessionNumber} index could not be fetched.`);
428
- }
429
- const infoTableDoc = findInfoTableDocument(filingIndex.directory.item);
430
- if (!infoTableDoc) {
431
- throw ctx.fail('no_info_table', `No information table XML found in filing ${filingMeta.accessionNumber}.`, {
432
- accession_number: filingMeta.accessionNumber,
433
- available_documents: filingIndex.directory.item.map((i) => i.name),
434
- });
435
- }
436
- const xmlText = await api.tryGetFilingDocument(match.cik, filingMeta.accessionNumber, infoTableDoc, callScope);
437
- if (!xmlText) {
438
- throw ctx.fail('no_info_table', `Information table document '${infoTableDoc}' could not be fetched.`);
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
- let parsed;
448
- try {
449
- parsed = parseInfoTableXml(xmlText);
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
- catch {
452
- throw ctx.fail('no_info_table', `Failed to parse information table XML for filing ${filingMeta.accessionNumber}.`);
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
- // SEC's 2022 Form 13F amendments (effective 2023-01-03) switched Information Table
455
- // Column 4 from thousands of dollars to whole dollars. Normalize older filings (still
456
- // reported in thousands) up to whole USD using the filing date — the literal compliance
457
- // boundary, and always present (unlike the cover-page reporting period).
458
- const valuesInThousands = filingMeta.filingDate < '2023-01-03';
459
- const toUsd = (v) => v === undefined ? undefined : valuesInThousands ? v * 1000 : v;
460
- const rows = parsed.holdings.map((h) => ({
461
- issuer_name: h.issuer_name,
462
- title_of_class: h.title_of_class,
463
- cusip: h.cusip,
464
- market_value_usd: toUsd(h.value_reported),
465
- shares_or_principal_amount: h.shares_or_principal_amount,
466
- shares_or_principal_type: h.shares_or_principal_type,
467
- put_call: h.put_call,
468
- investment_discretion: h.investment_discretion,
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 + input.limit;
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
- ctx.enrich.notice(`Offset (${input.offset}) is at or past the ${positions.length} positions in this filing. ` +
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
- ctx.enrich.notice(`The information table for this filing contained no holdings rows. ` +
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 (nextOffset !== undefined) {
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: input.limit,
530
- ...(dataset && { guidance: dataframeGuidance(dataset) }),
828
+ cap: limit,
829
+ ...(notices.length > 0 && { guidance: notices.join(' ') }),
531
830
  });
532
831
  }
533
- else if (dataset) {
534
- ctx.enrich.notice(dataframeGuidance(dataset));
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: parsed.holdings.length,
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
- total_holdings_in_filing: parsed.holdings.length,
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.total_holdings_in_filing} info-table rows)`
562
- : `Showing ${result.holdings.length} of ${result.total_holdings_in_filing} info-table rows`;
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