@llmindset/hf-mcp 0.2.5 → 0.2.7

package/src/dataset-search.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HfApiCall } from './hf-api-call.js';
 import { formatDate, formatNumber } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
 const TAGS_TO_RETURN = 20;
 // Dataset Search Tool Configuration
 export const DATASET_SEARCH_TOOL_CONFIG = {
@@ -83,7 +84,7 @@ export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiRes
 	/**
 	 * Search for datasets with detailed parameters
 	 */
-	async searchWithParams(params: Partial<DatasetSearchParams>): Promise<string> {
+	async searchWithParams(params: Partial<DatasetSearchParams>): Promise<ToolResult> {
 		try {
 			// Convert our params to the HF API format
 			const apiParams: DatasetApiParams = {};
@@ -118,7 +119,11 @@ export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiRes
 			const datasets = await this.callApi<DatasetApiResult[]>(apiParams);
 
 			if (datasets.length === 0) {
-				return `No datasets found for the given criteria.`;
+				return {
+					formatted: `No datasets found for the given criteria.`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			return formatSearchResults(datasets, params);
@@ -133,7 +138,7 @@ export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiRes
 	/**
 	 * Search for datasets with a specific filter (e.g., arxiv:XXXX.XXXXX)
 	 */
-	async searchWithFilter(filter: string, limit: number = 10): Promise<string> {
+	async searchWithFilter(filter: string, limit: number = 10): Promise<ToolResult> {
 		try {
 			const apiParams: DatasetApiParams = {
 				filter: filter,
@@ -146,7 +151,11 @@ export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiRes
 			const datasets = await this.callApi<DatasetApiResult[]>(apiParams);
 
 			if (datasets.length === 0) {
-				return `No datasets found referencing ${filter}.`;
+				return {
+					formatted: `No datasets found referencing ${filter}.`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			return formatSearchResults(datasets, { limit });
@@ -160,7 +169,7 @@ export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiRes
 }
 
 // Formatting Function
-function formatSearchResults(datasets: DatasetApiResult[], params: Partial<DatasetSearchParams>): string {
+function formatSearchResults(datasets: DatasetApiResult[], params: Partial<DatasetSearchParams>): ToolResult {
 	const r: string[] = [];
 
 	// Build search description
@@ -233,5 +242,9 @@ function formatSearchResults(datasets: DatasetApiResult[], params: Partial<Datas
 		r.push('');
 	}
 
-	return r.join('\n');
+	return {
+		formatted: r.join('\n'),
+		totalResults: datasets.length,
+		resultsShared: datasets.length
+	};
 }

package/src/docs-search/doc-fetch.ts

@@ -39,7 +39,6 @@ export class DocFetchTool {
 		this.turndownService.remove('head');
 		this.turndownService.remove('script');
 		this.turndownService.remove((node) => {
-			console.log(`${node.nodeName}	`);
 			if (node.nodeName === 'a' && node.innerHTML.includes('<!-- HTML_TAG_START -->')) {
 				return true;
 			}

package/src/docs-search/docs-semantic-search.test.ts

@@ -26,7 +26,9 @@ describe('DocSearchTool', () => {
 			});
 
 			const result = await docSearchTool.search({ query: 'nonexistent' });
-			expect(result).toBe(`No documentation found for query 'nonexistent'`);
+			expect(result.formatted).toBe(`No documentation found for query 'nonexistent'`);
+			expect(result.totalResults).toBe(0);
+			expect(result.resultsShared).toBe(0);
 		});
 
 		it('should return no results message with product filter', async () => {
@@ -36,7 +38,9 @@ describe('DocSearchTool', () => {
 			});
 
 			const result = await docSearchTool.search({ query: 'nonexistent', product: 'hub' });
-			expect(result).toBe(`No documentation found for query 'nonexistent' in product 'hub'`);
+			expect(result.formatted).toBe(`No documentation found for query 'nonexistent' in product 'hub'`);
+			expect(result.totalResults).toBe(0);
+			expect(result.resultsShared).toBe(0);
 		});
 
 		it('should format results grouped by product and page', async () => {
@@ -74,37 +78,39 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'analytics' });
 
 			// Check header
-			expect(result).toContain('# Documentation Library Search Results for "analytics"');
-			expect(result).toContain('Found 3 results');
+			expect(result.formatted).toContain('# Documentation Library Search Results for "analytics"');
+			expect(result.formatted).toContain('Found 3 results');
+			expect(result.totalResults).toBe(3);
+			expect(result.resultsShared).toBe(3);
 
 			// Check product grouping - hub should come before dataset-viewer (hub has 2 results, dataset-viewer has 1)
-			const hubIndex = result.indexOf('## Results for Product: hub');
-			const datasetViewerIndex = result.indexOf('## Results for Product: dataset-viewer');
+			const hubIndex = result.formatted.indexOf('## Results for Product: hub');
+			const datasetViewerIndex = result.formatted.indexOf('## Results for Product: dataset-viewer');
 			expect(hubIndex).toBeLessThan(datasetViewerIndex);
 			expect(hubIndex).toBeGreaterThan(-1);
 			expect(datasetViewerIndex).toBeGreaterThan(-1);
 
 			// Check that result counts are shown
-			expect(result).toContain('## Results for Product: hub (2 results)');
-			expect(result).toContain('## Results for Product: dataset-viewer (1 results)');
+			expect(result.formatted).toContain('## Results for Product: hub (2 results)');
+			expect(result.formatted).toContain('## Results for Product: dataset-viewer (1 results)');
 
 			// Check page links (without anchors)
-			expect(result).toContain(
+			expect(result.formatted).toContain(
 				'### Results from [Analytics](https://huggingface.co/docs/hub/enterprise-hub-analytics)'
 			);
-			expect(result).toContain('### Results from [Quickstart](https://huggingface.co/docs/dataset-viewer/quick_start)');
+			expect(result.formatted).toContain('### Results from [Quickstart](https://huggingface.co/docs/dataset-viewer/quick_start)');
 
 			// Check excerpts with heading2
-			expect(result).toContain('#### Excerpt from the "Export Analytics as CSV" section');
-			expect(result).toContain('#### Excerpt from the "View Analytics" section');
+			expect(result.formatted).toContain('#### Excerpt from the "Export Analytics as CSV" section');
+			expect(result.formatted).toContain('#### Excerpt from the "View Analytics" section');
 
 			// Check excerpt content appears as plain text
-			expect(result).toContain('Download a comprehensive CSV file containing analytics');
-			expect(result).toContain('View analytics for your repositories');
-			expect(result).toContain('In this quickstart, you will learn how to use the dataset viewer REST API');
+			expect(result.formatted).toContain('Download a comprehensive CSV file containing analytics');
+			expect(result.formatted).toContain('View analytics for your repositories');
+			expect(result.formatted).toContain('In this quickstart, you will learn how to use the dataset viewer REST API');
 
 			// Check footer
-			expect(result).toContain('Use the "' + DOC_FETCH_CONFIG.name + '" tool to fetch a document from the library.');
+			expect(result.formatted).toContain('Use the "' + DOC_FETCH_CONFIG.name + '" tool to fetch a document from the library.');
 		});
 
 		it('should handle results without heading2', async () => {
@@ -126,8 +132,10 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'transformers' });
 
 			// Should not contain "Excerpt from" when heading2 is missing
-			expect(result).not.toContain('#### Excerpt from');
-			expect(result).toContain('This is a simple text without heading2');
+			expect(result.formatted).not.toContain('#### Excerpt from');
+			expect(result.formatted).toContain('This is a simple text without heading2');
+			expect(result.totalResults).toBe(1);
+			expect(result.resultsShared).toBe(1);
 		});
 
 		it('should properly escape markdown special characters', async () => {
@@ -150,9 +158,11 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'special' });
 
 			// Check that special characters are escaped in headings and page titles
-			expect(result).toContain('Special \\* Characters');
+			expect(result.formatted).toContain('Special \\* Characters');
 			// Note: heading2 appears in header text, but brackets don't get escaped
-			expect(result).toContain('#### Excerpt from the "Section with [brackets]" section');
+			expect(result.formatted).toContain('#### Excerpt from the "Section with [brackets]" section');
+			expect(result.totalResults).toBe(1);
+			expect(result.resultsShared).toBe(1);
 		});
 
 		it('should clean HTML tags from text', async () => {
@@ -174,9 +184,11 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'html' });
 
 			// HTML tags should be removed
-			expect(result).toContain('Text with HTML tags and');
-			expect(result).not.toContain('<div');
-			expect(result).not.toContain('<img');
+			expect(result.formatted).toContain('Text with HTML tags and');
+			expect(result.formatted).not.toContain('<div');
+			expect(result.formatted).not.toContain('<img');
+			expect(result.totalResults).toBe(1);
+			expect(result.resultsShared).toBe(1);
 		});
 
 		it('should sort multiple products and pages correctly by count', async () => {
@@ -229,23 +241,25 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'test' });
 
 			// Check product order by count: hub (3) > transformers (1) = datasets (1)
-			const hubIndex = result.indexOf('## Results for Product: hub');
-			const transformersIndex = result.indexOf('## Results for Product: transformers');
-			const datasetsIndex = result.indexOf('## Results for Product: datasets');
+			const hubIndex = result.formatted.indexOf('## Results for Product: hub');
+			const transformersIndex = result.formatted.indexOf('## Results for Product: transformers');
+			const datasetsIndex = result.formatted.indexOf('## Results for Product: datasets');
 
 			expect(hubIndex).toBeLessThan(transformersIndex);
 			expect(hubIndex).toBeLessThan(datasetsIndex);
 
 			// Check that hub shows total count
-			expect(result).toContain('## Results for Product: hub (3 results)');
+			expect(result.formatted).toContain('## Results for Product: hub (3 results)');
 
 			// Check page order within hub product: page1 (2 results) should come before page2 (1 result)
-			const page1Index = result.indexOf('https://huggingface.co/docs/hub/page1');
-			const page2Index = result.indexOf('https://huggingface.co/docs/hub/page2');
+			const page1Index = result.formatted.indexOf('https://huggingface.co/docs/hub/page1');
+			const page2Index = result.formatted.indexOf('https://huggingface.co/docs/hub/page2');
 			expect(page1Index).toBeLessThan(page2Index);
 
 			// Check that page1 shows its multiple results count
-			expect(result).toContain('### Results from [Page 1](https://huggingface.co/docs/hub/page1) (2 results)');
+			expect(result.formatted).toContain('### Results from [Page 1](https://huggingface.co/docs/hub/page1) (2 results)');
+			expect(result.totalResults).toBe(5);
+			expect(result.resultsShared).toBe(5);
 		});
 
 		it('should include product filter in API call when provided', async () => {
@@ -295,16 +309,18 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'analytics' });
 
 			// All three results should be grouped under one page heading (without anchor)
-			expect(result).toContain('### Results from [Analytics](https://huggingface.co/docs/hub/analytics) (3 results)');
+			expect(result.formatted).toContain('### Results from [Analytics](https://huggingface.co/docs/hub/analytics) (3 results)');
 
 			// All three excerpts should appear under the same page
-			expect(result).toContain('First result from section 1');
-			expect(result).toContain('Second result from section 2');
-			expect(result).toContain('Third result from section 3');
+			expect(result.formatted).toContain('First result from section 1');
+			expect(result.formatted).toContain('Second result from section 2');
+			expect(result.formatted).toContain('Third result from section 3');
 
 			// There should only be one "Results from" heading for this page
-			const resultsFromCount = (result.match(/### Results from/g) || []).length;
+			const resultsFromCount = (result.formatted.match(/### Results from/g) || []).length;
 			expect(resultsFromCount).toBe(1);
+			expect(result.totalResults).toBe(3);
+			expect(result.resultsShared).toBe(3);
 		});
 
 		it('should handle API errors gracefully', async () => {
@@ -349,33 +365,35 @@ describe('DocSearchTool', () => {
 			const result = await smallBudgetTool.search({ query: 'test' });
 
 			// Should contain the header
-			expect(result).toContain('# Documentation Library Search Results for "test"');
-			expect(result).toContain('Found 8 results');
+			expect(result.formatted).toContain('# Documentation Library Search Results for "test"');
+			expect(result.formatted).toContain('Found 8 results');
 
 			// Early results should have full content
-			expect(result).toContain('This is a very long text that repeats');
+			expect(result.formatted).toContain('This is a very long text that repeats');
 
 			// Debug: let's see what the result looks like
-			console.log('Result length:', result.length);
-			console.log('Estimated tokens:', Math.ceil(result.length / 3.3));
+			console.log('Result length:', result.formatted.length);
+			console.log('Estimated tokens:', Math.ceil(result.formatted.length / 3.3));
 			
 			// Check that early pages have content 
-			expect(result).toContain('#### Excerpt from the "Section 0" section');
-			expect(result).toContain('This is a very long text that repeats');
+			expect(result.formatted).toContain('#### Excerpt from the "Section 0" section');
+			expect(result.formatted).toContain('This is a very long text that repeats');
 			
 			// With token budget, we should see either truncation or link-only section
-			const hasTruncation = result.includes(`*[Content truncated - use ${DOC_FETCH_CONFIG.name} for full text or narrow search terms]*`);
-			const hasAdditionalResults = result.includes('## Further results were found in:');
+			const hasTruncation = result.formatted.includes(`*[Content truncated - use ${DOC_FETCH_CONFIG.name} for full text or narrow search terms]*`);
+			const hasAdditionalResults = result.formatted.includes('## Further results were found in:');
 			
 			
 			// At least one of these should indicate budget management
 			expect(hasTruncation || hasAdditionalResults).toBeTruthy();
 
 			// Should still contain the footer
-			expect(result).toContain(`Use the "${DOC_FETCH_CONFIG.name}" tool to fetch a document from the library.`);
+			expect(result.formatted).toContain(`Use the "${DOC_FETCH_CONFIG.name}" tool to fetch a document from the library.`);
 
 			// Result should be around our smaller token budget (5k tokens = ~16.5k chars)
-			expect(result.length).toBeLessThan(25000); // Should be controlled by token budget
+			expect(result.formatted.length).toBeLessThan(25000); // Should be controlled by token budget
+			expect(result.totalResults).toBe(8);
+			expect(result.resultsShared).toBe(8);
 		});
 	});
 
@@ -413,18 +431,20 @@ describe('DocSearchTool', () => {
 			const result = await docSearchTool.search({ query: 'test' });
 
 			// Verify grouping structure in output
-			expect(result).toContain('## Results for Product: hub');
-			expect(result).toContain('## Results for Product: transformers');
+			expect(result.formatted).toContain('## Results for Product: hub');
+			expect(result.formatted).toContain('## Results for Product: transformers');
 
 			// Verify that both results from the same page are together
-			const result1Index = result.indexOf('Result 1');
-			const result2Index = result.indexOf('Result 2');
-			const result3Index = result.indexOf('Result 3');
+			const result1Index = result.formatted.indexOf('Result 1');
+			const result2Index = result.formatted.indexOf('Result 2');
+			const result3Index = result.formatted.indexOf('Result 3');
 
 			// Results 1 and 2 should be close together (same page)
 			expect(Math.abs(result2Index - result1Index)).toBeLessThan(100);
 			// Result 3 should be further away (different product)
 			expect(Math.abs(result3Index - result1Index)).toBeGreaterThan(50);
+			expect(result.totalResults).toBe(3);
+			expect(result.resultsShared).toBe(3);
 		});
 	});
 });

package/src/docs-search/docs-semantic-search.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { HfApiCall } from '../hf-api-call.js';
 import { escapeMarkdown, estimateTokens } from '../utilities.js';
 import { DOC_FETCH_CONFIG } from './doc-fetch.js';
+import type { ToolResult } from '../types/tool-result.js';
 
 /** token estimation. initial results for "how to load a image to image model in transformers" returned
  * 121973 characters (36711 anthropic tokens) */
@@ -72,9 +73,13 @@ export class DocSearchTool extends HfApiCall<DocSearchApiParams, DocSearchResult
 	 * @param query Search query string (e.g. "rate limits", "analytics")
 	 * @param product Optional product filter
 	 */
-	async search(params: DocSearchParams): Promise<string> {
+	async search(params: DocSearchParams): Promise<ToolResult> {
 		try {
-			if (!params.query) return 'No query provided';
+			if (!params.query) return {
+				formatted: 'No query provided',
+				totalResults: 0,
+				resultsShared: 0
+			};
 
 			const apiParams: DocSearchApiParams = { q: params.query.toLowerCase() };
 			if (params.product) {
@@ -84,9 +89,13 @@ export class DocSearchTool extends HfApiCall<DocSearchApiParams, DocSearchResult
 			const results = await this.callApi<DocSearchResult[]>(apiParams);
 
 			if (results.length === 0) {
-				return params.product
-					? `No documentation found for query '${params.query}' in product '${params.product}'`
-					: `No documentation found for query '${params.query}'`;
+				return {
+					formatted: params.product
+						? `No documentation found for query '${params.query}' in product '${params.product}'`
+						: `No documentation found for query '${params.query}'`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			return formatSearchResults(params.query, results, params.product, this.tokenBudget);
@@ -207,7 +216,7 @@ function formatSearchResults(
 	results: DocSearchResult[],
 	productFilter?: string,
 	tokenBudget = DEFAULT_TOKEN_BUDGET
-): string {
+): ToolResult {
 	const lines: string[] = [];
 	let hasShownTruncationMessage = false;
 
@@ -311,5 +320,9 @@ function formatSearchResults(
 	lines.push('---\n');
 	lines.push(`Use the "${DOC_FETCH_CONFIG.name}" tool to fetch a document from the library.`);
 
-	return lines.join('\n');
+	return {
+		formatted: lines.join('\n'),
+		totalResults: results.length,
+		resultsShared: results.length
+	};
 }

package/src/index.ts

@@ -16,5 +16,8 @@ export * from './paper-summary.js';
 export * from './docs-search/docs-semantic-search.js';
 export * from './docs-search/doc-fetch.js';
 
+// Export shared types
+export * from './types/tool-result.js';
+
 // Export tool IDs for external use - these are the canonical tool identifiers
 export * from './tool-ids.js';

package/src/model-detail.ts

@@ -1,6 +1,7 @@
 import { modelInfo } from '@huggingface/hub';
 import { z } from 'zod';
 import { formatDate, formatNumber } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
 
 const SPACES_TO_INCLUDE = 12;
 // Model Detail Tool Configuration
@@ -102,9 +103,9 @@ export class ModelDetailTool {
 	 * Get detailed information about a specific model
 	 *
 	 * @param modelId The model ID to get details for (e.g., microsoft/DialoGPT-large)
-	 * @returns Formatted string with model details
+	 * @returns ToolResult with formatted model details
 	 */
-	async getDetails(modelId: string): Promise<string> {
+	async getDetails(modelId: string): Promise<ToolResult> {
 		try {
 			// Define additional fields we want to retrieve (only those available in the hub library)
 			const additionalFields = [
@@ -252,7 +253,7 @@ export class ModelDetailTool {
 }
 
 // Formatting Function
-function formatModelDetails(model: ModelInformation): string {
+function formatModelDetails(model: ModelInformation): ToolResult {
 	const r: string[] = [];
 	const [authorFromName] = model.name.includes('/') ? model.name.split('/') : ['', model.name];
 
@@ -404,5 +405,9 @@ function formatModelDetails(model: ModelInformation): string {
 	// Link is reliable - based on model name which is required
 	r.push(`**Link:** [https://hf.co/${model.name}](https://hf.co/${model.name})`);
 
-	return r.join('\n');
+	return {
+		formatted: r.join('\n'),
+		totalResults: 1,  // Model was found
+		resultsShared: 1  // All details shared
+	};
 }

package/src/model-search.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HfApiCall } from './hf-api-call.js';
 import { formatDate, formatNumber } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
 
 export const TAGS_TO_RETURN = 20;
 // Model Search Tool Configuration
@@ -82,7 +83,7 @@ export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]>
 	/**
 	 * Search for models with detailed parameters
 	 */
-	async searchWithParams(params: Partial<ModelSearchParams>): Promise<string> {
+	async searchWithParams(params: Partial<ModelSearchParams>): Promise<ToolResult> {
 		try {
 			// Convert our params to the HF API format
 			const apiParams: ModelApiParams = {};
@@ -120,7 +121,11 @@ export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]>
 			const models = await this.callApi<ModelApiResult[]>(apiParams);
 
 			if (models.length === 0) {
-				return `No models found for the given criteria.`;
+				return {
+					formatted: `No models found for the given criteria.`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			return formatSearchResults(models, params);
@@ -135,7 +140,7 @@ export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]>
 	/**
 	 * Search for models with a specific filter (e.g., arxiv:XXXX.XXXXX)
 	 */
-	async searchWithFilter(filter: string, limit: number = 10): Promise<string> {
+	async searchWithFilter(filter: string, limit: number = 10): Promise<ToolResult> {
 		try {
 			const apiParams: ModelApiParams = {
 				filter: filter,
@@ -148,7 +153,11 @@ export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]>
 			const models = await this.callApi<ModelApiResult[]>(apiParams);
 
 			if (models.length === 0) {
-				return `No models found referencing ${filter}.`;
+				return {
+					formatted: `No models found referencing ${filter}.`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			return formatSearchResults(models, { limit });
@@ -162,7 +171,7 @@ export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]>
 }
 
 // Formatting Function
-function formatSearchResults(models: ModelApiResult[], params: Partial<ModelSearchParams>): string {
+function formatSearchResults(models: ModelApiResult[], params: Partial<ModelSearchParams>): ToolResult {
 	const r: string[] = [];
 
 	// Build search description
@@ -227,5 +236,9 @@ function formatSearchResults(models: ModelApiResult[], params: Partial<ModelSear
 		r.push('');
 	}
 
-	return r.join('\n');
+	return {
+		formatted: r.join('\n'),
+		totalResults: models.length,
+		resultsShared: models.length
+	};
 }

package/src/paper-search.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HfApiCall } from './hf-api-call.js';
 import { formatUnknownDate } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
 
 // https://github.com/huggingface/huggingface_hub/blob/a26b93e8ba0b51ce76ce5c2044896587c47c6b60/src/huggingface_hub/hf_api.py#L1481-L1542
 // Raw JSON response for https://hf.co/api/papers/search?q=llama%203%20herd Llama Herd is ~50,000 tokens
@@ -93,15 +94,23 @@ export class PaperSearchTool extends HfApiCall<PaperSearchParams, PaperSearchRes
 	 * Searches for papers on the Hugging Face Hub
 	 * @param query Search query string (e.g. "llama", "attention")
 	 * @param limit Maximum number of results to return
-	 * @returns Formatted string with paper information
+	 * @returns ToolResult with formatted paper information and metrics
 	 */
-	async search(query: string, limit: number = RESULTS_TO_RETURN, conciseOnly: boolean = false): Promise<string> {
+	async search(query: string, limit: number = RESULTS_TO_RETURN, conciseOnly: boolean = false): Promise<ToolResult> {
 		try {
-			if (!query) return 'No query';
+			if (!query) return {
+				formatted: 'No query',
+				totalResults: 0,
+				resultsShared: 0
+			};
 
 			const papers = await this.callApi<PaperSearchResult[]>({ q: query });
 
-			if (papers.length === 0) return `No papers found for query '${query}'`;
+			if (papers.length === 0) return {
+				formatted: `No papers found for query '${query}'`,
+				totalResults: 0,
+				resultsShared: 0
+			};
 			return formatSearchResults(query, papers.slice(0, limit), papers.length, conciseOnly);
 		} catch (error) {
 			if (error instanceof Error) {
@@ -122,7 +131,7 @@ function formatSearchResults(
 	papers: PaperSearchResult[],
 	totalCount: number,
 	conciseOnly: boolean = false
-): string {
+): ToolResult {
 	const r: string[] = [];
 	const showingText =
 		papers.length < totalCount
@@ -169,7 +178,11 @@ function formatSearchResults(
 	}
 	r.push('');
 	r.push('---');
-	return r.join('\n');
+	return {
+		formatted: r.join('\n'),
+		totalResults: totalCount,
+		resultsShared: papers.length
+	};
 }
 
 export function authors(authors: Author[] | undefined, authorsToShow: number = DEFAULT_AUTHORS_TO_SHOW): string {

package/src/paper-summary.ts

@@ -267,8 +267,8 @@ export class PaperSummaryPrompt extends HfApiCall<Record<string, string>, PaperD
 			const modelSearch = new ModelSearchTool(this.hfToken);
 			// Use the filter parameter to search for models referencing this paper
 			const modelResults = await modelSearch.searchWithFilter(`arxiv:${arxivId}`, 25);
-			if (modelResults && !modelResults.includes('No models found')) {
-				results.models = `## Related Models\n\n${modelResults}`;
+			if (modelResults && !modelResults.formatted.includes('No models found')) {
+				results.models = `## Related Models\n\n${modelResults.formatted}`;
 			}
 		} catch (error) {
 			console.warn(`Failed to fetch related models for paper ${arxivId}:`, error);
@@ -279,8 +279,8 @@ export class PaperSummaryPrompt extends HfApiCall<Record<string, string>, PaperD
 			const datasetSearch = new DatasetSearchTool(this.hfToken);
 			// Use the filter parameter to search for datasets referencing this paper
 			const datasetResults = await datasetSearch.searchWithFilter(`arxiv:${arxivId}`, 25);
-			if (datasetResults && !datasetResults.includes('No datasets found')) {
-				results.datasets = `## Related Datasets\n\n${datasetResults}`;
+			if (datasetResults && !datasetResults.formatted.includes('No datasets found')) {
+				results.datasets = `## Related Datasets\n\n${datasetResults.formatted}`;
 			}
 		} catch (error) {
 			console.warn(`Failed to fetch related datasets for paper ${arxivId}:`, error);
@@ -291,8 +291,8 @@ export class PaperSummaryPrompt extends HfApiCall<Record<string, string>, PaperD
 			const spaceSearch = new SpaceSearchTool(this.hfToken);
 			// Use the filter parameter to search for spaces referencing this paper
 			const spaceResults = await spaceSearch.searchWithFilter(`arxiv:${arxivId}`, 25, 2);
-			if (spaceResults && !spaceResults.includes('No matching Hugging Face Spaces found')) {
-				results.spaces = `## Related Spaces\n\n${spaceResults}`;
+			if (spaceResults && !spaceResults.formatted.includes('No matching Hugging Face Spaces found')) {
+				results.spaces = `## Related Spaces\n\n${spaceResults.formatted}`;
 			}
 		} catch (error) {
 			console.warn(`Failed to fetch related spaces for paper ${arxivId}:`, error);

package/src/space-search.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { HfApiCall } from './hf-api-call.js';
 import { escapeMarkdown } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
 
 // Define the SearchResult interface
 export interface SpaceSearchResult {
@@ -99,7 +100,7 @@ export class SpaceSearchTool extends HfApiCall<SpaceSearchParams, SpaceSearchRes
 	 * Search for spaces with a specific filter (e.g., arxiv:XXXX.XXXXX)
 	 * Note: For spaces, we need to use the regular API endpoint with filter parameter
 	 */
-	async searchWithFilter(filter: string, limit: number = 10, headerLevel: number = 1): Promise<string> {
+	async searchWithFilter(filter: string, limit: number = 10, headerLevel: number = 1): Promise<ToolResult> {
 		try {
 			// For spaces, we need to use the regular spaces API endpoint with filter
 			const url = new URL('https://huggingface.co/api/spaces');
@@ -111,7 +112,11 @@ export class SpaceSearchTool extends HfApiCall<SpaceSearchParams, SpaceSearchRes
 			const results = await this.fetchFromApi<SpaceSearchResult[]>(url);
 
 			if (results.length === 0) {
-				return `No matching Hugging Face Spaces found referencing ${filter}.`;
+				return {
+					formatted: `No matching Hugging Face Spaces found referencing ${filter}.`,
+					totalResults: 0,
+					resultsShared: 0
+				};
 			}
 
 			// Format results using the existing formatter
@@ -133,16 +138,20 @@ export type SearchParams = z.infer<typeof SEMANTIC_SEARCH_TOOL_CONFIG.schema>;
 /**
  * Formats search results as a markdown table for MCP friendly output
  * @param results The search results to format
- * @returns A markdown formatted string with the search results
+ * @returns A ToolResult with formatted string and metrics
  */
 export const formatSearchResults = (
 	query: string,
 	results: SpaceSearchResult[],
 	totalCount: number,
 	headerLevel: number = 1
-): string => {
+): ToolResult => {
 	if (results.length === 0) {
-		return `No matching Hugging Face Spaces found for the query '${query}'. Try a different query.`;
+		return {
+			formatted: `No matching Hugging Face Spaces found for the query '${query}'. Try a different query.`,
+			totalResults: 0,
+			resultsShared: 0
+		};
 	}
 
 	const showingText =
@@ -173,5 +182,9 @@ export const formatSearchResults = (
 			`| ${relevance} |\n`;
 	}
 
-	return markdown;
+	return {
+		formatted: markdown,
+		totalResults: totalCount,
+		resultsShared: results.length
+	};
 };