Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 28 additions & 3 deletions scripts/generate_mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@

from __future__ import annotations

import ast
import keyword
import re
import sys
Expand Down Expand Up @@ -658,24 +659,48 @@ 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():
lines.append("")
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


Expand Down Expand Up @@ -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:
Expand Down
34 changes: 17 additions & 17 deletions src/late/mcp/generated_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
34 changes: 34 additions & 0 deletions tests/test_generated_mcp_descriptions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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, [])

Expand Down
Loading