MCP exposes tools, resources, and schemas over JSON-RPC; add JSON-LD semantics so AI agents infer meaning reliably with less prompt glue. Read now.
What MCP gives agents out of the box
Model Context Protocol (MCP) is a structured way for an AI agent to discover and call capabilities over JSON-RPC. A server advertises tools (callable operations with input and output schemas), resources (readable data with URIs and MIME types), and related metadata so the agent does not have to guess how to interact. That contract is machine-readable: names, parameters, types, and descriptions travel with the interface instead of living only in prose docs or ad hoc prompt text.
This already reduces glue. Instead of hard-coding every endpoint shape into the system prompt, the agent can list tools, inspect schemas, and invoke operations with validated arguments. The remaining gap is meaning: a field named status or a tool named search may be syntactically clear and still ambiguous about domain, units, lifecycle, or how it relates to other entities the agent already holds.
Where JSON-LD adds reliable semantics
JSON-LD layers linked-data context onto the same JSON payloads agents already consume. By binding keys and values to stable vocabulary terms (types, properties, and relationships), a response or schema can say not only “this is a string called title” but “this is the name of a Document that is related to that Dataset.” Agents and middleware that understand the context graph can align fields across tools without inventing a private synonym table for every integration.
Used with MCP, JSON-LD works best as enrichment rather than replacement. Keep MCP’s tool and resource discovery as the operational surface; attach or return JSON-LD where identity and relationships matter—entity types on resource payloads, shared identifiers across tools, and property definitions that map local field names to common terms. The agent then infers meaning from the graph instead of from longer natural-language instructions that drift as APIs change.
A practical shape for self-documenting surfaces
Design each MCP tool so the schema is complete enough for safe calls: required inputs, enums where the set is closed, and descriptions that state preconditions and side effects. Pair that with semantic hooks agents can reuse:
- Stable IDs on resources so “the same object” is explicit across list, get, and update tools.
- A small, consistent vocabulary for core domain types instead of one-off labels per endpoint.
- JSON-LD
@context(inline or by URL) that maps payload keys to those types and properties. - Resource MIME types and tool result shapes that either embed JSON-LD or link to a description the agent can fetch once and cache.
Prefer precision over breadth. A handful of well-defined terms that every tool respects beats a large vocabulary no caller can load or trust. Document failure modes in the schema or tool description (what a missing ID means, what “not found” returns) so the agent can branch without extra prompt rules.
Less prompt glue, clearer agent loops
When discovery, types, and semantics travel with the API, the agent loop shrinks: discover tools, match a goal to a tool by schema and type, call, then ground the result in the same identity graph for the next step. Prompts stay about intent and policy—what to optimize for, what not to do—rather than restating field meanings that the server already publishes. As tools evolve, update the MCP schemas and JSON-LD context; agents that re-discover at runtime pick up the change without a full prompt rewrite.
Self-documenting here means the interface answers three questions without human mediation: what can I call, how must I call it, and what do the values mean in relation to everything else I know. MCP covers the first two over JSON-RPC; JSON-LD strengthens the third so meaning is inferred from shared structure, not from fragile free-text glue.