The problem

Most teams treat “give the agent a tool” as a binary checkbox: web search on/off, a database connector added, an MCP server plugged in. In practice that decision changes the character of the output as much as the prompt does — a model with code execution on stops guessing whether its code runs; a model wired to your Gmail and Photos can ground an answer in your actual car model instead of a generic one. Nobody designs for that on purpose; it just accretes, one integration at a time.

At company scale this shows up as a real cost, not a curiosity. Teams bolt MCP servers or API integrations onto agents ad hoc, and end up with context windows bloated by tool descriptions nobody reads, tool descriptions that quietly contradict each other, and — documented in the security material I pulled into this project — “tool poisoning” attacks where malicious instructions are hidden inside the tool metadata that’s supposed to make a tool discoverable. Adopting a standard like MCP is not the same thing as having a governance model for what an agent can see and touch in which context, and most orgs conflate the two.

The approach

This isn’t a shipped app — it’s a standing research and synthesis practice, one of the project folders inside CogitOS (my Substack-and-YouTube intelligence pipeline). It has no UI; the deliverable is a structured, sourced knowledge base: a manifest stating the working thesis, a refs file tracing every claim back to a specific article or talk transcript, and an ideas file of over twenty dated, individually-sourced notes, each distilled from a real piece of source material rather than written from memory.

What’s actually in it is concrete, not a vague “notes on AI tools” folder. It covers: deferred/progressive tool loading (registering tools but hiding their schemas until an agent explicitly searches for them, cutting context overhead by up to 70-80% in production harnesses); the CLI-vs-MCP trade-off (CLI tools compose and pipe, MCP tools are rigid but type-safe, and deferred loading is the synthesis that keeps both); MCP Apps and WebMCP (returning a live interactive UI or a typed browser-side tool declaration instead of raw text or scraped HTML); MCP Tasks (the async, human-in-the-loop task model needed once a tool call isn’t a single round trip); and the tool-poisoning security risk named above. Each note keeps its source line intact — a specific talk, a specific engineer’s account, a specific demo — so the file stays checkable, not just asserted.

What I learned

The throughline that emerged across a dozen unrelated sources was that tool-exposure design keeps collapsing into the same three decisions no matter who’s building it: what’s always visible to the model versus discoverable on demand, whether the interface is a typed schema (MCP) or something shell-composable (CLI), and who absorbs the translation cost — the agent inferring intent from raw HTML and screenshots, or the tool author declaring a clean, typed action up front. The other concrete lesson, which changed how I write tool descriptions in my own work: the docstring is the entire API contract for an LLM. There’s no separate schema-review step the way there is in traditional software — a well-described tool with mediocre code gets used correctly, and a well-built tool with a vague description gets ignored or misused, every time.

Where this could go

The direct next step is turning this from a reading file into a checklist I actually run against new integrations in CogitOS itself — the engine already makes some of these calls implicitly (CLI over SDK for LLM calls, file-writing over parsed stdout) without ever having named the pattern; this project is the naming pass.

The enterprise version of this is the more interesting one. One case in my notes is the sharpest illustration: a company can either bolt AI onto its existing UI (fragile, the agent has to guess) or expose its data model cleanly through a governed protocol so agents become first-class actors against the product (durable, compounding — Atlassian did exactly this with Jira/Confluence before there was even a public spec for what to do with it). Any organization standing up agent tooling across more than one team hits the identical fork — and the governance gap is the part most of them skip, since a standard like MCP buys interoperability but says nothing about scopes, audit trails, or which tools an agent is trusted with in which context. That’s the part worth building next: not more integrations, but the policy layer that decides who gets which tool, and when.