docs review: MCP `to_openai_tool()` DRY refactor (PraisonAI PR #3366) — verify existing MCP + tool-search pages stay accurate

[MervinPraison]

Source change

• Repo: MervinPraison/PraisonAI
• PR: #3366 — refactor: extract duplicate MCP to_openai_tool() into shared helper
• Fixes: #3364 — Duplicate logic: identical MCP to_openai_tool() copied across three transport tool classes
• Commit on main: 2bc80d84b7f6c5a721946d0d2fa4196ee5e459b9
• Category: Duplicate logic / internal DRY tidy-up
• Behaviour change: none (output dicts are byte-identical, including the __praisonai_deferrable__ marker)

What changed in the SDK

A new shared helper is added next to fix_array_schemas in praisonaiagents/mcp/mcp_schema_utils.py:

def build_openai_tool_dict(name: str, description: str, input_schema: Any) -> Dict[str, Any]:
    """
    Build an OpenAI function-calling tool dict for an MCP tool.

    DRY: This centralizes the OpenAI tool-dict construction (including the
    ``__praisonai_deferrable__`` marker) that was previously duplicated across
    ``mcp_sse``, ``mcp_http_stream``, and ``mcp_websocket``.
    """
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": fix_array_schemas(input_schema),
        },
        "__praisonai_deferrable__": True,  # Mark MCP tools as deferrable for tool search
    }

The three per-transport tool classes now delegate to it in a single line:

File	Class	Before	After
praisonaiagents/mcp/mcp_http_stream.py	HTTPStreamMCPTool.to_openai_tool	12-line inline dict construction	return build_openai_tool_dict(self.name, self.description, self.input_schema)
praisonaiagents/mcp/mcp_sse.py	SSEMCPTool.to_openai_tool	12-line inline dict construction	return build_openai_tool_dict(self.name, self.description, self.input_schema)
praisonaiagents/mcp/mcp_websocket.py	WebSocketMCPTool.to_openai_tool	12-line inline dict construction	return build_openai_tool_dict(self.name, self.description, self.input_schema)

Deliberately untouched: the MCP-class dispatcher to_openai_tool in mcp.py (praisonaiagents/mcp/mcp.py:922), and each transport class's public to_openai_tools() wrapper.

Documentation impact assessment

Verdict: No user-facing documentation update is required. This is a pure internal DRY refactor. Output dicts are byte-identical, including the __praisonai_deferrable__ marker, and no public method signatures or import paths change. Under the "user-focused, non-developer, agent-centric" docs principle from AGENTS.md, this refactor has zero surface area for a user-facing page.

The auto-generated SDK reference at docs/sdk/reference/praisonaiagents/functions/MCP-to_openai_tool.mdx will be regenerated by the parity system on the next generate_docs_parity.py --copy-docs run; no manual edit needed.

Existing PraisonAIDocs references verified

Every current mention of the affected symbols was re-read against the refactored SDK and remains accurate. No wording change required.

File	Line	Text	Still accurate?
docs/features/tool-search.mdx	219	**MCP tools**: Automatically marked with __praisonai_deferrable__ = True	✅ Yes — the marker still resolves to True from the shared helper.
docs/features/tool-search.mdx	148–149	enabled / threshold_pct params reference "deferrable schema tokens"	✅ Yes — deferrable classification is unchanged.
features/mcp/index.mdx	108	| to_openai_tool() | Converts tools to OpenAI format | (methods table)	✅ Yes — method exists, signature unchanged, return value unchanged.
docs/sdk/reference/praisonaiagents/functions/MCP-to_openai_tool.mdx	34–41	Signature / return docstring	✅ Yes — auto-generated; regenerate on next parity run for freshness.
docs/features/mcp.mdx, docs/features/mcp-three-layers.mdx, docs/features/mcp-client-protocol.mdx, docs/features/mcp-lifecycle.mdx, docs/features/mcp-recipe-server.mdx, docs/features/mcp-resources-and-prompts.mdx, docs/features/mcp-scoped-api-keys.mdx, docs/features/mcp-sse-security.mdx, docs/features/mcp-stdio-server-transport.mdx, docs/concepts/mcp.mdx	—	Describe the four transports (stdio / SSE / HTTP Stream / WebSocket) and MCP usage from the agent perspective	✅ Yes — none reference the extracted helper or the internal dict-construction code path.

Also confirmed: no PraisonAIDocs page references build_openai_tool_dict, mcp_schema_utils, HTTPStreamMCPTool, SSEMCPTool, or WebSocketMCPTool (searched with grep across docs/ and features/). The refactor introduces no new user-callable symbol that would need documenting.

Recommended disposition

For the next docs agent that picks this up:

1. Default action: close as no-op. Verified no page requires an edit. This issue exists purely for traceability so every PraisonAI PR has a corresponding docs-side review record.
2. Optional (nice-to-have, not required): re-run python3 src/praisonai/scripts/generate_docs_parity.py --copy-docs so the auto-generated MCP-to_openai_tool.mdx picks up the refreshed source-line link — the current href points to mcp/mcp.py#L567, which is still correct for the MCP-class dispatcher (not part of this refactor), so this is cosmetic.
3. Do NOT create a new page describing build_openai_tool_dict — per the AGENTS.md "user-focused, non-developer" principle, internal shared helpers are out of scope for the docs site.
4. Do NOT modify docs/concepts/mcp.mdx — per the folder-placement rules, docs/concepts/ is human-approved only, and this change gives no reason to touch it anyway.

Verification trail

Executed against a fresh clone of both repos at the current main heads:

# 1. Confirmed the three transports now delegate to the shared helper
grep -n "build_openai_tool_dict" src/praisonai-agents/praisonaiagents/mcp/*.py
#   mcp_http_stream.py:39, mcp_http_stream.py:154
#   mcp_schema_utils.py:41
#   mcp_sse.py:27, mcp_sse.py:114
#   mcp_websocket.py:31, mcp_websocket.py:356

# 2. Confirmed no PraisonAIDocs page references the helper or the internal classes
grep -rn "build_openai_tool_dict\|mcp_schema_utils\|HTTPStreamMCPTool\|SSEMCPTool\|WebSocketMCPTool" docs/ features/
#   (no matches)

# 3. Confirmed all existing mentions of the affected public symbols are still accurate
grep -rn "to_openai_tool\|__praisonai_deferrable__" docs/ features/
#   → matches shown in the table above; all remain correct.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Docs review: MCP to_openai_tool() DRY refactor (PR #3366)

• Read AGENTS.md folder/disposition rules
• Verify existing docs references (to_openai_tool, __praisonai_deferrable__)
• Confirm no page references internal helper/classes
• Check auto-generated SDK reference page
• Decide disposition & report

Verdict: ✅ No-op confirmed — no documentation change required

I independently re-verified every claim in the issue against this repo. The refactor extracts duplicated dict-building into a shared build_openai_tool_dict helper with byte-identical output (including the __praisonai_deferrable__ marker). It touches no public signature, import path, or user-callable symbol.

Existing references — all still accurate:

File:line	Text	Accurate?
docs/features/tool-search.mdx:219	MCP tools marked __praisonai_deferrable__ = True	✅ marker still resolves to True
docs/features/tool-search.mdx:148-149	deferrable schema-token params	✅ classification unchanged
features/mcp/index.mdx:108	to_openai_tool() methods-table row	✅ method exists, return unchanged
docs/sdk/reference/.../MCP-to_openai_tool.mdx	signature + mcp.py#L567 source link	✅ documents the MCP-class dispatcher, which the refactor deliberately leaves untouched

Grep confirmed: no page under docs/ or features/ references build_openai_tool_dict, mcp_schema_utils, HTTPStreamMCPTool, SSEMCPTool, or WebSocketMCPTool. Internal shared helpers are out of scope per AGENTS.md's "user-focused, non-developer" principle.

Note on the vendored SDK copy: this docs repo's praisonaiagents/mcp/ has not yet synced PR #3366 (inline dict construction still present, no build_openai_tool_dict). This is expected — the parity/sync system pulls SDK snapshots periodically. It doesn't affect the docs, since the output dict is identical before and after the refactor.

Why no PR was opened

There is nothing to edit — every affected doc line is already correct, and fabricating a change would violate both the "do nothing more than asked" rule and the folder-placement rules. An empty commit/PR isn't possible. Per the issue's own recommended disposition, this can be closed as a no-op; the auto-generated MCP-to_openai_tool.mdx will refresh on the next parity run (cosmetic only — its mcp.py#L567 link already targets the untouched dispatcher).

Job run · Branch: claude/issue-2393-20260727-0843 (no changes)