Get Deep Signal (paid)

Instructions

Implementation Reference

• src/server.ts:618-716 (registration)

  Tool registration in the TOOLS array with name 'get_deep_signal', including input/output schemas, description, and annotations.

  {
    name: "get_deep_signal",
    title: "Get Deep Signal (paid)",
    description: [
      "PAID per-request tool — costs 1 credit per match. Returns a deeply enriched signal profile for a single tracked startup, beyond what the free `get_startup_signal` returns: scored breakdown (velocity / growth / novelty / composite), in-sector rank and percentile, comparable startups, multi-period history, and a plain-English investment thesis.",
      "",
      "PRICING:",
      "- 100 credits = €19 one-time (€0.19 per call). Buy at " +
        CREDITS_PURCHASE_URL,
      "- 1 credit consumed only on a successful match. `found: false` is FREE.",
      "- Credits never expire.",
      "",
      "AUTHENTICATION:",
      "- Set environment variable `GITDEALFLOW_API_KEY` to the v2 key delivered in the credit-pack welcome email (format: `gdf_v2.cus_xxx.<hmac>`). The server reads it once on each call.",
      "- Without a key, this tool returns an error pointing at the purchase URL — the other 6 free tools are unaffected.",
      "",
      "WHEN TO USE (vs free `get_startup_signal`):",
      "- You already know the startup name and need scored / percentile / comparables / thesis output for a memo.",
      "- The agent's principal will read or quote the thesis line.",
      "- You're processing a watchlist programmatically and need a numeric composite score for ranking.",
      "",
      "DO NOT USE FOR:",
      "- Discovery — call free `get_trending_startups` or `search_startups_by_sector` first.",
      "- Bulk scoring an unknown universe — that's not yet shipped; submit feedback via signal@gitdealflow.com.",
      "- Methodology questions — call free `get_methodology`.",
      "",
      "PARAMETERS: `name` (required, string, 1-100 chars) — Startup display name OR GitHub org name. Case-insensitive matching, same as the free lookup.",
      "",
      "RETURNS: `{ found: boolean, name, sector, stage, geography, signalType, scores: { velocity, growth, novelty, composite }, rank: { inSector, sectorTotal, sectorPercentile }, thesis, comparables[], history[], links, balance, charged, citation }`. `balance` is the remaining credit count after this call. `charged` is 0 (miss) or 1 (hit).",
      "",
      "ERRORS: 401 = invalid/missing key; 402 = insufficient credits (top up at the purchase URL); 400 = malformed request.",
    ].join("\n"),
    inputSchema: {
      type: "object" as const,
      properties: {
        name: {
          type: "string",
          description:
            "Startup name or GitHub org name. Case-insensitive; punctuation and whitespace are ignored.",
          minLength: 1,
          maxLength: 100,
          examples: ["Roboflow", "SkyPilot", "Supabase"],
        },
      },
      required: ["name"],
      additionalProperties: false,
    },
    outputSchema: {
      type: "object" as const,
      properties: {
        found: { type: "boolean" },
        name: { type: "string" },
        sector: { type: "string" },
        stage: { type: "string" },
        geography: { type: "string" },
        signalType: { type: "string" },
        scores: {
          type: "object",
          properties: {
            velocity: { type: "integer", minimum: 0, maximum: 100 },
            growth: { type: "integer", minimum: 0, maximum: 100 },
            novelty: { type: "integer", minimum: 0, maximum: 100 },
            composite: { type: "integer", minimum: 0, maximum: 100 },
          },
        },
        rank: {
          type: "object",
          properties: {
            inSector: { type: "integer" },
            sectorTotal: { type: "integer" },
            sectorPercentile: { type: "integer", minimum: 0, maximum: 100 },
          },
        },
        thesis: { type: "string" },
        comparables: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: { type: "string" },
              commitVelocityChange: { type: "string" },
              signalType: { type: "string" },
            },
          },
        },
        balance: { type: "integer", minimum: 0 },
        charged: { type: "integer", minimum: 0, maximum: 1 },
        citation: { type: "string" },
      },
      required: ["found"],
    },
    annotations: {
      title: "Get Deep Signal (paid)",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  },

• src/server.ts:650-715 (schema)

  Input schema requiring a 'name' string (1-100 chars), and output schema defining the deep signal response structure (found, scores, rank, thesis, comparables, balance, etc.).

  inputSchema: {
    type: "object" as const,
    properties: {
      name: {
        type: "string",
        description:
          "Startup name or GitHub org name. Case-insensitive; punctuation and whitespace are ignored.",
        minLength: 1,
        maxLength: 100,
        examples: ["Roboflow", "SkyPilot", "Supabase"],
      },
    },
    required: ["name"],
    additionalProperties: false,
  },
  outputSchema: {
    type: "object" as const,
    properties: {
      found: { type: "boolean" },
      name: { type: "string" },
      sector: { type: "string" },
      stage: { type: "string" },
      geography: { type: "string" },
      signalType: { type: "string" },
      scores: {
        type: "object",
        properties: {
          velocity: { type: "integer", minimum: 0, maximum: 100 },
          growth: { type: "integer", minimum: 0, maximum: 100 },
          novelty: { type: "integer", minimum: 0, maximum: 100 },
          composite: { type: "integer", minimum: 0, maximum: 100 },
        },
      },
      rank: {
        type: "object",
        properties: {
          inSector: { type: "integer" },
          sectorTotal: { type: "integer" },
          sectorPercentile: { type: "integer", minimum: 0, maximum: 100 },
        },
      },
      thesis: { type: "string" },
      comparables: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            commitVelocityChange: { type: "string" },
            signalType: { type: "string" },
          },
        },
      },
      balance: { type: "integer", minimum: 0 },
      charged: { type: "integer", minimum: 0, maximum: 1 },
      citation: { type: "string" },
    },
    required: ["found"],
  },
  annotations: {
    title: "Get Deep Signal (paid)",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
  },

• src/server.ts:1338-1467 (handler)

  Handler logic for 'get_deep_signal': validates input, checks for GITDEALFLOW_API_KEY, calls the paid POST endpoint /api/agent/deep-signal with the API key, handles 401/402/not-found errors, and returns enriched signal data with scores, rank, thesis, comparables, and credit balance.

  case "get_deep_signal": {
    const inputName = String(
      (request.params.arguments as Record<string, unknown> | undefined)?.name ?? ""
    ).trim();
    if (!inputName || inputName.length > 100) {
      throw new Error("Invalid name. Must be 1-100 chars.");
    }
    const apiKey = process.env.GITDEALFLOW_API_KEY?.trim();
    if (!apiKey) {
      return {
        content: [
          {
            type: "text" as const,
            text: [
              `get_deep_signal is paid (€0.19/call, 100 credits = €19).`,
              ``,
              `Set the GITDEALFLOW_API_KEY environment variable to the key from your credit-pack welcome email.`,
              ``,
              `Buy credits: ${CREDITS_PURCHASE_URL}`,
              ``,
              `The 6 free tools (get_trending_startups, search_startups_by_sector, get_startup_signal, get_signals_summary, get_scout_receipts, get_methodology) are unaffected.`,
            ].join("\n"),
          },
        ],
        structuredContent: {
          found: false,
          error: "missing_api_key",
          purchaseUrl: CREDITS_PURCHASE_URL,
        },
        isError: true,
      };
    }
  
    const res = await fetch(`${BASE_URL}/api/agent/deep-signal`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "User-Agent": UA,
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify({ name: inputName }),
    });
  
    const data = (await res.json().catch(() => ({}))) as Record<string, unknown>;
  
    if (res.status === 401) {
      return {
        content: [
          {
            type: "text" as const,
            text: `API key did not validate. Re-check GITDEALFLOW_API_KEY against the welcome email, or buy a fresh key at ${CREDITS_PURCHASE_URL}.`,
          },
        ],
        structuredContent: data,
        isError: true,
      };
    }
    if (res.status === 402) {
      const balance = typeof data.balance === "number" ? data.balance : 0;
      return {
        content: [
          {
            type: "text" as const,
            text: `Out of credits (balance: ${balance}). Buy 100 more for €19 at ${CREDITS_PURCHASE_URL}.`,
          },
        ],
        structuredContent: data,
        isError: true,
      };
    }
    if (!res.ok) {
      throw new Error(`HTTP ${res.status} from /api/agent/deep-signal`);
    }
  
    if (data.found === false) {
      const suggestion =
        typeof data.suggestion === "string"
          ? data.suggestion
          : "Try the GitHub org name exactly, or call get_trending_startups to browse.";
      return {
        content: [
          {
            type: "text" as const,
            text: `"${inputName}" is not in the tracked universe. ${suggestion}\n\n(0 credits charged for misses.)`,
          },
        ],
        structuredContent: data,
      };
    }
  
    const text = (() => {
      const lines: string[] = [];
      lines.push(`${data.name as string} — Deep Signal (paid)`);
      lines.push("");
      const scores = data.scores as Record<string, number> | undefined;
      const rank = data.rank as Record<string, number> | undefined;
      if (scores) {
        lines.push(
          `Composite score: ${scores.composite}/100  ·  Velocity ${scores.velocity}  ·  Growth ${scores.growth}  ·  Novelty ${scores.novelty}`
        );
      }
      if (rank) {
        lines.push(
          `Sector rank: #${rank.inSector} of ${rank.sectorTotal} (${rank.sectorPercentile}th percentile in ${data.sector})`
        );
      }
      lines.push("");
      if (typeof data.thesis === "string") lines.push(`Thesis: ${data.thesis}`);
      const comps = data.comparables as Array<Record<string, unknown>> | undefined;
      if (comps && comps.length > 0) {
        lines.push("");
        lines.push("Comparables in sector:");
        for (const c of comps) {
          lines.push(`  - ${c.name} (${c.commitVelocityChange}, ${c.signalType})`);
        }
      }
      lines.push("");
      lines.push(`Credits remaining: ${data.balance ?? "?"}  ·  Charged: ${data.charged ?? 1}`);
      lines.push("");
      if (typeof data.citation === "string") lines.push(`Citation: ${data.citation}`);
      lines.push("");
      lines.push(FOOTER);
      return lines.join("\n");
    })();
  
    return {
      content: [{ type: "text" as const, text }],
      structuredContent: data,
    };
  }