Let tools return ToolReturn to pass additional content to model, or attach metadata that's not passed to the model

[Wh1isper]

closes #2034

This PR allows us to implement more complex tool return like computer use

Example response:

• content: Screenshots, including before and after
• tool_return: some console log

previous: #1517

[hyperlint-ai]

PR Change Summary

Added support for customizable multi-modal content presentation using the new MultiModalContent feature.

• Introduced MultiModalContent for enhanced content customization.
• Provided an example of using MultiModalContent with a custom image tool.
• Explained the automatic replacement of placeholders in prompts.

Modified Files

• docs/tools.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[Wh1isper]

@DouweM I did some refactoring and now I use the ToolReturn type for multimodal and artifact requirements.

[thisisarko]

lgtm

[DouweM]

@Wh1isper Thanks a ton!

[nathan-gage]

@Wh1isper is there a specific reason return_value/metadata are Any typed rather than Generic?