Skip to content

[Docs] Document sending only structured content from a tool #605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chr-hertel merged 1 commit into from
Oct 18, 2026
+25 −0
Merged

[Docs] Document sending only structured content from a tool #605

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/servers/tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,32 @@ three cases:
above. A `CallToolResult` you build yourself without `structuredContent` gets no warning.
- The result is already marked `isError: true`, because its content is a failure message and not the declared output.

#### Sending only structured content

By default, the SDK also JSON-encodes structured content into `content`. To send a large result only once, return a
`CallToolResult` with an empty `content` list:

```php
use Mcp\Schema\Result\CallToolResult;

#[McpTool(outputSchema: [/* ... */])]
public function getWeather(string $city): CallToolResult
{
return new CallToolResult([], structuredContent: ['temperature' => 22.5, 'conditions' => 'sunny']);
}
```

The SDK still validates `structuredContent` against the `outputSchema`, but it doesn't change the value for older
protocol versions. Before `2026-07-28`, clients may reject a list or a scalar, so always pass an associative array or an
object.

!!! warning
The [specification][sep-2106] recommends also sending the serialized JSON as text, and [SEP-2106][sep-2106-proposal]
requires it for a list or a scalar. Some hosts pass only `content` to the model, which then sees an empty result.
Send only structured content with object values and for clients that read `structuredContent`.

[sep-2106]: https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content
[sep-2106-proposal]: https://modelcontextprotocol.io/seps/2106-json-schema-2020-12#backward-compatibility

### Error Handling

Expand Down
Loading