From 912aec16fc0ad155d0e84dbc27c37eb90c1ecc66 Mon Sep 17 00:00:00 2001 From: Lucas Faria Date: Thu, 5 Nov 2026 09:35:41 -0300 Subject: [PATCH 1/2] fix(mcp): reword injected argument descriptions for directory review What: reworded the descriptions of the injected conversation_id and llm_model arguments and the get_more_tools and send_feedback virtual tools (plus the feedback_type property) so each states what the field is and that it is recorded for analytics. Removed behavioral instructions and broad-triggering lines. Descriptions only: names, annotations, schemas and the canned get_more_tools reply are unchanged. Adds a patch sampo changeset. Why: the ChatGPT and Claude directory reviews flag descriptions that tell the model how to behave beyond one call or ask to be triggered broadly. Tests: - pytest posthog/test/mcp (PYTHONPATH=worktree): 665 passed, 10 skipped - new parameterized test_advertised_descriptions_carry_no_behavioral_instructions failed 6/6 on the old text, passes now - ruff format --check / ruff check on posthog/mcp and posthog/test/mcp: clean Reviewer note: test_units asserted the old conversation_id clause "rest of the conversation, including after later user messages"; its comment says ChatGPT drops the handle without it. The new wording drops that clause as specified, so session continuity on ChatGPT is worth watching. --- .../mcp-reword-injected-descriptions.md | 5 +++ posthog/mcp/constants.py | 13 ++---- posthog/mcp/feedback.py | 11 ++--- posthog/mcp/tools.py | 4 +- posthog/test/mcp/test_feedback.py | 44 ++++++++++++++++++- posthog/test/mcp/test_units.py | 2 +- 6 files changed, 59 insertions(+), 20 deletions(-) create mode 100644 .sampo/changesets/mcp-reword-injected-descriptions.md diff --git a/.sampo/changesets/mcp-reword-injected-descriptions.md b/.sampo/changesets/mcp-reword-injected-descriptions.md new file mode 100644 index 000000000..7354cf9a6 --- /dev/null +++ b/.sampo/changesets/mcp-reword-injected-descriptions.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: patch +--- + +Reworded the descriptions of the injected `conversation_id` and `llm_model` arguments and the `get_more_tools` and `send_feedback` virtual tools so they describe the field instead of instructing the model. This changes your published tool definitions; if your server is listed in the ChatGPT or Claude directories, those platforms may re-review the updated tools. diff --git a/posthog/mcp/constants.py b/posthog/mcp/constants.py index de359e693..4a174bc86 100644 --- a/posthog/mcp/constants.py +++ b/posthog/mcp/constants.py @@ -28,18 +28,13 @@ ) DEFAULT_CONVERSATION_ID_DESCRIPTION = ( - "Pass the exact conversation_id from the server's previous response, unchanged. The server " - "provides it on the first call — never invent one, and do not issue parallel tool calls until " - "you have it. Keep passing the same conversation_id for the rest of the conversation, including " - "after later user messages or on a different task; do not reset it when the user starts a new " - "request." + "The conversation_id this server returned earlier in this conversation, unchanged. Omit it " + "if you have none. Recorded for the server developer's analytics." ) DEFAULT_MODEL_PARAMETER_DESCRIPTION = ( - "The exact model identifier you (the assistant) are running as, taken from your " - 'system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for ' - 'analytics only. If you do not know your model identifier with certainty, pass "unknown" ' - "— never guess." + 'The model identifier you are running as, for example "claude-opus-4-8" or "gpt-5.2". ' + 'Pass "unknown" if you are not certain. Recorded for the server developer\'s analytics.' ) POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics" diff --git a/posthog/mcp/feedback.py b/posthog/mcp/feedback.py index fcba7fad1..fd937070b 100644 --- a/posthog/mcp/feedback.py +++ b/posthog/mcp/feedback.py @@ -28,11 +28,9 @@ _TRUNCATION_SUFFIX = "..." _DEFAULT_FEEDBACK_DESCRIPTION = ( - "Send feedback about this server to its developers. Most important: report a missing " - "capability whenever no available tool fits your task, even if you can work around it " - '(feedback_type "missing_capability"). Also welcome: a tool that failed or confused you, ' - "an unhelpful error, or something that worked well. This records the feedback; it does " - "not add or change tools. Do not include user PII or sensitive content." + "Send feedback about this server to its developers: a capability you needed that no tool " + "provides, a tool that failed or misled you, or something that worked well. Records the " + "feedback; it does not add or change tools. Leave out personal or sensitive details." ) _SEND_FEEDBACK_RESULT_TEXT = ( @@ -47,8 +45,7 @@ "description": ( "What kind of feedback this is. Use 'missing_capability' when the tool you " "needed does not exist in the tool list - nothing failed, the capability is " - "absent (this is the most valuable report; send it even if you found a " - "workaround). Use 'issue' when an existing tool behaved badly: it failed, " + "absent. Use 'issue' when an existing tool behaved badly: it failed, " "returned a confusing error, or its description or schema misled you. Use " "'praise' when something worked notably well. Use 'other' for anything else." ), diff --git a/posthog/mcp/tools.py b/posthog/mcp/tools.py index ef59b7a28..97d4bb6eb 100644 --- a/posthog/mcp/tools.py +++ b/posthog/mcp/tools.py @@ -39,8 +39,8 @@ def build_report_missing_descriptor(name: str = GET_MORE_TOOLS_NAME) -> Dict[str return { "name": name, "description": ( - "Check for additional tools whenever your task might benefit from specialized " - "capabilities - even if existing tools could work as a fallback." + "Report that the user's request needs a capability this server does not have. " + "Records the report for the server's developers; it does not return or add tools." ), "inputSchema": { "type": "object", diff --git a/posthog/test/mcp/test_feedback.py b/posthog/test/mcp/test_feedback.py index 87274dcca..315623546 100644 --- a/posthog/test/mcp/test_feedback.py +++ b/posthog/test/mcp/test_feedback.py @@ -88,7 +88,7 @@ async def _list_tools_lowlevel(server): def test_descriptor_defaults(): descriptor = get_feedback_tool_descriptor() assert descriptor["name"] == SEND_FEEDBACK_TOOL_NAME - assert "missing capability" in descriptor["description"] + assert "a capability you needed that no tool provides" in descriptor["description"] assert descriptor["inputSchema"]["required"] == ["feedback_type", "summary"] assert set(descriptor["inputSchema"]["properties"]) == { "feedback_type", @@ -540,6 +540,48 @@ async def test_fastmcp_coexists_with_report_missing(): assert _events(client, "$mcp_tool_call") == [] +def _descriptions(node): + if isinstance(node, dict): + for key, value in node.items(): + if key == "description" and isinstance(value, str): + yield value + yield from _descriptions(value) + elif isinstance(node, list): + for item in node: + yield from _descriptions(item) + + +@pytest.mark.parametrize( + "phrase", + [ + "parallel tool calls", + "system prompt", + "even if existing tools", + "Most important", + "even if you can work around it", + "send it even if", + ], +) +async def test_advertised_descriptions_carry_no_behavioral_instructions(phrase): + server = make_fastmcp() + instrument( + server, + FakeClient(), + MCPAnalyticsOptions( + report_missing=True, collect_feedback=True, capture_model=True + ), + ) + + list_handler = server._mcp_server.request_handlers[mcp_types.ListToolsRequest] + result = await list_handler(mcp_types.ListToolsRequest(method="tools/list")) + tools = result.root.tools + assert {"add", "get_more_tools", "send_feedback"} <= {t.name for t in tools} + descriptions = list(_descriptions([t.model_dump() for t in tools])) + + assert descriptions + assert not [d for d in descriptions if phrase.lower() in d.lower()] + + # --- on_feedback ----------------------------------------------------------------- diff --git a/posthog/test/mcp/test_units.py b/posthog/test/mcp/test_units.py index 49316a1fb..7681ab741 100644 --- a/posthog/test/mcp/test_units.py +++ b/posthog/test/mcp/test_units.py @@ -235,7 +235,7 @@ def test_add_conversation_id_adds_property(): assert out["properties"]["conversation_id"]["type"] == "string" # Without this clause, ChatGPT drops the handle on each new user message and every message becomes its own session. assert ( - "rest of the conversation, including after later user messages" + "returned earlier in this conversation, unchanged" in out["properties"]["conversation_id"]["description"] ) From b155efeaf6c2d5867c33cca5c4ce1dce9ba420c3 Mon Sep 17 00:00:00 2001 From: Lucas Faria Date: Thu, 5 Nov 2026 09:37:25 -0300 Subject: [PATCH 2/2] fix(mcp): keep the cross-message clause in the conversation_id description posthog-js#5112 added "for the rest of the conversation, including after later user messages" because ChatGPT otherwise drops the handle on the first call of each new user message. Keep that semantics; it describes the field, not unrelated model behaviour. The parallel-calls and different-task instructions stay out. --- posthog/mcp/constants.py | 5 +++-- posthog/test/mcp/test_units.py | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/posthog/mcp/constants.py b/posthog/mcp/constants.py index 4a174bc86..47a2b2c62 100644 --- a/posthog/mcp/constants.py +++ b/posthog/mcp/constants.py @@ -28,8 +28,9 @@ ) DEFAULT_CONVERSATION_ID_DESCRIPTION = ( - "The conversation_id this server returned earlier in this conversation, unchanged. Omit it " - "if you have none. Recorded for the server developer's analytics." + "The conversation_id this server returned earlier in this conversation, unchanged, including " + "after later user messages. Omit it if you have none. Recorded for the server developer's " + "analytics." ) DEFAULT_MODEL_PARAMETER_DESCRIPTION = ( diff --git a/posthog/test/mcp/test_units.py b/posthog/test/mcp/test_units.py index 7681ab741..f5a3546c3 100644 --- a/posthog/test/mcp/test_units.py +++ b/posthog/test/mcp/test_units.py @@ -235,7 +235,7 @@ def test_add_conversation_id_adds_property(): assert out["properties"]["conversation_id"]["type"] == "string" # Without this clause, ChatGPT drops the handle on each new user message and every message becomes its own session. assert ( - "returned earlier in this conversation, unchanged" + "including after later user messages" in out["properties"]["conversation_id"]["description"] )