Skip to content

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

Merged
DEENUU1 merged 1 commit into
mainfrom
fix/returns-shape
Aug 22, 2026
Merged

fix(toolsets): send a return description the way pydantic-ai sends one#110
DEENUU1 merged 1 commit into
mainfrom
fix/returns-shape

Conversation

@DEENUU1

@DEENUU1 DEENUU1 commented Aug 22, 2026

Copy link
Copy Markdown
Member

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:

@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.

`render` appended a prose "Returns: ..." paragraph. pydantic-ai wraps a
docstring's `Returns:` section in `<summary>` and `<returns>` tags
instead, which is what every tool built from a docstring already sends -
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. That was invented here, and inventing
it was the mistake.

`render` emits the framework's shape now. The test pins it against a
tool pydantic-ai renders itself rather than against a string literal, so
a change on that side fails here rather than leaving these tools quietly
speaking the old dialect.

The `*_DESCRIPTION` constants carry the new shape with them. A catalogue
that wanted the prose reads `ToolText.summary`, which is the sentence it
wanted in the first place - agenticos already does.

Verified: 1716 tests pass, coverage 100%, pyright and mypy strict clean.
@github-project-automation github-project-automation Bot moved this to Triage in Vstorm OSS Aug 22, 2026
@DEENUU1
DEENUU1 merged commit 3f75409 into main Aug 22, 2026
15 checks passed
@DEENUU1
DEENUU1 deleted the fix/returns-shape branch August 22, 2026 10:21
DEENUU1 added a commit that referenced this pull request Aug 22, 2026
`docs/.DS_Store` was swept into #110 by a `git add docs`. Removed from
the index, and `.DS_Store` added to `.gitignore` so the next staged
directory does not bring it back.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage

Development

Successfully merging this pull request may close these issues.

1 participant