@coldiq/mcp 0.4.6 → 0.5.0

package/src/registry.ts

@@ -1857,104 +1857,183 @@ const verifyEmailProviders: ProviderEntry[] = [
 // ---------------------------------------------------------------------------
 
 const findPhoneProviders: ProviderEntry[] = [
+  // Mirror of the API registry (validation/listing only — execution order and
+  // predicates live server-side in src/router/registry.ts). 2026-07-24 v2:
+  // prospeo → leadmagic → ai-ark → limadata → fullenrich (premium closer);
+  // findymail dropped (1 hit/30d); ai-ark/limadata accept the schema's `domain`.
   {
-    id: 'findymail',
-    endpoint: '/findymail/search/phone',
+    id: 'prospeo',
+    endpoint: '/prospeo/enrich-person',
+    method: 'POST',
+    priority: 1,
+    isApplicable: (input) => {
+      if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
+      const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
+        typeof input.last_name === 'string' && (input.last_name as string).length > 0
+      const domain = (input.domain ?? input.company_domain) as string | undefined
+      const hasCompany = (typeof domain === 'string' && domain.length > 0) ||
+        (typeof input.company_name === 'string' && (input.company_name as string).length > 0)
+      return hasName && hasCompany
+    },
+    mapParams: (input) => {
+      const domain = (input.domain ?? input.company_domain) as string | undefined
+      const data: Record<string, unknown> = input.linkedin_url
+        ? { linkedin_url: input.linkedin_url }
+        : {
+            first_name: input.first_name,
+            last_name: input.last_name,
+            ...(domain ? { company_website: domain } : {}),
+            ...(input.company_name ? { company_name: input.company_name } : {}),
+          }
+      return { body: { enrich_mobile: true, data } }
+    },
+    hasResult: (data) => {
+      const d = data as Record<string, unknown>
+      const person = d.person as Record<string, unknown> | undefined
+      const mobile = person?.mobile as Record<string, unknown> | undefined
+      return typeof mobile?.mobile === 'string' && (mobile.mobile as string).length > 0
+    },
+  },
+  {
+    id: 'leadmagic',
+    endpoint: '/leadmagic/people/mobile-finder',
     method: 'POST',
     priority: 2,
-    isApplicable: (input) => typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0,
-    mapParams: (input) => ({ body: { linkedin_url: input.linkedin_url } }),
+    isApplicable: (input) =>
+      (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) ||
+      (typeof input.email === 'string' && (input.email as string).length > 0),
+    mapParams: (input) => ({
+      body: input.linkedin_url
+        ? { profile_url: input.linkedin_url }
+        : { work_email: input.email },
+    }),
     hasResult: (data) => {
       const d = data as Record<string, unknown>
-      return typeof d.phone === 'string' || isNonEmptyArray(d.phones)
+      return typeof d.mobile_number === 'string' && (d.mobile_number as string).length > 0
     },
   },
   {
-    id: 'limadata',
-    endpoint: '/limadata/find/phone',
+    id: 'ai-ark',
+    endpoint: '/ai-ark/people/mobile-phone-finder',
     method: 'POST',
     priority: 3,
     isApplicable: (input) => {
       if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
       const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
         typeof input.last_name === 'string' && (input.last_name as string).length > 0
-      const hasCompany = (typeof input.company_domain === 'string' && (input.company_domain as string).length > 0) ||
-        (typeof input.company_name === 'string' && (input.company_name as string).length > 0)
-      return hasName && hasCompany
+      const domain = (input.domain ?? input.company_domain) as string | undefined
+      return hasName && typeof domain === 'string' && domain.length > 0
     },
     mapParams: (input) => {
       const firstName = input.first_name as string | undefined
       const lastName = input.last_name as string | undefined
       const fullName = [firstName, lastName].filter(Boolean).join(' ') || undefined
+      const domain = (input.domain ?? input.company_domain) as string | undefined
       return {
         body: {
-          ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+          ...(input.linkedin_url ? { linkedin: input.linkedin_url } : {}),
+          ...(domain ? { domain } : {}),
           ...(fullName ? { name: fullName } : {}),
-          ...(input.company_name ? { company_name: input.company_name } : {}),
-          ...(input.company_domain ? { company_domain: input.company_domain } : {}),
         },
       }
     },
     hasResult: (data) => {
       const d = data as Record<string, unknown>
-      if (typeof d.phone === 'string' && (d.phone as string).length > 0) return true
-      if (isNonEmptyArray(d.phones)) return true
-      if (isNonEmptyArray(d.phone_numbers)) return true
-      const nested = d.data as Record<string, unknown> | undefined
-      if (nested && typeof nested.phone === 'string' && (nested.phone as string).length > 0) return true
-      if (nested && isNonEmptyArray(nested.phones)) return true
-      if (nested && isNonEmptyArray(nested.phone_numbers)) return true
-      return false
+      return Array.isArray(d.data) &&
+        (d.data as unknown[]).some(
+          (arr) => Array.isArray(arr) && (arr as unknown[]).length > 0 && typeof (arr as unknown[])[0] === 'string',
+        )
     },
   },
   {
-    id: 'ai-ark',
-    endpoint: '/ai-ark/people/mobile-phone-finder',
+    id: 'limadata',
+    endpoint: '/limadata/find/phone',
     method: 'POST',
     priority: 4,
     isApplicable: (input) => {
       if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
       const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
         typeof input.last_name === 'string' && (input.last_name as string).length > 0
-      const hasDomain = typeof input.company_domain === 'string' && (input.company_domain as string).length > 0
-      return hasName && hasDomain
+      const domain = (input.domain ?? input.company_domain) as string | undefined
+      const hasCompany = (typeof domain === 'string' && domain.length > 0) ||
+        (typeof input.company_name === 'string' && (input.company_name as string).length > 0)
+      return hasName && hasCompany
     },
     mapParams: (input) => {
       const firstName = input.first_name as string | undefined
       const lastName = input.last_name as string | undefined
       const fullName = [firstName, lastName].filter(Boolean).join(' ') || undefined
+      const domain = (input.domain ?? input.company_domain) as string | undefined
       return {
         body: {
-          ...(input.linkedin_url ? { linkedin: input.linkedin_url } : {}),
-          ...(input.company_domain ? { domain: input.company_domain } : {}),
+          ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
           ...(fullName ? { name: fullName } : {}),
+          ...(input.company_name ? { company_name: input.company_name } : {}),
+          ...(domain ? { company_domain: domain } : {}),
         },
       }
     },
     hasResult: (data) => {
       const d = data as Record<string, unknown>
-      return Array.isArray(d.data) &&
-        (d.data as unknown[]).some(
-          (arr) => Array.isArray(arr) && (arr as unknown[]).length > 0 && typeof (arr as unknown[])[0] === 'string',
-        )
+      if (typeof d.phone === 'string' && (d.phone as string).length > 0) return true
+      if (isNonEmptyArray(d.phones)) return true
+      if (isNonEmptyArray(d.phone_numbers)) return true
+      const nested = d.data as Record<string, unknown> | undefined
+      if (nested && typeof nested.phone === 'string' && (nested.phone as string).length > 0) return true
+      if (nested && isNonEmptyArray(nested.phones)) return true
+      if (nested && isNonEmptyArray(nested.phone_numbers)) return true
+      return false
     },
   },
   {
-    id: 'leadmagic',
-    endpoint: '/leadmagic/people/mobile-finder',
+    id: 'fullenrich',
+    endpoint: '/fullenrich/contact/enrich/bulk',
     method: 'POST',
-    priority: 1,
-    isApplicable: (input) =>
-      (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) ||
-      (typeof input.email === 'string' && (input.email as string).length > 0),
+    priority: 5,
+    isApplicable: (input) => {
+      if (typeof input.linkedin_url === 'string' && (input.linkedin_url as string).length > 0) return true
+      const hasName = typeof input.first_name === 'string' && (input.first_name as string).length > 0 &&
+        typeof input.last_name === 'string' && (input.last_name as string).length > 0
+      const domain = (input.domain ?? input.company_domain) as string | undefined
+      const hasCompany = (typeof domain === 'string' && domain.length > 0) ||
+        (typeof input.company_name === 'string' && (input.company_name as string).length > 0)
+      return hasName && hasCompany
+    },
     mapParams: (input) => ({
-      body: input.linkedin_url
-        ? { profile_url: input.linkedin_url }
-        : { work_email: input.email },
+      body: {
+        name: 'mcp-find-phone',
+        data: [{
+          first_name: input.first_name,
+          last_name: input.last_name,
+          domain: input.domain ?? input.company_domain,
+          company_name: input.company_name,
+          ...(input.linkedin_url ? { linkedin_url: input.linkedin_url } : {}),
+          enrich_fields: ['contact.phones'],
+        }],
+      },
     }),
     hasResult: (data) => {
       const d = data as Record<string, unknown>
-      return typeof d.mobile_number === 'string' && (d.mobile_number as string).length > 0
+      const items = d.data as Array<Record<string, unknown>> | undefined
+      if (!Array.isArray(items) || items.length === 0) return false
+      const contactInfo = items[0]?.contact_info as Record<string, unknown> | undefined
+      if (!contactInfo) return false
+      const phones = contactInfo.phones as Array<Record<string, unknown>> | undefined
+      return Array.isArray(phones) && phones.some((p) => typeof p?.number === 'string' && (p.number as string).length > 0)
+    },
+    async: {
+      extractId: (response) => {
+        const d = response as Record<string, unknown>
+        return d.enrichment_id as string
+      },
+      pollEndpoint: (id) => `/fullenrich/contact/enrich/bulk/${id}`,
+      pollIntervalMs: 2500,
+      timeoutMs: 60_000,
+      isComplete: (data) => {
+        const d = data as Record<string, unknown>
+        const status = d.status as string | undefined
+        return status === 'FINISHED' || status === 'CANCELED'
+      },
     },
   },
 ]

package/src/tools/list-skills.ts

@@ -3,11 +3,12 @@ import { listSkills } from '../skills.js'
 export const listSkillsName = 'list_skills'
 
 export const listSkillsDescription =
-  'List the available ColdIQ GTM playbooks ("skills") — step-by-step expert workflows for go-to-market ' +
+  'Legacy compatibility tool. Prefer search_knowledge for each new substantive GTM task because it returns the ' +
+  'current ranked workflow and provider order. Lists the available ColdIQ GTM playbooks ("skills") — ' +
+  'step-by-step expert workflows for go-to-market ' +
   'tasks: building a TAM, Apollo / company / people search, contact enrichment and email waterfalls, ' +
   'signal detection, ICP & personas, cold-email copy, campaign delivery, and more. Returns each skill\'s ' +
-  'name and a one-line description of when to use it. Call this when starting a prospecting / outreach / ' +
-  'GTM task to check for a relevant playbook, then call load_skill to read the full step-by-step guide. ' +
+  'name and a one-line description of when to use it; load_skill reads the full legacy guide. ' +
   '(Claude Code and Cursor load these skills natively; on other agents this is how you reach them.)'
 
 export const listSkillsSchema = {}

package/src/tools/load-skill.ts

@@ -4,7 +4,8 @@ import { loadSkill } from '../skills.js'
 export const loadSkillName = 'load_skill'
 
 export const loadSkillDescription =
-  'Load the full ColdIQ GTM playbook ("skill") by name — the complete step-by-step expert workflow, ' +
+  'Legacy compatibility tool. Prefer search_knowledge for the current task. Loads a ColdIQ GTM playbook ' +
+  '("skill") by name — the complete step-by-step expert workflow, ' +
   'including which ColdIQ tools/endpoints to call at each step. Call list_skills first to get the available ' +
   'names. The returned guide (with any referenced reference docs inlined) tells you exactly how to run the ' +
   'task using the other ColdIQ tools.'

package/src/tools/search-knowledge.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+import { callApi } from '../client.js'
+
+const KNOWLEDGE_DOC_TYPES = ['play', 'provider', 'strategy'] as const
+const DEFAULT_KNOWLEDGE_DOC_TYPES = ['play', 'strategy'] as const
+
+export const searchKnowledgeName = 'search_knowledge'
+
+export const searchKnowledgeDescription =
+  'MANDATORY FIRST TOOL: for every new substantive GTM task, call search_knowledge before any other ColdIQ tool. ' +
+  'Pass the user’s complete task as the query and do not reuse results from a previous task. FREE. Searches ColdIQ ' +
+  'plays, provider deep-docs, and GTM strategy, returning ranked metadata and bounded document bodies. Follow the ' +
+  'retrieved workflow and provider order. If search fails or returns no usable result, continue with endpoint discovery.'
+
+export const searchKnowledgeSchema = {
+  query: z
+    .string()
+    .describe('The user’s complete substantive GTM task, including requested entities, filters, outputs, and count.'),
+  types: z
+    .array(z.enum(KNOWLEDGE_DOC_TYPES))
+    .max(3)
+    .optional()
+    .describe('Optional document filters: play, provider, or strategy. Omit to search plays and strategy; request provider explicitly for provider documentation.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(15)
+    .default(5)
+    .optional()
+    .describe('Maximum ranked documents to return (default 5, max 15).'),
+}
+
+export async function searchKnowledgeHandler(input: Record<string, unknown>) {
+  const res = await callApi('POST', '/knowledge/search', {
+    query: input.query,
+    types: input.types ?? [...DEFAULT_KNOWLEDGE_DOC_TYPES],
+    limit: input.limit,
+  })
+  if (!res.ok) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({ error: 'Knowledge search failed', status: res.status }),
+      }],
+      isError: true,
+    }
+  }
+  return { content: [{ type: 'text' as const, text: JSON.stringify(res.data) }] }
+}

package/src/utils/provider-resolver.ts

@@ -226,9 +226,8 @@ const GATED_DESCRIPTIONS: Partial<Record<Capability, Partial<Record<string, Gate
   verify_email: {},
   // -------------------------------------------------------------------------
   find_phone: {
-    findymail: { kind: 'requires', fields: 'linkedin_url' },
-    limadata:  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
-    'ai-ark':  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and company domain)' },
+    limadata:  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and domain/company_name)' },
+    'ai-ark':  { kind: 'requires', fields: 'linkedin_url or (first_name, last_name, and domain)' },
   },
   // -------------------------------------------------------------------------
   enrich_company: {

package/src/utils/selection-insight.ts

@@ -96,9 +96,9 @@ const STRENGTHS: Partial<Record<InsightCapability, Record<string, string>>> = {
     'linkupapi-validate': 'LinkedIn-aware email validation',
   },
   find_phone: {
-    findymail: 'verified mobile-number coverage',
     limadata: 'phone lookup by LinkedIn URL or name + company',
     'ai-ark': 'phone lookup across multiple identifiers',
+    fullenrich: 'a phone waterfall aggregated across many upstream sources',
   },
   enrich_company: {
     companyenrich: 'broad firmographic enrichment from a domain',

package/tests/client.test.ts

@@ -41,6 +41,18 @@ describe('client', () => {
     expect(capturedHeaders['Content-Type']).toBe('application/json')
   })
 
+  it('declares the mcp client surface on every request (usage attribution)', async () => {
+    let capturedHeaders: Record<string, string> = {}
+    globalThis.fetch = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+      capturedHeaders = Object.fromEntries(Object.entries(init?.headers ?? {}))
+      return new Response(JSON.stringify({}), { status: 200 })
+    }) as typeof fetch
+
+    await callApi('GET', '/me/credits')
+
+    expect(capturedHeaders['X-ColdIQ-Client-Surface']).toBe('mcp')
+  })
+
   it('appends query params for GET requests', async () => {
     let capturedUrl = ''
     globalThis.fetch = vi.fn(async (url: string | URL | Request) => {

package/tests/instructions.test.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  MANDATORY_KNOWLEDGE_FIRST_RULE,
+  MCP_SERVER_INSTRUCTIONS,
+} from '../src/instructions.js'
+import {
+  KNOWLEDGE_FIRST_REQUIREMENT,
+  withKnowledgeFirstRequirement,
+} from '../src/knowledge-policy.js'
+
+const VALID_INSTRUCTION_TOOL_NAMES = new Set([
+  'search_knowledge',
+  'search_endpoints',
+  'get_endpoint_details',
+  'call_endpoint',
+  'list_skills',
+  'load_skill',
+])
+
+describe('MCP knowledge-first policy', () => {
+  it('keeps server instructions within client limits and front-loads the complete rule', () => {
+    expect(Buffer.byteLength(MCP_SERVER_INSTRUCTIONS, 'utf8')).toBeLessThan(2_048)
+    expect(Buffer.byteLength(MANDATORY_KNOWLEDGE_FIRST_RULE, 'utf8')).toBeLessThanOrEqual(512)
+    expect(MCP_SERVER_INSTRUCTIONS.startsWith(MANDATORY_KNOWLEDGE_FIRST_RULE)).toBe(true)
+    expect(Buffer.from(MCP_SERVER_INSTRUCTIONS, 'utf8').subarray(0, 512).toString())
+      .toContain(MANDATORY_KNOWLEDGE_FIRST_RULE)
+  })
+
+  it('mentions only real, valid MCP tool names', () => {
+    const referencedNames = [...MCP_SERVER_INSTRUCTIONS.matchAll(/`([a-z0-9_-]+)`/g)]
+      .map((match) => match[1])
+
+    expect(referencedNames.length).toBeGreaterThan(0)
+    for (const name of referencedNames) {
+      expect(name).toMatch(/^[a-zA-Z0-9_-]{1,128}$/)
+      expect(VALID_INSTRUCTION_TOOL_NAMES.has(name)).toBe(true)
+    }
+  })
+
+  it('prepends the knowledge prerequisite to operational descriptions', () => {
+    const description = withKnowledgeFirstRequirement('Perform an operation.')
+
+    expect(description.startsWith(KNOWLEDGE_FIRST_REQUIREMENT)).toBe(true)
+    expect(description).toContain('search_knowledge as the first ColdIQ tool')
+  })
+
+  it('registers search_knowledge first and guards every operational description', () => {
+    const indexPath = fileURLToPath(new URL('../src/index.ts', import.meta.url))
+    const registrations = readFileSync(indexPath, 'utf8')
+      .split('\n')
+      .filter((line) => line.trimStart().startsWith('server.tool('))
+    const unguardedCompatibilityTools = [
+      'getCreditBalanceName',
+      'getSessionUsageName',
+      'listSkillsName',
+      'loadSkillName',
+    ]
+
+    expect(registrations[0]).toContain('server.tool(searchKnowledgeName, searchKnowledgeDescription')
+    for (const registration of registrations.slice(1)) {
+      if (unguardedCompatibilityTools.some((name) => registration.includes(`server.tool(${name},`))) continue
+      expect(registration).toContain('withKnowledgeFirstRequirement(')
+    }
+  })
+})

package/tests/registry.test.ts

@@ -950,35 +950,12 @@ describe('registry', () => {
   })
 
   describe('find_phone', () => {
-    it('providers are ordered leadmagic → findymail → limadata → ai-ark', () => {
+    it('providers mirror the server order: prospeo → leadmagic → ai-ark → limadata → fullenrich', () => {
       const providers = getProviders('find_phone')
-      expect(providers.map((p) => p.id)).toEqual(['leadmagic', 'findymail', 'limadata', 'ai-ark'])
+      expect(providers.map((p) => p.id)).toEqual(['prospeo', 'leadmagic', 'ai-ark', 'limadata', 'fullenrich'])
     })
 
-    it('Findymail isApplicable requires linkedin_url', () => {
-      const fm = getProviders('find_phone').find((p) => p.id === 'findymail')!
-      expect(fm.isApplicable!({})).toBe(false)
-      expect(fm.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', company_domain: 'coldiq.com' })).toBe(false)
-      expect(fm.isApplicable!({ linkedin_url: 'https://linkedin.com/in/michel-lieben' })).toBe(true)
-    })
-
-    it('Findymail mapParams passes linkedin_url', () => {
-      const fm = getProviders('find_phone').find((p) => p.id === 'findymail')!
-      expect(fm.mapParams({ linkedin_url: 'https://linkedin.com/in/michel-lieben' }).body).toEqual({
-        linkedin_url: 'https://linkedin.com/in/michel-lieben',
-      })
-    })
-
-    it('Findymail hasResult accepts top-level phone or phones array', () => {
-      const fm = getProviders('find_phone').find((p) => p.id === 'findymail')!
-      expect(fm.hasResult({ phone: '+33612345678' })).toBe(true)
-      expect(fm.hasResult({ phones: ['+33612345678'] })).toBe(true)
-      expect(fm.hasResult({})).toBe(false)
-      expect(fm.hasResult({ phone: null })).toBe(false)
-      expect(fm.hasResult({ phones: [] })).toBe(false)
-    })
-
-    it('Lima Data isApplicable accepts linkedin_url or name+company', () => {
+    it('Lima Data isApplicable accepts linkedin_url or name+company (incl. the schema `domain` field)', () => {
       const ld = getProviders('find_phone').find((p) => p.id === 'limadata')!
       expect(ld.isApplicable!({})).toBe(false)
       expect(ld.isApplicable!({ first_name: 'Michel' })).toBe(false)
@@ -986,6 +963,7 @@ describe('registry', () => {
       expect(ld.isApplicable!({ linkedin_url: 'https://linkedin.com/in/michel-lieben' })).toBe(true)
       expect(ld.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', company_name: 'ColdIQ' })).toBe(true)
       expect(ld.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', company_domain: 'coldiq.com' })).toBe(true)
+      expect(ld.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' })).toBe(true)
     })
 
     it('Lima Data mapParams forwards linkedin_url path', () => {
@@ -995,12 +973,16 @@ describe('registry', () => {
       })
     })
 
-    it('Lima Data mapParams forwards name+company path', () => {
+    it('Lima Data mapParams forwards name+company path (schema `domain` maps to company_domain)', () => {
       const ld = getProviders('find_phone').find((p) => p.id === 'limadata')!
       expect(ld.mapParams({ first_name: 'Michel', last_name: 'Lieben', company_domain: 'coldiq.com' }).body).toEqual({
         name: 'Michel Lieben',
         company_domain: 'coldiq.com',
       })
+      expect(ld.mapParams({ first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' }).body).toEqual({
+        name: 'Michel Lieben',
+        company_domain: 'coldiq.com',
+      })
     })
 
     it('Lima Data mapParams forwards company_name when no domain', () => {
@@ -1026,12 +1008,13 @@ describe('registry', () => {
       expect(ld.hasResult({ data: {} })).toBe(false)
     })
 
-    it('AI Ark isApplicable accepts linkedin_url or name+company_domain (not company_name)', () => {
+    it('AI Ark isApplicable accepts linkedin_url or name+domain (not company_name)', () => {
       const ark = getProviders('find_phone').find((p) => p.id === 'ai-ark')!
       expect(ark.isApplicable!({})).toBe(false)
       expect(ark.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', company_name: 'ColdIQ' })).toBe(false)
       expect(ark.isApplicable!({ linkedin_url: 'https://linkedin.com/in/michel-lieben' })).toBe(true)
       expect(ark.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', company_domain: 'coldiq.com' })).toBe(true)
+      expect(ark.isApplicable!({ first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' })).toBe(true)
     })
 
     it('AI Ark mapParams uses linkedin key (not linkedin_url)', () => {
@@ -1041,12 +1024,16 @@ describe('registry', () => {
       })
     })
 
-    it('AI Ark mapParams maps name+domain path', () => {
+    it('AI Ark mapParams maps name+domain path (schema `domain` accepted)', () => {
       const ark = getProviders('find_phone').find((p) => p.id === 'ai-ark')!
       expect(ark.mapParams({ first_name: 'Michel', last_name: 'Lieben', company_domain: 'coldiq.com' }).body).toEqual({
         name: 'Michel Lieben',
         domain: 'coldiq.com',
       })
+      expect(ark.mapParams({ first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' }).body).toEqual({
+        name: 'Michel Lieben',
+        domain: 'coldiq.com',
+      })
     })
 
     it('AI Ark hasResult requires non-empty inner string arrays in data', () => {

package/tests/tools/get-credit-balance.test.ts

@@ -29,6 +29,17 @@ describe('get_credit_balance handler', () => {
     expect(parsed.data).toEqual({ balance: 250, usedThisMonth: 47 })
   })
 
+  it('passes through a negative true-up balance', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ balance: -1.674351, usedThisMonth: 2.199351 }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await getCreditBalanceHandler({})
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed.data).toEqual({ balance: -1.674351, usedThisMonth: 2.199351 })
+  })
+
   it('sends the API key as a bearer token', async () => {
     let capturedAuth: string | null = null
     globalThis.fetch = vi.fn(async (_url: string | URL | Request, opts?: RequestInit) => {

package/tests/tools/search-knowledge.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { initClient } from '../../src/client.js'
+import {
+  searchKnowledgeDescription,
+  searchKnowledgeHandler,
+  searchKnowledgeName,
+  searchKnowledgeSchema,
+} from '../../src/tools/search-knowledge.js'
+
+describe('search_knowledge', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => initClient('http://test-api.local', 'test-key'))
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('matches the agent schema and repeats the mandatory first-tool rule', () => {
+    const schema = z.object(searchKnowledgeSchema).strict()
+
+    expect(searchKnowledgeName).toBe('search_knowledge')
+    expect(searchKnowledgeDescription).toMatch(/mandatory first tool/i)
+    expect(searchKnowledgeDescription).toContain('before any other ColdIQ tool')
+    expect(schema.parse({ query: 'Find ColdIQ decision makers' })).toEqual({
+      query: 'Find ColdIQ decision makers',
+    })
+    expect(schema.parse({
+      query: 'Find ColdIQ decision makers',
+      types: ['play', 'provider'],
+      limit: 10,
+    })).toEqual({
+      query: 'Find ColdIQ decision makers',
+      types: ['play', 'provider'],
+      limit: 10,
+    })
+    expect(() => schema.parse({ query: 'x', types: ['unknown'] })).toThrow()
+    expect(() => schema.parse({ query: 'x', limit: 16 })).toThrow()
+  })
+
+  it('proxies the complete request to /v1/knowledge/search', async () => {
+    let capturedUrl = ''
+    let capturedBody: unknown
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      capturedUrl = url.toString()
+      capturedBody = JSON.parse(String(init?.body))
+      return new Response(JSON.stringify({
+        results: [{ slug: 'find-people', body: '# Find people' }],
+      }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchKnowledgeHandler({
+      query: 'Find ColdIQ decision makers',
+      types: ['play'],
+      limit: 3,
+    })
+
+    expect(capturedUrl).toBe('http://test-api.local/v1/knowledge/search')
+    expect(capturedBody).toEqual({
+      query: 'Find ColdIQ decision makers',
+      types: ['play'],
+      limit: 3,
+    })
+    expect(result.isError).toBeFalsy()
+    expect(JSON.parse(result.content[0].text).results[0].slug).toBe('find-people')
+  })
+
+  it('defaults to workflow knowledge while preserving explicit provider searches', async () => {
+    const bodies: unknown[] = []
+    globalThis.fetch = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+      bodies.push(JSON.parse(String(init?.body)))
+      return new Response(JSON.stringify({ results: [] }), { status: 200 })
+    }) as typeof fetch
+
+    await searchKnowledgeHandler({ query: 'Build a list of ColdIQ decision makers' })
+    await searchKnowledgeHandler({ query: 'Apollo request schema', types: ['provider'] })
+
+    expect(bodies).toEqual([
+      {
+        query: 'Build a list of ColdIQ decision makers',
+        types: ['play', 'strategy'],
+      },
+      {
+        query: 'Apollo request schema',
+        types: ['provider'],
+      },
+    ])
+  })
+
+  it('returns a sanitized error without forwarding response details', async () => {
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      error: 'database password secret leaked',
+      stack: 'internal stack',
+    }), { status: 500 })) as typeof fetch
+
+    const result = await searchKnowledgeHandler({ query: 'Find decision makers' })
+    const error = JSON.parse(result.content[0].text)
+
+    expect(result.isError).toBe(true)
+    expect(error).toEqual({ error: 'Knowledge search failed', status: 500 })
+    expect(result.content[0].text).not.toContain('secret')
+    expect(result.content[0].text).not.toContain('stack')
+  })
+})