@cyanheads/secedgar-mcp-server 0.18.1 → 0.19.1

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 (141) hide show
  1. package/AGENTS.md +36 -24
  2. package/CLAUDE.md +36 -24
  3. package/README.md +16 -12
  4. package/changelog/0.19.x/0.19.0.md +47 -0
  5. package/changelog/0.19.x/0.19.1.md +35 -0
  6. package/changelog/template.md +10 -3
  7. package/dist/config/server-config.js +2 -2
  8. package/dist/config/server-config.js.map +1 -1
  9. package/dist/index.js +27 -9
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
  12. package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
  13. package/dist/mcp-server/tools/dataset-schema.js +16 -0
  14. package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
  15. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
  16. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
  18. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
  20. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
  22. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
  24. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
  26. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
  28. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
  30. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
  32. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
  34. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
  36. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
  38. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  39. package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
  40. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  41. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
  42. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
  44. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
  46. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
  48. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
  50. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
  51. package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
  52. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  53. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
  54. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  55. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
  56. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  57. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
  58. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  59. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
  60. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  61. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
  62. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  63. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
  64. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  65. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
  66. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  67. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
  68. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  69. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
  70. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
  71. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
  72. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
  73. package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
  74. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  75. package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
  76. package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
  77. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
  78. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  79. package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
  80. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  81. package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
  82. package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
  83. package/dist/mcp-server/tools/resolved-as.js +13 -0
  84. package/dist/mcp-server/tools/resolved-as.js.map +1 -0
  85. package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
  86. package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
  87. package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
  88. package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
  89. package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
  90. package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
  91. package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
  92. package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
  93. package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
  94. package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
  95. package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
  96. package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
  97. package/dist/services/edgar/concept-map.d.ts +10 -6
  98. package/dist/services/edgar/concept-map.d.ts.map +1 -1
  99. package/dist/services/edgar/concept-map.js +90 -22
  100. package/dist/services/edgar/concept-map.js.map +1 -1
  101. package/dist/services/edgar/data/former-tickers.json +24159 -0
  102. package/dist/services/edgar/edgar-api-service.d.ts +250 -62
  103. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  104. package/dist/services/edgar/edgar-api-service.js +808 -189
  105. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  106. package/dist/services/edgar/filing-to-text.d.ts +71 -2
  107. package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
  108. package/dist/services/edgar/filing-to-text.js +533 -5
  109. package/dist/services/edgar/filing-to-text.js.map +1 -1
  110. package/dist/services/edgar/former-tickers.d.ts +47 -0
  111. package/dist/services/edgar/former-tickers.d.ts.map +1 -0
  112. package/dist/services/edgar/former-tickers.js +77 -0
  113. package/dist/services/edgar/former-tickers.js.map +1 -0
  114. package/dist/services/edgar/listing-codes.d.ts +47 -0
  115. package/dist/services/edgar/listing-codes.d.ts.map +1 -0
  116. package/dist/services/edgar/listing-codes.js +110 -0
  117. package/dist/services/edgar/listing-codes.js.map +1 -0
  118. package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
  119. package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
  120. package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
  121. package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
  122. package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
  123. package/dist/services/edgar/mirror/tickers-sync.js +1 -3
  124. package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
  125. package/dist/services/edgar/mirror/types.d.ts +3 -1
  126. package/dist/services/edgar/mirror/types.d.ts.map +1 -1
  127. package/dist/services/edgar/mirror/types.js +3 -1
  128. package/dist/services/edgar/mirror/types.js.map +1 -1
  129. package/dist/services/edgar/trigram-similarity.d.ts +5 -3
  130. package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
  131. package/dist/services/edgar/trigram-similarity.js +18 -17
  132. package/dist/services/edgar/trigram-similarity.js.map +1 -1
  133. package/dist/services/edgar/types.d.ts +20 -7
  134. package/dist/services/edgar/types.d.ts.map +1 -1
  135. package/package.json +6 -5
  136. package/server.json +3 -3
  137. package/skills/secedgar-guide/SKILL.md +3 -3
  138. package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
  139. package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
  140. package/dist/mcp-server/tools/escape-inline.js +0 -51
  141. package/dist/mcp-server/tools/escape-inline.js.map +0 -1
@@ -52,6 +52,12 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
52
52
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
53
53
  readonly when: "The DataCanvas service is not configured for this deployment";
54
54
  readonly recovery: "Dataframes need the DuckDB canvas. On an npm or Docker install, set CANVAS_PROVIDER_TYPE=duckdb (the default when unset) and restart the server; the MCPB bundle ships without DuckDB, so there the data tools return their results inline and stage no dataframe.";
55
+ }, {
56
+ readonly reason: "listing_unavailable";
57
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Forbidden;
58
+ readonly when: "name is omitted or empty over HTTP with auth none, where every caller shares one canvas";
59
+ readonly recovery: "Pass the exact df_XXXXX_XXXXX name the producing tool returned in its `dataset` field, or the register_as name you chose; this deployment does not list dataframes.";
60
+ readonly severity: "notice";
55
61
  }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
56
62
  company: import("zod").ZodString;
57
63
  quarter: import("zod").ZodOptional<import("zod").ZodString>;
@@ -148,31 +154,39 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
148
154
  readonly when: "The 13F-HR filing was found but the information table XML document could not be located";
149
155
  readonly recovery: "Use secedgar_get_filing with the accession number to inspect the filing documents directly.";
150
156
  }, {
151
- readonly reason: "rate_limited";
157
+ readonly reason: 'rate_limited';
152
158
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
153
159
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
154
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
160
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
155
161
  readonly retryable: true;
156
- readonly thrownBy: "service";
162
+ readonly thrownBy: 'service';
157
163
  }, {
158
- readonly reason: "sec_unreachable";
164
+ readonly reason: 'sec_unreachable';
159
165
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
160
166
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
161
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
167
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
162
168
  readonly retryable: true;
163
- readonly thrownBy: "service";
169
+ readonly thrownBy: 'service';
164
170
  }, {
165
- readonly reason: "efts_degraded_response";
171
+ readonly reason: 'sec_unavailable';
166
172
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
167
- readonly when: "EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list";
168
- readonly recovery: "Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.";
173
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
174
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
169
175
  readonly retryable: true;
170
- readonly thrownBy: "service";
176
+ readonly thrownBy: 'service';
177
+ }, {
178
+ readonly reason: 'efts_degraded_response';
179
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
180
+ readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
181
+ readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
182
+ readonly retryable: true;
183
+ readonly thrownBy: 'service';
171
184
  }], {
172
185
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
173
186
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
174
187
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
175
188
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
189
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
176
190
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
177
191
  query: import("zod").ZodString;
178
192
  include_filings: import("zod").ZodDefault<import("zod").ZodBoolean>;
@@ -210,7 +224,7 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
210
224
  }, import("zod/v4/core").$strip>, readonly [{
211
225
  readonly reason: "no_match";
212
226
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
213
- readonly when: "No company matches the query";
227
+ readonly when: "No company matches the query in SEC's ticker file, the former names it records, or EDGAR's entity index of every filer";
214
228
  readonly recovery: "SEC's ticker index reflects the filer's own submissions record, which can differ from the exchange-listed symbol. ETFs and mutual funds resolve only by ticker (e.g. \"VOO\"); operating companies also resolve by full legal name or 10-digit CIK.";
215
229
  }, {
216
230
  readonly reason: "ambiguous_company";
@@ -218,24 +232,39 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
218
232
  readonly when: "The company input resolves to multiple entities and the target is ambiguous";
219
233
  readonly recovery: "Use a ticker symbol or 10-digit CIK from the matches list for an exact match.";
220
234
  }, {
221
- readonly reason: "rate_limited";
235
+ readonly reason: 'rate_limited';
222
236
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
223
237
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
224
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
238
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
225
239
  readonly retryable: true;
226
- readonly thrownBy: "service";
240
+ readonly thrownBy: 'service';
227
241
  }, {
228
- readonly reason: "sec_unreachable";
242
+ readonly reason: 'sec_unreachable';
229
243
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
230
244
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
231
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
245
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
232
246
  readonly retryable: true;
233
- readonly thrownBy: "service";
247
+ readonly thrownBy: 'service';
248
+ }, {
249
+ readonly reason: 'sec_unavailable';
250
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
251
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
252
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
253
+ readonly retryable: true;
254
+ readonly thrownBy: 'service';
255
+ }, {
256
+ readonly reason: 'efts_degraded_response';
257
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
258
+ readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
259
+ readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
260
+ readonly retryable: true;
261
+ readonly thrownBy: 'service';
234
262
  }], {
235
263
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
236
264
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
237
265
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
238
266
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
267
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
239
268
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
240
269
  query: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"">, import("zod").ZodString]>>;
241
270
  forms: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -304,6 +333,12 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
304
333
  readonly when: "A cik: targeting token in the query is not a 1-10 digit number";
305
334
  readonly recovery: "Pass a numeric CIK such as cik:320193 — find it with secedgar_company_search if unknown.";
306
335
  readonly thrownBy: "service";
336
+ }, {
337
+ readonly reason: "unsupported_entity_scope";
338
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
339
+ readonly when: "A ticker: or cik: token in the query is led by - or a NOT term, or follows another entity token";
340
+ readonly recovery: "Keep one ticker: or cik: token as its own term with no - or NOT before it. To leave a company out, drop the token and skip the result rows whose cik is that company's.";
341
+ readonly thrownBy: "service";
307
342
  }, {
308
343
  readonly reason: "entity_not_found";
309
344
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
@@ -327,26 +362,33 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
327
362
  readonly recovery: "Use an offset of 9900 or less — a page there with limit 100 reaches EDGAR's 10,000-document cap — or narrow the search with a shorter filed_after/filed_before window, a forms filter, or more specific terms so fewer documents match.";
328
363
  readonly retryable: false;
329
364
  }, {
330
- readonly reason: "rate_limited";
365
+ readonly reason: 'rate_limited';
331
366
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
332
367
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
333
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
368
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
334
369
  readonly retryable: true;
335
- readonly thrownBy: "service";
370
+ readonly thrownBy: 'service';
336
371
  }, {
337
- readonly reason: "sec_unreachable";
372
+ readonly reason: 'sec_unreachable';
338
373
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
339
374
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
340
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
375
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
341
376
  readonly retryable: true;
342
- readonly thrownBy: "service";
377
+ readonly thrownBy: 'service';
343
378
  }, {
344
- readonly reason: "efts_degraded_response";
379
+ readonly reason: 'sec_unavailable';
345
380
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
346
- readonly when: "EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list";
347
- readonly recovery: "Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.";
381
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
382
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
348
383
  readonly retryable: true;
349
- readonly thrownBy: "service";
384
+ readonly thrownBy: 'service';
385
+ }, {
386
+ readonly reason: 'efts_degraded_response';
387
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
388
+ readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
389
+ readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
390
+ readonly retryable: true;
391
+ readonly thrownBy: 'service';
350
392
  }], {
351
393
  readonly effectiveQuery: import("zod").ZodString;
352
394
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
@@ -361,6 +403,7 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
361
403
  include_xbrl: import("zod").ZodDefault<import("zod").ZodBoolean>;
362
404
  offset: import("zod").ZodDefault<import("zod").ZodNumber>;
363
405
  section: import("zod").ZodOptional<import("zod").ZodString>;
406
+ find: import("zod").ZodOptional<import("zod").ZodString>;
364
407
  }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
365
408
  accession_number: import("zod").ZodString;
366
409
  form: import("zod").ZodOptional<import("zod").ZodString>;
@@ -408,6 +451,11 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
408
451
  heading: import("zod").ZodString;
409
452
  offset: import("zod").ZodNumber;
410
453
  }, import("zod/v4/core").$strip>>>;
454
+ occurrences: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
455
+ offset: import("zod").ZodNumber;
456
+ context: import("zod").ZodString;
457
+ }, import("zod/v4/core").$strip>>>;
458
+ occurrences_total: import("zod").ZodOptional<import("zod").ZodNumber>;
411
459
  filing_url: import("zod").ZodString;
412
460
  }, import("zod/v4/core").$strip>, readonly [{
413
461
  readonly reason: "document_not_found";
@@ -438,21 +486,33 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
438
486
  readonly reason: "section_not_found";
439
487
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
440
488
  readonly when: "The section string matched no detected heading and no line of the document";
441
- readonly recovery: "Pick a heading from the outline in the error message, pass a subheading exactly as the document prints it, or use offset paging instead.";
489
+ readonly recovery: "Pick a heading from the outline in the error message or pass a subheading exactly as the document prints it; pass a phrase that is not a heading as find, or page with offset.";
442
490
  }, {
443
- readonly reason: "rate_limited";
491
+ readonly reason: "phrase_not_found";
492
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
493
+ readonly when: "No occurrence of the find phrase starts at or after offset: the document does not contain it, or holds it only before offset";
494
+ readonly recovery: "Check the phrase against the document text, or pass a smaller offset to search from earlier in the document.";
495
+ }, {
496
+ readonly reason: 'rate_limited';
444
497
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
445
498
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
446
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
499
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
447
500
  readonly retryable: true;
448
- readonly thrownBy: "service";
501
+ readonly thrownBy: 'service';
449
502
  }, {
450
- readonly reason: "sec_unreachable";
503
+ readonly reason: 'sec_unreachable';
451
504
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
452
505
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
453
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
506
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
454
507
  readonly retryable: true;
455
- readonly thrownBy: "service";
508
+ readonly thrownBy: 'service';
509
+ }, {
510
+ readonly reason: 'sec_unavailable';
511
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
512
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
513
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
514
+ readonly retryable: true;
515
+ readonly thrownBy: 'service';
456
516
  }], {
457
517
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
458
518
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
@@ -535,24 +595,32 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
535
595
  readonly when: "The unit input names a unit the resolved concept is not reported in for this company";
536
596
  readonly recovery: "Pass one of the units the error lists, or omit unit to read the default series.";
537
597
  }, {
538
- readonly reason: "rate_limited";
598
+ readonly reason: 'rate_limited';
539
599
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
540
600
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
541
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
601
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
542
602
  readonly retryable: true;
543
- readonly thrownBy: "service";
603
+ readonly thrownBy: 'service';
544
604
  }, {
545
- readonly reason: "sec_unreachable";
605
+ readonly reason: 'sec_unreachable';
546
606
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
547
607
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
548
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
608
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
549
609
  readonly retryable: true;
550
- readonly thrownBy: "service";
610
+ readonly thrownBy: 'service';
611
+ }, {
612
+ readonly reason: 'sec_unavailable';
613
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
614
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
615
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
616
+ readonly retryable: true;
617
+ readonly thrownBy: 'service';
551
618
  }], {
552
619
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
553
620
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
554
621
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
555
622
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
623
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
556
624
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
557
625
  company: import("zod").ZodString;
558
626
  taxonomy: import("zod").ZodDefault<import("zod").ZodEnum<{
@@ -626,20 +694,29 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
626
694
  readonly when: "The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant";
627
695
  readonly recovery: "Check the filer files XBRL financial statements, or read the filings directly with secedgar_search_filings.";
628
696
  }, {
629
- readonly reason: "rate_limited";
697
+ readonly reason: 'rate_limited';
630
698
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
631
699
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
632
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
700
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
633
701
  readonly retryable: true;
634
- readonly thrownBy: "service";
702
+ readonly thrownBy: 'service';
635
703
  }, {
636
- readonly reason: "sec_unreachable";
704
+ readonly reason: 'sec_unreachable';
637
705
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
638
706
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
639
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
707
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
640
708
  readonly retryable: true;
641
- readonly thrownBy: "service";
642
- }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
709
+ readonly thrownBy: 'service';
710
+ }, {
711
+ readonly reason: 'sec_unavailable';
712
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
713
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
714
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
715
+ readonly retryable: true;
716
+ readonly thrownBy: 'service';
717
+ }], {
718
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
719
+ }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
643
720
  company: import("zod").ZodString;
644
721
  items: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
645
722
  [x: string]: string;
@@ -688,24 +765,32 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
688
765
  readonly when: "The company input resolves to multiple entities and the target is ambiguous";
689
766
  readonly recovery: "Use a ticker symbol or 10-digit CIK from the matches list for an exact match.";
690
767
  }, {
691
- readonly reason: "rate_limited";
768
+ readonly reason: 'rate_limited';
692
769
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
693
770
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
694
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
771
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
695
772
  readonly retryable: true;
696
- readonly thrownBy: "service";
773
+ readonly thrownBy: 'service';
697
774
  }, {
698
- readonly reason: "sec_unreachable";
775
+ readonly reason: 'sec_unreachable';
699
776
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
700
777
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
701
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
778
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
702
779
  readonly retryable: true;
703
- readonly thrownBy: "service";
780
+ readonly thrownBy: 'service';
781
+ }, {
782
+ readonly reason: 'sec_unavailable';
783
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
784
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
785
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
786
+ readonly retryable: true;
787
+ readonly thrownBy: 'service';
704
788
  }], {
705
789
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
706
790
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
707
791
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
708
792
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
793
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
709
794
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
710
795
  company: import("zod").ZodString;
711
796
  transaction_type: import("zod").ZodDefault<import("zod").ZodEnum<{
@@ -769,24 +854,32 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
769
854
  readonly when: "A call without a date window finds no Form 4 filings in the recent submissions window";
770
855
  readonly recovery: "Pass filed_after / filed_before to read an older period, or use secedgar_search_filings with forms=[\"4\"] to find the filings.";
771
856
  }, {
772
- readonly reason: "rate_limited";
857
+ readonly reason: 'rate_limited';
773
858
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
774
859
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
775
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
860
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
776
861
  readonly retryable: true;
777
- readonly thrownBy: "service";
862
+ readonly thrownBy: 'service';
778
863
  }, {
779
- readonly reason: "sec_unreachable";
864
+ readonly reason: 'sec_unreachable';
780
865
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
781
866
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
782
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
867
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
783
868
  readonly retryable: true;
784
- readonly thrownBy: "service";
869
+ readonly thrownBy: 'service';
870
+ }, {
871
+ readonly reason: 'sec_unavailable';
872
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
873
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
874
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
875
+ readonly retryable: true;
876
+ readonly thrownBy: 'service';
785
877
  }], {
786
878
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
787
879
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
788
880
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
789
881
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
882
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
790
883
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
791
884
  issuer: import("zod").ZodString;
792
885
  cusip: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"">, import("zod").ZodString]>>;
@@ -832,32 +925,40 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
832
925
  readonly when: "The issuer name matches several EDGAR companies and no cusip was given";
833
926
  readonly recovery: "Retry with the ticker or the 10-digit CIK of the intended issuer from the matches list.";
834
927
  }, {
835
- readonly reason: "rate_limited";
928
+ readonly reason: 'rate_limited';
836
929
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
837
930
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
838
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
931
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
839
932
  readonly retryable: true;
840
- readonly thrownBy: "service";
933
+ readonly thrownBy: 'service';
841
934
  }, {
842
- readonly reason: "sec_unreachable";
935
+ readonly reason: 'sec_unreachable';
843
936
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
844
937
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
845
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
938
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
846
939
  readonly retryable: true;
847
- readonly thrownBy: "service";
940
+ readonly thrownBy: 'service';
848
941
  }, {
849
- readonly reason: "efts_degraded_response";
942
+ readonly reason: 'sec_unavailable';
850
943
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
851
- readonly when: "EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list";
852
- readonly recovery: "Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.";
944
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
945
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
853
946
  readonly retryable: true;
854
- readonly thrownBy: "service";
947
+ readonly thrownBy: 'service';
948
+ }, {
949
+ readonly reason: 'efts_degraded_response';
950
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
951
+ readonly when: 'EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list';
952
+ readonly recovery: 'Retry the same call in a minute unless the error is marked not retryable; then change the request as upstreamErrorMessage indicates.';
953
+ readonly retryable: true;
954
+ readonly thrownBy: 'service';
855
955
  }], {
856
956
  readonly ordering: import("zod").ZodString;
857
957
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
858
958
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
859
959
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
860
960
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
961
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
861
962
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
862
963
  issuer: import("zod").ZodString;
863
964
  form_kind: import("zod").ZodDefault<import("zod").ZodEnum<{
@@ -944,24 +1045,32 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
944
1045
  readonly when: "The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind";
945
1046
  readonly recovery: "Use secedgar_search_filings with forms [\"SC 13D\",\"SC 13G\"] to reach the pre-2024-12-18 text filings, then read them with secedgar_get_filing.";
946
1047
  }, {
947
- readonly reason: "rate_limited";
1048
+ readonly reason: 'rate_limited';
948
1049
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
949
1050
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
950
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
1051
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
951
1052
  readonly retryable: true;
952
- readonly thrownBy: "service";
1053
+ readonly thrownBy: 'service';
953
1054
  }, {
954
- readonly reason: "sec_unreachable";
1055
+ readonly reason: 'sec_unreachable';
955
1056
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
956
1057
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
957
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
1058
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
958
1059
  readonly retryable: true;
959
- readonly thrownBy: "service";
1060
+ readonly thrownBy: 'service';
1061
+ }, {
1062
+ readonly reason: 'sec_unavailable';
1063
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1064
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
1065
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
1066
+ readonly retryable: true;
1067
+ readonly thrownBy: 'service';
960
1068
  }], {
961
1069
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
962
1070
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
963
1071
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
964
1072
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
1073
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
965
1074
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
966
1075
  fund: import("zod").ZodString;
967
1076
  series_id: import("zod").ZodOptional<import("zod").ZodString>;
@@ -1031,25 +1140,33 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1031
1140
  readonly when: "No NPORT-P report exists for this fund, or none covers the report_date requested";
1032
1141
  readonly recovery: "Drop report_date to take the newest report, or use secedgar_search_filings with forms [\"NPORT-P\"] to see what the registrant has filed.";
1033
1142
  }, {
1034
- readonly reason: "rate_limited";
1143
+ readonly reason: 'rate_limited';
1035
1144
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
1036
1145
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
1037
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
1146
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
1038
1147
  readonly retryable: true;
1039
- readonly thrownBy: "service";
1148
+ readonly thrownBy: 'service';
1040
1149
  }, {
1041
- readonly reason: "sec_unreachable";
1150
+ readonly reason: 'sec_unreachable';
1042
1151
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1043
1152
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
1044
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
1153
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
1045
1154
  readonly retryable: true;
1046
- readonly thrownBy: "service";
1155
+ readonly thrownBy: 'service';
1156
+ }, {
1157
+ readonly reason: 'sec_unavailable';
1158
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1159
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
1160
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
1161
+ readonly retryable: true;
1162
+ readonly thrownBy: 'service';
1047
1163
  }], {
1048
1164
  readonly as_of: import("zod").ZodString;
1049
1165
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
1050
1166
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
1051
1167
  readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
1052
1168
  readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
1169
+ readonly resolvedAs: import("zod").ZodOptional<import("zod").ZodString>;
1053
1170
  }> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
1054
1171
  concept: import("zod").ZodString;
1055
1172
  taxonomy: import("zod").ZodDefault<import("zod").ZodEnum<{
@@ -1121,19 +1238,26 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1121
1238
  readonly when: "Concept resolves but no companies report the tag this call read for the requested period and unit";
1122
1239
  readonly recovery: "Check duration vs. instant period and the unit, then query each tag the error lists in unqueried_tags — a tag has frames only for the periods filers reported it in, so another tag the concept maps to can cover a period this one lacks.";
1123
1240
  }, {
1124
- readonly reason: "rate_limited";
1241
+ readonly reason: 'rate_limited';
1125
1242
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
1126
1243
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
1127
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
1244
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
1128
1245
  readonly retryable: true;
1129
- readonly thrownBy: "service";
1246
+ readonly thrownBy: 'service';
1130
1247
  }, {
1131
- readonly reason: "sec_unreachable";
1248
+ readonly reason: 'sec_unreachable';
1132
1249
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1133
1250
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
1134
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
1251
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
1135
1252
  readonly retryable: true;
1136
- readonly thrownBy: "service";
1253
+ readonly thrownBy: 'service';
1254
+ }, {
1255
+ readonly reason: 'sec_unavailable';
1256
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1257
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
1258
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
1259
+ readonly retryable: true;
1260
+ readonly thrownBy: 'service';
1137
1261
  }], {
1138
1262
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
1139
1263
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
@@ -1224,19 +1348,26 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1224
1348
  readonly when: "Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent";
1225
1349
  readonly recovery: "Use a friendly name from secedgar_search_concepts or a valid raw XBRL tag.";
1226
1350
  }, {
1227
- readonly reason: "rate_limited";
1351
+ readonly reason: 'rate_limited';
1228
1352
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
1229
1353
  readonly when: "SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs";
1230
- readonly recovery: "Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.";
1354
+ readonly recovery: 'Wait the retryAfter seconds the error carries, then retry — SEC lifts the block only once requests stop for ten minutes.';
1231
1355
  readonly retryable: true;
1232
- readonly thrownBy: "service";
1356
+ readonly thrownBy: 'service';
1233
1357
  }, {
1234
- readonly reason: "sec_unreachable";
1358
+ readonly reason: 'sec_unreachable';
1235
1359
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1236
1360
  readonly when: "SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent";
1237
- readonly recovery: "Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.";
1361
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR did not deliver a complete, readable response, and nothing in the request needs to change.';
1238
1362
  readonly retryable: true;
1239
- readonly thrownBy: "service";
1363
+ readonly thrownBy: 'service';
1364
+ }, {
1365
+ readonly reason: 'sec_unavailable';
1366
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
1367
+ readonly when: "SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out)";
1368
+ readonly recovery: 'Retry the same call in a minute — SEC EDGAR failed on its side, and nothing in the request needs to change.';
1369
+ readonly retryable: true;
1370
+ readonly thrownBy: 'service';
1240
1371
  }], {
1241
1372
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
1242
1373
  readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
@@ -1303,14 +1434,14 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1303
1434
  }, {
1304
1435
  readonly reason: "system_catalog_access";
1305
1436
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
1306
- readonly when: "The SQL query references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*)";
1307
- readonly recovery: "Query only df_<id> tables. Use secedgar_dataframe_describe to list available dataframes.";
1437
+ readonly when: "The SQL query references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*), or names a column alias, table alias, or CTE spelled like one";
1438
+ readonly recovery: "Query only the df_<id> tables, by the name the producing tool returned in its `dataset` field; a column alias, table alias, or CTE named like a DuckDB metadata view (the name the message gives) is refused too, so rename it.";
1308
1439
  readonly thrownBy: "service";
1309
1440
  }, {
1310
1441
  readonly reason: "missing_table";
1311
1442
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
1312
1443
  readonly when: "The SQL query references a df_<id> table that does not exist or has expired";
1313
- readonly recovery: "Use secedgar_dataframe_describe to list available dataframes and verify the table name.";
1444
+ readonly recovery: "Reference the df_<id> name the producing tool returned in its `dataset` field, or a register_as name, and re-run that tool if the table expired. secedgar_dataframe_describe without a name lists the active dataframes, except over HTTP with auth none, where that listing is refused.";
1314
1445
  readonly thrownBy: "service";
1315
1446
  }, {
1316
1447
  readonly reason: "invalid_sql";
@@ -1334,7 +1465,7 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1334
1465
  readonly reason: "non_select_statement";
1335
1466
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
1336
1467
  readonly when: "The SQL is not a SELECT (DROP, INSERT, UPDATE, DDL, PRAGMA, EXPLAIN, etc.) or does not parse — only read-only SELECTs run against dataframes";
1337
- readonly recovery: "Query only SELECT statements against df_<id> tables. Use secedgar_dataframe_describe to inspect available dataframes.";
1468
+ readonly recovery: "Rewrite as one read-only SELECT over the df_<id> tables; writes, DDL, and other statements that are not a SELECT are refused.";
1338
1469
  readonly thrownBy: "service";
1339
1470
  }, {
1340
1471
  readonly reason: "multi_statement";
@@ -1346,19 +1477,19 @@ export declare function buildToolDefinitions(options: ToolDefinitionOptions): (i
1346
1477
  readonly reason: "denied_function";
1347
1478
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
1348
1479
  readonly when: "The SQL calls a file-reading or external-data table function (read_csv, read_parquet, glob), a function that reads an engine setting (current_setting, current_schema — an unqualified current_schema is refused even where it names a column, which reads qualified as <table>.current_schema), or one that runs SQL or names a table from a string (query_table, or query() over anything but a single string literal)";
1349
- readonly recovery: "Remove the function the message names, or qualify a column it names with its table, and query only the df_<id> tables secedgar_dataframe_describe lists.";
1480
+ readonly recovery: "Remove the function the message names, or qualify a column it names with its table, and query only the df_<id> tables the data tools returned.";
1350
1481
  readonly thrownBy: "service";
1351
1482
  }, {
1352
1483
  readonly reason: "sql_read_only";
1353
1484
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
1354
1485
  readonly when: "The SQL names a file as a table (FROM 'data.csv') — the dataframe engine reads no files";
1355
- readonly recovery: "Query only the df_<id> tables secedgar_dataframe_describe lists, referenced by bare name.";
1486
+ readonly recovery: "Query only the df_<id> tables, by the name the producing tool returned in its `dataset` field, referenced by bare name; this surface reads no files and cannot create, alter, or drop anything.";
1356
1487
  readonly thrownBy: "service";
1357
1488
  }, {
1358
1489
  readonly reason: "plan_operator_not_allowed";
1359
1490
  readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
1360
- readonly when: "The query plan uses an operator outside the read-only allowlist, such as the range() or generate_series() table functions";
1361
- readonly recovery: "Rewrite with read-only SELECT constructs — joins, aggregates, window functions, CTEs, and unnest() are supported.";
1491
+ readonly when: "The query plan uses an operator outside the read-only allowlist, such as range() or generate_series() given a column or subquery argument instead of constants";
1492
+ readonly recovery: "Rewrite with read-only SELECT constructs — joins, aggregates, window functions, CTEs, unnest(), and range() or generate_series() over constant arguments are supported.";
1362
1493
  readonly thrownBy: "service";
1363
1494
  }], {
1364
1495
  readonly notice: import("zod").ZodOptional<import("zod").ZodString>;