afpnews-mcp-server 2.0.0 → 2.0.2

package/src/__tests__/list-facets.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, mock } from 'bun:test';
+import { afpListFacetsTool } from '../tools/list-facets.js';
+
+describe('afpListFacetsTool', () => {
+  it('returns no-results message when list is empty', async () => {
+    const apicore = { list: mock().mockResolvedValue({ keywords: [] }) };
+
+    const result = await afpListFacetsTool.handler(apicore, { facet: 'slug' });
+
+    expect(result.content).toHaveLength(1);
+    expect(result.content[0]!.text).toContain('No facet values found');
+  });
+
+  it('applies AFP text defaults with explicit lang outside preset', async () => {
+    const apicore = { list: mock().mockResolvedValue({ keywords: [{ name: 'economy', count: 42 }] }) };
+
+    await afpListFacetsTool.handler(apicore, { facet: 'slug', lang: 'en' });
+
+    const [, params] = apicore.list.mock.calls[0]!;
+    expect(params).toEqual({ class: ['text'], provider: ['afp'], langs: ['en'], size: 10 });
+  });
+
+  it('adds truncation hint in json output when facet list is too large', async () => {
+    const keywords = Array.from({ length: 3000 }, (_, i) => ({ name: `topic-${i}-${'x'.repeat(30)}`, count: i + 1 }));
+    const apicore = { list: mock().mockResolvedValue({ keywords }) };
+
+    const result = await afpListFacetsTool.handler(apicore, { facet: 'slug', format: 'json' });
+
+    expect(result.content.length).toBeGreaterThan(1);
+    expect(result.content[1]!.text).toContain('Response truncated');
+  });
+
+  it('adds truncation hint in csv output when facet list is too large', async () => {
+    const keywords = Array.from({ length: 3000 }, (_, i) => ({ name: `topic-${i}-${'x'.repeat(30)}`, count: i + 1 }));
+    const apicore = { list: mock().mockResolvedValue({ keywords }) };
+
+    const result = await afpListFacetsTool.handler(apicore, { facet: 'slug', format: 'csv' });
+
+    expect(result.content.length).toBeGreaterThan(1);
+    expect(result.content[1]!.text).toContain('Response truncated');
+  });
+
+  it('adds truncation hint in markdown output when facet list is too large', async () => {
+    const keywords = Array.from({ length: 3000 }, (_, i) => ({ name: `topic-${i}-${'x'.repeat(30)}`, count: i + 1 }));
+    const apicore = { list: mock().mockResolvedValue({ keywords }) };
+
+    const result = await afpListFacetsTool.handler(apicore, { facet: 'slug' });
+
+    expect(result.content.length).toBeGreaterThan(1);
+    expect(result.content[1]!.text).toContain('Response truncated');
+  });
+});

package/src/__tests__/server.test.ts

@@ -5,6 +5,7 @@ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { registerTools } from '../tools/index.js';
 import { registerResources } from '../resources/index.js';
 import { registerPrompts } from '../prompts/index.js';
+import type { ServerContext } from '../mcp-server.js';
 import { FIXTURE_DOC, makeDocs } from './fixtures.js';
 
 function createMockApicore() {
@@ -12,7 +13,7 @@ function createMockApicore() {
     search: mock().mockResolvedValue({ documents: makeDocs(3), count: 3 }),
     get: mock().mockResolvedValue(makeDocs(1)[0]),
     mlt: mock().mockResolvedValue({ documents: makeDocs(2), count: 2 }),
-    list: mock().mockResolvedValue([{ name: 'economy', count: 42 }]),
+    list: mock().mockResolvedValue({ keywords: [{ name: 'economy', count: 42 }] }),
   };
 }
 
@@ -20,10 +21,21 @@ function getText(result: any, index = 0): string {
   return (result.content[index] as { type: string; text: string }).text;
 }
 
+function makeLargeDocs(count: number) {
+  return Array.from({ length: count }, (_, i) => ({
+    uno: `AFP-LARGE-${String(i + 1).padStart(4, '0')}`,
+    headline: `Article ${i + 1} ${'H'.repeat(180)}`,
+    published: '2026-02-14T10:00:00Z',
+    lang: 'fr',
+    genre: 'news',
+    news: [`Paragraph ${i + 1} ${'B'.repeat(700)}`],
+  }));
+}
+
 async function setupServer() {
   const server = new McpServer({ name: 'test', version: '0.0.1' });
   const apicore = createMockApicore();
-  const ctx = { server, apicore } as any;
+  const ctx = { server, apicore } as ServerContext;
 
   registerTools(ctx);
   registerResources(ctx);
@@ -74,8 +86,8 @@ describe('MCP integration', () => {
       const result = await client.callTool({ name: 'afp_search_articles', arguments: { query: 'test' } });
       // pagination line + 1 document
       const msg = result.content![1] as { type: string; text: string };
-      expect(msg.text).toContain('Fourth paragraph wraps up.');
-      expect(msg.text).not.toContain('Fifth paragraph is extra content.');
+      expect(msg.text).toContain('Second paragraph with more details.');
+      expect(msg.text).not.toContain('Third paragraph continues.');
     });
 
     it('returns full text when fullText=true', async () => {
@@ -93,7 +105,7 @@ describe('MCP integration', () => {
 
       const [request] = apicore.search.mock.calls.at(-1)!;
       expect(request.class).toEqual(['text']);
-      expect(request.lang).toEqual(['fr']);
+      expect(request.langs).toEqual(['fr']);
       expect(request.slug).toEqual(['afp', 'actualites']);
       expect(request.dateFrom).toBe('now-1d');
       expect(request.size).toBe(1);
@@ -141,7 +153,8 @@ describe('MCP integration', () => {
       const result = await client.callTool({ name: 'afp_search_articles', arguments: { query: 'test' } });
       const pagination = result.content![0] as { type: string; text: string };
       expect(pagination.text).toContain('Showing 3 of 10 results');
-      expect(pagination.text).toContain('offset=3');
+      expect(pagination.text).toContain('offset: 0');
+      expect(pagination.text).toContain('offset: 3');  // suggests next offset
     });
 
     it('returns isError on API failure', async () => {
@@ -188,20 +201,18 @@ describe('MCP integration', () => {
     });
 
     it('truncates json when exceeding character limit', async () => {
-      const largeDocs = makeDocs(400);
+      const largeDocs = makeLargeDocs(400);
       apicore.search.mockResolvedValueOnce({ documents: largeDocs, count: 400 });
       const result = await client.callTool({ name: 'afp_search_articles', arguments: { query: 'test', format: 'json' } });
       const parsed = JSON.parse(getText(result));
       expect(parsed.truncated).toBe(true);
       expect(parsed.shown).toBeLessThan(400);
       expect(parsed.total).toBe(400);
-      // Should have a truncation hint as second content block
-      expect(result.content).toHaveLength(2);
-      expect(getText(result, 1)).toContain('truncated');
+      expect(parsed.remaining).toBe(400 - parsed.shown);
     });
 
     it('truncates csv when exceeding character limit', async () => {
-      const largeDocs = makeDocs(800);
+      const largeDocs = makeLargeDocs(800);
       apicore.search.mockResolvedValueOnce({ documents: largeDocs, count: 800 });
       const result = await client.callTool({ name: 'afp_search_articles', arguments: { query: 'test', format: 'csv' } });
       const lines = getText(result).split('\n');
@@ -323,7 +334,7 @@ describe('MCP integration', () => {
 
       const [facet, params] = apicore.list.mock.calls.at(-1)!;
       expect(facet).toBe('slug');
-      expect(params).toMatchObject({ langs: ['fr'], class: ['text'], dateFrom: 'now-1d' });
+      expect(params).toMatchObject({ langs: ['fr'], class: ['text'], provider: ['afp'], dateFrom: 'now-1d' });
     });
 
     it('returns isError on API failure', async () => {
@@ -352,7 +363,7 @@ describe('MCP integration', () => {
     it('topics resource returns catalog', async () => {
       const result = await client.readResource({ uri: 'afp://topics' });
       expect(result.contents).toHaveLength(1);
-      const parsed = JSON.parse(result.contents[0].text as string);
+      const parsed = JSON.parse((result.contents[0] as { text: string }).text);
       expect(parsed).toHaveProperty('fr');
       expect(parsed).toHaveProperty('en');
     });

package/src/__tests__/tool-defaults.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, mock } from 'bun:test';
+import { afpSearchArticlesTool } from '../tools/search-articles.js';
+import { afpSearchMediaTool } from '../tools/search-media.js';
+import { afpListFacetsTool } from '../tools/list-facets.js';
+import { FIXTURE_DOC } from './fixtures.js';
+
+describe('tool defaults', () => {
+  it('afp_search_articles defaults to AFP French text documents', async () => {
+    const apicore = {
+      search: mock().mockResolvedValue({ documents: [FIXTURE_DOC], count: 1 }),
+    };
+
+    await afpSearchArticlesTool.handler(apicore, { query: 'test' });
+
+    const [request] = apicore.search.mock.calls[0]!;
+    expect(request.class).toEqual(['text']);
+    expect(request.provider).toEqual(['afp']);
+    expect(request.langs).toEqual(['fr']);
+  });
+
+  it('afp_search_media defaults to AFP provider only', async () => {
+    const apicore = {
+      search: mock().mockResolvedValue({
+        documents: [{
+          uno: 'MEDIA-001',
+          title: 'Photo',
+          caption: ['Caption'],
+          class: 'picture',
+          bagItem: [{ medias: [{ role: 'Thumbnail', href: 'https://example.com/thumb.jpg', width: 320, height: 213, type: 'Photo' }] }],
+        }],
+        count: 1,
+      }),
+    };
+
+    await afpSearchMediaTool.handler(apicore, { query: 'test', class: 'picture' });
+
+    const [request] = apicore.search.mock.calls[0]!;
+    expect(request.class).toEqual(['picture']);
+    expect(request.provider).toEqual(['afp']);
+  });
+
+  it('afp_list_facets defaults to AFP text documents', async () => {
+    const apicore = {
+      list: mock().mockResolvedValue({ keywords: [{ name: 'economy', count: 42 }] }),
+    };
+
+    await afpListFacetsTool.handler(apicore, { facet: 'slug' });
+
+    const [, params] = apicore.list.mock.calls[0]!;
+    expect(params.class).toEqual(['text']);
+    expect(params.provider).toEqual(['afp']);
+  });
+});

package/src/__tests__/types-media.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect } from 'bun:test';
 import type { AFPMediaDocument, MediaRendition, MediaRenditions, ImageContent, AnyContent, ToolSuccess } from '../utils/types.js';
 
 describe('AFPMediaDocument type', () => {

package/src/prompts/country-news.ts

@@ -13,7 +13,7 @@ export const countryNewsPrompt = {
       role: 'user' as const,
       content: {
         type: 'text' as const,
-        text: `Use afp_search_articles to find recent news for country "${country}" (facets: { lang: ["${lang}"], country: ["${country}"] }, size: 15). Write a news summary for this country covering the main stories of the day.`,
+        text: `Use afp_search_articles to find recent news for country "${country}" (facets: { langs: ["${lang}"], country: ["${country}"] }, size: 15). Write a news summary for this country covering the main stories of the day.`,
       },
     }],
   }),

package/src/tools/find-similar.ts

@@ -15,7 +15,7 @@ const inputSchema = z.object({
   lang: langEnum.describe("Language for results (e.g. 'en', 'fr')"),
   size: z.number().optional().describe('Number of similar articles to return (default 10)'),
   format: outputFormatEnum.optional().describe('Output format: markdown (default, with article excerpt), json (structured, no body), csv (tabular, no body).'),
-  fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: afpshortid, uno, headline, published, lang, genre.'),
+  fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: uno, headline, lang, genre.'),
 });
 
 type FindSimilarInput = z.infer<typeof inputSchema>;
@@ -44,7 +44,7 @@ Examples:
   - Find similar articles in French: { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e", lang: "fr" }
   - Export similar as CSV: { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e", lang: "en", format: "csv", fields: ["uno", "headline"] }`,
   inputSchema,
-  handler: async (apicore: ApiCore, { uno, lang, size, format = 'markdown', fields }: FindSimilarInput) => {
+  handler: async (apicore: Pick<ApiCore, 'mlt'>, { uno, lang, size, format = 'markdown', fields }: FindSimilarInput) => {
     try {
       const { documents, count } = await apicore.mlt(uno, lang, size);
       if (count === 0) {

package/src/tools/get-article.ts

@@ -39,7 +39,7 @@ Returns:
 Example:
   { uno: "newsml.afp.com.20260222T090659Z.doc-98hu39e" }`,
   inputSchema,
-  handler: async (apicore: ApiCore, { uno }: GetArticleInput) => {
+  handler: async (apicore: Pick<ApiCore, 'get'>, { uno }: GetArticleInput) => {
     try {
       const doc = await apicore.get(uno);
       return { content: [formatFullArticle(doc)] };

package/src/tools/get-media.ts

@@ -47,7 +47,7 @@ const inputSchema = z.object({
 
 type GetMediaInput = z.infer<typeof inputSchema>;
 
-function formatFullMediaText(doc: any, renditions: MediaRenditions, note?: string): string {
+function formatFullMediaText(doc: Record<string, unknown>, renditions: MediaRenditions, note?: string): string {
   const lines: string[] = [];
   if (doc.title) lines.push(`## ${doc.title}`);
   lines.push(`**UNO:** ${doc.uno}`);
@@ -57,7 +57,8 @@ function formatFullMediaText(doc: any, renditions: MediaRenditions, note?: strin
   if (doc.published)  lines.push(`**Published:** ${doc.published}`);
   if (doc.country || doc.city) lines.push(`**Location:** ${[doc.city, doc.country].filter(Boolean).join(', ')}`);
   if (doc.urgency != null) lines.push(`**Urgency:** ${doc.urgency}`);
-  if (doc.aspectRatios?.length) lines.push(`**Aspect:** ${doc.aspectRatios.join(', ')}`);
+  const aspectRatios = doc.aspectRatios as string[] | undefined;
+  if (aspectRatios?.length) lines.push(`**Aspect:** ${aspectRatios.join(', ')}`);
 
   const caption = Array.isArray(doc.caption) ? doc.caption[0] : doc.caption;
   if (caption) lines.push(`\n${caption}`);
@@ -93,14 +94,15 @@ Returns:
   - With embed: metadata + MCP image block (Claude can analyse the image)`,
   inputSchema,
   handler: async (
-    apicore: ApiCore,
+    apicore: Pick<ApiCore, 'get'>,
     { uno, embed = false, rendition: requestedRendition = 'preview' }: GetMediaInput,
   ) => {
     try {
-      const doc = await apicore.get(uno) as any;
-      if (!doc) {
+      const raw = await apicore.get(uno);
+      if (!raw) {
         return toolError(`Media document not found: ${uno}`);
       }
+      const doc = raw as Record<string, unknown>;
 
       const renditions = extractRenditions(doc.bagItem ?? []);
       const metadataText = textContent(formatFullMediaText(doc, renditions));

package/src/tools/index.ts

@@ -32,7 +32,7 @@ export function registerTools(ctx: ServerContext) {
         inputSchema: tool.inputSchema,
         annotations: READ_ONLY_ANNOTATIONS,
       },
-      async (args: Record<string, unknown>) => tool.handler(ctx.apicore, args as never),
+      async (args: Record<string, unknown>) => (tool.handler as any)(ctx.apicore, args),
     );
   }
 }

package/src/tools/list-facets.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import type { ApiCore } from 'afpnews-api';
-import { escapeCsvValue, textContent, toolError, truncateToLimit, TRUNCATION_HINT } from '../utils/format.js';
+import type { ApiCore, SearchQueryParams } from 'afpnews-api';
+import { escapeCsvValue, textContent, toolError, truncateToLimit, truncationHint } from '../utils/format.js';
 import {
   type FacetResult,
   formatErrorMessage,
@@ -42,7 +42,7 @@ Examples:
   - List available genres as CSV: { facet: "genre", format: "csv" }
   - List countries as JSON: { facet: "country", size: 30, format: "json" }`,
   inputSchema,
-  handler: async (apicore: ApiCore, { preset, facet, lang, size, format = 'markdown' }: ListFacetsInput) => {
+  handler: async (apicore: Pick<ApiCore, 'list'>, { preset, facet, lang, size, format = 'markdown' }: ListFacetsInput) => {
     try {
       const isTrendingTopics = preset === 'trending-topics';
       const resolvedFacet = isTrendingTopics ? 'slug' : facet;
@@ -52,41 +52,46 @@ Examples:
       }
 
       const resolvedSize = size ?? 10;
-      const params: Record<string, unknown> = isTrendingTopics
-        ? { langs: [lang ?? 'fr'], class: ['text'], dateFrom: 'now-1d', size: resolvedSize }
-        : { ...(lang ? { langs: [lang] } : {}), size: resolvedSize };
+      const params: SearchQueryParams = isTrendingTopics
+        ? { langs: [lang ?? 'fr'], class: ['text'], provider: ['afp'], dateFrom: 'now-1d', size: resolvedSize }
+        : { class: ['text'], provider: ['afp'], ...(lang ? { langs: [lang] } : {}), size: resolvedSize };
 
-      const rawResult = await apicore.list(resolvedFacet, params as any, 1) as any;
-      const results: FacetResult[] = rawResult?.keywords ?? rawResult ?? [];
+      const { keywords } = await apicore.list(resolvedFacet, params, 1);
+      const results: FacetResult[] = keywords.map(k => ({ name: k.name ?? '', count: k.count }));
 
       if (results.length === 0) {
         return { content: [textContent(`No facet values found for "${resolvedFacet}".`)] };
       }
 
       if (format === 'json') {
-        const { text, truncated } = truncateToLimit(
+        const { text, truncated, remaining } = truncateToLimit(
           results,
           (slice) => JSON.stringify(slice, null, 2),
         );
         const content = [textContent(text)];
-        if (truncated) content.push(textContent(TRUNCATION_HINT));
+        if (truncated) content.push(textContent(truncationHint(remaining)));
         return { content };
       }
 
       if (format === 'csv') {
         const rows = results.map(r => `${escapeCsvValue(r.name)},${r.count}`);
-        const { text, truncated } = truncateToLimit(
+        const { text, truncated, remaining } = truncateToLimit(
           rows,
           (slice) => ['name,count', ...slice].join('\n'),
         );
         const content = [textContent(text)];
-        if (truncated) content.push(textContent(TRUNCATION_HINT));
+        if (truncated) content.push(textContent(truncationHint(remaining)));
         return { content };
       }
 
       const heading = isTrendingTopics ? 'Trending Topics' : `Facet: ${resolvedFacet}`;
-      const lines = results.map((item) => `- **${item.name}** — ${item.count} articles`);
-      return { content: [textContent(`## ${heading}\n\n${lines.join('\n')}`)] };
+      const { text, truncated, remaining } = truncateToLimit(
+        results,
+        (slice) => `## ${heading}\n\n${slice.map((item) => `- **${item.name}** — ${item.count} articles`).join('\n')}`,
+      );
+      const content = [textContent(text)];
+      if (truncated) content.push(textContent(truncationHint(remaining)));
+      return { content };
     } catch (error) {
       return toolError(formatErrorMessage('listing facet values', error, "Check that the facet name is valid (e.g. 'slug', 'genre', 'country')."));
     }

package/src/tools/search-articles.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { ApiCore } from 'afpnews-api';
+import type { ApiCore, SearchQueryParams } from 'afpnews-api';
 import {
   MARKDOWN_API_FIELDS,
   textContent,
@@ -34,13 +34,13 @@ const reservedFacetKeys = new Set([
 const inputSchema = z.object({
   preset: searchPresetEnum.optional().describe('Optional preset that applies predefined AFP filters. Available presets: a-la-une, agenda, previsions, major-stories.'),
   format: outputFormatEnum.optional().describe('Output format: markdown (default, with article body), json (structured, no body), csv (tabular, no body).'),
-  fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: afpshortid, uno, headline, published, lang, genre.'),
+  fields: docFieldEnum.array().optional().describe('Fields to include in json/csv output. Default: uno, headline, lang, genre.'),
   fullText: z.boolean().optional().describe('When true, returns the full article body (markdown only). Default is false. Presets override to true.'),
   query: z.string().optional().describe("List of keywords to search for in the news articles (e.g. 'climate change'). If not specified, the search will be performed in all languages."),
   size: z.number().optional().describe('Number of results to return (default 10, max 1000)'),
   sortOrder: z.enum(['asc', 'desc']).optional().describe("Sort order by date (default 'desc')"),
   offset: z.number().optional().describe('Offset for pagination (number of results to skip)'),
-  facets: z.record(z.string(), facetParamValueSchema).optional().describe("Facet filters passed to the AFP query (e.g. { lang: ['fr'], dateFrom: '2026-01-01', dateTo: '2026-01-31', country: ['usa'], genre: 'Papier général', urgency: 1 })."),
+  facets: z.record(z.string(), facetParamValueSchema).optional().describe("Facet filters passed to the AFP query (e.g. { langs: ['fr'], dateFrom: '2026-01-01', dateTo: '2026-01-31', country: ['usa'], genre: 'Papier général', urgency: 1 })."),
 }).strict().superRefine((value, ctx) => {
   for (const key of Object.keys(value.facets ?? {})) {
     if (reservedFacetKeys.has(key)) {
@@ -58,7 +58,9 @@ type SearchInput = z.infer<typeof inputSchema>;
 export const afpSearchArticlesTool = {
   name: 'afp_search_articles',
   title: 'Search AFP News Articles',
-  description: `Search AFP news articles with filters and presets. This is the primary query tool for all AFP news search use cases.
+  description: `Search AFP news articles with filters and presets. This is the primary query tool for AFP news search.
+
+Prefer this tool over afp_search_media unless the user explicitly asks for photos, videos, graphics, or motion design.
 
 ${UNO_FORMAT_NOTE}
 
@@ -72,30 +74,38 @@ Args:
   - size: Number of results (default 10, max 1000)
   - sortOrder: 'asc' or 'desc' by date (default 'desc')
   - offset: Pagination offset (number of results to skip)
-  - facets: All facet filters as key/value pairs (e.g. { lang: ['fr'], dateFrom: '2026-01-01', dateTo: '2026-01-31', country: ['usa'], genre: 'Papier général', urgency: 1 })
+  - facets: All facet filters as key/value pairs (e.g. { langs: ['en'], dateFrom: '2026-01-01', dateTo: '2026-01-31', country: ['usa'], genre: 'Papier général', urgency: 1 }).
+           Defaults: class=text, provider=afp, langs=fr. Override langs for other languages (e.g. { langs: ['en'] } or { langs: ['fr', 'en'] }).
+
+Pagination:
+  Use \`offset\` to paginate through results (e.g. offset=10 to skip the first 10).
+  For large chronological scans, prefer narrowing \`dateFrom\`/\`dateTo\` ranges over high offsets.
+  Keep \`size\` small (10–20) for best performance.
 
 Returns:
   - markdown: Pagination summary line + formatted articles with headline, metadata, body
-  - json: { total, shown, offset, documents: [...] } with selected fields
+  - json: { total, shown, offset, truncated, remaining, documents: [...] } with selected fields
   - csv: Header row + data rows with selected fields
 
 Examples:
-  - Latest Ukraine news: { query: "Ukraine", facets: { lang: ["en"] }, size: 5 }
+  - Latest Ukraine news: { query: "Ukraine", facets: { langs: ["en"] }, size: 5 }
   - French front page: { preset: "a-la-une" }
   - Export metadata as CSV: { query: "economy", format: "csv", fields: ["uno", "headline", "country"] }`,
   inputSchema,
   handler: async (
-    apicore: ApiCore,
+    apicore: Pick<ApiCore, 'search'>,
     { preset, format = 'markdown', fields, fullText = false, query, size = DEFAULT_SEARCH_SIZE, sortOrder = 'desc', offset, facets }: SearchInput,
   ) => {
     try {
       const facetFilters = {
         class: ['text'],
+        provider: ['afp'],
+        langs: ['fr'],
         genreid: GENRE_EXCLUSIONS,
         ...(facets ?? {}),
       };
 
-      let request: Record<string, unknown> = {
+      let request: SearchQueryParams = {
         query,
         size,
         sortOrder,
@@ -111,9 +121,9 @@ Examples:
       const outputFields: string[] = fields ?? [...DEFAULT_OUTPUT_FIELDS];
       const apiFields = format === 'markdown'
         ? [...MARKDOWN_API_FIELDS]
-        : [...new Set(['afpshortid', 'uno', ...outputFields])];
+        : [...new Set(outputFields)];
 
-      const { documents, count } = await apicore.search(request as any, apiFields);
+      const { documents, count } = await apicore.search(request, apiFields);
       if (count === 0) {
         return { content: [textContent('No results found.')] };
       }
@@ -124,7 +134,7 @@ Examples:
         fields: outputFields,
         fullText: effectiveFullText,
         jsonMeta: { total: count, offset: currentOffset },
-        markdownPrefix: [textContent(buildPaginationLine(documents.length, count, currentOffset))],
+        markdownPrefix: (shown) => [textContent(buildPaginationLine(shown, count, currentOffset))],
       });
     } catch (error) {
       return toolError(formatErrorMessage('searching AFP articles', error, 'Check your query parameters and try again.'));

package/src/tools/search-media.ts

@@ -1,13 +1,10 @@
 import { z } from 'zod';
-import type { ApiCore } from 'afpnews-api';
-import { textContent, toolError, TRUNCATION_HINT, buildPaginationLine } from '../utils/format.js';
+import type { ApiCore, SearchQueryParams } from 'afpnews-api';
+import { textContent, toolError, buildPaginationLine } from '../utils/format.js';
 import {
-  formatMediaDocument,
-  formatMediaDocumentsAsJson,
-  formatMediaDocumentsAsCsv,
-  extractRenditions,
+  formatMediaOutput,
+  normalizeMediaDocument,
 } from '../utils/format-media.js';
-import type { AFPMediaDocument } from '../utils/types.js';
 import { DEFAULT_SEARCH_SIZE } from '../utils/types.js';
 import {
   mediaClassEnum,
@@ -32,7 +29,7 @@ const inputSchema = z.object({
   sortOrder: z.enum(['asc', 'desc']).optional().describe("Sort order by date (default 'desc')"),
   format: outputFormatEnum.optional().describe('Output format: markdown (default), json, or csv'),
   facets: z.record(z.string(), facetParamValueSchema).optional().describe(
-    "Additional AFP facet filters (e.g. { lang: ['fr'], country: ['fra'], dateFrom: '2026-01-01' })"
+    "Additional AFP facet filters (e.g. { langs: ['fr'], country: ['fra'], dateFrom: '2026-01-01' })"
   ),
 }).strict().superRefine((value, ctx) => {
   for (const key of Object.keys(value.facets ?? {})) {
@@ -48,29 +45,13 @@ const inputSchema = z.object({
 
 type SearchMediaInput = z.infer<typeof inputSchema>;
 
-function buildMediaDocument(raw: any): AFPMediaDocument {
-  return {
-    uno: raw.uno,
-    title: raw.title,
-    caption: Array.isArray(raw.caption) ? raw.caption[0] : raw.caption,
-    creditLine: raw.creditLine,
-    creator: raw.creator,
-    country: raw.country,
-    city: raw.city,
-    published: raw.published,
-    urgency: raw.urgency,
-    class: raw.class,
-    aspectRatios: raw.aspectRatios,
-    advisory: raw.advisory,
-    renditions: extractRenditions(raw.bagItem ?? []),
-  };
-}
-
 export const afpSearchMediaTool = {
   name: 'afp_search_media',
   title: 'Search AFP Media (Photos, Videos, Graphics)',
   description: `Search AFP media documents: photos, videos, infographics, and motion design.
 
+Use this tool only when the user explicitly asks for media assets. For general news retrieval, prefer afp_search_articles.
+
 Media classes:
   - picture: AFP photos. Captions are always in English — do not filter by lang, or use lang=en.
   - video: AFP video clips. No language constraint.
@@ -84,10 +65,15 @@ Args:
   - offset: Pagination offset
   - sortOrder: 'asc' or 'desc' (default 'desc')
   - format: markdown (default, with inline thumbnails), json (structured with rendition URLs), csv
-  - facets: Additional AFP filters (e.g. { lang: ['fr'], country: ['fra'], dateFrom: '2026-01-01' })
+  - facets: Additional AFP filters (e.g. { langs: ['fr'], country: ['fra'], dateFrom: '2026-01-01' }).
+           Defaults: provider=afp. Override provider only when partner media is explicitly needed.
+
+Pagination:
+  Use \`offset\` to paginate (e.g. offset=10 to skip the first 10).
+  Keep \`size\` small (10–20) for best performance.
 
 Returns (json):
-  { total, shown, offset, truncated, documents: [{ uno, title, caption, creditLine, creator,
+  { total, shown, offset, truncated, remaining, documents: [{ uno, title, caption, creditLine, creator,
     country, city, published, urgency, class, aspectRatios, advisory,
     renditions: { thumbnail, preview, highdef } }] }
 
@@ -98,56 +84,38 @@ Rendition sizes:
 
 Examples:
   - AFP football photos: { class: "picture", query: "football" }
-  - French infographics on economy: { class: "graphic", query: "économie", facets: { lang: ["fr"] } }
+  - French infographics on economy: { class: "graphic", query: "économie", facets: { langs: ["fr"] } }
   - All media on a topic: { query: "climate protest", format: "json" }
   - Export gallery CSV: { class: "picture", query: "Paris", format: "csv" }`,
   inputSchema,
   handler: async (
-    apicore: ApiCore,
+    apicore: Pick<ApiCore, 'search'>,
     { class: mediaClass, query, size = DEFAULT_SEARCH_SIZE, offset, sortOrder = 'desc', format = 'markdown', facets }: SearchMediaInput,
   ) => {
     try {
       const classFilter = mediaClass ? [mediaClass] : ['picture', 'video', 'graphic', 'videography'];
-      const request: Record<string, unknown> = {
+      const request: SearchQueryParams = {
         query,
         size,
         sortOrder,
         startAt: offset,
         class: classFilter,
+        provider: ['afp'],
         ...(facets ?? {}),
       };
 
-      const { documents: rawDocs, count } = await apicore.search(request as any, [...MEDIA_API_FIELDS]);
+      const { documents: rawDocs, count } = await apicore.search(request, [...MEDIA_API_FIELDS]);
 
       if (count === 0) {
         return { content: [textContent('No results found.')] };
       }
 
-      const docs = (rawDocs as any[]).map(buildMediaDocument);
+      const docs = rawDocs.map(normalizeMediaDocument);
       const currentOffset = offset ?? 0;
-
-      if (format === 'json') {
-        const { content, truncated } = formatMediaDocumentsAsJson(docs, { total: count, offset: currentOffset });
-        const result = [content];
-        if (truncated) result.push(textContent(TRUNCATION_HINT));
-        return { content: result };
-      }
-
-      if (format === 'csv') {
-        const { content, truncated } = formatMediaDocumentsAsCsv(docs);
-        const result = [content];
-        if (truncated) result.push(textContent(TRUNCATION_HINT));
-        return { content: result };
-      }
-
-      // markdown
-      const items = docs.map(formatMediaDocument);
-      return {
-        content: [
-          textContent(buildPaginationLine(docs.length, count, currentOffset)),
-          ...items,
-        ],
-      };
+      return formatMediaOutput(docs, format, {
+        jsonMeta: { total: count, offset: currentOffset },
+        markdownPrefix: (shown) => [textContent(buildPaginationLine(shown, count, currentOffset))],
+      });
     } catch (error) {
       return toolError(formatErrorMessage('searching AFP media', error, 'Check your query parameters and try again.'));
     }

package/src/tools/shared.ts

@@ -72,7 +72,7 @@ export const GENRE_EXCLUSIONS = {
 
 interface PresetOverrides {
   class?: string[];
-  lang?: string[];
+  langs?: string[];
   slug?: string[];
   dateFrom?: string;
   size?: number;
@@ -82,7 +82,7 @@ interface PresetOverrides {
 export const SEARCH_PRESETS: Record<SearchPreset, PresetOverrides> = {
   'a-la-une': {
     class: ['text'],
-    lang: ['fr'],
+    langs: ['fr'],
     slug: ['afp', 'actualites'],
     dateFrom: 'now-1d',
     size: 1,