Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: list large MCP tool schemas compactly and load the full schema on demand (#11046)

Nilayfb5a9216e24f
diff --git a/studio/MCP.md b/studio/MCP.md
index 6ddc3e31ed6..4f57bc43f47 100644
--- a/studio/MCP.md
+++ b/studio/MCP.md
@@ -35,6 +35,25 @@ Downloads are staged and verified before activation; failures leave the server
disabled and can be retried with **Enable Blender MCP**. Merely opening the dialog
or launching Unsloth Studio does not download anything.
+## Large tool catalogs
+
+A server can expose dozens of tools with long descriptions and deeply nested
+parameter schemas: Notion's catalog alone is about 65,000 tokens. Every tool is
+listed in full whenever the catalog fits the loaded local model's context window,
+so a model that can hold the full listing always gets it.
+
+When the full listing would take more than three quarters of the window, which
+would otherwise get even a short prompt refused, the largest tools (only those
+whose description and schema together exceed about 1,500 characters) are listed
+in a compact form, largest first, until the listing fits: a compact tool shows its
+first sentence plus its top-level parameters with their types, required flags and
+short enums. Every other tool keeps its full schema. The model then also gets `mcp_tool_schema`, which returns a tool's
+full description and JSON Schema on demand, in pages when it is longer than the
+room left for a tool result. A compact tool called without one of its required
+arguments, or whose call the server rejects, answers with that schema so the model
+can correct the call. Arguments to a compact tool are still typed against its full
+schema. External providers always get the full listing.
+
## Unsloth Decisions MCP
When the Decision API is on (**Settings → API**), the chat's MCP menu lists
diff --git a/studio/backend/core/inference/tool_loop_controller.py b/studio/backend/core/inference/tool_loop_controller.py
index 4a8a5d49452..bfbe7f5954a 100644
--- a/studio/backend/core/inference/tool_loop_controller.py
+++ b/studio/backend/core/inference/tool_loop_controller.py
@@ -668,11 +668,22 @@ def _declared_properties(tool_name: str, tool_schemas) -> Any:
function = tool.get("function") if isinstance(tool, Mapping) else None
if not isinstance(function, Mapping) or function.get("name") != tool_name:
continue
- parameters = function.get("parameters")
+ parameters = _mcp_full_parameters(tool_name) or function.get("parameters")
return parameters.get("properties") if isinstance(parameters, Mapping) else None
return None
+def _mcp_full_parameters(tool_name: str) -> Any:
+ # A large MCP tool is listed with only its top-level parameters; type its arguments by the full schema.
+ if not tool_name.startswith("mcp__"):
+ return None
+ try:
+ from core.inference.tools import mcp_tool_input_schema # noqa: PLC0415 -- cycle at import time
+ return mcp_tool_input_schema(tool_name)
+ except Exception: # noqa: BLE001 -- typing must never break a chat
+ return None
+
+
def coerce_tool_arguments(
raw_args: Any,
*,
diff --git a/studio/backend/core/inference/tools.py b/studio/backend/core/inference/tools.py
index d6cb7fecb72..26ba72a57ff 100644
--- a/studio/backend/core/inference/tools.py
+++ b/studio/backend/core/inference/tools.py
@@ -7075,6 +7075,7 @@ _ALWAYS_SAFE_TOOLS = frozenset(
"search_conversation",
"read_skill",
"deep_research",
+ "mcp_tool_schema",
}
)
@@ -13207,6 +13208,238 @@ _MCP_ALIAS_DIGEST_LEN = 8
# The "_" plus digest every alias ends with, which is the room its stem does not get.
_MCP_ALIAS_SUFFIX_LEN = _MCP_ALIAS_DIGEST_LEN + 1
+_MCP_COMPACT_SPEC_CHARS = 1500
+_MCP_SUMMARY_CHARS = 240
+_MCP_COMPACT_HINT = "Full parameters via mcp_tool_schema."
+_MCP_MIN_SCHEMA_PAGE_CHARS = 64
+_MCP_FULL_LISTING_SHARE = 0.75
+_MCP_LISTING_CONTEXT_TOKENS: ContextVar = ContextVar("mcp_listing_context_tokens", default = None)
+# (account, window) -> tools its last MCP listing compacted; per account since studio.db (and so MCP servers) is.
+_MCP_COMPACTED_WINDOWS: dict[tuple, frozenset] = {}
+
+
+def set_mcp_listing_context_tokens(context_tokens) -> None:
+ """The local window the next MCP listing in this context is sized against; unset lists every tool in full."""
+ valid = isinstance(context_tokens, int) and context_tokens > 0
+ _MCP_LISTING_CONTEXT_TOKENS.set(context_tokens if valid else None)
+
+
+MCP_TOOL_SCHEMA_TOOL = {
+ "type": "function",
+ "function": {
+ "name": "mcp_tool_schema",
+ "description": (
+ "Return the full description and parameter schema of an MCP tool. A tool whose "
+ f"listing ends with '{_MCP_COMPACT_HINT}' shows only its top-level parameters; "
+ "call this before using it when that listing is not enough."
+ ),
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "The MCP tool name exactly as listed, including its mcp__ prefix.",
+ },
+ "offset": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Character offset for the next page. Defaults to 0.",
+ },
+ },
+ "required": ["name"],
+ },
+ },
+}
+
+
+def _mcp_input_schema(tool: dict) -> dict:
+ return (
+ tool.get("inputSchema") or tool.get("input_schema") or {"type": "object", "properties": {}}
+ )
+
+
+def _mcp_spec_compacted(tool: dict) -> bool:
+ schema_chars = len(json.dumps(_mcp_input_schema(tool), separators = (",", ":")))
+ return schema_chars + len(tool.get("description") or "") > _MCP_COMPACT_SPEC_CHARS
+
+
+def _mcp_summary(description: str) -> str:
+ text = " ".join((description or "").split()).lstrip("# ")
+ match = re.match(r"(.+?[.!?])(?:\s|$)", text)
+ if match:
+ text = match.group(1)
+ if len(text) > _MCP_SUMMARY_CHARS:
+ text = text[: _MCP_SUMMARY_CHARS - 3].rstrip() + "..."
+ return text
+
+
+def _mcp_compact_parameters(schema: dict) -> dict:
+ properties: dict[str, dict] = {}
+ for key, value in (schema.get("properties") or {}).items():
+ prop: dict = {}
+ if isinstance(value, dict):
+ branches = value.get("anyOf") or value.get("oneOf") or []
+ branch_types = [b.get("type") for b in branches if isinstance(b, dict)]
+ if isinstance(value.get("type"), (str, list)):
+ prop["type"] = value["type"]
+ elif branch_types and all(isinstance(kind, str) for kind in branch_types):
+ kinds = list(dict.fromkeys(branch_types))
+ prop["type"] = kinds[0] if len(kinds) == 1 else kinds
+ if isinstance(value.get("enum"), list) and len(json.dumps(value["enum"])) <= 200:
+ prop["enum"] = value["enum"]
+ # llama.cpp compiles an empty schema to an object-only grammar; a description alone accepts any value.
+ properties[key] = prop or {"description": "See mcp_tool_schema."}
+ compact: dict = (
+ {"type": "object", "properties": properties} if properties else {"type": "object"}
+ )
+ if isinstance(schema.get("required"), list):
+ compact["required"] = schema["required"]
+ return compact
+
+
+def _mcp_compact_spec(name: str, display: str, tool: dict, description: str) -> dict:
+ parts = (f"[{display}]", _mcp_summary(description), _MCP_COMPACT_HINT)
+ return {
+ "type": "function",
+ "function": {
+ "name": name,
+ "description": " ".join(part for part in parts if part),
+ "parameters": _mcp_compact_parameters(_mcp_input_schema(tool)),
+ },
+ }
+
+
+def _mcp_tool_schema_text(display: str, tool: dict) -> str:
+ schema = json.dumps(_mcp_input_schema(tool), separators = (",", ":"))
+ description = " ".join((tool.get("description") or "").split())
+ return f"[{display}] {tool.get('name')}: {description}\n\nParameters (JSON Schema): {schema}"
+
+
+def _mcp_cached_tool(server: dict, tool_name: str) -> dict | None:
+ for tool in get_cached_tools(server["id"]) or []:
+ if tool.get("name") == tool_name and _mcp_tool_model_visible(tool):
+ return tool
+ return None
+
+
+def _mcp_resolve_tool(name) -> "tuple[dict | None, dict | None, str]":
+ if not isinstance(name, str) or not name.startswith(MCP_TOOL_PREFIX) or name.count("__") < 2:
+ return None, None, ""
+ _, server_key, _ = name.split("__", 2)
+ tool_name = _mcp_raw_tool_name(name)
+ server = mcp_servers_db.get_server_for_tool(server_key)
+ return server, _mcp_cached_tool(server, tool_name) if server else None, tool_name
+
+
+def mcp_tool_input_schema(name) -> dict | None:
+ tool = _mcp_resolve_tool(name)[1]
+ return _mcp_input_schema(tool) if tool is not None else None
+
+
+def _mcp_schema_page(prefix: str, text: str, offset: int) -> str:
+ page_chars = _tool_result_char_budget()
+ while True:
+ end = min(offset + page_chars, len(text))
+ page = prefix + text[offset:end]
+ if end < len(text):
+ page += (
+ f"\n\n[Characters {offset}-{end} of {len(text)}. "
+ f"Call mcp_tool_schema with offset={end} for the rest.]"
+ )
+ if _fit_result_to_room(page, "mcp_tool_schema") == page:
+ return page
+ if page_chars < _MCP_MIN_SCHEMA_PAGE_CHARS:
+ # The prefix may be a server's own unbounded error text.
+ return _fit_result_to_room(
+ (prefix or "Error: ") + "Not enough context room to read this MCP tool schema. "
+ "Reduce the conversation context and retry.",
+ "mcp_tool_schema",
+ )
+ page_chars //= 2
+
+
+def _mcp_tool_schema(name, offset = None) -> str:
+ server, tool, tool_name = _mcp_resolve_tool(name)
+ if not tool_name:
+ return "Error: mcp_tool_schema needs an MCP tool name as listed, such as mcp__<server>__<tool>."
+ if not server:
+ return f"Error: MCP server for tool '{tool_name}' not found"
+ display = server.get("display_name") or server["id"]
+ if tool is None:
+ return f"Error: MCP server '{display}' does not list a tool named '{tool_name}'"
+ text = _mcp_tool_schema_text(display, tool)
+ offset = 0 if offset is None else offset
+ if isinstance(offset, bool) or not isinstance(offset, int) or not 0 <= offset < len(text):
+ return f"Error: offset must be an integer from 0 to {len(text) - 1}."
+ return _mcp_schema_page("", text, offset)
+
+
+def _mcp_compact_candidates(listed) -> list[tuple[int, dict]]:
+ """(index in the flat listing, compact spec) for every large tool, largest saving first."""
+ candidates: list[tuple[int, int, dict]] = []
+ index = 0
+ for server, payload, server_specs in listed:
+ display = server.get("display_name") or server["id"]
+ by_name = {tool.get("name"): tool for tool in payload if isinstance(tool, dict)}
+ for spec in server_specs:
+ function = spec["function"]
+ tool = by_name.get(_mcp_raw_tool_name(function["name"]))
+ if tool is not None and _mcp_spec_compacted(tool):
+ description = function["description"].removeprefix(f"[{display}]").strip()
+ compact = _mcp_compact_spec(function["name"], display, tool, description)
+ saving = len(json.dumps(spec, separators = (",", ":"))) - len(
+ json.dumps(compact, separators = (",", ":"))
+ )
+ if saving > 0:
+ candidates.append((saving, index, compact))
+ index += 1
+ candidates.sort(key = lambda item: -item[0])
+ return [(index, compact) for _, index, compact in candidates]
+
+
+def _mcp_listing(listed: list[tuple[dict, list[dict], list[dict]]]) -> list[dict]:
+ specs = [spec for _, _, server_specs in listed for spec in server_specs]
+ ctx = _MCP_LISTING_CONTEXT_TOKENS.get()
+ if not ctx or not specs:
+ return specs
+ budget = ctx * _MCP_FULL_LISTING_SHARE
+ text = json.dumps(specs, separators = (",", ":"))
+ listing_tokens = _text_token_cost(text, ctx)
+ if listing_tokens <= budget:
+ _MCP_COMPACTED_WINDOWS[(current_account_id(), ctx)] = frozenset()
+ return specs
+ # Compact the largest tools first and stop once the listing fits, so every tool that can keep its nested and
+ # union parameters does: dropping them costs tool-call accuracy (#11046 measurements).
+ tokens_per_char = listing_tokens / max(len(text), 1)
+ budget -= _text_token_cost(json.dumps(MCP_TOOL_SCHEMA_TOOL, separators = (",", ":")), ctx)
+ listing = list(specs)
+ candidates = _mcp_compact_candidates(listed)
+ chars = len(text)
+ compacted: set[str] = set()
+ for position, (index, compact) in enumerate(candidates):
+ chars -= len(json.dumps(listing[index], separators = (",", ":"))) - len(
+ json.dumps(compact, separators = (",", ":"))
+ )
+ listing[index] = compact
+ compacted.add(compact["function"]["name"])
+ if chars * tokens_per_char > budget:
+ continue
+ # The per-character rate is an average; confirm on the real listing before stopping short of the rest.
+ if (
+ position == len(candidates) - 1
+ or _text_token_cost(json.dumps(listing, separators = (",", ":")), ctx) <= budget
+ ):
+ break
+ _MCP_COMPACTED_WINDOWS[(current_account_id(), ctx)] = frozenset(compacted)
+ if compacted:
+ listing.append(MCP_TOOL_SCHEMA_TOOL)
+ return listing
+
+
+def _mcp_listing_compacted(name: str) -> bool:
+ key = (current_account_id(), _window_context_tokens() or 0)
+ return name in _MCP_COMPACTED_WINDOWS.get(key, frozenset())
+
def _mcp_tool_model_visible(tool: dict) -> bool:
"""False for MCP Apps tools marked app-only (_meta.ui.visibility without "model"): those exist
@@ -13345,7 +13578,7 @@ def cached_mcp_tools() -> tuple[list[dict], bool]:
if not stdio_mcp_enabled():
servers = [s for s in servers if not is_stdio(s["url"])]
- specs: list[dict] = []
+ listed: list[tuple[dict, list[dict], list[dict]]] = []
complete = True
for server in servers:
payload = get_cached_tools(server["id"])
@@ -13353,8 +13586,8 @@ def cached_mcp_tools() -> tuple[list[dict], bool]:
if not in_failure_cooloff(server["id"]):
complete = False
continue
- specs.extend(_mcp_specs_for_server(server, payload))
- return specs, complete
+ listed.append((server, payload, _mcp_specs_for_server(server, payload)))
+ return _mcp_listing(listed), complete
async def get_enabled_mcp_tools() -> list[dict]:
@@ -13406,13 +13639,13 @@ async def get_enabled_mcp_tools() -> list[dict]:
continue
cache_tools(server["id"], payload)
- specs: list[dict] = []
+ listed: list[tuple[dict, list[dict], list[dict]]] = []
for server in servers:
payload = get_cached_tools(server["id"])
if payload is None:
continue
- specs.extend(_mcp_specs_for_server(server, payload))
- return specs
+ listed.append((server, payload, _mcp_specs_for_server(server, payload)))
+ return _mcp_listing(listed)
_TIMEOUT_UNSET = object()
@@ -13596,6 +13829,8 @@ def execute_tool(
)
if name == "render_html":
return _fit_result_to_room(_render_html_result(arguments), name)
+ if name == "mcp_tool_schema":
+ return _mcp_tool_schema(arguments.get("name"), arguments.get("offset"))
if name.startswith(MCP_TOOL_PREFIX):
# An MCP server is not inside the terminal sandbox, so the local refusal has to hold here too.
if _mcp_arguments_reference_studio_credential(arguments):
@@ -13614,6 +13849,17 @@ def execute_tool(
return f"Error: MCP server '{display}' is disabled"
if is_stdio(server["url"]) and not stdio_mcp_enabled():
return f"Error: stdio MCP server '{display}' is disabled on this host"
+ tool = _mcp_cached_tool(server, tool_name) if _mcp_listing_compacted(name) else None
+ if tool is not None and isinstance(arguments, dict):
+ missing = [
+ key for key in _mcp_input_schema(tool).get("required") or [] if key not in arguments
+ ]
+ if missing:
+ return _mcp_schema_page(
+ f"Error: MCP tool '{tool_name}' requires {', '.join(missing)}.\n\n",
+ _mcp_tool_schema_text(display, tool),
+ 0,
+ )
# Persist a stateful stdio session only per conversation (thread_id). session_id is the project-wide sandbox
# id, so scoping by it alone leaks browser/DB/REPL state across conversations; fall back to one-shot. Tag +
# percent-quote the parts so ids can't collide or ":" merge conversations.
@@ -13642,20 +13888,22 @@ def execute_tool(
and bool(row.get("use_oauth")) == use_oauth
)
- return _fit_result_to_room(
- call_tool_sync(
- url = url,
- headers = headers,
- name = tool_name,
- args = arguments,
- timeout = effective_timeout,
- use_oauth = use_oauth,
- cancel_event = cancel_event,
- scope = mcp_scope,
- config_check = _config_current,
- ),
- name,
+ result = call_tool_sync(
+ url = url,
+ headers = headers,
+ name = tool_name,
+ args = arguments,
+ timeout = effective_timeout,
+ use_oauth = use_oauth,
+ cancel_event = cancel_event,
+ scope = mcp_scope,
+ config_check = _config_current,
)
+ if tool is not None and isinstance(result, str) and result.startswith("Error:"):
+ return _mcp_schema_page(
+ result.rstrip() + "\n\n", _mcp_tool_schema_text(display, tool), 0
+ )
+ return _fit_result_to_room(result, name)
if name == "deep_research":
if not str(arguments.get("question") or "").strip():
return "Error: deep_research needs a question to investigate."
@@ -16138,7 +16386,8 @@ def _text_token_cost(text: str, ctx: int) -> float:
return measured
# A counter that could not answer is a counter that is not there: taking its presence as proof the estimate is
# safe is what leaves dense ASCII priced at the English rate.
- estimate = sum(0.25 if character.isascii() else 1.0 for character in text)
+ ascii_chars = len(text.encode("ascii", "ignore"))
+ estimate = ascii_chars * 0.25 + (len(text) - ascii_chars)
return estimate / _UNMEASURED_ROOM_MARGIN
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index cfbd9519cd3..7d2c6568109 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -27265,6 +27265,9 @@ async def produce_openai_chat_completions(
use_tools = True
if use_tools:
+ from core.inference.tools import set_mcp_listing_context_tokens
+
+ set_mcp_listing_context_tokens(getattr(llama_backend, "context_length", None))
tools_to_use = await _select_request_tools(
payload,
tools_on = _tools_on,
@@ -29274,6 +29277,9 @@ async def produce_openai_chat_completions(
)
if _sf_use_tools:
+ from core.inference.tools import set_mcp_listing_context_tokens
+
+ set_mcp_listing_context_tokens(_monitor_context_length())
_sf_tools_to_use = await _select_request_tools(
payload, tools_on = _sf_tools_on, mcp_allowed = _sf_mcp_allowed
)
@@ -35890,7 +35896,9 @@ async def _mlx_count_chat_tokens(payload, request = None) -> Optional[JSONRespon
_mcp_tools: list[dict] = []
if _mcp_on:
from core.inference.mcp_client import mcp_server_snapshot_guard
- from core.inference.tools import cached_mcp_tools
+ from core.inference.tools import cached_mcp_tools, set_mcp_listing_context_tokens
+
+ set_mcp_listing_context_tokens(_monitor_context_length())
# A database read, so off the loop. Guarded as the GGUF count guards it, or
# an interleaving edit pairs a new row with the schema cached before it.
@@ -36261,7 +36269,9 @@ async def chat_count_tokens(
_mcp_allowed = False
_mcp_tools: list[dict] = []
if _mcp_on and not _takes_passthrough and llama_backend.supports_tools:
- from core.inference.tools import cached_mcp_tools
+ from core.inference.tools import cached_mcp_tools, set_mcp_listing_context_tokens
+
+ set_mcp_listing_context_tokens(getattr(llama_backend, "context_length", None))
from core.inference.mcp_client import mcp_server_snapshot_guard
# Keep the SQLite read off-loop while coordinating the row/cache snapshot with edits.
diff --git a/studio/backend/tests/test_mcp_servers.py b/studio/backend/tests/test_mcp_servers.py
index f7c73d1b946..a3453a33066 100644
--- a/studio/backend/tests/test_mcp_servers.py
+++ b/studio/backend/tests/test_mcp_servers.py
@@ -2193,3 +2193,408 @@ def test_adversarial_display_names_do_not_break_provenance(tmp_path, monkeypatch
# Stored verbatim; escaping is the renderer's job.
assert provisional_tool_provenance("mcp__srv1__run")["mcp_server"] == display
+
+
+def _big_mcp_tool():
+ return {
+ "name": "query",
+ "description": "Query rows. Use SQL mode by default.\nLong details follow.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "anyOf": [
+ {
+ "type": "object",
+ "properties": {"q": {"type": "string", "description": "x" * 900}},
+ },
+ {"type": "object"},
+ ]
+ },
+ "mode": {"type": "string", "enum": ["sql", "rows"], "description": "y" * 800},
+ "tags": {"type": "array", "items": {"type": "string"}},
+ },
+ "required": ["data"],
+ },
+ }
+
+
+def _cache_server_tools(tmp_path, monkeypatch, tools):
+ from core.inference import mcp_client, tools as tools_mod
+
+ _reset_db(tmp_path, monkeypatch)
+ monkeypatch.setattr(mcp_client, "_tool_cache", {})
+ monkeypatch.setattr(tools_mod, "_MCP_COMPACTED_WINDOWS", {})
+ mcp_servers_db.create_server(id = "srv1", display_name = "A", url = "https://a.example/mcp")
+ mcp_client.cache_tools("srv1", tools)
+
+
+def listing_window():
+ from core.inference import tools as tools_mod
+
+ tokens = []
+
+ def _set(context_tokens):
+ tokens.append(tools_mod._MCP_LISTING_CONTEXT_TOKENS.set(context_tokens))
+ return context_tokens
+
+ yield _set
+ for token in reversed(tokens):
+ tools_mod._MCP_LISTING_CONTEXT_TOKENS.reset(token)
+
+
+def compacting(monkeypatch, listing_window):
+ from core.inference import tools as tools_mod
+ monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 0.0)
+ return listing_window(100_000)
+
+
+_PING = {
+ "name": "ping",
+ "description": "Ping. Returns pong.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {"n": {"type": "integer", "description": "count"}},
+ },
+}
+
+
+def test_mcp_listing_stays_full_when_it_fits_the_window(tmp_path, monkeypatch, listing_window):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool()])
+ unsized = tools_mod.cached_mcp_tools()[0]
+ assert [s["function"]["name"] for s in unsized] == ["mcp__srv1__ping", "mcp__srv1__query"]
+ assert unsized[1]["function"]["parameters"] == _big_mcp_tool()["inputSchema"]
+
+ listing_window(1_000_000)
+ assert tools_mod.cached_mcp_tools()[0] == unsized
+ assert list(tools_mod._MCP_COMPACTED_WINDOWS.values()) == [frozenset()]
+
+ listing_window(1_000)
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert tools_mod._MCP_COMPACTED_WINDOWS[(tools_mod.current_account_id(), 1_000)] == {
+ "mcp__srv1__query"
+ }
+ assert specs[0] == unsized[0]
+ assert specs[1]["function"]["parameters"] != unsized[1]["function"]["parameters"]
+ assert specs[2] == tools_mod.MCP_TOOL_SCHEMA_TOOL
+
+
+def test_mcp_listing_compacts_only_the_largest_tools_it_needs_to(
+ tmp_path, monkeypatch, listing_window
+):
+ from core.inference import tools as tools_mod
+
+ huge = dict(_big_mcp_tool(), name = "huge")
+ huge["inputSchema"] = dict(huge["inputSchema"], description = "z" * 20_000)
+ _cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool(), huge])
+ full = tools_mod.cached_mcp_tools()[0]
+ full_tokens = tools_mod._text_token_cost(json.dumps(full, separators = (",", ":")), 10_000)
+
+ ctx = listing_window(int(full_tokens * 0.9 / tools_mod._MCP_FULL_LISTING_SHARE))
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert tools_mod._MCP_COMPACTED_WINDOWS[(tools_mod.current_account_id(), ctx)] == {
+ "mcp__srv1__huge"
+ }
+ assert specs[:2] == full[:2]
+ assert specs[2]["function"]["parameters"] != full[2]["function"]["parameters"]
+ assert specs[3] == tools_mod.MCP_TOOL_SCHEMA_TOOL
+ listed = tools_mod._text_token_cost(json.dumps(specs, separators = (",", ":")), ctx)
+ assert listed <= ctx * tools_mod._MCP_FULL_LISTING_SHARE
+
+ monkeypatch.setattr(tools_mod, "_window_context_tokens", lambda: ctx)
+ assert tools_mod._mcp_listing_compacted("mcp__srv1__huge")
+ assert not tools_mod._mcp_listing_compacted("mcp__srv1__query")
+
+
+def test_mcp_listing_never_compacts_a_tool_its_compact_form_would_enlarge(
+ tmp_path, monkeypatch, compacting
+):
+ from core.inference import tools as tools_mod
+
+ loose = {
+ "name": "loose",
+ "description": "Takes anything.",
+ "inputSchema": {"type": "object", "properties": {f"p{i}": {} for i in range(200)}},
+ }
+ _cache_server_tools(tmp_path, monkeypatch, [_PING, loose])
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert specs[1]["function"]["parameters"] == loose["inputSchema"]
+ assert tools_mod.MCP_TOOL_SCHEMA_TOOL not in specs
+
+
+def test_compacted_tools_are_remembered_per_account(tmp_path, monkeypatch, compacting):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
+ monkeypatch.setattr(tools_mod, "_window_context_tokens", lambda: compacting)
+ monkeypatch.setattr(tools_mod, "current_account_id", lambda: "alice")
+ tools_mod.cached_mcp_tools()
+ assert tools_mod._mcp_listing_compacted("mcp__srv1__query")
+
+ # Another account whose catalog fits the same window lists in full.
+ monkeypatch.setattr(tools_mod, "current_account_id", lambda: "bob")
+ monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 1.0)
+ tools_mod.cached_mcp_tools()
+ assert not tools_mod._mcp_listing_compacted("mcp__srv1__query")
+
+ monkeypatch.setattr(tools_mod, "current_account_id", lambda: "alice")
+ assert tools_mod._mcp_listing_compacted("mcp__srv1__query")
+
+
+def test_mcp_listing_compacts_large_schemas(tmp_path, monkeypatch, compacting):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_PING, _big_mcp_tool()])
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert specs[0]["function"]["description"] == "[A] Ping. Returns pong."
+ assert specs[0]["function"]["parameters"] == _PING["inputSchema"]
+ compact = specs[1]["function"]
+ assert compact["name"] == "mcp__srv1__query"
+ assert compact["description"] == "[A] Query rows. Full parameters via mcp_tool_schema."
+ assert compact["parameters"] == {
+ "type": "object",
+ "properties": {
+ "data": {"type": "object"},
+ "mode": {"type": "string", "enum": ["sql", "rows"]},
+ "tags": {"type": "array"},
+ },
+ "required": ["data"],
+ }
+
+
+def test_mcp_summary_caps_a_description_without_a_sentence_end():
+ from core.inference.tools import _mcp_summary
+
+ assert _mcp_summary(" Fetch a page\n by id. Then more. ") == "Fetch a page by id."
+ assert _mcp_summary("## Overview\n\nCreates pages. Details.") == "Overview Creates pages."
+ long = _mcp_summary("word " * 100)
+ assert len(long) == 240 and long.endswith("...")
+
+
+def test_mcp_tool_lists_offer_the_schema_tool_only_when_something_was_compacted(
+ tmp_path, monkeypatch, compacting
+):
+ import asyncio
+
+ from core.inference import mcp_client, tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [{"name": "ping"}])
+ specs, complete = tools_mod.cached_mcp_tools()
+ assert complete is True
+ assert [s["function"]["name"] for s in specs] == ["mcp__srv1__ping"]
+ assert asyncio.run(tools_mod.get_enabled_mcp_tools()) == specs
+
+ mcp_client.cache_tools("srv1", [{"name": "ping"}, _big_mcp_tool()])
+ names = [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]]
+ assert names == ["mcp__srv1__ping", "mcp__srv1__query", "mcp_tool_schema"]
+ assert [s["function"]["name"] for s in asyncio.run(tools_mod.get_enabled_mcp_tools())] == names
+
+
+def test_execute_tool_answers_a_compacted_call_missing_required_args_with_its_schema(
+ tmp_path, monkeypatch, compacting
+):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
+ tools_mod.cached_mcp_tools()
+ calls = []
+ monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: calls.append(kwargs) or "ran")
+
+ out = tools_mod.execute_tool("mcp__srv1__query", {"mode": "sql"}, context_tokens = compacting)
+ assert out.startswith("Error: MCP tool 'query' requires data.\n\n[A] query: Query rows.")
+ assert json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":")) in out
+ assert calls == []
+
+ assert (
+ tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = compacting) == "ran"
+ )
+ assert calls[0]["name"] == "query" and calls[0]["args"] == {"data": {}}
+
+
+def test_execute_tool_returns_the_schema_with_a_rejected_compacted_call(
+ tmp_path, monkeypatch, listing_window
+):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
+ rejected = "Error: data: 'q' is a required property"
+ monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: rejected)
+ schema = json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":"))
+
+ fits = listing_window(1_000_000)
+ tools_mod.cached_mcp_tools()
+ assert (
+ tools_mod.execute_tool("mcp__srv1__query", {"mode": "sql"}, context_tokens = fits) == rejected
+ )
+ assert tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = fits) == rejected
+
+ monkeypatch.setattr(tools_mod, "_MCP_FULL_LISTING_SHARE", 0.0)
+ overflows = listing_window(100_000)
+ tools_mod.cached_mcp_tools()
+ out = tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = overflows)
+ assert out == rejected + "\n\n" + tools_mod._mcp_tool_schema_text("A", _big_mcp_tool())
+ assert schema in out
+
+
+def test_a_rejected_compacted_call_stays_within_the_room_left(tmp_path, monkeypatch, compacting):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
+ rejected = "Error: " + "invalid value " * 2_000
+ monkeypatch.setattr(tools_mod, "call_tool_sync", lambda **kwargs: rejected)
+ monkeypatch.setattr(tools_mod, "_fit_result_to_room", lambda text, name = None: text[:200])
+ tools_mod.cached_mcp_tools()
+ out = tools_mod.execute_tool("mcp__srv1__query", {"data": {}}, context_tokens = compacting)
+ assert out == rejected[:200]
+
+
+def test_execute_tool_mcp_tool_schema(tmp_path, monkeypatch):
+ from core.inference import tools as tools_mod
+
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool()])
+ out = tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__query"})
+ assert out.startswith("[A] query: Query rows. Use SQL mode by default. Long details follow.")
+ assert out.endswith(json.dumps(_big_mcp_tool()["inputSchema"], separators = (",", ":")))
+ assert (
+ tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__nope"})
+ == "Error: MCP server 'A' does not list a tool named 'nope'"
+ )
+ assert (
+ tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__missing__query"})
+ == "Error: MCP server for tool 'query' not found"
+ )
+ assert tools_mod.execute_tool("mcp_tool_schema", {"name": "query"}).startswith(
+ "Error: mcp_tool_schema needs an MCP tool name"
+ )
+ assert not tools_mod.is_potentially_unsafe_tool_call("mcp_tool_schema", {"name": "x"})
+ assert not tools_mod.is_high_risk_tool_call("mcp_tool_schema", {"name": "x"})
+
+
+def test_mcp_compact_parameters_never_emit_an_empty_schema():
+ from core.inference.tools import _mcp_compact_parameters
+
+ compact = _mcp_compact_parameters(
+ {
+ "type": "object",
+ "properties": {
+ "labels": {"type": "array", "items": {"type": "string"}},
+ "assignees": {
+ "anyOf": [{"type": "array", "items": {"type": "string"}}, {"type": "null"}]
+ },
+ "state": {"$ref": "#/$defs/State"},
+ },
+ }
+ )
+ assert compact["properties"] == {
+ "labels": {"type": "array"},
+ "assignees": {"type": ["array", "null"]},
+ "state": {"description": "See mcp_tool_schema."},
+ }
+ assert _mcp_compact_parameters({"$ref": "#/$defs/Args"}) == {"type": "object"}
+
+
+def test_compacted_mcp_call_arguments_are_typed_by_the_full_schema(
+ tmp_path, monkeypatch, compacting
+):
+ from core.inference import tools as tools_mod
+ from core.inference.tool_loop_controller import coerce_tool_arguments
+
+ tool = _big_mcp_tool()
+ tool["inputSchema"]["properties"]["filter"] = {
+ "type": "object",
+ "properties": {"archived": {"type": "boolean"}, "limit": {"type": "integer"}},
+ }
+ _cache_server_tools(tmp_path, monkeypatch, [tool])
+ specs = tools_mod.cached_mcp_tools()[0]
+ assert "archived" not in json.dumps(specs[0]["function"]["parameters"])
+ coerced = coerce_tool_arguments(
+ {"filter": '{"archived": "false", "limit": "25"}'},
+ heal = False,
+ tool_name = "mcp__srv1__query",
+ tool_schemas = specs,
+ )
+ assert coerced.arguments == {"filter": {"archived": False, "limit": 25}}
+
+
+def test_mcp_tool_schema_pages_a_schema_larger_than_the_result_room(tmp_path, monkeypatch):
+ from core.inference import tools as tools_mod
+
+ tool = _big_mcp_tool()
+ tool["inputSchema"]["properties"]["notes"] = {"type": "string", "description": "z " * 12000}
+ _cache_server_tools(tmp_path, monkeypatch, [tool])
+ full = tools_mod._mcp_tool_schema_text("A", tool)
+ monkeypatch.setattr(tools_mod, "_loaded_context_tokens", lambda: 16384)
+ token = tools_mod._REQUEST_RESULT_BUDGET.set(2000)
+ try:
+ pages, offset = [], 0
+ for _ in range(50):
+ out = tools_mod.execute_tool(
+ "mcp_tool_schema", {"name": "mcp__srv1__query", "offset": offset}
+ )
+ body, marker, rest = out.partition("\n\n[Characters ")
+ pages.append(body)
+ if not marker:
+ break
+ offset = int(rest.split("offset=")[1].split(" ")[0])
+ finally:
+ tools_mod._REQUEST_RESULT_BUDGET.reset(token)
+ assert len(pages) > 1
+ assert "".join(pages) == full
+
+
+def test_hidden_large_mcp_tool_does_not_offer_the_schema_tool(tmp_path, monkeypatch, compacting):
+ from core.inference import tools as tools_mod
+
+ hidden = _big_mcp_tool()
+ hidden["_meta"] = {"ui": {"visibility": ["app"]}}
+ _cache_server_tools(tmp_path, monkeypatch, [{"name": "ping"}, hidden])
+ assert [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]] == ["mcp__srv1__ping"]
+
+
+def test_mcp_tool_schema_does_not_reveal_an_app_only_tool(tmp_path, monkeypatch, compacting):
+ from core.inference import tools as tools_mod
+
+ hidden = {
+ "name": "widget_refresh",
+ "description": "Refresh the widget.",
+ "_meta": {"ui": {"visibility": ["app"]}},
+ }
+ _cache_server_tools(tmp_path, monkeypatch, [_big_mcp_tool(), hidden])
+ assert "mcp_tool_schema" in [s["function"]["name"] for s in tools_mod.cached_mcp_tools()[0]]
+ assert (
+ tools_mod.execute_tool("mcp_tool_schema", {"name": "mcp__srv1__widget_refresh"})
+ == "Error: MCP server 'A' does not list a tool named 'widget_refresh'"
+ )
+
+
+def test_compacted_alias_keeps_its_raw_name_and_resolves_its_schema(
+ tmp_path, monkeypatch, compacting
+):
+ from core.inference import tools as tools_mod
+ from core.inference.tool_loop_controller import coerce_tool_arguments
+
+ tool = _big_mcp_tool()
+ tool["name"] = "catalog.query"
+ tool["inputSchema"]["properties"]["filter"] = {
+ "type": "object",
+ "properties": {"limit": {"type": "integer"}},
+ }
+ _cache_server_tools(tmp_path, monkeypatch, [tool])
+ specs = tools_mod.cached_mcp_tools()[0]
+ spec = specs[0]["function"]
+ alias = spec["name"]
+ assert alias != "mcp__srv1__catalog.query"
+ assert (
+ spec["description"]
+ == "[A] (catalog.query) Query rows. Full parameters via mcp_tool_schema."
+ )
+ out = tools_mod.execute_tool("mcp_tool_schema", {"name": alias})
+ assert out.startswith("[A] catalog.query: Query rows.")
+ coerced = coerce_tool_arguments(
+ {"filter": '{"limit": "25"}'}, heal = False, tool_name = alias, tool_schemas = specs
+ )
+ assert coerced.arguments == {"filter": {"limit": 25}}