Skip to content

feat: show return types in the catalog and point the names tier at stubs - #29

Merged
benclarkeio merged 12 commits into
mainfrom
claude/quirky-turing-jbsmjg-catalog
Nov 8, 2026
Merged

benclarkeio merged 12 commits into
mainfrom
claude/quirky-turing-jbsmjg-catalog

Conversation

@benclarkeio

@benclarkeio benclarkeio commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Show return types and shared TypedDict definitions in the full tool catalog.
  • Point the names and pointer tiers to the generated stubs, including top-level helpers.
  • Keep the Code Mode 2.x result formats for the 2.1.0 release. Tool result artifacts still use the existing size threshold and pointer. Artifact loads keep their kind, data, and MIME type fields. MCP calls keep the ADK result envelope, with the output schema rendered under structuredContent.
  • Describe both the inline type and the artifact pointer in typed stubs and catalogs.

Tests

  • Existing artifact and large-result tests cover the 2.x formats.
  • MCP dispatch tests cover the result envelope and saved artifact.
  • Stub, catalog, and metadata tests cover shared types, name collisions, fallback tiers, and the large-result pointer.

- Build each stub's return type from `response_json_schema`: objects become
  `TypedDict` classes in the stub module, arrays `list[...]`, the rest `Any`
- Let a tool with exactly one required parameter take it positionally
- Escape backslashes and `"""` in generated docstrings so regex patterns
  no longer raise `SyntaxWarning`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Define each module's `TypedDict` return types once at the top of its
  catalog section, ahead of the signatures
- In the names tier, tell the model to run `help(fn)` or read the stub
  before calling a function it hasn't used
- Document return types and the positional parameter in the README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Hand code an MCP tool's `structuredContent` when it declares an
  `outputSchema`, after callbacks have seen ADK's result
- Read MCP return types from the tool's `outputSchema`, so they no longer
  need ADK's JSON-schema feature flag
- Give identical shapes one `TypedDict` across a module's tools
- Name classes after their `$defs` key or `title`, else the property
  holding them; qualify by parent, then number, on a clash
- Resolve `$ref` into `$defs`/`definitions`, including recursive refs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Name it `<Tool>Response` rather than reusing another tool's identical
  shape, which named it after whichever tool sorted first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Only an untitled top-level object stays per tool; array items are
  entities like any nested object

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Render each catalog section with `render_tools`, so it shares classes
  with the stubs and defines each shape once
- Update the README example and catalog test for the new names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
@benclarkeio

Copy link
Copy Markdown
Contributor Author
  • [P3] Qualify return types that share a name across catalog sections. The new allocator handles collisions within a namespace. Two namespaces can still emit different Record classes in the same Python block. For example, tools.tasks.get_task can return a Record with count: int, while tools.teams.get_team returns one with id: str. Both signatures say -> Record and section comments create no Python scope. Per-module rendering
  • [P3] Point the names tier to the source that shows the response fields. help(fn) prints a return name such as FindResponse without its fields. The documented /tools/<module>/<fn>.py path also misses top-level helpers such as /tools/load_artifact.py. Give both source paths and direct callers to the stub when they need the response shape. Names-tier instructions

Base automatically changed from claude/quirky-turing-jbsmjg to main November 8, 2026 13:18
- Take main's stubs, dispatcher and MCP result handling from #28 and #27
- Keep this branch's per-module catalog rendering

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip
…ier at stubs

- Share one name registry across modules, so two sections never define
  different classes with the same name; a clash falls back to the tool's
  or parent's name
- Render the catalog from one render_tools call, so it claims the same
  names as the stubs
- Names tier: tell the model to read the stub, which has the return type's
  fields, instead of help(fn), and give the top-level /tools/<fn>.py path

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip

Copy link
Copy Markdown
Contributor Author

Both addressed in df4b2ff:

  • Qualify return types that share a name across catalog sections: fixed. All modules now share one name registry, so two sections never define different classes with the same name. A clash falls back to the tool's or parent's name, then a number, as clashes within a module already did. In your example, get_task keeps Record and get_team returns GetTeamResponse. Shapes are still only shared within a module, so an unrelated API's class is never reused just because the fields match. The catalog now renders all tools in one render_tools call, so it claims the same names as the stubs. Covered by test_render_catalog_keeps_class_names_unique_across_modules.
  • Point the names tier to the source that shows the response fields: fixed. The text now drops help(fn) and points to the stub, giving both paths: "Before calling a function you haven't used, read its source to see its signature, docstring and the fields of its return type: /tools/<module>/<fn>.py, or /tools/<fn>.py for a function imported from tools."

I also merged main into this branch to resolve the conflicts with #27 and #28.


Generated by Claude Code

claude and others added 4 commits November 8, 2026 18:05
- Pointer tier and the no-metadata tool description now carry the same
  read-before-calling text as the names tier, after a line on listing
  /tools/
- Tell the model to print every stub it needs in one execute_code call
- Keep all guidance in <how-to-use>; the pointer's <tools-package> only
  says the catalog is too large

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip
- Say tool calls that call APIs raise HTTP errors as HTTPStatusError, and
  other failures raise ToolError
- Sync the README's copy of the tool description with the real text

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip
- Replace the save_artifact/load_artifact persistence sentence: files and
  tool results are saved automatically, so only load_artifact is needed
- Drop the tool-result clause when save_tool_results_as_artifacts is off
  and the load_artifact clause when include_artifact_tools is off
- Update the README and the constructor docstring to match

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip
- Preserve artifact envelopes, large-result pointers, and the wrapper threshold API.
- Keep the full MCP result and describe its structured content in typed catalogs and stubs.
- Cover the return formats and the large-result pointer type in the tests.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants