Test Failure Analysis

Summary: The CI failure is a pre-existing flaky timeout test unrelated to this PR's changes. The same test (TestTimeout::test_timeout_client_timeout_does_not_override_tool_call_timeout_if_lower) has failed across multiple unrelated branches on the same day.

Root Cause: tests/client/test_sse.py::TestTimeout::test_timeout_client_timeout_does_not_override_tool_call_timeout_if_lower uses very tight timing thresholds (client timeout=0.1s, tool sleep of 0.03s, per-call timeout of 2s). Under CI load, the connection initialization itself — the __aenter__ / initialize() handshake — consumes the 0.1s client timeout before the actual call_tool is ever invoked. The error is thrown during session setup (mcp.shared.session.py:294), not during the tool call.

This PR (feat/code-mode-markdown-serializer) did not touch tests/client/test_sse.py or any timeout-related client code. An earlier run of this exact branch (22528048506) passed all tests cleanly.

Suggested Solution: Re-run the failed job — this is a CI infrastructure flake. The underlying test itself should be fixed separately by either relaxing its timing margins or marking it with @pytest.mark.flaky to tolerate intermittent failures.

async def test_timeout_client_timeout_does_not_override_tool_call_timeout_if_lower(
    self, sse_server: str
):
    async with Client(
        transport=SSETransport(sse_server),
        timeout=0.1,   # <-- only 100ms for entire connection
    ) as client:
        await client.call_tool("sleep", {"seconds": 0.03}, timeout=2)

E  mcp.shared.exceptions.McpError: Timed out while waiting for response to ClientRequest. Waited 0.1 seconds.
   .venv/lib/python3.10/site-packages/mcp/shared/session.py:294: McpError

🤖 Generated with Claude Code

More general comment when it comes to token usage and search tools, maybe a follow-up PR.
But from my experience, from a context perspective, I have found the approach taken by mcp-cli where you have a two step search:

1. candidate selection (name + short description)
2. full schema for only 1-2 finalists

A lot more token efficient and scales better when you have a lot of tools.

Could be something like:

# default `summary`: name, short description, tags/category
# optional `detail="full"` for current behavior

search(query, detail="summary")

# return full input/output schema for selected tool(s)
get_schema(name | [name1, name2, ...] )

Thanks @MagnusS0 this is really solid work! The serializer hook and the markdown rendering are both well thought out, and I totally agree with the direction you're going here. Your follow-up comment about two-stage search actually resolves some tension I've been feeling about how search results scale with complex tool catalogs, so thanks for surfacing that.

Here's where I think this should land architecturally: we'll split the current search tool into a progressive disclosure flow —

• search returns just names and short descriptions, super lightweight. Option to get more detail.
• get_schema takes tool name(s) and returns abbreviated markdown (your serializer) by default, with an option to get the full JSON schema when the LLM needs it
• execute stays as-is

The LLM regulates its own token budget — scan candidates cheaply, pull schema detail only for the tools it actually cares about. Some default to let users err for more detail on simple servers (where two calls is worse than one due to latency) or less detail on complex servers (where two search calls is probably more efficient overall).

Since you already suggested this as a follow-up, I'd love to merge this as-is and then quickly follow up with a PR that implements the staged approach on top. You've already done the heavy lifting here with the serializer — the rest is reshaping the tool surface around it. This will all land together before it ships. Ideally targeting later this week or next.

Thanks @jlowin, really glad it landed well and that you like the direction!

One more thought for the staged approach, since you're designing the tool surface now anyway, for MCPs or converted APIs with say 10–20 domains, even a lightweight search over all candidates can get noisy. A list_categories() call as a cheap first step would let the agent scope before it does anything else:

list_categories()   # ["equity", "sec", "etf", ...]
search("price", category="equity", detail="summary")   # scoped candidates
get_schema("price_history")   # full detail

This could map to MCP tags if tools already have them, so no extra annotation burden. For servers where tags aren't set maybe don't expose the tool at all.

One pattern I've hit personally: sub-categories (e.g. equity → {price, fundamentals}). Probably niche, but if it's easy to expose as an opt-in, say a custom categories mapping on the transform, it would be very nice.

Just flagging before the surface is locked in, easier to bake in now than retrofit later.

So there is this interesting fallback (we actually started with it but it's too complicated for simple cases) where you can use the call tool to actually learn what the tools are. like we could actually expose the schema as a data structure and allow an LLM to process it arbitrarily. I think its a interesting extreme case. Maybe we find a way to support a spectrum of tools with some signature. I'll think on it!