Detailed Analysis
A developer building an MCP (Model Context Protocol) server for TikTok content research recently shared a debugging story that surfaces an important, underappreciated distinction in agentic AI development: the difference between tool capability and tool judgment. The developer's server drove a local Chrome instance to search TikTok for account discovery, using filters like follower count, average views, and posting cadence, since TikTok has no public API. Despite well-typed parameters and clear tool descriptions, Claude consistently returned poor results, surfacing accounts with a single viral post from months prior rather than accounts demonstrating a sustainable, repeatable content format. The developer spent three weeks iterating on tool descriptions, lengthening them, shortening them, adding and removing schema examples, before realizing the problem wasn't the interface at all.
The actual fix was a SKILL.md file, part of Anthropic's Claude Skills system, which encodes procedural knowledge, evaluation criteria, and domain expertise separately from the tool definitions themselves. The insight the developer arrived at is that tool descriptions communicate what a model is capable of doing, while skill files communicate what a good outcome looks like. In this case, no amount of schema engineering could encode the tacit judgment that one viral post is often luck while forty consistent posts signal a replicable format, or that a year of daily posting outweighs a single high-performing outlier. That kind of domain expertise, essentially editorial taste, isn't a parameter constraint; it's a decision-making framework, and it belongs in a different layer of the system entirely. Once that judgment was externalized into an explicit skill document with reject criteria and a defined order of operations, the same underlying tools began producing usable results almost immediately, with no changes to the tool schema itself.
This distinction matters because it cuts against the common instinct among developers integrating LLMs with tools: when an agent underperforms, the default move is to tweak the interface, adding more examples, more constraints, more verbose descriptions in hopes that clarity alone will produce better judgment. This anecdote suggests that's often the wrong lever. Tool descriptions are best treated as an API contract: they tell the model what actions are available and how to invoke them correctly. Skills, by contrast, function more like an onboarding document for a new hire, encoding heuristics, evaluation standards, and workflow sequencing that would otherwise require deep contextual experience to infer. Conflating the two means asking a single artifact to do two structurally different jobs, and it explains why so many well-engineered tool schemas still yield mediocre agent behavior.
The broader pattern reflects where agentic AI tooling is heading in 2025 and 2026: as MCP becomes a standard way to connect Claude and similar models to external systems, the bottleneck is shifting from "can the model call the right tool" to "does the model know what a good result looks like once it has the tool." Anthropic's Skills framework, and community practices growing up around it, exist precisely to fill this gap, treating domain expertise as a portable, editable artifact rather than something baked into prompts or brittle tool metadata. A secondary but practical lesson from the post, adding a caching tool to prevent redundant slow searches, also points to a maturing pattern in agent design: giving models lightweight infrastructure affordances (like memory of prior actions) so they can self-optimize within a session rather than repeating expensive operations. Together these observations reflect a broader shift in agentic system design away from prompt/schema tinkering and toward explicit, structured knowledge layers that separate mechanical capability from applied judgment.
Read original article →