<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Pulkit Mundra - Engineering Deep Dives]]></title><description><![CDATA[Pulkit Mundra - Engineering Deep Dives]]></description><link>https://pulkitmundra.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 13:22:54 GMT</lastBuildDate><atom:link href="https://pulkitmundra.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Bypassing GNOME Wayland's Fullscreen Black Curtain for an Always-on-Top Translucent Player]]></title><description><![CDATA[How to fix GNOME Wayland's opaque black fullscreen curtain and X11's quadratic 0.5x0.5 alpha dimming for Always-on-Top translucent Linux video player.]]></description><link>https://pulkitmundra.hashnode.dev/bypassing-gnome-wayland-s-fullscreen-black-curtain-for-an-always-on-top-translucent-player</link><guid isPermaLink="true">https://pulkitmundra.hashnode.dev/bypassing-gnome-wayland-s-fullscreen-black-curtain-for-an-always-on-top-translucent-player</guid><category><![CDATA[Electron]]></category><category><![CDATA[Ubuntu]]></category><category><![CDATA[JavaScript]]></category><category><![CDATA[desktop apps]]></category><category><![CDATA[wayland]]></category><category><![CDATA[Linux]]></category><dc:creator><![CDATA[Pulkit Mundra]]></dc:creator><pubDate>Sat, 14 Nov 2026 18:19:53 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af80a39b48a8c15442d9de7/d86e6e55-8710-4fdb-a4fe-7a2f6daf18c9.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>TL;DR Summary</h2>
<ul>
<li>Browser Picture-in-Picture on Linux often drops styled anime subtitles or sinks behind active IDE windows as soon as you click your terminal.</li>
<li>On GNOME Wayland (Mutter), exclusive _NET_WM_STATE_FULLSCREEN windows are backed by a solid black compositor curtain, and XWayland ignores _NET_WM_WINDOW_OPACITY.</li>
<li>Stacking CSS root alpha (--cr-window-opacity) with native win.setOpacity() on X11 multiplies both alphas together (0.5 * 0.5 = 0.25), making 20% opacity nearly invisible (4%) until unified onto a single ARGB alpha layer</li>
</ul>
<h2>Linux Compositor Window Translucency Behavior (X11 vs XWayland vs Wayland Bypass)</h2>
<table>
<thead>
<tr>
<th>Compositor Mode</th>
<th>Native <code>win.setOpacity(0.5)</code></th>
<th>CSS ARGB <code>--cr-window-opacity: 0.5</code></th>
<th>Combined Result Before -&gt; After Fix</th>
</tr>
</thead>
<tbody><tr>
<td>X11 Windowed</td>
<td>50% <code>_NET_WM_WINDOW_OPACITY</code></td>
<td>50% surface alpha</td>
<td>25% quadratic dark -&gt; 50% linear ARGB</td>
</tr>
<tr>
<td>GNOME Wayland Fullscreen</td>
<td>Ignored by XWayland</td>
<td>Composited over black curtain</td>
<td>Fades to black -&gt; Borderless <code>workArea</code> see-through</td>
</tr>
<tr>
<td>GNOME Wayland Auto-PiP</td>
<td>Always-on-Top <code>560x315</code></td>
<td>Crisp 100% or custom alpha</td>
<td>Subtitles intact over active IDE/terminal</td>
</tr>
</tbody></table>
<h2>1. Why Browser PiP Breaks Down for Anime + Coding Workflows</h2>
<p>Modern AI-assisted software engineering involves lots of 2-to-10-minute waits while Python test suites, Docker builds, or multi-step coding agents run. Watching subbed anime in a normal browser tab fails immediately: HTML5 Picture-in-Picture skips custom subtitle overlays on many Linux builds, and unpinned floating windows vanish the instant you click back into your editor or terminal. Using AI-assisted desktop engineering on top of Castlabs' Widevine DRM runtime, I built Crunchyroll Ubuntu Desktop around two Linux window-management primitives: Smart Auto-PiP (which automatically shrinks and pins an Always-on-Top mini-window with full subtitles whenever focus moves to another app) and See-Through Player Translucency (20% to 100%) so you can watch terminal logs progress right behind an episode.</p>
<h2>2. Compositor Trap #1: Mutter's Fullscreen Black Curtain</h2>
<p>Even when a desktop window is created with transparent: true (32-bit ARGB visual), setting actual _NET_WM_STATE_FULLSCREEN on GNOME Wayland instructs Mutter to scan out the surface over an opaque black fullscreen backdrop for direct-scanout optimization. Lowering alpha just fades the video into pitch black instead of revealing your code editor underneath. Our fix automatically detects when player opacity drops below 100% while fullscreen: the main process exits exclusive fullscreen and snaps the borderless window to screen.getDisplayMatching(bounds).workArea. Visually it still fills your workspace, but Mutter now composites the 32-bit ARGB surface cleanly over your underlying windows, restoring true fullscreen automatically at 100%.</p>
<h2>3. Compositor Trap #2: Quadratic Double-Dimming (0.5 * 0.5 = 0.25)</h2>
<p>Initially we set both CSS --cr-window-opacity on body.player-active (so Wayland's ARGB buffer carried the alpha) AND native win.setOpacity(alpha) (for X11 window managers). On X11/XWayland compositors that honor both 32-bit ARGB alpha and _NET_WM_WINDOW_OPACITY, the compositor multiplied the two layers together: choosing 50% gave 25% brightness, and choosing 20% gave 4%! Keeping native window opacity at 1.0 and driving translucency solely through the 32-bit ARGB surface alpha (--cr-window-opacity) made translucency strictly linear from 20% to 100% across both Wayland and X11 while keeping Ctrl+Shift+S frame captures at full 100% clarity. <strong>Single-layer ARGB opacity + GNOME Wayland fullscreen workArea bypass</strong></p>
<pre><code class="language-javascript">// Keep native window opacity at 1.0 so X11/XWayland never squares alpha (0.5 * 0.5 = 0.25).
// When &lt; 100% while fullscreen, exit _NET_WM_STATE_FULLSCREEN and snap to workArea
// so GNOME Wayland composites the 32-bit ARGB surface over underlying IDE windows.
if (clamped &lt; 0.999 &amp;&amp; win.isFullScreen()) {
  translucentFullscreenBypass = true;
  win.setFullScreen(false);
  win.setBounds(screen.getDisplayMatching(win.getBounds()).workArea);
}
</code></pre>
<h2>Technical Q&amp;A</h2>
<h3>Why does a transparent Electron or GTK window turn solid black in fullscreen on GNOME Wayland?</h3>
<p>When <code>_NET_WM_STATE_FULLSCREEN</code> is set on GNOME Wayland, Mutter places an opaque black direct-scanout backdrop behind the surface. Exiting exclusive fullscreen into a borderless window sized to <code>screen.getDisplayMatching(bounds).workArea</code> preserves a full-workspace view while letting Mutter composite 32-bit ARGB transparency over underlying windows.</p>
<h3>Why does combining Electron win.setOpacity() with CSS rgba/opacity make windows way too dark on X11?</h3>
<p>On X11 compositors, <code>_NET_WM_WINDOW_OPACITY</code> multiplies on top of the window's per-pixel ARGB alpha channel (<code>0.5 * 0.5 = 0.25</code>, <code>0.2 * 0.2 = 0.04</code>). Keeping native window opacity at <code>1.0</code> and driving alpha solely via CSS on a <code>transparent: true</code> visual gives linear 20%-100% translucency across both X11 and Wayland.</p>
<hr />
<p>Originally published with an interactive in-browser simulator at <a href="https://pulkit-mundra-portfolio.vercel.app/engineering/wayland-fullscreen-black-curtain-translucent-linux-player">https://pulkit-mundra-portfolio.vercel.app/engineering/wayland-fullscreen-black-curtain-translucent-linux-player</a>.</p>
]]></content:encoded></item><item><title><![CDATA[650 MB to 70 MB RAM: Porting a 12-Camera Python CCTV Wall to a Native Binary with AI (and the 64 KB Linux Pipe Trap)]]></title><description><![CDATA[Porting a 12-camera Python RTSP wall to a 70 MB OpenGL binary: fixing Linux's 64 KB pipe FIONREAD trap, <0.9s cold startup & Cloud P2P isolation.]]></description><link>https://pulkitmundra.hashnode.dev/650-mb-to-70-mb-ram-porting-a-12-camera-python-cctv-wall-to-a-native-binary-with-ai-and-the-64-kb-linux-pipe-trap</link><guid isPermaLink="true">https://pulkitmundra.hashnode.dev/650-mb-to-70-mb-ram-porting-a-12-camera-python-cctv-wall-to-a-native-binary-with-ai-and-the-64-kb-linux-pipe-trap</guid><category><![CDATA[Rust]]></category><category><![CDATA[Linux]]></category><category><![CDATA[Python]]></category><category><![CDATA[performance]]></category><category><![CDATA[Systems Programming]]></category><dc:creator><![CDATA[Pulkit Mundra]]></dc:creator><pubDate>Sat, 14 Nov 2026 18:14:38 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af80a39b48a8c15442d9de7/52872e55-8d08-4b37-aec2-857b00d1fbcb.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>TL;DR Summary</h2>
<ul>
<li>Prototyping our 12-camera RTSP surveillance wall in Python/Tkinter/OpenCV first proved the architecture, and using AI-assisted engineering to port that pipeline into a compiled Rust/OpenGL binary cut memory from ~650 MB to ~70 MB and cold startup from ~14s to &lt;0.9s.</li>
<li>Linux defaults anonymous pipes to 64 KiB (65,536 bytes), which is smaller than a single 480x270 (270p) RGBA SD frame (518,400 bytes) - meaning ioctl(FIONREAD) never saw 2 queued frames until we expanded the kernel pipe via fcntl(F_SETPIPE_SZ, 1_048_576).</li>
<li>On shared UDP Cloud P2P tunnels, replacing blocking channel sends with try_send + per-camera write timeouts isolated stalled streams so 1 bad camera never freezes the other 11.</li>
</ul>
<h2>Python/OpenCV Prototype vs AI-Ported Native OpenGL Binary (12 Live RTSP Streams)</h2>
<table>
<thead>
<tr>
<th>System Metric</th>
<th>Python + Tkinter + OpenCV</th>
<th>Native Rust + OpenGL (glow)</th>
<th>Root Engineering Cause</th>
</tr>
</thead>
<tbody><tr>
<td>Resident Memory (12 cams)</td>
<td>~650 MB</td>
<td>~70 MB (-89%)</td>
<td>Zero Python object/frame-copy heap overhead</td>
</tr>
<tr>
<td>Parallel Cold Startup</td>
<td>~14.0 seconds</td>
<td>&lt;0.9 seconds</td>
<td>12 OS threads + FFmpeg <code>-fpsprobesize 0</code></td>
</tr>
<tr>
<td>Glass-to-Glass Latency</td>
<td>2.0 - 5.0 s drift</td>
<td>&lt;80 ms live edge</td>
<td><code>fcntl(F_SETPIPE_SZ, 1 MiB)</code> + <code>FIONREAD</code> drain</td>
</tr>
<tr>
<td>Digital Zoom (1x - 5x)</td>
<td>CPU frame crop/rescale</td>
<td>0.0% CPU</td>
<td>GPU fragment UV coordinate remapping</td>
</tr>
<tr>
<td>Stalled P2P Camera Blast Radius</td>
<td>Freezes shared loop</td>
<td>Isolated single tile</td>
<td>Non-blocking <code>try_send</code> + 3s TCP write timeout</td>
</tr>
</tbody></table>
<p>##1. Prototyping in Python &amp; AI-Assisted Porting to a Native GPU Binary</p>
<p>Running 12 concurrent H.265/H.264 cameras 24/7 exposes every hidden buffer in your stack. As a Python backend engineer, I built the first working prototype in Python, Tkinter, and OpenCV. It worked, but GIL contention and software frame resizing meant any brief UI stall let TCP socket buffers accumulate 2 to 5 seconds of stale video across cameras. Rather than claiming years of hand-written Rust experience, I treated the systems architecture as the spec - zero-probe FFmpeg demuxing (-probesize 32768 -analyzeduration 0 -fpsprobesize 0), lock-free latest-frame slots, and GPU UV-coordinate zoom (1.0x to 5.0x at 0.0% CPU cost) - and used AI-assisted engineering to port the Python prototype into a 70 MB compiled eframe/egui OpenGL binary that boots all 12 streams in under 0.9 seconds.</p>
<h2>2. The Subtle Bug: Why Linux's 64 KB Pipe Defeated ioctl(FIONREAD)</h2>
<p>To guarantee &lt;80ms live-edge latency, each worker thread reads raw RGBA frames from its FFmpeg child's stdout pipe and checks ioctl(pipe_fd, FIONREAD) right after each frame: if at least one more complete frame (frame_bytes = width * height * 4) is already waiting in the kernel pipe, we immediately drain it into the back buffer before swapping the UI mutex, skipping intermediate stale frames. During a deep systems audit, we caught a classic Linux kernel gotcha that AI code generation alone missed until we did the byte math: on Linux, default anonymous pipe capacity is 16 pages = 65,536 bytes (64 KiB). Even a sub-stream 16:9 SD RGBA frame at 270p (480x270x4) is 518,400 bytes! Because the pipe could only hold ~12.6% of a single frame at a time, FIONREAD could never report &gt;= 518,400 bytes, pushing backpressure right back into FFmpeg's internal TCP buffer. <strong>Expanding the Linux kernel pipe ring so FIONREAD holds ~2 full SD frames</strong></p>
<pre><code class="language-rust">#[cfg(target_os = "linux")]
unsafe {
    // Default Linux pipe is 64 KiB (&lt; 1 RGBA 480x270 SD frame of 518,400 B).
    // Expand to 1 MiB (best-effort) so ioctl(FIONREAD) can genuinely
    // detect and drain burst frames without backpressuring FFmpeg.
    let _ = libc::fcntl(pipe_fd, libc::F_SETPIPE_SZ, 1_048_576);
}
'frame_loop: loop {
    if stdout.read_exact(&amp;mut back_buf).is_err() {
        break 'frame_loop;
    }
    while pipe_available_bytes(pipe_fd) &gt;= frame_bytes {
        if stdout.read_exact(&amp;mut back_buf).is_err() {
            break 'frame_loop; // Never publish a partially overwritten frame
        }
    }
    publish_latest_frame(&amp;slot, &amp;mut back_buf);
}
</code></pre>
<h2>3. Eliminating Head-of-Line Blocking on Multiplexed Cloud P2P Tunnels</h2>
<p>When viewing cameras remotely outside the home LAN without router port forwarding, all 12 RTSP streams multiplex over a single encrypted UDP PTCP session. Originally, the UDP reader task forwarded decrypted realm packets into per-camera bounded channels using blocking .send().await. If a single camera's local consumer stalled, its bounded channel filled up and parked the shared UDP reader loop, freezing all 11 healthy cameras! Switching the demuxer to non-blocking try_send with automatic realm eviction (plus a 3-second TCP write timeout and PR_SET_PDEATHSIG(SIGKILL) child cleanup) made the video wall genuinely resilient for unattended 24/7 operation.</p>
<h2>Technical Q&amp;A</h2>
<h3>Why does ioctl(FIONREAD) fail to drain raw video frames on default Linux anonymous pipes?</h3>
<p>Linux defaults anonymous pipes to 16 pages = 65,536 bytes (64 KiB), whereas a single 480x270 RGBA video frame is 518,400 bytes (~506 KiB). Because a full frame cannot sit in a 64 KiB pipe, FIONREAD never reports &gt;= 518,400 bytes until the pipe capacity is expanded to 1 MiB via <code>fcntl(pipe_fd, F_SETPIPE_SZ, 1_048_576)</code>.</p>
<h3>How do you eliminate FFmpeg's 3-to-5 second startup delay on RTSP IP cameras?</h3>
<p>Pass <code>-probesize 32768 -analyzeduration 0 -fpsprobesize 0 -fflags nobuffer -flags low_delay</code> when spawning each camera's FFmpeg demuxer in parallel worker threads, cutting 12-camera cold startup from ~14s to under 0.9s.</p>
<hr />
<p>Originally published with an interactive in-browser simulator at <a href="https://pulkit-mundra-portfolio.vercel.app/engineering/python-to-rust-12-camera-nvr-linux-pipe-trap">https://pulkit-mundra-portfolio.vercel.app/engineering/python-to-rust-12-camera-nvr-linux-pipe-trap</a>.</p>
]]></content:encoded></item><item><title><![CDATA[Cutting Agent Tool Tokens by ~80% at 99% Solvability Parity: 5 Lessons from Refactoring Verbose APIs]]></title><description><![CDATA[How consolidating 60 API endpoints into 18 Python @tool_spec MCP tools cut schema tokens 66% and payloads 80% while keeping 99% LLM solvability parity]]></description><link>https://pulkitmundra.hashnode.dev/cutting-agent-tool-tokens-by-80-at-99-solvability-parity-5-lessons-from-refactoring-verbose-apis</link><guid isPermaLink="true">https://pulkitmundra.hashnode.dev/cutting-agent-tool-tokens-by-80-at-99-solvability-parity-5-lessons-from-refactoring-verbose-apis</guid><category><![CDATA[Python]]></category><category><![CDATA[Artificial Intelligence]]></category><category><![CDATA[llm]]></category><category><![CDATA[software architecture]]></category><dc:creator><![CDATA[Pulkit Mundra]]></dc:creator><pubDate>Sat, 14 Nov 2026 08:06:17 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af80a39b48a8c15442d9de7/2e9b42f7-b9ee-467b-ac57-436e44f70f47.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<h2>TL;DR Summary</h2>
<ul>
<li>Consolidating sprawling CRUD surfaces into intent-aligned Python @tool_spec overlays (e.g., 60 email endpoints -&gt; 18 tools) and stripping blocked schema fields cut static tool schemas by ~50-82%.</li>
<li>Replacing fat list responses with summary projections intentionally increased follow-up hydrate calls (+56%) while slashing net response payload tokens by ~78-83% (and up to 88-99% on mutating endpoints).</li>
<li>Moving pagination + financial math into deterministic Python Decimal tools on Google ADK SkillToolset cut multi-turn prompt tokens by ~32%, while state-based eval assertions proved ~99% solvability parity (0.0pp accuracy loss).</li>
</ul>
<h2>Measured Token &amp; Solvability Impact Across Refactored Agent Tool Suites</h2>
<table>
<thead>
<tr>
<th>Optimization Layer</th>
<th>Mechanism</th>
<th>Token Impact</th>
<th>Accuracy / Parity</th>
</tr>
</thead>
<tbody><tr>
<td>Static Tool Schema (Email)</td>
<td>60 V1 endpoints -&gt; 18 flat @tool_spec tools</td>
<td>-82% schema tokens</td>
<td>~99% solvability parity</td>
</tr>
<tr>
<td>Combined Email + Calendar Suite</td>
<td>Intent-aligned action overlays + flat validators</td>
<td>-66% schema tokens</td>
<td>0.0pp true accuracy drop</td>
</tr>
<tr>
<td>Backwards-Compatible V1 Strip</td>
<td>Declarative FD blocked_fields config</td>
<td>-23% to -34% schema</td>
<td>100% V1 signature preserved</td>
</tr>
<tr>
<td>Search + Mutator Payloads</td>
<td>4-field summary projection + thin mutator ack</td>
<td>-78% to -83% net (-99% mutators)</td>
<td>+56% calls, 5x leaner net context</td>
</tr>
<tr>
<td>Cross-Service Ledger Math</td>
<td>Google ADK SkillToolset + Python Decimal tool</td>
<td>-32% multi-turn tokens</td>
<td>Eliminated float/sum drift</td>
</tr>
</tbody></table>
<h2>1. Consolidating 60 Endpoints into 18 Workflow Tools (&amp; FD Schema Stripping)</h2>
<p>Auto-exposing an entire legacy API catalog directly to an LLM taxes every single turn of an agent trajectory. Public tool-use benchmarks such as LongFuncEval (arXiv:2505.10570) and Meta-Harness (arXiv:2603.28052) show sharp reasoning degradation once tool catalogs exceed ~20 tools, nest inputs past 2 levels, or flood context windows (where 4x leaner context yields up to +7.7pp higher accuracy). To optimize multi-service tool catalogs without breaking deterministic execution, we combined two complementary mechanisms depending on backwards-compatibility constraints:</p>
<ul>
<li>Action-oriented @tool_spec overlays (StrictBaseModel, extra='forbid'): Consolidating 60 raw email endpoints (26 workflow-relevant functions merged/wrapped + 34 rarely used admin, POP/IMAP, and S/MIME endpoints excluded) into 18 flat, intent-aligned tools cut full static schema tokens by ~82% (and ~66% across combined email + calendar suites).</li>
<li>Function Definition (FD) schema stripping: Where existing V1 function names and runtime return shapes had to remain 100% untouched, declarative FD configs stripped unused blocked_fields and rewrote verbose parameter descriptions at schema-generation time, saving ~23% to 34% of schema tokens with zero runtime code changes.</li>
<li>All-or-nothing flat group validators: Instead of deeply nested union objects, flat optional scalar parameters validated via Pydantic v2 @model_validator gave models clear, self-correcting error messages on invalid combinations.</li>
</ul>
<h2>2. The Real List-vs-Hydrate Tradeoff: Fat Lists -&gt; Thin Summaries -&gt; Selective Projection</h2>
<p>Conventional wisdom assumes fewer tool calls always means fewer tokens. Production trace telemetry proved the exact opposite on search-heavy workflows. Our baseline V1 list endpoint was not too thin - it was far too fat, returning full message objects with 12+ fields, nested MIME headers, bodies, and base64 raw payloads on every search (~516 tokens per call), while mutating calls like send or trash echoed entire 6.8 KB resource snapshots. We iterated through two measured stages:</p>
<ul>
<li>Stage 1 (Summary-first search + on-demand hydrate): Stripping search results down to 4 lightweight fields (id, sender, subject, snippet at ~87 tokens/call) paired with an on-demand get_message tool intentionally increased total tool calls by ~56% - yet still cut total runtime response tokens across trajectories by ~78% to 83% (and cut mutating trash/send outputs by 88% to 99%).</li>
<li>Stage 2 (Trace-driven selective projection): Inspecting follow-up hydrate traces revealed that models almost exclusively fetched messages just to read plain-text body and timestamp. Selectively projecting those two clean fields onto search items eliminated 95%+ of follow-up get calls without bringing back MIME or base64 bloat. <strong>Strict Pydantic v2 @tool_spec boundary with flat group validation and projected summary output</strong></li>
</ul>
<pre><code class="language-python">from pydantic import BaseModel, ConfigDict, Field, model_validator
class StrictToolModel(BaseModel):
    model_config = ConfigDict(extra="forbid")
class SearchMessagesInput(StrictToolModel):
    query: str = Field(..., description="Keyword or sender/status filter.")
    max_results: int = Field(10, ge=1, le=50, description="Max items returned.")
    after_iso: str | None = Field(None, description="Inclusive start ISO-8601 date.")
    before_iso: str | None = Field(None, description="Exclusive end ISO-8601 date.")
    @model_validator(mode="after")
    def check_date_window(self) -&gt; "SearchMessagesInput":
        if self.after_iso and self.before_iso and self.after_iso &gt;= self.before_iso:
            raise ValueError("after_iso must be earlier than before_iso.")
        return self
class MessageSummaryItem(StrictToolModel):
    id: str
    sender: str
    subject: str
    received_at: str
    snippet: str
</code></pre>
<h2>3. Google ADK Progressive Skill Disclosure &amp; Deterministic Decimal Compute</h2>
<p>On cross-service commerce and finance workflows (spanning orders, calendars, email, and SQLite ledgers), dumping paginated raw order JSON into the prompt and asking an LLM to sum net revenue across partial refunds and cancelled line items fails twice: it burns massive cumulative prompt context and introduces subtle floating-point / status-filtering hallucinations. Using Google Agent Development Kit (ADK SkillToolset) for progressive skill disclosure alongside MCP connectors, we pushed pagination and financial math into deterministic Python Decimal aggregation tools (such as summarizing countable orders and ledger balances server-side). Across multi-turn cross-source scenarios, progressive skill loading + server-side aggregation reduced cumulative prompt tokens by ~32% and eliminated customer-facing math errors.</p>
<h2>4. The Evaluation Harness Trap: Why Tool-Name Assertions Fake a -5pp Regression</h2>
<p>When we first benchmarked the consolidated ergonomic toolset against the V1 baseline across thousands of multi-hop tasks, automated graders flagged an alarming <del>5 percentage point drop in solvability. Before rolling anything back, we audited the failing trajectories one by one and uncovered a classic evaluation anti-pattern: ~90% of the 'failed' tasks had actually achieved the exact right user outcome in the database, but legacy grader scripts contained brittle assertions checking hardcoded V1 function names in the call log! Replacing call-trace assertions with deterministic final-state assertions proved 0.0pp true accuracy degradation (</del>99% solvability parity) while cutting schema and payload tokens by ~66% to 82%.</p>
<h2>Technical Q&amp;A</h2>
<h3>How do you reduce MCP server token usage without hurting LLM tool-calling accuracy?</h3>
<p>Combine three layers: (1) consolidate granular CRUD endpoints into 15-20 flat, workflow-aligned @tool_spec tools with Pydantic v2 <code>extra='forbid'</code>, (2) return lean 4-to-6 field summaries on list/search tools instead of full MIME/raw objects, and (3) return minimal acknowledgements on mutating tools instead of echoing full resource snapshots.</p>
<h3>How many tools should a single MCP server expose to an LLM agent?</h3>
<p>Empirical tool-use benchmarks (such as LongFuncEval) and production trace telemetry show reasoning accuracy degrades sharply past ~20 tools or &gt;2 levels of nested input schemas. When a domain has 50+ operations, consolidate common workflows into ~15-20 primary tools or use progressive skill disclosure (like Google ADK SkillToolset).</p>
<h3>Why do LLM agent benchmarks sometimes report fake regressions after refactoring tool schemas?</h3>
<p>Many legacy evaluation suites assert hardcoded V1 function names in the call log rather than checking whether the agent achieved the correct final database state. Auditing our -5pp initial drop showed ~90% of flagged tasks had succeeded in the database; switching to deterministic final-state assertions proved ~99% solvability parity.</p>
<hr />
<p>Originally published with an interactive in-browser simulator at <a href="https://pulkit-mundra-portfolio.vercel.app/engineering/ergonomic-mcp-schemas-80-percent-payload-reduction">https://pulkit-mundra-portfolio.vercel.app/engineering/ergonomic-mcp-schemas-80-percent-payload-reduction</a>.</p>
]]></content:encoded></item></channel></rss>