fix(toolsets): send a return description the way pydantic-ai sends one (#110)

`render` appended a prose `Returns: …` paragraph. pydantic-ai does
something else with a docstring's `Returns:` section — it wraps the
prose in `<summary>` and the return description in `<returns>`:

```
<summary>Draw a chart of numbers you already have, so the user can see them.

Use this whenever the user asks to plot, chart, graph or compare figures …</summary>
<returns>
<description>The chart specification, already on its way to the user.</description>
</returns>
```

So a host that registers these tools beside tools of its own ends up
with two conventions in one tool list: `create_chart`, built from a
docstring, arriving as XML, and `ls` arriving as prose describing the
same kind of thing. That shape was invented here, and inventing it was
the mistake — the framework already had one.

`render` emits the framework's shape now.

The test pins it against a tool pydantic-ai renders itself rather than
against a string literal:

```python
@native.tool_plain
def demo() -> str:
    """Do a thing.

    A second paragraph of usage.

    Returns:
        One line per entry.
    """

assert ToolText(summary=..., usage=..., returns=...).render() == native.tools["demo"].tool_def.description
```

If pydantic-ai changes how it renders that section, this fails here
rather than leaving these tools quietly speaking the old dialect.

A `ToolText` with no `returns` is still plain prose, which is also what
the framework does with a docstring that has no `Returns:` section.

The `*_DESCRIPTION` constants carry the new shape with them. A catalogue
that wanted the prose reads `ToolText.summary` — the sentence it wanted
in the first place, and what agenticos already shows beside its approval
checkboxes.

Verified: 1716 tests pass, coverage 100%, pyright and mypy strict clean.

Author: DEENUU1

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.29] - 2026-08-22
+
+### Fixed
+
+- **A tool's return description now reaches the model the way pydantic-ai sends
+  every other one.** `render` appended a prose `Returns: …` paragraph, where the
+  framework wraps a docstring's `Returns:` section in `<summary>` and `<returns>`
+  tags — so a host registering these beside tools of its own put two conventions
+  in one tool list, `create_chart` arriving as XML and `ls` as prose describing
+  the same kind of thing. `render` emits the framework's shape now, and
+  `tests/test_tool_text.py` pins it against a tool pydantic-ai renders itself, so
+  a change on that side fails here rather than leaving these tools speaking the
+  old dialect. The `*_DESCRIPTION` constants carry the new shape with them; a
+  catalogue wanting prose reads `ToolText.summary`, which is what it wanted.
+
 ## [0.2.28] - 2026-08-22
 
 ### Changed

docs/.DS_Store

@@ -91,6 +91,24 @@ TOOL_TEXT["grep"].args  # keyed by parameter name
 TOOL_TEXT["grep"].render()  # the description the model is given
 ```
 
+`render` produces what pydantic-ai produces for a docstring with a `Returns:`
+section — the prose inside `<summary>`, the return description inside
+`<returns>`:
+
+```
+<summary>Search the contents of files for a regular expression.
+
+Use this rather than a shell `grep` …</summary>
+<returns>
+<description>`files_with_matches` lists paths, `content` lists `path:line: text` …</description>
+</returns>
+```
+
+That is deliberate rather than decorative: a host registers these beside tools of
+its own that were built from docstrings, and two conventions in one tool list is
+one more thing for the model to reconcile. `tests/test_tool_text.py` pins the
+shape against a tool the framework renders itself.
+
 ### Profiles
 
 Two kinds of agent read these tools and they need different amounts of text. A

docs/concepts/console-toolset.md

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-ai-backend"
-version = "0.2.28"
+version = "0.2.29"
 description = "File storage and sandbox backends for AI agents"
 readme = "README.md"
 license = "MIT"

pyproject.toml

@@ -8,6 +8,11 @@
 `grep` answers three different shapes, that a listing may be a truncated slice,
 and that a failed `execute` still returns its output.
 
+What reaches the model is shaped the way pydantic-ai shapes a docstring with a
+`Returns:` section - `<summary>` around the prose, `<returns>` around the return
+description - so these tools read the same as every tool built from a docstring
+rather than introducing a second convention into one tool list.
+
 Two audiences read this text and they need different amounts of it. A coding
 agent wants the git and dependency guidance; an agent that keeps a scratch
 workspace for a report never sees a repository and pays for those sentences on
@@ -69,6 +74,16 @@ class ToolText:
     def render(self, profile: Profile = DEFAULT_PROFILE) -> str:
         """The description handed to the model.
 
+        Shaped the way pydantic-ai shapes a docstring that has a `Returns:`
+        section - the prose inside `<summary>`, the return description inside
+        `<returns>` - because that is what every tool built from a docstring
+        already sends, and a host registering these beside its own would
+        otherwise put two conventions in one tool list. A prose `Returns:`
+        paragraph was the first attempt and is what that inconsistency looked
+        like. `tests/test_tool_text.py` pins the shape against a tool the
+        framework renders itself, so a change there fails here rather than
+        drifting quietly.
+
         Args:
             profile: Which audience to write for.
         """
@@ -77,9 +92,13 @@ def render(self, profile: Profile = DEFAULT_PROFILE) -> str:
             parts.append(self.usage)
         if self.coding and profile == "coding":
             parts.append(self.coding)
-        if self.returns:
-            parts.append(f"Returns: {self.returns}")
-        return "\n\n".join(parts)
+        body = "\n\n".join(parts)
+        if not self.returns:
+            return body
+        return (
+            f"<summary>{body}</summary>\n"
+            f"<returns>\n<description>{self.returns}</description>\n</returns>"
+        )
 
     def docstring(self) -> str:
         """A Google-style docstring carrying the argument text.

src/pydantic_ai_backends/toolsets/descriptions.py

@@ -4,6 +4,7 @@
 
 import pytest
 from pydantic_ai.exceptions import UserError
+from pydantic_ai.toolsets import FunctionToolset
 
 from pydantic_ai_backends import create_console_toolset
 from pydantic_ai_backends.toolsets import descriptions as text_module
@@ -70,6 +71,53 @@ def test_the_exported_constants_render_the_same_objects(self) -> None:
         ) == text_module.HASHLINE_READ_FILE_DESCRIPTION
 
 
+class TestTheShapeIsTheFrameworksOwn:
+    """One convention per tool list, and it is not ours to invent."""
+
+    def test_it_matches_a_tool_pydantic_ai_renders_itself(self) -> None:
+        """A tool built from a docstring is what a host registers these beside.
+
+        Pinned against the framework rather than against a string literal: if
+        pydantic-ai changes how it renders a `Returns:` section, this fails here
+        rather than leaving these tools quietly speaking the old dialect.
+        """
+        native: FunctionToolset[None] = FunctionToolset()
+
+        @native.tool_plain
+        def demo() -> str:
+            """Do a thing.
+
+            A second paragraph of usage.
+
+            Returns:
+                One line per entry.
+            """
+            return ""  # pragma: no cover - never called, only described
+
+        rendered = ToolText(
+            summary="Do a thing.",
+            usage="A second paragraph of usage.",
+            returns="One line per entry.",
+        ).render()
+
+        assert rendered == native.tools["demo"].tool_def.description
+
+    def test_a_tool_with_nothing_to_report_is_left_as_prose(self) -> None:
+        """No `Returns:` section, no tags - which is what the framework does."""
+        assert ToolText(summary="Do a thing.", usage="Carefully.").render() == (
+            "Do a thing.\n\nCarefully."
+        )
+
+    def test_the_registered_description_carries_the_return_shape(self) -> None:
+        toolset = create_console_toolset()
+
+        described = toolset.tools["grep"].tool_def.description
+
+        assert described is not None
+        assert described.startswith("<summary>")
+        assert "<description>`files_with_matches` lists paths" in described
+
+
 class TestProfiles:
     def test_the_agent_profile_drops_the_repository_guidance(self) -> None:
         """An agent with a scratch workspace pays for none of it."""