A tool call result in MCP is never just a string. It’s a content array, and every entry in that array is one of a small, fixed set of block types — text, image, audio, an embedded resource, or a link to one. Most servers only ever return the first kind and never think about the rest. That’s fine for a lookup that answers in prose, but it leaves real capability on the table for a tool that generates an image, reads a PDF, or wants to hand back a large file without stuffing its bytes into the model’s context. Here’s what each content type actually is, and when reaching for one of the less common ones is the right call.
The five shapes a content block can take
Text is the default: a plain string. Almost every tool result you’ve seen is one or more of these, and if you’ve only ever written tools that return a sentence or a block of formatted output, this is the only content type you’ve used.
Image and audio blocks carry base64-encoded binary data plus a MIME type — a screenshot a tool just took, a chart it rendered, a chunk of speech it synthesized. The model can reason about an image block the same way it reasons about one you paste into a chat; the wire format is just a different field than text.
Embedded resource blocks carry an actual resource — the same kind of thing a server exposes through resources/list and resources/read, covered in our tools, resources, and prompts guide — inlined directly into the tool result instead of making the client fetch it separately. A tool that reads a file and wants to hand the whole thing back, with its URI and MIME type attached, uses this instead of pasting raw text into a plain text block.
Resource link blocks are the lightweight alternative: a pointer to a resource — its URI, a name, usually a MIME type — without the resource’s contents attached. The client decides whether to fetch it. This is the one content type most tool authors don’t know exists, and it’s the one that matters most once a result’s payload gets big.
Embedded resource vs. resource link: when each one earns its keep
The choice is really about size and certainty of use. If a tool’s result is a short file the model will almost certainly need to read right away — a small config file, a short log excerpt — embedding it saves a round trip. If the result is a large document, a big dataset, or something the model might not need to actually open (it just needs to know it exists, or point a person at it), a resource link avoids forcing megabytes of base64 into context that gets thrown away unread.
This is the same context-budget problem we covered in paginating large MCP tool results, approached from the opposite direction: pagination shrinks what one call returns, a resource link defers returning it at all. A search tool that finds twenty matching documents is usually better off returning twenty resource links than twenty embedded resources — the model can ask for the one or two it actually needs next.
This isn’t the same thing as structured output
It’s easy to conflate content types with MCP structured output, since both are about a tool result carrying more than a plain string. They’re answering different questions. Structured output is about whether a result’s text data has a declared, validated shape — JSON matching an outputSchema instead of a string the model has to parse. Content types are about what kind of thing a block in the array is in the first place — text, a picture, a sound, a resource. A tool can combine both: a text block with structuredContent describing the data, plus an image block showing a chart of it, in the same result.
What a client actually does with each type
None of this is self-enforcing. A client that doesn’t render images will show nothing useful for an image block, the same way a client with no audio player has nothing to do with an audio block beyond acknowledging it arrived. A resource link is a pointer, not an instruction — whether the client follows it, and when, is entirely up to that client’s own judgment, not something the content block can force. If you’re building a server meant to work across more than one AI client, it’s worth checking what the specific clients you care about actually render before leaning on image or audio blocks as the primary way a tool communicates its result.
If you’re building a server
Reach for an image or audio block when the result genuinely is an image or audio — not as a workaround for returning binary data you could otherwise describe in text. Reach for a resource link whenever a result could plausibly be large or might not get used, and save embedded resources for small, almost-certainly-needed attachments. If you’re generating a server from an existing API with gate’s MCP server builder, this is one of the places a straight REST-to-tool mapping tends to default to plain text for everything, including a response that was a binary file or an image URL in the original API — worth a manual pass once the generated server is otherwise working, alongside the output-shape gaps we noted in turning an API into an MCP server.
The bottom line
A tool result’s content array isn’t limited to text — image, audio, embedded resources, and resource links are all first-class options, and the last two give you a real answer to “this result is too big to just paste into context.” Pick the content type that matches what the result actually is, not whichever one happens to be the default in whatever framework generated your server. See our tools, resources, and prompts guide for how resources fit into MCP’s broader primitive model.