Add the option to specify the tool descriptions in markdown

[ryx2]

Description

Our system prompt and tool descriptions are in markdown. However, when pydantic-ai creates the tool description strings that are passed in, the only option is to wrap it in xml.

So I'm wondering if we could specify an option to allow the tool descriptions to instead be in markdown format.

In pydantic_ai_slim/pydantic_ai/_griffe.py:

         type_tag = f'<type>{return_type}</type>\n' if return_type else ''
         return_xml = f'<returns>\n{type_tag}<description>{return_desc}</description>\n</returns>'
 
         if main_desc:
             main_desc = f'<summary>{main_desc}</summary>\n{return_xml}'
         else:
             main_desc = return_xml

But instead of this, with the .md option, this could be:

type_line = f'**Type:** `{return_type}`\n\n' if return_type else ''
return_md = f'### Returns\n\n{type_line}{return_desc}'

if main_desc:
    main_desc = f'## Summary\n\n{main_desc}\n\n{return_md}'
else:
    main_desc = return_md

References

No response

[ryx2]

I've implemented this feature and created a PR: #3132

The implementation adds a new description_format parameter to the Tool class that accepts either 'xml' (default) or 'markdown'.

When set to 'markdown', tool descriptions with returns sections will be formatted like this:

## Summary

Tool description here.

### Returns

**Type:** `return_type`

Return description here.

The parameter is fully backward compatible, defaulting to 'xml' format.