AFP News MCP Server has well-defined tools with clear naming conventions (verb_noun pattern), detailed descriptions, and comprehensive parameter schemas. All 6 tools follow consistent patterns and include structured output formats. However, output schemas are not explicitly documented in the source code, and error handling recovery guidance is absent. Tool names correctly use action verbs (search, get, find, list), and parameter descriptions are thorough with enum constraints and format specifications. The server accepts multiple output formats (markdown, json, csv) and supports pagination with explicit limit parameters, which aligns with Arcade patterns for result limiting and pagination. Main gaps: no documented output schema structure, no error recovery hints in descriptions, and missing tool annotations (readOnlyHint despite all tools being read-only operations).

• Document output schemas for all 6 tools. Specify the structure of search results (include 'uno', 'headline', 'published', 'body' for articles; 'uno', 'title', 'url', 'mediaType' for media). Include field types and which fields are guaranteed vs optional. This enables LLMs to extract chaining IDs (uno) and plan follow-up calls.
• Add readOnlyHint to all tool definitions in the MCP server registration. Mark all 6 tools as readonly since they only query the AFP API without modifying state. This signals to agents that results can be safely cached and retried.
• Enhance parameter descriptions with recovery guidance. For example, afp_search_articles could note: 'If no results found, try a broader query or check facet_genres to refine by available genres. Use afp_list_facets to discover valid filter values.'
• Expand the 'facets' parameter documentation or replace it with explicit named facet parameters. Current description lists 'e.g. langs, genres, countries, dateFrom, dateTo' as examples, which LLMs may treat as the only valid keys. Either provide a strict JSON Schema object with named properties, or split into separate parameters: facet_genres (array), facet_countries (array), facet_dateFrom (string), facet_dateTo (string).
• Add dependency hints to afp_get_article, afp_get_media, and afp_find_similar: 'To get the uno identifier, use afp_search_articles or afp_search_media first. The returned 'uno' field is the unique article/media identifier.'
• Consider adding a 'total_results' or 'total_count' field to paginated responses (search tools) so agents know when they have exhausted all pages. This aligns with pagination patterns in production tools.