Topic 4: Results and errors

Unstructured versus structured results

A tool result (CallToolResult) has three fields you care about:

• content: a list of content blocks (text, image, audio, resource link, embedded resource). This is the unstructured result, and it is what the model reads.
• structured_content: one JSON value that conforms to the output schema, if the tool has one. This is the structured result, for code.
• is_error: True when the tool ran and failed.

You saw both channels filled by search_notes in Part A. The first attempt's -> str produced {"result": "sleep-and-memory (11)\n..."}: technically structured, practically useless. The rule of thumb: structure the result when a program will read fields from it, and keep the text channel readable for the model. The SDK serializes a model return value as indented JSON in content, which models read well, at the cost of some whitespace (measured next).