From 752628dc19d24e4a1f144d0c950b37459dc1df29 Mon Sep 17 00:00:00 2001 From: Oscar Perez Date: Thu, 19 Nov 2026 16:36:48 +0100 Subject: [PATCH] fix(mcp): a tool's Platforms line never lists values its platform enum rejects x-platforms holds product names (meta, x) while the platform parameter's enum holds stored values (facebook, twitter). Agents copied "meta" from the docstring and FastMCP rejected it before any HTTP call (literal_error). When the enum rejects an x-platforms value, the line now lists the enum; a narrower, valid x-platforms (e.g. google) is kept. Co-Authored-By: Claude Opus 5.5 --- scripts/generate_mcp_tools.py | 31 ++++++++++++++++++--- src/late/mcp/generated_tools.py | 34 ++++++++++++------------ tests/test_generated_mcp_descriptions.py | 34 ++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 20 deletions(-) diff --git a/scripts/generate_mcp_tools.py b/scripts/generate_mcp_tools.py index d8accf14..834aa265 100644 --- a/scripts/generate_mcp_tools.py +++ b/scripts/generate_mcp_tools.py @@ -14,6 +14,7 @@ from __future__ import annotations +import ast import keyword import re import sys @@ -658,16 +659,35 @@ def _escape_docstring_text(text: str) -> str: return text.replace("\\", "\\\\").replace('"', '\\"') +def _platform_param_values(params: list[dict[str, Any]]) -> tuple[str, list[str]] | None: + """Name and allowed values of the tool's `platform`/`platforms` argument + when it is typed as a string enum, read off its generated `Literal[...]`.""" + for p in params: + if p["name"] not in ("platform", "platforms"): + continue + match = re.search(r"Literal\[([^\]]*)\]", p["type"]) + if match: + return p["name"], list(ast.literal_eval(f"({match.group(1)},)")) + return None + + def build_tool_description_lines( summary: str, description: str, platforms: list[str], + params: list[dict[str, Any]] | None = None, ) -> list[str]: - """Summary, then the operation description and its `x-platforms`. + """Summary, then the operation description and its supported platforms. The MCP tool description is all an agent sees when picking a tool, so the spec's operation description (e.g. "Google only; every other platform returns 501") and supported platforms must reach it, not just the summary. + + `x-platforms` holds product names ("meta", "x") while a `platform` enum + holds stored values ("facebook", "twitter"); agents copy the docstring into + the argument, so when the enum rejects an `x-platforms` value the line + lists the enum instead. A narrower `x-platforms` (e.g. "google" against a + wider enum) is kept: it is valid and says more. """ lines = [summary.rstrip()] if description.strip(): @@ -675,7 +695,12 @@ def build_tool_description_lines( lines.extend(_escape_docstring_text(_truncate_description(description)).split("\n")) if platforms: lines.append("") - lines.append(f"Platforms: {', '.join(platforms)}") + platform_param = _platform_param_values(params or []) + if platform_param and not set(platforms) <= set(platform_param[1]): + name, values = platform_param + lines.append(f"Platforms (the {name} parameter takes): {', '.join(values)}") + else: + lines.append(f"Platforms: {', '.join(platforms)}") return lines @@ -708,7 +733,7 @@ def generate_tool_handler( sig = ", ".join(sig_params) # Docstring - strip trailing whitespace from all lines - doc_lines = build_tool_description_lines(summary, description, platforms or []) + doc_lines = build_tool_description_lines(summary, description, platforms or [], params) if idempotency_scope: doc_lines.extend(["", SAME_ARGUMENTS_IDEMPOTENT_NOTE]) if params: diff --git a/src/late/mcp/generated_tools.py b/src/late/mcp/generated_tools.py index fc710ba4..75e77ddf 100644 --- a/src/late/mcp/generated_tools.py +++ b/src/late/mcp/generated_tools.py @@ -5824,7 +5824,7 @@ def ad_audiences_list_ad_audiences( On Reddit, `size` is the lower bound of Reddit's matched-users range, and `status` is `too_small` while the list has matched fewer than 1,000 people. - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit + Platforms (the platform parameter takes): facebook, instagram, googleads, tiktok, tiktokads, pinterest, linkedin, linkedinads, twitter, xads, redditads Args: account_id: Account ID (required) @@ -6577,7 +6577,7 @@ def ad_campaigns_list_ads( 1. Filter by platformAdId (the Meta ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: page: Page number (1-based) @@ -7257,7 +7257,7 @@ def ad_campaigns_list_ad_campaigns( Zernio's own status writes re-read the switches they change. A change made in the ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: include_empty: Meta only. Set true to also list campaigns with ZERO ads, with `adCount: 0` and zeroed metrics. @@ -7517,7 +7517,7 @@ def ad_campaigns_update_ad_campaign_status( - **Already in the requested state:** nothing is written (`updated: 0`, `skipped: 1`, with the reason). - **Otherwise:** the switch is written (`updated: 1`), read back and stored. The delivery status of the ads under it (up to 20) is re-read and stored, so an immediate GET returns what the platform now ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: campaign_id: Platform campaign ID (required) @@ -7799,7 +7799,7 @@ def ad_campaigns_update_ad_campaign( | `name` | Yes | 501 | Reddit: Yes; others 501 | | ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: campaign_id: Platform campaign ID (required) @@ -7894,7 +7894,7 @@ def ad_campaigns_delete_ad_campaign( Google, TikTok, LinkedIn, Pinterest and Reddit take the ad account from the synced ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: campaign_id: Platform campaign ID (required) @@ -8094,7 +8094,7 @@ def ad_campaigns_duplicate_ad_campaign( - `statusOption` applies at every level. - If any child copy fails, the partial copy is deleted and the request fails with Meta's error, so a retry starts ... - Platforms: meta, tiktok, linkedin, google + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, google Args: campaign_id: Source platform campaign ID (required) @@ -8284,7 +8284,7 @@ def ad_campaigns_list_ad_sets( So ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit Args: account_id: Account ID @@ -8461,7 +8461,7 @@ def ad_campaigns_duplicate_ad_set( - If an ad copy fails, the partial ad set copy is deleted and the request fails with Meta's error. - A sync discovery starts automatically and runs after the response (`syncAfter: false` to skip). The copy is readable through Zernio once it finishes, usually within a few minutes. Until then, calls that take a copied id return 404, so retry them. ... - Platforms: meta, tiktok + Platforms (the platform parameter takes): facebook, instagram, tiktok Args: ad_set_id: Source platform ad set ID (required) @@ -8675,7 +8675,7 @@ def ad_campaigns_update_ad_set( - Sending `valueRulesApplied: false` TOGETHER with `valueRuleSetId` returns 400 `mutually_exclusive_fields`. - Eligibility: only ad sets on ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit Args: ad_set_id: Platform ad set ID (required) @@ -8903,7 +8903,7 @@ def ad_campaigns_update_ad_set_status( - When that live read ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, openai, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: ad_set_id: Platform ad set ID (required) @@ -9001,7 +9001,7 @@ def ad_campaigns_get_ad_tree( The older days (up to 730 days back) are imported in the background; repeat the request until it returns 200. A request scoped to no Meta ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: page: Page number (1-based) @@ -9127,7 +9127,7 @@ def ad_campaigns_list_ads_by_performance( A Meta range older than the imported history answers `202` with `backfillPending: true` and the covered part; repeat the request until it returns 200. - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: account_id: Account ID. Sibling-expanded to its linked posting and ads pair. An id the API key cannot reach answers 404. (required) @@ -9198,7 +9198,7 @@ def ad_campaigns_get_ads_timeline( When an ad account connects, Zernio ... - Platforms: meta, google, tiktok, linkedin, pinterest, x, reddit, microsoft + Platforms (the platform parameter takes): facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit, microsoft Args: account_id: Account ID. Sibling-expanded to its linked posting↔ads pair. An id that does not exist or sits on a profile the API key cannot reach answers 404 (code: account_not_found). (required) @@ -26348,7 +26348,7 @@ def connect_ads( A reconnect is accepted when the new grant shares at least one ad ... - Platforms: meta, linkedin, tiktok, twitter, pinterest, google, reddit + Platforms (the platform parameter takes): facebook, instagram, linkedin, tiktok, twitter, pinterest, googleads, redditads, microsoftads Args: identity_provider: Microsoft Ads only. How the user signs in to Microsoft Advertising: `google` for a Microsoft Advertising login that is a Google account. `google` on any other platform returns 400 `invalid_field_value`. @@ -45470,7 +45470,7 @@ def posts_unpublish_post( Deletes a published post from the specified platform. The post record in Zernio is kept but its status is updated to cancelled. Not supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent. - Platforms: facebook, youtube, linkedin, twitter, threads, googlebusiness, pinterest, reddit, telegram, bluesky, discord, slack + Platforms (the platform parameter takes): threads, facebook, twitter, linkedin, youtube, pinterest, reddit, bluesky, googlebusiness, telegram Args: post_id: (required) @@ -57233,7 +57233,7 @@ def workflows_create_workflow( Create a branching conversation workflow (draft) from a node/edge graph. Created in `draft` status; activate it to start matching inbound messages. The graph is validated structurally; completeness (a trigger node + reachable entry) is required at activation. - Platforms: hubspot, salesforce + Platforms (the platform parameter takes): whatsapp, instagram, facebook, telegram, twitter, bluesky, reddit, tiktok, line, wechat Args: profile_id: (required) diff --git a/tests/test_generated_mcp_descriptions.py b/tests/test_generated_mcp_descriptions.py index 9b19ca1f..7b322703 100644 --- a/tests/test_generated_mcp_descriptions.py +++ b/tests/test_generated_mcp_descriptions.py @@ -98,6 +98,40 @@ def test_a_value_outside_a_string_enum_is_rejected_before_the_api_is_called(gene ) +ADS_LIST_OPERATION = { + "summary": "List campaigns", + "x-platforms": ["meta", "google", "x"], + "parameters": [ + { + "name": "platform", + "in": "query", + "schema": {"type": "string", "enum": ["facebook", "instagram", "google", "twitter"]}, + }, + ], +} + + +def test_platforms_line_lists_the_platform_enum_when_x_platforms_disagrees(generator): + mcp = _register_probe(generator, ADS_LIST_OPERATION) + tool = asyncio.run(mcp.list_tools())[0] + + assert tool.description.startswith( + "List campaigns\n\n" + "Platforms (the platform parameter takes): facebook, instagram, google, twitter\n\n" + "Args:" + ) + with pytest.raises(Exception, match="Input should be 'facebook'"): + asyncio.run(mcp.call_tool("probe_tool", {"platform": "meta"})) + + +def test_platforms_line_keeps_x_platforms_without_a_platform_enum(generator): + operation = {"summary": "List leads", "x-platforms": ["meta", "linkedin"], "parameters": []} + mcp = _register_probe(generator, operation) + tool = asyncio.run(mcp.list_tools())[0] + + assert tool.description == "List leads\n\nPlatforms: meta, linkedin" + + def test_long_operation_descriptions_are_capped(generator): lines = generator.build_tool_description_lines("Summary", "word " * 1000, [])