@coldiq/mcp 0.3.18 → 0.3.20

package/dist/tools/find-people.d.ts

@@ -9,6 +9,7 @@ export declare const findPeopleSchema: {
     locations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     limit: z.ZodDefault<z.ZodNumber>;
+    max_per_company: z.ZodOptional<z.ZodNumber>;
     fields: z.ZodDefault<z.ZodEnum<["compact", "verbose"]>>;
     reveal: z.ZodOptional<z.ZodBoolean>;
     use_providers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;

package/dist/tools/find-people.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-people.d.ts","sourceRoot":"","sources":["../../src/tools/find-people.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAWiJ,CAAA;AAEnL,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAW5B,CAAA;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;GAErE"}
+{"version":3,"file":"find-people.d.ts","sourceRoot":"","sources":["../../src/tools/find-people.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAWiJ,CAAA;AAEnL,eAAO,MAAM,gBAAgB;;;;;;;;;;;;CAY5B,CAAA;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;GAErE"}

package/dist/tools/find-people.js

@@ -21,6 +21,7 @@ export const findPeopleSchema = {
     locations: z.array(z.string()).optional().describe('Person locations as either ISO-2 country codes ("BR") or English country names ("Brazil") — both are accepted and normalized internally. LeadsFactory uses these to scope contacts to the country; other providers fall back to free-text matching.'),
     keywords: z.array(z.string()).optional().describe('Free-text keyword search terms (e.g. ["growth", "AI"])'),
     limit: z.number().min(1).max(500).default(25).describe('Max results across all companies combined (default: 25, max: 500). For multiple companies multiply: e.g. 10 companies × 5 each = 50. Note: when the matched provider is Apollo, results are capped at 100 per call (Apollo upstream limit).'),
+    max_per_company: z.number().min(1).optional().describe('Cap the number of contacts returned per company (e.g. 3 for a buying committee). Applied across all matched companies, before the global limit.'),
     fields: z.enum(['compact', 'verbose']).default('compact').describe('Response shape. "compact" (default) returns a small, predictable per-person record: name, title, linkedin_url, company {name, domain, linkedin_url, headcount}, plus seniority/email/location when the upstream provider includes them. "verbose" returns the raw provider passthrough (~30KB+ per record from FullEnrich: employment history, every company office, descriptions, skills, languages) — only use when you specifically need those fields.'),
     reveal: z.boolean().optional().describe('Apollo-only: when true, follow the obfuscated Apollo people-search results with /apollo/people/bulk-match to reveal full names, emails, and LinkedIn URLs. Costs 1 extra credit per revealed person on top of the search credit. Has no effect for other providers (their data is already unobfuscated). Default false to protect credits.'),
     use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_people').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),

package/dist/tools/find-people.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-people.js","sourceRoot":"","sources":["../../src/tools/find-people.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAEzE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,MAAM,CAAC,MAAM,qBAAqB,GAChC,kDAAkD;IAClD,8MAA8M;IAC9M,qEAAqE;IACrE,uGAAuG;IACvG,yHAAyH;IACzH,uIAAuI;IACvI,iQAAiQ;IACjQ,6FAA6F;IAC7F,uHAAuH;IACvH,oMAAoM;IACpM,iLAAiL,CAAA;AAEnL,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gHAAgH,CAAC;IAChL,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kHAAkH,CAAC;IAC5K,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACtG,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IAC7G,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qPAAqP,CAAC;IACzS,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;IAC3G,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,6OAA6O,CAAC;IACrS,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,2bAA2b,CAAC;IAC/f,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4UAA4U,CAAC;IACrX,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gLAAgL,yBAAyB,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,qEAAqE,CAAC;CACjW,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA8B;IACpE,OAAO,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;AAC1C,CAAC"}
+{"version":3,"file":"find-people.js","sourceRoot":"","sources":["../../src/tools/find-people.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAEzE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,MAAM,CAAC,MAAM,qBAAqB,GAChC,kDAAkD;IAClD,8MAA8M;IAC9M,qEAAqE;IACrE,uGAAuG;IACvG,yHAAyH;IACzH,uIAAuI;IACvI,iQAAiQ;IACjQ,6FAA6F;IAC7F,uHAAuH;IACvH,oMAAoM;IACpM,iLAAiL,CAAA;AAEnL,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gHAAgH,CAAC;IAChL,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kHAAkH,CAAC;IAC5K,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACtG,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IAC7G,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qPAAqP,CAAC;IACzS,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;IAC3G,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,6OAA6O,CAAC;IACrS,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iJAAiJ,CAAC;IACzM,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,2bAA2b,CAAC;IAC/f,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4UAA4U,CAAC;IACrX,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gLAAgL,yBAAyB,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,qEAAqE,CAAC;CACjW,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA8B;IACpE,OAAO,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;AAC1C,CAAC"}

package/dist/tools/get-session-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAMuB,CAAA;AAE9D,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAEvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAG3E"}
+{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAOY,CAAA;AAEnD,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAMvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GA8B3E"}

package/dist/tools/get-session-usage.js

@@ -1,14 +1,45 @@
 import { getSessionUsage } from '../session-usage.js';
+import { callApi } from '../client.js';
 export const getSessionUsageName = 'get_session_usage';
-export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-    'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-    'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-    'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-    'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-    'for the authoritative live balance use get_credit_balance.';
+export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+    'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+    'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+    'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+    'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+    'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+    '(or get_credit_balance) as the source of truth.';
 export const getSessionUsageSchema = {};
+const SESSION_USAGE_NOTE = 'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+    'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).';
 export async function getSessionUsageHandler(_input) {
     const usage = getSessionUsage();
-    return { content: [{ type: 'text', text: JSON.stringify({ data: usage }) }] };
+    // Reconcile against the authoritative balance. /me/credits is not billed, so this
+    // call never pollutes the tally. Best-effort: a failure just omits the field.
+    let authoritativeBalance;
+    try {
+        const res = await callApi('GET', '/me/credits');
+        if (res.ok && res.data && typeof res.data === 'object') {
+            const bal = res.data.data?.balance;
+            if (typeof bal === 'number')
+                authoritativeBalance = bal;
+        }
+    }
+    catch {
+        // ignore — reconciliation is best-effort
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    data: {
+                        ...usage,
+                        ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+                        note: SESSION_USAGE_NOTE,
+                    },
+                }),
+            },
+        ],
+    };
 }
 //# sourceMappingURL=get-session-usage.js.map

package/dist/tools/get-session-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,yFAAyF;IACzF,mGAAmG;IACnG,0GAA0G;IAC1G,kGAAkG;IAClG,sGAAsG;IACtG,4DAA4D,CAAA;AAE9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAC/B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;AACxF,CAAC"}
+{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,wGAAwG;IACxG,8GAA8G;IAC9G,+GAA+G;IAC/G,4GAA4G;IAC5G,2GAA2G;IAC3G,iHAAiH;IACjH,iDAAiD,CAAA;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,kBAAkB,GACtB,2GAA2G;IAC3G,uGAAuG,CAAA;AAEzG,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAE/B,kFAAkF;IAClF,8EAA8E;IAC9E,IAAI,oBAAwC,CAAA;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QAC/C,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,GAAG,GAAI,GAAG,CAAC,IAAyC,CAAC,IAAI,EAAE,OAAO,CAAA;YACxE,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,oBAAoB,GAAG,GAAG,CAAA;QACzD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IAED,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,IAAI,EAAE;wBACJ,GAAG,KAAK;wBACR,GAAG,CAAC,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC9F,IAAI,EAAE,kBAAkB;qBACzB;iBACF,CAAC;aACH;SACF;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/tools/find-people.ts

@@ -25,6 +25,7 @@ export const findPeopleSchema = {
   locations: z.array(z.string()).optional().describe('Person locations as either ISO-2 country codes ("BR") or English country names ("Brazil") — both are accepted and normalized internally. LeadsFactory uses these to scope contacts to the country; other providers fall back to free-text matching.'),
   keywords: z.array(z.string()).optional().describe('Free-text keyword search terms (e.g. ["growth", "AI"])'),
   limit: z.number().min(1).max(500).default(25).describe('Max results across all companies combined (default: 25, max: 500). For multiple companies multiply: e.g. 10 companies × 5 each = 50. Note: when the matched provider is Apollo, results are capped at 100 per call (Apollo upstream limit).'),
+  max_per_company: z.number().min(1).optional().describe('Cap the number of contacts returned per company (e.g. 3 for a buying committee). Applied across all matched companies, before the global limit.'),
   fields: z.enum(['compact', 'verbose']).default('compact').describe('Response shape. "compact" (default) returns a small, predictable per-person record: name, title, linkedin_url, company {name, domain, linkedin_url, headcount}, plus seniority/email/location when the upstream provider includes them. "verbose" returns the raw provider passthrough (~30KB+ per record from FullEnrich: employment history, every company office, descriptions, skills, languages) — only use when you specifically need those fields.'),
   reveal: z.boolean().optional().describe('Apollo-only: when true, follow the obfuscated Apollo people-search results with /apollo/people/bulk-match to reveal full names, emails, and LinkedIn URLs. Costs 1 extra credit per revealed person on top of the search credit. Has no effect for other providers (their data is already unobfuscated). Default false to protect credits.'),
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically pick the best tool for your inputs — recommended for most use cases. Available providers: ${getProvidersForCapability('find_people').join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),

package/src/tools/get-session-usage.ts

@@ -1,18 +1,51 @@
 import { getSessionUsage } from '../session-usage.js'
+import { callApi } from '../client.js'
 
 export const getSessionUsageName = 'get_session_usage'
 
 export const getSessionUsageDescription =
-  'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-  'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-  'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-  'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-  'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-  'for the authoritative live balance use get_credit_balance.'
+  'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+  'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+  'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+  'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+  'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+  'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+  '(or get_credit_balance) as the source of truth.'
 
 export const getSessionUsageSchema = {}
 
+const SESSION_USAGE_NOTE =
+  'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+  'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).'
+
 export async function getSessionUsageHandler(_input: Record<string, unknown>) {
   const usage = getSessionUsage()
-  return { content: [{ type: 'text' as const, text: JSON.stringify({ data: usage }) }] }
+
+  // Reconcile against the authoritative balance. /me/credits is not billed, so this
+  // call never pollutes the tally. Best-effort: a failure just omits the field.
+  let authoritativeBalance: number | undefined
+  try {
+    const res = await callApi('GET', '/me/credits')
+    if (res.ok && res.data && typeof res.data === 'object') {
+      const bal = (res.data as { data?: { balance?: unknown } }).data?.balance
+      if (typeof bal === 'number') authoritativeBalance = bal
+    }
+  } catch {
+    // ignore — reconciliation is best-effort
+  }
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({
+          data: {
+            ...usage,
+            ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+            note: SESSION_USAGE_NOTE,
+          },
+        }),
+      },
+    ],
+  }
 }

package/tests/find-people-schema.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+import { z } from 'zod'
+import { findPeopleSchema } from '../src/tools/find-people.js'
+
+describe('find_people MCP tool schema', () => {
+  it('exposes max_per_company so the cap reaches the server (was silently dropped)', () => {
+    // Live matrix bug: the server verb honors max_per_company (D3), but the MCP tool
+    // schema didn't expose it, so Zod stripped it and the cap never applied (a
+    // multi-company search returned 5 notion contacts for max_per_company:3).
+    expect(Object.keys(findPeopleSchema)).toContain('max_per_company')
+    const parsed = z.object(findPeopleSchema).parse({
+      company_domains: ['figma.com', 'notion.so'],
+      job_titles: ['Account Executive'],
+      max_per_company: 3,
+    })
+    expect(parsed.max_per_company).toBe(3)
+  })
+})

package/tests/session-usage.test.ts

@@ -6,6 +6,7 @@ import {
   resetSessionUsage,
 } from '../src/session-usage.js'
 import { initClient, callApi } from '../src/client.js'
+import { getSessionUsageHandler } from '../src/tools/get-session-usage.js'
 
 describe('session-usage accumulator', () => {
   beforeEach(() => {
@@ -128,3 +129,34 @@ describe('callApi records credit charges into session usage', () => {
     expect(getSessionUsage().billedCalls).toBe(0)
   })
 })
+
+// --- B2: get_session_usage reconciles against the authoritative balance ------
+describe('get_session_usage handler reconciliation (B2)', () => {
+  const originalFetch = globalThis.fetch
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+    resetSessionUsage(0)
+  })
+  afterEach(() => { globalThis.fetch = originalFetch })
+
+  it('attaches the live authoritative_balance and a best-effort note', async () => {
+    recordCharge('/email/find', 2, 500) // header-derived tally (may drift from real balance)
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ data: { balance: 480.5, usedThisMonth: 20 } }), { status: 200 }),
+    ) as typeof fetch
+
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.totalCreditsCharged).toBe(2)
+    expect(payload.authoritative_balance).toBe(480.5) // reconciliation source of truth
+    expect(payload.note).toMatch(/best-effort/i)
+  })
+
+  it('still returns the tally + note when the balance lookup fails (best-effort)', async () => {
+    globalThis.fetch = vi.fn(async () => new Response('nope', { status: 502 })) as typeof fetch
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.authoritative_balance).toBeUndefined()
+    expect(payload.note).toBeTruthy()
+  })
+})