get_usage

Instructions

Implementation Reference

• src/index.ts:162-166 (schema)

  Registration (schema + description) for the 'get_usage' tool. Defined in the tools list with name, description, and empty inputSchema (no parameters required).

  {
    name: "get_usage",
    description: "Check your FundzWatch API usage: calls made, limits, current tier.",
    inputSchema: { type: "object" as const, properties: {} },
  },

• src/index.ts:312-321 (handler)

  Handler for the 'get_usage' tool. Makes a GET request to '/usage' API endpoint and formats the response showing tier, API calls used/limit, AI score calls used/limit, and last API call timestamp.

  case "get_usage": {
    const data = await apiRequest("GET", "/usage");
    const text =
      `FundzWatch Usage (${data.current_period}):\n\n` +
      `Tier: ${data.tier}\n` +
      `API Calls: ${data.api_calls_used} / ${data.limits.api_calls_monthly}\n` +
      `AI Score Calls: ${data.ai_score_calls_used} / ${data.limits.ai_score_calls_monthly}\n` +
      (data.last_api_call ? `Last API Call: ${data.last_api_call}` : "");
    return textResult(text);
  }

• src/index.ts:71-168 (registration)

  The 'get_usage' tool is registered as part of the tools array in the ListToolsRequestSchema handler, and its case handler is included in the CallToolRequestSchema switch statement.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "get_scored_leads",
        description:
          "Get AI-scored sales leads based on your ICP (Ideal Customer Profile). " +
          "Returns companies with recent business events scored by AI for buyer intent, " +
          "buying stage, and recommended outreach strategy.",
        inputSchema: {
          type: "object" as const,
          properties: {
            min_score: { type: "number", description: "Minimum buyer intent score (0-100). Default: 0" },
            max_results: { type: "number", description: "Max leads to return (1-50). Default: 25" },
            buying_stages: {
              type: "array",
              items: { type: "string" },
              description: "Filter by buying stage: 'Active Evaluation', 'Decision', 'Research', 'Awareness'",
            },
            industries: {
              type: "array",
              items: { type: "string" },
              description: "Filter by industry (e.g., ['SaaS', 'HealthTech', 'FinTech'])",
            },
          },
        },
      },
      {
        name: "get_events",
        description:
          "Get real-time business events: funding rounds, acquisitions, executive hires, " +
          "government contracts, and product launches. Filter by type, industry, and location.",
        inputSchema: {
          type: "object" as const,
          properties: {
            types: { type: "string", description: "Comma-separated: funding, acquisition, hiring, contract, product_launch. Default: all" },
            days: { type: "number", description: "Look back days (1-90). Default: 7" },
            limit: { type: "number", description: "Max events (1-200). Default: 50" },
            industries: { type: "string", description: "Comma-separated industries" },
            locations: { type: "string", description: "Comma-separated locations" },
          },
        },
      },
      {
        name: "get_market_pulse",
        description:
          "Get real-time market activity overview: funding totals, acquisition counts, " +
          "executive moves, contracts, and product launches for the past 7 and 30 days.",
        inputSchema: { type: "object" as const, properties: {} },
      },
      {
        name: "get_market_brief",
        description:
          "Get today's AI-generated strategic intelligence brief with narrative analysis " +
          "of the most important market movements, patterns, and opportunities.",
        inputSchema: { type: "object" as const, properties: {} },
      },
      {
        name: "manage_watchlist",
        description:
          "Add, remove, or list companies on your watchlist. Tracked companies generate " +
          "alerts when they have new events.",
        inputSchema: {
          type: "object" as const,
          properties: {
            action: {
              type: "string",
              enum: ["list", "add", "remove"],
              description: "Action: 'list' to view, 'add' to track, 'remove' to untrack",
            },
            domains: {
              type: "array",
              items: { type: "string" },
              description: "Company domains for add/remove (e.g., ['stripe.com', 'github.com'])",
            },
          },
          required: ["action"],
        },
      },
      {
        name: "get_watchlist_events",
        description:
          "Get recent events for companies on your watchlist: funding, acquisitions, " +
          "executive hires, contracts.",
        inputSchema: {
          type: "object" as const,
          properties: {
            days: { type: "number", description: "Look back days (1-90). Default: 7" },
            types: { type: "string", description: "Comma-separated event types" },
          },
        },
      },
      {
        name: "get_usage",
        description: "Check your FundzWatch API usage: calls made, limits, current tier.",
        inputSchema: { type: "object" as const, properties: {} },
      },
    ],
  }));

• src/index.ts:21-56 (helper)

  The apiRequest helper function is used by the get_usage handler to make the GET request to the /usage API endpoint.

  async function apiRequest(
    method: string,
    path: string,
    params?: Record<string, any>
  ): Promise<any> {
    const apiKey = getApiKey();
    const url = new URL(`${API_BASE}${path}`);
  
    const options: RequestInit = {
      method,
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "User-Agent": "fundzwatch-mcp/1.0.1",
      },
    };
  
    if (method === "GET" && params) {
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== null) {
          url.searchParams.append(key, String(value));
        }
      });
    } else if (method !== "GET" && params) {
      options.body = JSON.stringify(params);
    }
  
    const response = await fetch(url.toString(), options);
  
    if (!response.ok) {
      const errBody: any = await response.json().catch(() => ({ message: response.statusText }));
      throw new Error(`API error ${response.status}: ${errBody.message || errBody.error || response.statusText}`);
    }
  
    return response.json();
  }

• src/index.ts:58-60 (helper)

  The textResult helper formats the response as a text content block, used by get_usage to return the formatted usage string.

  function textResult(text: string) {
    return { content: [{ type: "text" as const, text }] };
  }