@coldiq/mcp 0.4.7 → 0.5.0

package/dist/index.js

@@ -2,7 +2,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { initClient } from './client.js';
+import { MCP_SERVER_INSTRUCTIONS } from './instructions.js';
+import { withKnowledgeFirstRequirement } from './knowledge-policy.js';
 import { readPackageVersion } from './version.js';
+import { searchKnowledgeName, searchKnowledgeDescription, searchKnowledgeSchema, searchKnowledgeHandler, } from './tools/search-knowledge.js';
 import { searchCompaniesName, searchCompaniesDescription, searchCompaniesSchema, searchCompaniesHandler, } from './tools/search-companies.js';
 import { findPeopleName, findPeopleDescription, findPeopleSchema, findPeopleHandler, } from './tools/find-people.js';
 import { findEmailName, findEmailDescription, findEmailSchema, findEmailHandler, } from './tools/find-email.js';
@@ -51,53 +54,46 @@ const server = new McpServer({
     name: 'coldiq',
     version: packageVersion,
 }, {
-    // Surfaced to the model at init. Enforces batching on the multi-company
-    // prospecting flow — the dominant latency driver. Looping these tools
-    // per-item multiplies wall-clock with zero quality gain: find_people runs a
-    // ~90s async job per call, so N looped calls cost ~N×90s vs ~90s batched.
-    instructions: [
-        'ColdIQ prospecting tools. Always BATCH, never loop, to keep multi-step prospecting fast:',
-        '1. To find people across several companies, make ONE find_people call passing every company in company_linkedin_urls (preferred) or company_domains — never one call per company. Set limit = (results wanted per company) × (number of companies).',
-        '2. To find emails for several people, make ONE find_emails call with all of them — never loop find_email per person. find_emails runs providers in parallel and is several times faster.',
-        '3. Typical flow: search_companies → find_people (one batched call) → find_emails (one batched call).',
-    ].join('\n'),
+    instructions: MCP_SERVER_INSTRUCTIONS,
 });
-// Register all tools
-server.tool(searchCompaniesName, searchCompaniesDescription, searchCompaniesSchema, searchCompaniesHandler);
-server.tool(findPeopleName, findPeopleDescription, findPeopleSchema, findPeopleHandler);
-server.tool(findEmailName, findEmailDescription, findEmailSchema, findEmailHandler);
-server.tool(enrichPersonName, enrichPersonDescription, enrichPersonSchema, enrichPersonHandler);
-server.tool(findEmailsName, findEmailsDescription, findEmailsSchema, findEmailsHandler);
-server.tool(verifyEmailName, verifyEmailDescription, verifyEmailSchema, verifyEmailHandler);
-server.tool(verifyEmailsBulkName, verifyEmailsBulkDescription, verifyEmailsBulkSchema, verifyEmailsBulkHandler);
-server.tool(findEmailsBulkName, findEmailsBulkDescription, findEmailsBulkSchema, findEmailsBulkHandler);
-server.tool(enrichPersonBulkName, enrichPersonBulkDescription, enrichPersonBulkSchema, enrichPersonBulkHandler);
-server.tool(enrichCompanyBulkName, enrichCompanyBulkDescription, enrichCompanyBulkSchema, enrichCompanyBulkHandler);
-server.tool(findPhoneBulkName, findPhoneBulkDescription, findPhoneBulkSchema, findPhoneBulkHandler);
-server.tool(getBulkJobName, getBulkJobDescription, getBulkJobSchema, getBulkJobHandler);
-server.tool(cancelBulkJobName, cancelBulkJobDescription, cancelBulkJobSchema, cancelBulkJobHandler);
-server.tool(findPhoneName, findPhoneDescription, findPhoneSchema, findPhoneHandler);
-server.tool(enrichCompanyName, enrichCompanyDescription, enrichCompanySchema, enrichCompanyHandler);
-server.tool(searchWebName, searchWebDescription, searchWebSchema, searchWebHandler);
-server.tool(searchJobsName, searchJobsDescription, searchJobsSchema, searchJobsHandler);
-server.tool(searchAdsName, searchAdsDescription, searchAdsSchema, searchAdsHandler);
-server.tool(searchPlacesName, searchPlacesDescription, searchPlacesSchema, searchPlacesHandler);
-server.tool(findInfluencersName, findInfluencersDescription, findInfluencersSchema, findInfluencersHandler);
-server.tool(searchRedditName, searchRedditDescription, searchRedditSchema, searchRedditHandler);
-server.tool(searchSeoName, searchSeoDescription, searchSeoSchema, searchSeoHandler);
-server.tool(findSignalsName, findSignalsDescription, findSignalsSchema, findSignalsHandler);
-server.tool(fetchPageContentName, fetchPageContentDescription, fetchPageContentSchema, fetchPageContentHandler);
+// Register knowledge retrieval before every operational tool so clients that
+// preserve registration order surface the mandatory prerequisite first.
+server.tool(searchKnowledgeName, searchKnowledgeDescription, searchKnowledgeSchema, searchKnowledgeHandler);
+server.tool(searchCompaniesName, withKnowledgeFirstRequirement(searchCompaniesDescription), searchCompaniesSchema, searchCompaniesHandler);
+server.tool(findPeopleName, withKnowledgeFirstRequirement(findPeopleDescription), findPeopleSchema, findPeopleHandler);
+server.tool(findEmailName, withKnowledgeFirstRequirement(findEmailDescription), findEmailSchema, findEmailHandler);
+server.tool(enrichPersonName, withKnowledgeFirstRequirement(enrichPersonDescription), enrichPersonSchema, enrichPersonHandler);
+server.tool(findEmailsName, withKnowledgeFirstRequirement(findEmailsDescription), findEmailsSchema, findEmailsHandler);
+server.tool(verifyEmailName, withKnowledgeFirstRequirement(verifyEmailDescription), verifyEmailSchema, verifyEmailHandler);
+server.tool(verifyEmailsBulkName, withKnowledgeFirstRequirement(verifyEmailsBulkDescription), verifyEmailsBulkSchema, verifyEmailsBulkHandler);
+server.tool(findEmailsBulkName, withKnowledgeFirstRequirement(findEmailsBulkDescription), findEmailsBulkSchema, findEmailsBulkHandler);
+server.tool(enrichPersonBulkName, withKnowledgeFirstRequirement(enrichPersonBulkDescription), enrichPersonBulkSchema, enrichPersonBulkHandler);
+server.tool(enrichCompanyBulkName, withKnowledgeFirstRequirement(enrichCompanyBulkDescription), enrichCompanyBulkSchema, enrichCompanyBulkHandler);
+server.tool(findPhoneBulkName, withKnowledgeFirstRequirement(findPhoneBulkDescription), findPhoneBulkSchema, findPhoneBulkHandler);
+server.tool(getBulkJobName, withKnowledgeFirstRequirement(getBulkJobDescription), getBulkJobSchema, getBulkJobHandler);
+server.tool(cancelBulkJobName, withKnowledgeFirstRequirement(cancelBulkJobDescription), cancelBulkJobSchema, cancelBulkJobHandler);
+server.tool(findPhoneName, withKnowledgeFirstRequirement(findPhoneDescription), findPhoneSchema, findPhoneHandler);
+server.tool(enrichCompanyName, withKnowledgeFirstRequirement(enrichCompanyDescription), enrichCompanySchema, enrichCompanyHandler);
+server.tool(searchWebName, withKnowledgeFirstRequirement(searchWebDescription), searchWebSchema, searchWebHandler);
+server.tool(searchJobsName, withKnowledgeFirstRequirement(searchJobsDescription), searchJobsSchema, searchJobsHandler);
+server.tool(searchAdsName, withKnowledgeFirstRequirement(searchAdsDescription), searchAdsSchema, searchAdsHandler);
+server.tool(searchPlacesName, withKnowledgeFirstRequirement(searchPlacesDescription), searchPlacesSchema, searchPlacesHandler);
+server.tool(findInfluencersName, withKnowledgeFirstRequirement(findInfluencersDescription), findInfluencersSchema, findInfluencersHandler);
+server.tool(searchRedditName, withKnowledgeFirstRequirement(searchRedditDescription), searchRedditSchema, searchRedditHandler);
+server.tool(searchSeoName, withKnowledgeFirstRequirement(searchSeoDescription), searchSeoSchema, searchSeoHandler);
+server.tool(findSignalsName, withKnowledgeFirstRequirement(findSignalsDescription), findSignalsSchema, findSignalsHandler);
+server.tool(fetchPageContentName, withKnowledgeFirstRequirement(fetchPageContentDescription), fetchPageContentSchema, fetchPageContentHandler);
 server.tool(getCreditBalanceName, getCreditBalanceDescription, getCreditBalanceSchema, getCreditBalanceHandler);
 server.tool(getSessionUsageName, getSessionUsageDescription, getSessionUsageSchema, getSessionUsageHandler);
-server.tool(listDataSourcesName, listDataSourcesDescription, listDataSourcesSchema, listDataSourcesHandler);
+server.tool(listDataSourcesName, withKnowledgeFirstRequirement(listDataSourcesDescription), listDataSourcesSchema, listDataSourcesHandler);
 server.tool(listSkillsName, listSkillsDescription, listSkillsSchema, listSkillsHandler);
 server.tool(loadSkillName, loadSkillDescription, loadSkillSchema, loadSkillHandler);
-server.tool(extractPostEngagementName, extractPostEngagementDescription, extractPostEngagementSchema, extractPostEngagementHandler);
-server.tool(getPlaceReviewsName, getPlaceReviewsDescription, getPlaceReviewsSchema, getPlaceReviewsHandler);
+server.tool(extractPostEngagementName, withKnowledgeFirstRequirement(extractPostEngagementDescription), extractPostEngagementSchema, extractPostEngagementHandler);
+server.tool(getPlaceReviewsName, withKnowledgeFirstRequirement(getPlaceReviewsDescription), getPlaceReviewsSchema, getPlaceReviewsHandler);
 // Generic endpoint discovery + invoke: reach any integrated provider without a dedicated tool.
-server.tool(searchEndpointsName, searchEndpointsDescription, searchEndpointsSchema, searchEndpointsHandler);
-server.tool(getEndpointDetailsName, getEndpointDetailsDescription, getEndpointDetailsSchema, getEndpointDetailsHandler);
-server.tool(callEndpointName, callEndpointDescription, callEndpointSchema, callEndpointHandler);
+server.tool(searchEndpointsName, withKnowledgeFirstRequirement(searchEndpointsDescription), searchEndpointsSchema, searchEndpointsHandler);
+server.tool(getEndpointDetailsName, withKnowledgeFirstRequirement(getEndpointDetailsDescription), getEndpointDetailsSchema, getEndpointDetailsHandler);
+server.tool(callEndpointName, withKnowledgeFirstRequirement(callEndpointDescription), callEndpointSchema, callEndpointHandler);
 // Connect via stdio transport
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/instructions.d.ts

@@ -0,0 +1,3 @@
+export declare const MANDATORY_KNOWLEDGE_FIRST_RULE = "For every new substantive GTM task, you MUST call `search_knowledge` as the first ColdIQ tool, before endpoint discovery or data calls. Pass the user\u2019s complete task as the query. Follow the retrieved play and provider order. Do not reuse knowledge from a previous task. If search fails or returns no usable result, continue with endpoint discovery.";
+export declare const MCP_SERVER_INSTRUCTIONS: string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8BAA8B,uWACsT,CAAA;AAEjW,eAAO,MAAM,uBAAuB,QAMxB,CAAA"}

package/dist/instructions.js

@@ -0,0 +1,9 @@
+export const MANDATORY_KNOWLEDGE_FIRST_RULE = 'For every new substantive GTM task, you MUST call `search_knowledge` as the first ColdIQ tool, before endpoint discovery or data calls. Pass the user’s complete task as the query. Follow the retrieved play and provider order. Do not reuse knowledge from a previous task. If search fails or returns no usable result, continue with endpoint discovery.';
+export const MCP_SERVER_INSTRUCTIONS = [
+    MANDATORY_KNOWLEDGE_FIRST_RULE,
+    '',
+    'Retrieved knowledge controls the workflow and provider order; do not invent or override them. Prefer batched dedicated tools when they fit, and batch inputs instead of looping. Otherwise use `search_endpoints` → `get_endpoint_details` → `call_endpoint`.',
+    'Stop as soon as the requested count and fields are satisfied. Include source/provider attribution and disclose gaps or uncertainty.',
+    '`list_skills` and `load_skill` are legacy compatibility tools; prefer knowledge retrieval. Greetings, acknowledgements, balance checks, and other non-GTM administrative requests may skip knowledge search.',
+].join('\n');
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,8BAA8B,GACzC,+VAA+V,CAAA;AAEjW,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,8BAA8B;IAC9B,EAAE;IACF,+PAA+P;IAC/P,qIAAqI;IACrI,8MAA8M;CAC/M,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA"}

package/dist/knowledge-policy.d.ts

@@ -0,0 +1,3 @@
+export declare const KNOWLEDGE_FIRST_REQUIREMENT = "For every new substantive GTM task, call search_knowledge as the first ColdIQ tool and pass the user\u2019s complete task as the query.";
+export declare function withKnowledgeFirstRequirement(description: string): string;
+//# sourceMappingURL=knowledge-policy.d.ts.map

package/dist/knowledge-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-policy.d.ts","sourceRoot":"","sources":["../src/knowledge-policy.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,4IAC8F,CAAA;AAEtI,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/dist/knowledge-policy.js

@@ -0,0 +1,5 @@
+export const KNOWLEDGE_FIRST_REQUIREMENT = 'For every new substantive GTM task, call search_knowledge as the first ColdIQ tool and pass the user’s complete task as the query.';
+export function withKnowledgeFirstRequirement(description) {
+    return `${KNOWLEDGE_FIRST_REQUIREMENT} ${description}`;
+}
+//# sourceMappingURL=knowledge-policy.js.map

package/dist/knowledge-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-policy.js","sourceRoot":"","sources":["../src/knowledge-policy.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,2BAA2B,GACtC,oIAAoI,CAAA;AAEtI,MAAM,UAAU,6BAA6B,CAAC,WAAmB;IAC/D,OAAO,GAAG,2BAA2B,IAAI,WAAW,EAAE,CAAA;AACxD,CAAC"}

package/dist/tools/list-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-skills.d.ts","sourceRoot":"","sources":["../../src/tools/list-skills.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAMkE,CAAA;AAEpG,eAAO,MAAM,gBAAgB,IAAK,CAAA;AAElC,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAUtE"}
+{"version":3,"file":"list-skills.d.ts","sourceRoot":"","sources":["../../src/tools/list-skills.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAOkE,CAAA;AAEpG,eAAO,MAAM,gBAAgB,IAAK,CAAA;AAElC,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAUtE"}

package/dist/tools/list-skills.js

@@ -1,10 +1,11 @@
 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 ' +
+export const listSkillsDescription = '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 = {};
 export async function listSkillsHandler(_input) {

package/dist/tools/list-skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-skills.js","sourceRoot":"","sources":["../../src/tools/list-skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,MAAM,CAAC,MAAM,qBAAqB,GAChC,sGAAsG;IACtG,oGAAoG;IACpG,wGAAwG;IACxG,wGAAwG;IACxG,uGAAuG;IACvG,kGAAkG,CAAA;AAEpG,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAElC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAA+B;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;QACjC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;IACzF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,6CAA8C,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;YAC5I,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"list-skills.js","sourceRoot":"","sources":["../../src/tools/list-skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,MAAM,CAAC,MAAM,qBAAqB,GAChC,8GAA8G;IAC9G,oGAAoG;IACpG,iDAAiD;IACjD,oGAAoG;IACpG,wGAAwG;IACxG,6FAA6F;IAC7F,kGAAkG,CAAA;AAEpG,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAA;AAElC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAA+B;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;QACjC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;IACzF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,6CAA8C,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;YAC5I,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/tools/load-skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-skill.d.ts","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,oBAAoB,QAIK,CAAA;AAEtC,eAAO,MAAM,eAAe;;CAI3B,CAAA;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAcpE"}
+{"version":3,"file":"load-skill.d.ts","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,oBAAoB,QAKK,CAAA;AAEtC,eAAO,MAAM,eAAe;;CAI3B,CAAA;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAcpE"}

package/dist/tools/load-skill.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 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, ' +
+export const loadSkillDescription = '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/dist/tools/load-skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-skill.js","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAC/B,mGAAmG;IACnG,2GAA2G;IAC3G,0GAA0G;IAC1G,oCAAoC,CAAA;AAEtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CAAC,gGAAgG,CAAC;CAC9G,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA8B;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,wEAAwE,EAAE,CAAC;YACpH,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAA;QAClC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC9F,CAAC;AACH,CAAC"}
+{"version":3,"file":"load-skill.js","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAC/B,uGAAuG;IACvG,iEAAiE;IACjE,2GAA2G;IAC3G,0GAA0G;IAC1G,oCAAoC,CAAA;AAEtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CAAC,gGAAgG,CAAC;CAC9G,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA8B;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,wEAAwE,EAAE,CAAC;YACpH,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAA;QAClC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC9F,CAAC;AACH,CAAC"}

package/dist/tools/search-knowledge.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const searchKnowledgeName = "search_knowledge";
+export declare const searchKnowledgeDescription: string;
+export declare const searchKnowledgeSchema: {
+    query: z.ZodString;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<["play", "provider", "strategy"]>, "many">>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+};
+export declare function searchKnowledgeHandler(input: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+//# sourceMappingURL=search-knowledge.d.ts.map

package/dist/tools/search-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-knowledge.d.ts","sourceRoot":"","sources":["../../src/tools/search-knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAErD,eAAO,MAAM,0BAA0B,QAIkF,CAAA;AAEzH,eAAO,MAAM,qBAAqB;;;;CAiBjC,CAAA;AAED,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAgB1E"}

package/dist/tools/search-knowledge.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { callApi } from '../client.js';
+const KNOWLEDGE_DOC_TYPES = ['play', 'provider', 'strategy'];
+const DEFAULT_KNOWLEDGE_DOC_TYPES = ['play', 'strategy'];
+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) {
+    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',
+                    text: JSON.stringify({ error: 'Knowledge search failed', status: res.status }),
+                }],
+            isError: true,
+        };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(res.data) }] };
+}
+//# sourceMappingURL=search-knowledge.js.map

package/dist/tools/search-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-knowledge.js","sourceRoot":"","sources":["../../src/tools/search-knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAU,CAAA;AACrE,MAAM,2BAA2B,GAAG,CAAC,MAAM,EAAE,UAAU,CAAU,CAAA;AAEjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAA;AAErD,MAAM,CAAC,MAAM,0BAA0B,GACrC,gHAAgH;IAChH,kHAAkH;IAClH,iHAAiH;IACjH,uHAAuH,CAAA;AAEzH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CAAC,sGAAsG,CAAC;IACnH,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,oJAAoJ,CAAC;IACjK,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,yDAAyD,CAAC;CACvE,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAA8B;IACzE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,mBAAmB,EAAE;QACrD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,GAAG,2BAA2B,CAAC;QACtD,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC,CAAA;IACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,yBAAyB,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;iBAC/E,CAAC;YACF,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAA;AACjF,CAAC"}

package/package.json

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

package/src/index.ts

@@ -3,7 +3,15 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { initClient } from './client.js'
+import { MCP_SERVER_INSTRUCTIONS } from './instructions.js'
+import { withKnowledgeFirstRequirement } from './knowledge-policy.js'
 import { readPackageVersion } from './version.js'
+import {
+  searchKnowledgeName,
+  searchKnowledgeDescription,
+  searchKnowledgeSchema,
+  searchKnowledgeHandler,
+} from './tools/search-knowledge.js'
 
 import {
   searchCompaniesName,
@@ -201,55 +209,48 @@ const server = new McpServer(
     version: packageVersion,
   },
   {
-    // Surfaced to the model at init. Enforces batching on the multi-company
-    // prospecting flow — the dominant latency driver. Looping these tools
-    // per-item multiplies wall-clock with zero quality gain: find_people runs a
-    // ~90s async job per call, so N looped calls cost ~N×90s vs ~90s batched.
-    instructions: [
-      'ColdIQ prospecting tools. Always BATCH, never loop, to keep multi-step prospecting fast:',
-      '1. To find people across several companies, make ONE find_people call passing every company in company_linkedin_urls (preferred) or company_domains — never one call per company. Set limit = (results wanted per company) × (number of companies).',
-      '2. To find emails for several people, make ONE find_emails call with all of them — never loop find_email per person. find_emails runs providers in parallel and is several times faster.',
-      '3. Typical flow: search_companies → find_people (one batched call) → find_emails (one batched call).',
-    ].join('\n'),
+    instructions: MCP_SERVER_INSTRUCTIONS,
   },
 )
 
-// Register all tools
-server.tool(searchCompaniesName, searchCompaniesDescription, searchCompaniesSchema, searchCompaniesHandler)
-server.tool(findPeopleName, findPeopleDescription, findPeopleSchema, findPeopleHandler)
-server.tool(findEmailName, findEmailDescription, findEmailSchema, findEmailHandler)
-server.tool(enrichPersonName, enrichPersonDescription, enrichPersonSchema, enrichPersonHandler)
-server.tool(findEmailsName, findEmailsDescription, findEmailsSchema, findEmailsHandler)
-server.tool(verifyEmailName, verifyEmailDescription, verifyEmailSchema, verifyEmailHandler)
-server.tool(verifyEmailsBulkName, verifyEmailsBulkDescription, verifyEmailsBulkSchema, verifyEmailsBulkHandler)
-server.tool(findEmailsBulkName, findEmailsBulkDescription, findEmailsBulkSchema, findEmailsBulkHandler)
-server.tool(enrichPersonBulkName, enrichPersonBulkDescription, enrichPersonBulkSchema, enrichPersonBulkHandler)
-server.tool(enrichCompanyBulkName, enrichCompanyBulkDescription, enrichCompanyBulkSchema, enrichCompanyBulkHandler)
-server.tool(findPhoneBulkName, findPhoneBulkDescription, findPhoneBulkSchema, findPhoneBulkHandler)
-server.tool(getBulkJobName, getBulkJobDescription, getBulkJobSchema, getBulkJobHandler)
-server.tool(cancelBulkJobName, cancelBulkJobDescription, cancelBulkJobSchema, cancelBulkJobHandler)
-server.tool(findPhoneName, findPhoneDescription, findPhoneSchema, findPhoneHandler)
-server.tool(enrichCompanyName, enrichCompanyDescription, enrichCompanySchema, enrichCompanyHandler)
-server.tool(searchWebName, searchWebDescription, searchWebSchema, searchWebHandler)
-server.tool(searchJobsName, searchJobsDescription, searchJobsSchema, searchJobsHandler)
-server.tool(searchAdsName, searchAdsDescription, searchAdsSchema, searchAdsHandler)
-server.tool(searchPlacesName, searchPlacesDescription, searchPlacesSchema, searchPlacesHandler)
-server.tool(findInfluencersName, findInfluencersDescription, findInfluencersSchema, findInfluencersHandler)
-server.tool(searchRedditName, searchRedditDescription, searchRedditSchema, searchRedditHandler)
-server.tool(searchSeoName, searchSeoDescription, searchSeoSchema, searchSeoHandler)
-server.tool(findSignalsName, findSignalsDescription, findSignalsSchema, findSignalsHandler)
-server.tool(fetchPageContentName, fetchPageContentDescription, fetchPageContentSchema, fetchPageContentHandler)
+// Register knowledge retrieval before every operational tool so clients that
+// preserve registration order surface the mandatory prerequisite first.
+server.tool(searchKnowledgeName, searchKnowledgeDescription, searchKnowledgeSchema, searchKnowledgeHandler)
+server.tool(searchCompaniesName, withKnowledgeFirstRequirement(searchCompaniesDescription), searchCompaniesSchema, searchCompaniesHandler)
+server.tool(findPeopleName, withKnowledgeFirstRequirement(findPeopleDescription), findPeopleSchema, findPeopleHandler)
+server.tool(findEmailName, withKnowledgeFirstRequirement(findEmailDescription), findEmailSchema, findEmailHandler)
+server.tool(enrichPersonName, withKnowledgeFirstRequirement(enrichPersonDescription), enrichPersonSchema, enrichPersonHandler)
+server.tool(findEmailsName, withKnowledgeFirstRequirement(findEmailsDescription), findEmailsSchema, findEmailsHandler)
+server.tool(verifyEmailName, withKnowledgeFirstRequirement(verifyEmailDescription), verifyEmailSchema, verifyEmailHandler)
+server.tool(verifyEmailsBulkName, withKnowledgeFirstRequirement(verifyEmailsBulkDescription), verifyEmailsBulkSchema, verifyEmailsBulkHandler)
+server.tool(findEmailsBulkName, withKnowledgeFirstRequirement(findEmailsBulkDescription), findEmailsBulkSchema, findEmailsBulkHandler)
+server.tool(enrichPersonBulkName, withKnowledgeFirstRequirement(enrichPersonBulkDescription), enrichPersonBulkSchema, enrichPersonBulkHandler)
+server.tool(enrichCompanyBulkName, withKnowledgeFirstRequirement(enrichCompanyBulkDescription), enrichCompanyBulkSchema, enrichCompanyBulkHandler)
+server.tool(findPhoneBulkName, withKnowledgeFirstRequirement(findPhoneBulkDescription), findPhoneBulkSchema, findPhoneBulkHandler)
+server.tool(getBulkJobName, withKnowledgeFirstRequirement(getBulkJobDescription), getBulkJobSchema, getBulkJobHandler)
+server.tool(cancelBulkJobName, withKnowledgeFirstRequirement(cancelBulkJobDescription), cancelBulkJobSchema, cancelBulkJobHandler)
+server.tool(findPhoneName, withKnowledgeFirstRequirement(findPhoneDescription), findPhoneSchema, findPhoneHandler)
+server.tool(enrichCompanyName, withKnowledgeFirstRequirement(enrichCompanyDescription), enrichCompanySchema, enrichCompanyHandler)
+server.tool(searchWebName, withKnowledgeFirstRequirement(searchWebDescription), searchWebSchema, searchWebHandler)
+server.tool(searchJobsName, withKnowledgeFirstRequirement(searchJobsDescription), searchJobsSchema, searchJobsHandler)
+server.tool(searchAdsName, withKnowledgeFirstRequirement(searchAdsDescription), searchAdsSchema, searchAdsHandler)
+server.tool(searchPlacesName, withKnowledgeFirstRequirement(searchPlacesDescription), searchPlacesSchema, searchPlacesHandler)
+server.tool(findInfluencersName, withKnowledgeFirstRequirement(findInfluencersDescription), findInfluencersSchema, findInfluencersHandler)
+server.tool(searchRedditName, withKnowledgeFirstRequirement(searchRedditDescription), searchRedditSchema, searchRedditHandler)
+server.tool(searchSeoName, withKnowledgeFirstRequirement(searchSeoDescription), searchSeoSchema, searchSeoHandler)
+server.tool(findSignalsName, withKnowledgeFirstRequirement(findSignalsDescription), findSignalsSchema, findSignalsHandler)
+server.tool(fetchPageContentName, withKnowledgeFirstRequirement(fetchPageContentDescription), fetchPageContentSchema, fetchPageContentHandler)
 server.tool(getCreditBalanceName, getCreditBalanceDescription, getCreditBalanceSchema, getCreditBalanceHandler)
 server.tool(getSessionUsageName, getSessionUsageDescription, getSessionUsageSchema, getSessionUsageHandler)
-server.tool(listDataSourcesName, listDataSourcesDescription, listDataSourcesSchema, listDataSourcesHandler)
+server.tool(listDataSourcesName, withKnowledgeFirstRequirement(listDataSourcesDescription), listDataSourcesSchema, listDataSourcesHandler)
 server.tool(listSkillsName, listSkillsDescription, listSkillsSchema, listSkillsHandler)
 server.tool(loadSkillName, loadSkillDescription, loadSkillSchema, loadSkillHandler)
-server.tool(extractPostEngagementName, extractPostEngagementDescription, extractPostEngagementSchema, extractPostEngagementHandler)
-server.tool(getPlaceReviewsName, getPlaceReviewsDescription, getPlaceReviewsSchema, getPlaceReviewsHandler)
+server.tool(extractPostEngagementName, withKnowledgeFirstRequirement(extractPostEngagementDescription), extractPostEngagementSchema, extractPostEngagementHandler)
+server.tool(getPlaceReviewsName, withKnowledgeFirstRequirement(getPlaceReviewsDescription), getPlaceReviewsSchema, getPlaceReviewsHandler)
 // Generic endpoint discovery + invoke: reach any integrated provider without a dedicated tool.
-server.tool(searchEndpointsName, searchEndpointsDescription, searchEndpointsSchema, searchEndpointsHandler)
-server.tool(getEndpointDetailsName, getEndpointDetailsDescription, getEndpointDetailsSchema, getEndpointDetailsHandler)
-server.tool(callEndpointName, callEndpointDescription, callEndpointSchema, callEndpointHandler)
+server.tool(searchEndpointsName, withKnowledgeFirstRequirement(searchEndpointsDescription), searchEndpointsSchema, searchEndpointsHandler)
+server.tool(getEndpointDetailsName, withKnowledgeFirstRequirement(getEndpointDetailsDescription), getEndpointDetailsSchema, getEndpointDetailsHandler)
+server.tool(callEndpointName, withKnowledgeFirstRequirement(callEndpointDescription), callEndpointSchema, callEndpointHandler)
 
 // Connect via stdio transport
 const transport = new StdioServerTransport()

package/src/instructions.ts

@@ -0,0 +1,10 @@
+export const MANDATORY_KNOWLEDGE_FIRST_RULE =
+  'For every new substantive GTM task, you MUST call `search_knowledge` as the first ColdIQ tool, before endpoint discovery or data calls. Pass the user’s complete task as the query. Follow the retrieved play and provider order. Do not reuse knowledge from a previous task. If search fails or returns no usable result, continue with endpoint discovery.'
+
+export const MCP_SERVER_INSTRUCTIONS = [
+  MANDATORY_KNOWLEDGE_FIRST_RULE,
+  '',
+  'Retrieved knowledge controls the workflow and provider order; do not invent or override them. Prefer batched dedicated tools when they fit, and batch inputs instead of looping. Otherwise use `search_endpoints` → `get_endpoint_details` → `call_endpoint`.',
+  'Stop as soon as the requested count and fields are satisfied. Include source/provider attribution and disclose gaps or uncertainty.',
+  '`list_skills` and `load_skill` are legacy compatibility tools; prefer knowledge retrieval. Greetings, acknowledgements, balance checks, and other non-GTM administrative requests may skip knowledge search.',
+].join('\n')

package/src/knowledge-policy.ts

@@ -0,0 +1,6 @@
+export const KNOWLEDGE_FIRST_REQUIREMENT =
+  'For every new substantive GTM task, call search_knowledge as the first ColdIQ tool and pass the user’s complete task as the query.'
+
+export function withKnowledgeFirstRequirement(description: string): string {
+  return `${KNOWLEDGE_FIRST_REQUIREMENT} ${description}`
+}

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/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/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')
+  })
+})