Skip to content

fix(tools): include the response schema in RestApiTool declarations - #8033

Open
benclarkeio wants to merge 4 commits into
google:mainfrom
benclarkeio:fix/rest-api-tool-response-schema
Open

benclarkeio wants to merge 4 commits into
google:mainfrom
benclarkeio:fix/rest-api-tool-response-schema

Conversation

@benclarkeio

@benclarkeio benclarkeio commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

Problem:

RestApiTool._get_declaration() builds the declaration from the operation's parameters only, so tools generated by OpenAPIToolset never tell the model what they return, even though OperationParser already parses the 2xx response schema.

Solution:

  • Add include_response_schema to OpenAPIToolset, RestApiTool, and RestApiTool.from_parsed_operation(). The option defaults to False and enables response_json_schema on the JSON Schema declaration path.
  • Describe the successful results across declared 2xx statuses and media types. Combine distinct result shapes with anyOf. When a declared JSON response has an unknown shape, omit the response schema.
  • Preserve explicit JSON null constraints, translate OpenAPI nullable, and make write-only fields optional in the response schema.
  • Opted-in tools return decoded JSON values for JSON media types, including +json. Explicitly non-JSON responses return a {"text": ...} object, even when the text is valid JSON.
  • With include_response_schema=True, a success response that lists JSON beside another media type (for example application/json and text/csv) is declared by its JSON alone, and the tool sends an Accept header listing the media types the declaration describes (here Accept: application/json). Without that header, httpx sends Accept: */* and the server can pick either type, so the declaration had to be a union of the JSON shape and a text object. Parameters such as version=2 are kept, since they can select the shape. Operations whose listed success media types are all declared, or whose response schema is unknown, send no Accept.

Testing Plan

Unit Tests:

  • I have added or updated unit tests for my change.
  • All unit tests pass locally.
$ pytest tests/unittests/tools/openapi_tool
449 passed

Tests cover opting in through OpenAPIToolset, nested nullable and writeOnly fields, explicit const: null, and successful array, text, +json, and empty responses.

Manual End-to-End (E2E) Tests:

With the pet store spec from #8031:

tool = OpenAPIToolset(spec_dict=spec, include_response_schema=True).get_tool(
    "list_toys"
)
print(tool._get_declaration().response_json_schema)

Before (on main, where the option doesn't exist, the schema is never included):

None

After:

{'items': {'properties': {'id': {'type': 'string'}, 'name': {'type': 'string'}}, 'type': 'object', 'required': ['id', 'name']}, 'type': 'array'}

Checklist

  • I have read the CONTRIBUTING.md document.
  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • I have manually tested my changes end-to-end.
  • Any dependent changes have been merged and published in downstream modules.

- Set response_json_schema on the function declaration from the
  operation's parsed 2xx response schema, as McpTool does with
  outputSchema.
- Add OperationParser.get_response_json_schema(), which returns None
  when the operation declares no 2xx response schema.
- Add include_response_schema to RestApiTool, from_parsed_operation and
  OpenAPIToolset, defaulting to False, so declarations only carry the
  2xx response schema when asked and existing requests don't grow.
- Test the option on RestApiTool and that OpenAPIToolset forwards it.
- Describe the supported success statuses and media types as one schema.
- Preserve explicit null constraints and translate nullable and write-only fields.
- Return declared non-JSON bodies as text objects for opted-in tools.
- Cover the schema and decoded results with OpenAPI tool tests.
A success response that lists JSON beside another media type, such as
`text/csv`, was declared as a union of its JSON shape and a text object,
because httpx sends `Accept: */*` and the server may pick either. Declare
such a response by its JSON alone and send an `Accept` header listing the
media types the declaration describes, keeping parameters such as
`version=2` that can select the shape.

- Only tools created with `include_response_schema=True` change.
- Operations whose every listed success media type is declared, or whose
  response schema is unknown, send no `Accept`.
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.

RestApiTool function declarations omit the operation's response schema

2 participants