From 26a34e0a85ce94c0eae1edad8ae5c085dfc68685 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gemma=20Torell=C3=B3?= Date: Thu, 12 Nov 2026 18:29:44 +0100 Subject: [PATCH 1/2] perf(mcp): pin the tools sessions use, unpin the ones they do not The 53 pinned definitions cost 87.8K characters on every turn of every session. Pins the inbox conversation reads and the media presigned URL (searched for by 6-13% of sessions) and moves 13 tools that almost no session calls (queue, tracking tags, usage, ...) behind search_tools. Clients now see 44 tools and 75.5K characters instead of 55 and 89.4K. A guessed name now also suggests pinned tools that share its words. Co-Authored-By: Claude Opus 5.5 --- src/late/mcp/server.py | 53 ++++++++++++++++++++------------- tests/test_mcp_pinned_tools.py | 44 +++++++++++++++++++++++++++ tests/test_mcp_tool_guidance.py | 4 +-- 3 files changed, 78 insertions(+), 23 deletions(-) create mode 100644 tests/test_mcp_pinned_tools.py diff --git a/src/late/mcp/server.py b/src/late/mcp/server.py index 7f0927a0..5b464b5d 100644 --- a/src/late/mcp/server.py +++ b/src/late/mcp/server.py @@ -109,13 +109,13 @@ def _api_transport() -> httpx.BaseTransport: # Always-visible core: the 20 hand-written ergonomic tools (guardrails + # LLM-shaped args, preferred over their raw generated twins) plus the generated -# tools central to working on a profile — posting, the scheduling queue, -# pre-publish validation, account health, cross-platform analytics basics, and -# engagement on published posts. The remaining ~430 generated tools (messaging -# suite, ads, connect, platform-specific analytics, ...) sit behind the BM25 -# tool-search transform (search_tools / call_tool), so clients see ~51 tools up -# front instead of 481 — small enough that clients which cap or truncate large -# tool lists show them all. +# tools most sessions need, chosen by measured use: posting, pre-publish +# validation, account health, cross-platform analytics basics, engagement on +# published posts, and the inbox conversation and media URL reads that 6-13% of +# sessions otherwise reached through a search. Every pinned definition is sent +# on every turn of every session, so a tool few sessions call (the scheduling +# queue, tracking tags, usage) stays behind the BM25 tool-search transform +# (search_tools / call_tool) with the rest of the ~1,200 generated tools. _PINNED_TOOLS = [ # Hand-written ergonomic tools "accounts_list", "accounts_get", @@ -127,26 +127,21 @@ def _api_transport() -> httpx.BaseTransport: # Paid diagnosis and its poll fallback "support_ask", "support_assistant_get_support_answer", # Posting operations not covered by the ergonomic set - "posts_bulk_upload_posts", "posts_unpublish_post", "posts_edit_post", - # Scheduling queue - "queue_list_queue_slots", "queue_create_queue_slot", "queue_update_queue_slot", - "queue_delete_queue_slot", "queue_preview_queue", "queue_get_next_queue_slot", + "posts_unpublish_post", "posts_edit_post", "media_get_media_presigned_url", # Pre-publish validation - "validate_post", "validate_post_length", "validate_media", - # Account health & organisation + "validate_post", "validate_media", + # Account health "accounts_get_all_accounts_health", "accounts_get_account_health", - "accounts_get_follower_stats", "accounts_move_account_to_profile", - "account_groups_list_account_groups", + "accounts_get_follower_stats", + # Inbox conversations + "messages_list_inbox_conversations", "messages_get_inbox_conversation_messages", # Cross-platform analytics basics "analytics_get_analytics", "analytics_get_best_time_to_post", "analytics_get_daily_metrics", "analytics_get_post_timeline", # Engagement on published posts "comments_list_inbox_comments", "comments_get_inbox_post_comments", "comments_reply_to_inbox_post", - "mentions_list_inbox_mentions", "mentions_reply_to_mention", - # Campaign tags & usage - "tracking_tags_list_tracking_tags", "tracking_tags_get_tracking_tag_stats", - "usage_get_usage", + "mentions_list_inbox_mentions", # Report bugs and missing features to Zernio FEEDBACK_TOOL, ] @@ -236,15 +231,31 @@ async def _search(self, tools: Sequence[Tool], query: str) -> Sequence[Tool]: async def closest_tools(self, name: str, ctx: Context | None) -> list[str]: """Real tool names nearest a mistyped or guessed one, pinned tools included.""" hidden = await self._get_visible_tools(ctx) - names = [t.name for t in hidden] + sorted(self._always_visible) + pinned = sorted(self._always_visible) + names = [t.name for t in hidden] + pinned by_words = [t.name for t in await self._search(hidden, name)] + by_pinned_words = _names_sharing_words(name, pinned) by_spelling = difflib.get_close_matches(name, names, n=_MAX_TOOL_SUGGESTIONS) # Word matches lead: they named the intended tool first for every # guessed name seen in production, spelling only for some. - interleaved = [n for pair in zip_longest(by_words, by_spelling) for n in pair if n] + interleaved = [ + n + for group in zip_longest(by_words, by_pinned_words, by_spelling) + for n in group + if n + ] return list(dict.fromkeys(interleaved))[:_MAX_TOOL_SUGGESTIONS] +def _names_sharing_words(guess: str, names: Sequence[str]) -> list[str]: + guess_words = set(guess.lower().split("_")) + shared = {name: len(guess_words & set(name.split("_"))) for name in names} + ranked = sorted( + (n for n, count in shared.items() if count >= 2), key=lambda n: -shared[n] + ) + return ranked[:_MAX_TOOL_SUGGESTIONS] + + _search_transform = _AnnotatedBM25SearchTransform( always_visible=_PINNED_TOOLS, max_results=8, diff --git a/tests/test_mcp_pinned_tools.py b/tests/test_mcp_pinned_tools.py new file mode 100644 index 00000000..9c79dc54 --- /dev/null +++ b/tests/test_mcp_pinned_tools.py @@ -0,0 +1,44 @@ +from __future__ import annotations + +from fastmcp import Client + +from late.mcp import server + + +async def test_every_pinned_name_is_a_registered_tool() -> None: + registered = {t.name for t in await server.mcp.list_tools(run_middleware=False)} + + assert [name for name in server._PINNED_TOOLS if name not in registered] == [] + + +async def test_the_inbox_and_media_url_reads_are_listed_without_a_search() -> None: + listed = {t.name for t in await server.mcp.list_tools()} + + assert { + "messages_list_inbox_conversations", + "messages_get_inbox_conversation_messages", + "media_get_media_presigned_url", + } <= listed + + +async def test_an_unpinned_tool_is_found_by_search_and_not_listed_up_front() -> None: + listed = {t.name for t in await server.mcp.list_tools()} + async with Client(server.mcp) as client: + result = await client.call_tool("search_tools", {"query": "list queue slots"}) + + assert "queue_list_queue_slots" not in listed + assert "queue_list_queue_slots" in result.content[0].text + + +async def test_agents_that_call_a_newly_pinned_tool_through_call_tool_still_reach_it() -> ( + None +): + async with Client(server.mcp) as client: + result = await client.call_tool( + "call_tool", + {"name": "messages_get_inbox_conversation_messages", "arguments": {}}, + raise_on_error=False, + ) + + assert "Unknown tool" not in result.content[0].text + assert "conversation_id" in result.content[0].text diff --git a/tests/test_mcp_tool_guidance.py b/tests/test_mcp_tool_guidance.py index b308a0d2..fd54181e 100644 --- a/tests/test_mcp_tool_guidance.py +++ b/tests/test_mcp_tool_guidance.py @@ -38,11 +38,11 @@ async def test_a_guessed_name_through_call_tool_suggests_the_real_tool(): async def test_call_tool_runs_a_proxied_search_instead_of_refusing_it(): is_error, text = await _call( "call_tool", - {"name": "search_tools", "arguments": {"query": "list inbox conversations"}}, + {"name": "search_tools", "arguments": {"query": "search inbox conversations"}}, ) assert not is_error - assert "messages_list_inbox_conversations" in text + assert "messages_search_inbox_conversations" in text async def test_call_tool_still_refuses_to_call_itself(): From 0377e17c8222785af2616775ebc278044f81a30d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gemma=20Torell=C3=B3?= Date: Thu, 12 Nov 2026 18:31:26 +0100 Subject: [PATCH 2/2] fix(mcp): pinned-name suggestions understand camelCase and kebab-case guesses Co-Authored-By: Claude Opus 5.5 --- src/late/mcp/server.py | 14 ++++++-------- tests/test_mcp_tool_guidance.py | 2 ++ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/late/mcp/server.py b/src/late/mcp/server.py index 5b464b5d..40497179 100644 --- a/src/late/mcp/server.py +++ b/src/late/mcp/server.py @@ -109,13 +109,10 @@ def _api_transport() -> httpx.BaseTransport: # Always-visible core: the 20 hand-written ergonomic tools (guardrails + # LLM-shaped args, preferred over their raw generated twins) plus the generated -# tools most sessions need, chosen by measured use: posting, pre-publish -# validation, account health, cross-platform analytics basics, engagement on -# published posts, and the inbox conversation and media URL reads that 6-13% of -# sessions otherwise reached through a search. Every pinned definition is sent -# on every turn of every session, so a tool few sessions call (the scheduling -# queue, tracking tags, usage) stays behind the BM25 tool-search transform -# (search_tools / call_tool) with the rest of the ~1,200 generated tools. +# tools most sessions need, chosen by measured use. Every pinned definition is +# sent on every turn of every session, so a tool few sessions call stays behind +# the BM25 tool-search transform (search_tools / call_tool) with the rest of the +# generated tools. _PINNED_TOOLS = [ # Hand-written ergonomic tools "accounts_list", "accounts_get", @@ -248,7 +245,8 @@ async def closest_tools(self, name: str, ctx: Context | None) -> list[str]: def _names_sharing_words(guess: str, names: Sequence[str]) -> list[str]: - guess_words = set(guess.lower().split("_")) + split_camel_case = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", guess) + guess_words = set(re.findall(r"[a-z0-9]+", split_camel_case.lower())) shared = {name: len(guess_words & set(name.split("_"))) for name in names} ranked = sorted( (n for n, count in shared.items() if count >= 2), key=lambda n: -shared[n] diff --git a/tests/test_mcp_tool_guidance.py b/tests/test_mcp_tool_guidance.py index fd54181e..13cf756c 100644 --- a/tests/test_mcp_tool_guidance.py +++ b/tests/test_mcp_tool_guidance.py @@ -14,6 +14,8 @@ async def _call(name: str, arguments: dict) -> tuple[bool, str]: ("guess", "real"), [ ("inbox_list_conversations", "messages_list_inbox_conversations"), + ("inboxListConversations", "messages_list_inbox_conversations"), + ("inbox-get-conversation-messages", "messages_get_inbox_conversation_messages"), ("ads_list_ads", "ad_campaigns_list_ads"), ("comment_automations_list", "comment_automations_list_comment_automations"), ],