Tool calling: return types?

[domenic]

Our current proposal for tool-calling is that the execute() function always returns a string. (Any other returned value will be converted to a string, e.g. an object will become "[object Object]".)

This is a good simple starting point, and upgrading it is probably backward-compatible in the future (since it is hard to rely on "[object Object]" being the correct result).

But here is some research on alternatives:

• OpenAI function calling behaves like ours, in that it must always be a string.
• Vercel AI SDK doesn't seem to have clear docs, but shows examples of returning arbitrary objects. Probably they are stringified?
• MCP has a lot more structure to result types. It seems the basic idea is to allow inserting messages into the stream, so translated to our spec, you return an array of LanguageModelResultContents. They also have a separate output type called structuredContent for objects that conform to the outputSchema.

As I said above, I think we can expand our current output format, to support both simple string returns and objects in the future. We should determine whether doing that would be valuable. From a developer ergonomics perspective, maybe it's nice to just not have to call JSON.stringify(). But maybe there's more benefits possible.

Developer experience on more complicated return value formats would be welcome.