fmp-ai-tools 0.2.4-beta.1 → 0.2.4-beta.2

package/README.md

@@ -339,7 +339,8 @@ Each tool accepts specific parameters. Here are some common ones:
 - `from` - Start date in YYYY-MM-DD format
 - `to` - End date in YYYY-MM-DD format
 - `name` - For economic indicators: specific indicator name
-- `limit` - Max rows returned by tools that wrap large list endpoints (earnings/economic calendars, institutional and ETF holdings, market performance, executive compensation, congressional trades by name; defaults 20–50). Institutional and ETF holdings are sorted largest-first.
+- `limit` - Max rows returned by tools that wrap large list endpoints (earnings/economic calendars, institutional and ETF holdings, market performance, executive compensation, congressional trades by name; defaults 20–50). When rows are cut, the tool returns `{ data, truncated: true, note }` saying how many rows exist. Institutional holders (latest filing per holder from the past year) and ETF holdings (latest filing date by default) are sorted largest-first.
+- `symbols` - `getEarningsCalendar` only: return just these companies (a week can hold ~2,000 worldwide)
 
 ## Error Handling
 

package/dist/providers/openai/index.js

@@ -197,6 +197,20 @@ function limitRows(res, limit2, compare) {
   const rows = compare ? [...res.data].sort(compare) : res.data;
   return { ...res, data: rows.slice(0, limit2) };
 }
+function toCappedToolResponse(res, limit2, options = {}) {
+  const total = res.success !== false && Array.isArray(res.data) ? res.data.length : 0;
+  const capped = limitRows(res, limit2, options.compare);
+  if (total <= limit2) return toToolResponse(capped);
+  return JSON.stringify(
+    {
+      data: capped.data,
+      truncated: true,
+      note: `Showing ${limit2} of ${total} rows. ${options.hint ?? "Increase `limit` to see more."}`
+    },
+    null,
+    2
+  );
+}
 function toToolError(error) {
   const message = error instanceof Error ? error.message : String(error);
   let type = "unknown";
@@ -278,7 +292,7 @@ var quoteDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(30).describe("Max number of most-recent days to return (default 30)")
     }),
-    execute: async ({ symbol: symbol2, from, to, limit: limit2 = 30 }) => {
+    execute: async ({ symbol: symbol2, from, to, limit: limit2 }) => {
       const res = await getFMPClient().quote.getHistoricalPrice({
         symbol: symbol2,
         from: from ?? void 0,
@@ -288,7 +302,7 @@ var quoteDefinitions = [
       if (res.success && data && Array.isArray(data.historical)) {
         return toToolResponse({
           ...res,
-          data: { ...data, historical: data.historical.slice(0, limit2) }
+          data: { ...data, historical: data.historical.slice(0, limit2 ?? 30) }
         });
       }
       return toToolResponse(res);
@@ -304,7 +318,7 @@ var quoteDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of most-recent bars to return (default 50)")
     }),
-    execute: async ({ symbol: symbol2, interval = "5min", from, to, limit: limit2 = 50 }) => {
+    execute: async ({ symbol: symbol2, interval = "5min", from, to, limit: limit2 }) => {
       const res = await getFMPClient().quote.getIntraday({
         symbol: symbol2,
         interval,
@@ -312,7 +326,7 @@ var quoteDefinitions = [
         to: to ?? void 0
       });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 50) });
       }
       return toToolResponse(res);
     }
@@ -340,7 +354,7 @@ var companyDefinitions = [
     inputSchema: symbolSchema.extend({
       limit: zod.z.number().int().positive().default(20).describe("Max number of compensation records to return (default 20)")
     }),
-    execute: async ({ symbol: symbol2, limit: limit2 = 20 }) => toToolResponse(limitRows(await getFMPClient().company.getExecutiveCompensation(symbol2), limit2))
+    execute: async ({ symbol: symbol2, limit: limit2 }) => toCappedToolResponse(await getFMPClient().company.getExecutiveCompensation(symbol2), limit2 ?? 20)
   }),
   defineTool({
     name: "getStockPeers",
@@ -356,7 +370,7 @@ var statementTool = (name, description, what, call) => defineTool({
   name,
   description,
   inputSchema: zod.z.object({ symbol: symbol(what), period, limit }),
-  execute: async ({ symbol: symbol2, period: period2, limit: limit2 }) => toToolResponse(await call({ symbol: symbol2, period: period2, limit: limit2 }))
+  execute: async ({ symbol: symbol2, period: period2, limit: limit2 }) => toToolResponse(await call({ symbol: symbol2, period: period2, limit: limit2 ?? void 0 }))
 });
 var financialDefinitions = [
   statementTool(
@@ -426,7 +440,9 @@ var financialDefinitions = [
       symbol: symbol("earnings historical"),
       limit: zod.z.number().default(10).describe("The number of periods to retrieve")
     }),
-    execute: async ({ symbol: symbol2, limit: limit2 }) => toToolResponse(await getFMPClient().financial.getEarningsHistorical({ symbol: symbol2, limit: limit2 }))
+    execute: async ({ symbol: symbol2, limit: limit2 }) => toToolResponse(
+      await getFMPClient().financial.getEarningsHistorical({ symbol: symbol2, limit: limit2 ?? 10 })
+    )
   }),
   defineTool({
     name: "getFinancialScores",
@@ -471,30 +487,33 @@ var dateRangeSchema = zod.z.object({
 var calendarDefinitions = [
   defineTool({
     name: "getEarningsCalendar",
-    description: "Get earnings calendar showing upcoming and recent earnings announcements (at most `limit` entries; narrow the date range for full coverage)",
-    inputSchema: dateRangeSchema,
-    execute: async ({ from, to, limit: limit2 = 50 }) => toToolResponse(
-      limitRows(
-        await getFMPClient().calendar.getEarningsCalendar({
-          from: from ?? void 0,
-          to: to ?? void 0
-        }),
-        limit2
-      )
-    )
+    description: "Get earnings calendar showing upcoming and recent earnings announcements, in date order. A week can hold ~2,000 companies worldwide, so pass `symbols` to look up specific companies (e.g. mega-cap tech) instead of scanning the whole calendar.",
+    inputSchema: dateRangeSchema.extend({
+      symbols: zod.z.array(zod.z.string().min(1)).optional().nullable().describe('Only return these symbols (e.g., ["AAPL", "MSFT", "NVDA"])')
+    }),
+    execute: async ({ from, to, symbols, limit: limit2 }) => {
+      const res = await getFMPClient().calendar.getEarningsCalendar({
+        from: from ?? void 0,
+        to: to ?? void 0
+      });
+      const wanted = symbols?.length ? new Set(symbols.map((s) => s.toUpperCase())) : null;
+      const filtered = wanted && res.success !== false && Array.isArray(res.data) ? { ...res, data: res.data.filter((row) => wanted.has(row.symbol.toUpperCase())) } : res;
+      return toCappedToolResponse(filtered, limit2 ?? 50, {
+        hint: "Rows are in date order. Pass `symbols` to find specific companies, or narrow the date range."
+      });
+    }
   }),
   defineTool({
     name: "getEconomicCalendar",
-    description: "Get economic calendar showing upcoming and recent economic events and indicators (at most `limit` entries; narrow the date range for full coverage)",
+    description: "Get economic calendar showing upcoming and recent economic events and indicators, in date order (at most `limit` entries; narrow the date range for full coverage)",
     inputSchema: dateRangeSchema,
-    execute: async ({ from, to, limit: limit2 = 50 }) => toToolResponse(
-      limitRows(
-        await getFMPClient().calendar.getEconomicsCalendar({
-          from: from ?? void 0,
-          to: to ?? void 0
-        }),
-        limit2
-      )
+    execute: async ({ from, to, limit: limit2 }) => toCappedToolResponse(
+      await getFMPClient().calendar.getEconomicsCalendar({
+        from: from ?? void 0,
+        to: to ?? void 0
+      }),
+      limit2 ?? 50,
+      { hint: "Rows are in date order; narrow the date range to see the rest." }
     )
   })
 ];
@@ -561,17 +580,29 @@ var etfDefinitions = [
     description: "Get the largest holdings of an ETF (by portfolio weight), showing the underlying assets and their weights",
     inputSchema: zod.z.object({
       symbol: zod.z.string().min(1, "ETF symbol is required").describe("ETF symbol (e.g., SPY, QQQ, VTI)"),
-      date: zod.z.string().optional().nullable().describe("Date for holdings in YYYY-MM-DD format (optional)"),
+      date: zod.z.string().optional().nullable().describe("Holdings date in YYYY-MM-DD format (optional; defaults to the latest filing)"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of holdings to return, largest weight first (default 50)")
     }),
-    execute: async ({ symbol: symbol2, date, limit: limit2 = 50 }) => {
+    execute: async ({ symbol: symbol2, date, limit: limit2 }) => {
+      const client = getFMPClient();
+      let holdingsDate = date ?? void 0;
+      if (!holdingsDate) {
+        const dates = await client.etf.getHoldingDates(symbol2);
+        if (dates.success !== false && Array.isArray(dates.data)) {
+          holdingsDate = dates.data.reduce(
+            (latest, d) => !latest || d.date > latest ? d.date : latest,
+            void 0
+          );
+        }
+      }
       const params = { symbol: symbol2 };
-      if (date) {
-        params.date = date;
+      if (holdingsDate) {
+        params.date = holdingsDate;
       }
-      return toToolResponse(
-        limitRows(await getFMPClient().etf.getHoldings(params), limit2, (a, b) => b.pctVal - a.pctVal)
-      );
+      return toCappedToolResponse(await client.etf.getHoldings(params), limit2 ?? 50, {
+        compare: (a, b) => b.pctVal - a.pctVal,
+        hint: `Largest positions first, as of ${holdingsDate ?? "the requested date"}.`
+      });
     }
   }),
   defineTool({
@@ -594,23 +625,36 @@ var insiderDefinitions = [
     execute: async ({ symbol: symbol2, page }) => toToolResponse(await getFMPClient().insider.getInsiderTradesBySymbol(symbol2, page))
   })
 ];
+var YEAR_MS = 365 * 24 * 60 * 60 * 1e3;
+var holderKey = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\b(inc|corp|corporation|co|llc|ltd|lp|plc|the)\b/g, " ").replace(/\s+/g, " ").trim();
+function currentHolders(rows) {
+  const newest = rows.reduce((max, r) => Math.max(max, Date.parse(r.dateReported) || 0), 0);
+  const latest = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const reported = Date.parse(row.dateReported);
+    if (!(reported >= newest - YEAR_MS)) continue;
+    const key = holderKey(row.holder);
+    const prev = latest.get(key);
+    if (!prev || reported > Date.parse(prev.dateReported)) latest.set(key, row);
+  }
+  return [...latest.values()];
+}
 var institutionalDefinitions = [
   defineTool({
     name: "getInstitutionalHolders",
-    description: "Get the largest institutional holders of a stock (by shares held), showing which institutions own shares and their holdings",
+    description: "Get a stock's largest current institutional holders by shares held (each holder's latest 13F filing from the past year)",
     inputSchema: zod.z.object({
       symbol: zod.z.string().min(1, "Stock symbol is required").describe("Stock symbol (e.g., AAPL, MSFT, GOOGL)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of holders to return, largest first (default 20)")
     }),
-    // FMP returns thousands of holders in no particular order (~1 MB for AAPL),
-    // so sort by shares held and keep the top `limit`.
-    execute: async ({ symbol: symbol2, limit: limit2 = 20 }) => toToolResponse(
-      limitRows(
-        await getFMPClient().institutional.getInstitutionalHolders({ symbol: symbol2 }),
-        limit2,
-        (a, b) => b.shares - a.shares
-      )
-    )
+    execute: async ({ symbol: symbol2, limit: limit2 }) => {
+      const res = await getFMPClient().institutional.getInstitutionalHolders({ symbol: symbol2 });
+      const current = res.success !== false && Array.isArray(res.data) ? { ...res, data: currentHolders(res.data) } : res;
+      return toCappedToolResponse(current, limit2 ?? 20, {
+        compare: (a, b) => b.shares - a.shares,
+        hint: "Holders are ordered by shares held, largest first."
+      });
+    }
   })
 ];
 var empty = zod.z.object({});
@@ -625,7 +669,7 @@ var marketDefinitions = [
     inputSchema: zod.z.object({
       limit: zod.z.number().int().positive().default(50).describe("Max number of indices to return (default 50)")
     }),
-    execute: async ({ limit: limit2 = 50 }) => toToolResponse(limitRows(await getFMPClient().market.getMarketPerformance(), limit2))
+    execute: async ({ limit: limit2 }) => toCappedToolResponse(await getFMPClient().market.getMarketPerformance(), limit2 ?? 50)
   }),
   defineTool({
     name: "getSectorPerformance",
@@ -677,11 +721,11 @@ var newsDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of articles to return (default 20)")
     }),
-    execute: async ({ from, to, limit: limit2 = 20 }) => toToolResponse(
+    execute: async ({ from, to, limit: limit2 }) => toToolResponse(
       await getFMPClient().news.getStockNews({
         from: from ?? void 0,
         to: to ?? void 0,
-        limit: limit2
+        limit: limit2 ?? 20
       })
     )
   }),
@@ -694,12 +738,12 @@ var newsDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of articles to return (default 20)")
     }),
-    execute: async ({ symbols, from, to, limit: limit2 = 20 }) => toToolResponse(
+    execute: async ({ symbols, from, to, limit: limit2 }) => toToolResponse(
       await getFMPClient().news.getStockNewsBySymbol({
         symbols,
         from: from ?? void 0,
         to: to ?? void 0,
-        limit: limit2
+        limit: limit2 ?? 20
       })
     )
   })
@@ -721,8 +765,8 @@ var screenerDefinitions = [
       isActivelyTrading: zod.z.boolean().optional().nullable().describe("Restrict to actively trading"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of results to return (default 50)")
     }),
-    execute: async ({ limit: limit2 = 50, ...filters }) => {
-      const params = { limit: limit2 };
+    execute: async ({ limit: limit2, ...filters }) => {
+      const params = { limit: limit2 ?? 50 };
       for (const [key, value] of Object.entries(filters)) {
         if (value !== null && value !== void 0) params[key] = value;
       }
@@ -739,8 +783,12 @@ var searchDefinitions = [
       limit: zod.z.number().int().positive().default(10).describe("Max number of results to return (default 10)"),
       exchange: zod.z.string().optional().nullable().describe('Restrict to a specific exchange (optional, e.g., "NASDAQ")')
     }),
-    execute: async ({ query, limit: limit2 = 10, exchange }) => toToolResponse(
-      await getFMPClient().search.search({ query, limit: limit2, exchange: exchange ?? void 0 })
+    execute: async ({ query, limit: limit2, exchange }) => toToolResponse(
+      await getFMPClient().search.search({
+        query,
+        limit: limit2 ?? 10,
+        exchange: exchange ?? void 0
+      })
     )
   })
 ];
@@ -753,7 +801,9 @@ var analystDefinitions = [
       period: zod.z.enum(["annual", "quarter"]).default("annual").describe("The period type (annual or quarter)"),
       limit: zod.z.number().int().positive().default(10).describe("Max number of periods to return (default 10)")
     }),
-    execute: async ({ symbol: symbol2, period: period2 = "annual", limit: limit2 = 10 }) => toToolResponse(await getFMPClient().analyst.getEstimates({ symbol: symbol2, period: period2, limit: limit2 }))
+    execute: async ({ symbol: symbol2, period: period2 = "annual", limit: limit2 }) => toToolResponse(
+      await getFMPClient().analyst.getEstimates({ symbol: symbol2, period: period2, limit: limit2 ?? 10 })
+    )
   }),
   defineTool({
     name: "getPriceTargetConsensus",
@@ -770,10 +820,10 @@ var analystDefinitions = [
       symbol: zod.z.string().min(1).describe("The stock symbol (e.g., AAPL)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of grade entries to return (default 20)")
     }),
-    execute: async ({ symbol: symbol2, limit: limit2 = 20 }) => {
+    execute: async ({ symbol: symbol2, limit: limit2 }) => {
       const res = await getFMPClient().analyst.getGrades({ symbol: symbol2 });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 20) });
       }
       return toToolResponse(res);
     }
@@ -815,7 +865,7 @@ var technicalDefinitions = [
       timeframe: zod.z.enum(["1min", "5min", "15min", "30min", "1hour", "4hour", "1day", "1week", "1month"]).default("1day").describe("Bar timeframe"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of most-recent bars to return (default 50)")
     }),
-    execute: async ({ symbol: symbol2, type, periodLength = 10, timeframe = "1day", limit: limit2 = 50 }) => {
+    execute: async ({ symbol: symbol2, type, periodLength = 10, timeframe = "1day", limit: limit2 }) => {
       const res = await getFMPClient().technical.getTechnicalIndicator({
         symbol: symbol2,
         type,
@@ -823,7 +873,7 @@ var technicalDefinitions = [
         timeframe
       });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 50) });
       }
       return toToolResponse(res);
     }
@@ -856,8 +906,9 @@ var senateHouseDefinitions = [
       name: zod.z.string().min(1, "Name is required").describe("The name of the senator to get trading data for"),
       limit: byNameLimit
     }),
-    execute: async ({ name, limit: limit2 = 50 }) => toToolResponse(
-      limitRows(await getFMPClient().senateHouse.getSenateTradingByName({ name }), limit2)
+    execute: async ({ name, limit: limit2 }) => toCappedToolResponse(
+      await getFMPClient().senateHouse.getSenateTradingByName({ name }),
+      limit2 ?? 50
     )
   }),
   defineTool({
@@ -867,8 +918,9 @@ var senateHouseDefinitions = [
       name: zod.z.string().min(1, "Name is required").describe("The name of the representative to get trading data for"),
       limit: byNameLimit
     }),
-    execute: async ({ name, limit: limit2 = 50 }) => toToolResponse(
-      limitRows(await getFMPClient().senateHouse.getHouseTradingByName({ name }), limit2)
+    execute: async ({ name, limit: limit2 }) => toCappedToolResponse(
+      await getFMPClient().senateHouse.getHouseTradingByName({ name }),
+      limit2 ?? 50
     )
   }),
   defineTool({