Token warning during tool call

[luarss]

Raise a warning (in prompt) or truncate automatically if output exceeds X tokens?

• what is X? refer to how other mcp servers (e.g. playwright does it)

completion: user should be able to see the warning visibly in tool call result.

[hilay020905]

Implementation proposal

After looking at the source, the cleanest insertion point is BaseTool._format_result() in src/openroad_mcp/tools/base.py it's the single exit path for all tool output, so one change covers every tool automatically.

What X should be: 20_000 characters (same default as Playwright MCP / executeautomation). Configurable via OPENROAD_MAX_OUTPUT_CHARS env var, set to 0 to disable.

---

src/openroad_mcp/config/settings.py

Add to Settings class:

MAX_OUTPUT_CHARS: int = Field(
    default=20_000,
    description="Max characters in tool output before truncation warning (0 = unlimited)",
)

Add to env_mapping in from_env():

"MAX_OUTPUT_CHARS": ("OPENROAD_MAX_OUTPUT_CHARS", int),

---

src/openroad_mcp/tools/base.py

Replace _format_result and add _guard_output:

def _format_result(self, result: ...) -> str:
    """Format result as JSON string."""
    if isinstance(result, InteractiveExecResult):
        result = self._guard_output(result)
    if hasattr(result, "model_dump"):
        return json.dumps(result.model_dump(), separators=(",", ":"))
    return json.dumps(result, separators=(",", ":"))

def _guard_output(self, result: InteractiveExecResult) -> InteractiveExecResult:
    """Truncate output and prepend a visible warning if it exceeds MAX_OUTPUT_CHARS."""
    from ..config.settings import settings
    max_chars = settings.MAX_OUTPUT_CHARS
    if max_chars <= 0 or len(result.output) <= max_chars:
        return result
    warning = (
        f"\u26a0\ufe0f  [OUTPUT TRUNCATED] Response was {len(result.output):,} chars, "
        f"limit is {max_chars:,} chars. "
        f"Showing first {max_chars:,} chars. "
        f"Set OPENROAD_MAX_OUTPUT_CHARS env var to increase (or 0 to disable).\n"
        f"{'\u2500' * 60}\n"
    )
    return result.model_copy(update={"output": warning + result.output[:max_chars]})

---

Why this approach

• Single insertion point — _format_result is called by every tool, no need to touch individual tool classes
• Warning at the top — visible in the tool call result pane regardless of client truncation behavior
• Uses model_copy — Pydantic v2 pattern, keeps the result immutable until the last step
• InteractiveExecResult only — targets the output field which holds raw PTY output; metadata-only results (session lists, metrics) are not affected
• Env-var configurable — follows the existing OPENROAD_* naming convention in settings.py

Happy to open a PR with this + a test in tests/ if the approach looks good.