ADR-03 for Responses tool interface boundaries#20
Conversation
noobHappylife
requested review from
bbrowning,
franciscojavierarceo,
jiahuei,
leseb,
maralbahari,
qandrew and
tjtanaa
as code owners
Signed-off-by: noobhappylife <aratar1991@hotmail.com>
noobHappylife
force-pushed
the
adr-03-tool
branch
from
cf7e7f4 to
f012754
Compare
Signed-off-by: noobhappylife <aratar1991@hotmail.com>
| - which tool interface types the gateway should support | ||
| - what each interface is good for | ||
| - what trade-offs each interface creates | ||
| - what minimum work is required for `code_interpreter`, `web_search`, hosted MCP, remote MCP, and `file_search` |
There was a problem hiding this comment.
given file_search implies vectors and files, could we postpone it? technically, we could handle all tools separately. like start with web_search, then code_interpreter and finally file_search?
There was a problem hiding this comment.
Yes thank you for pointing this out. The minimum work is more like the eventual tools that this repo will have. Will update this.
There was a problem hiding this comment.
FWIW I put a demo together of that in #22
And I'll leave the comment I made there:
Note: This is a draft — we may instead integrate OGX's existing file_search implementation rather than maintaining a separate one here. OGX already implements prompts, conversations, and file_search with a battle-tested retrieval stack.
OGX also supports MCP and I believe has support for web_search (though I haven't tested it much myself)
There was a problem hiding this comment.
FWIW, if we decide not to go with OGX, the surface area of a file_search tool with feature/performance parity is quite large (which you can look through the OGX code to confirm the magnitude).
| - which tool interface types the gateway should support | ||
| - what each interface is good for | ||
| - what trade-offs each interface creates | ||
| - what minimum work is required for `code_interpreter`, `web_search`, hosted MCP, remote MCP, and `file_search` |
There was a problem hiding this comment.
code_interpret feels like a big rabbit hole, that I do want to invest time on coming with a thoughtful proposal because it has broad security implications that we would need to be thoughtful about.
There was a problem hiding this comment.
The web_search tool seems manageable though.
3 participants
Summary
Adds ADR-03 as a discussion-oriented ADR for Responses API tool interface boundaries, especially gateway-owned and server-side executed tools.
The ADR is structured around four tool interface categories:
Built-in tools: stable gateway-owned tools with model-facing contracts, such as
code_interpreter,web_search, andfile_search.Dynamic model-facing toolsets: discovered tool inventories exposed directly to the model, such as hosted MCP or request-declared remote MCP.
Backend adapters: hidden backend-facing interfaces used by built-in tools when the model-facing contract should stay stable while the execution backend can vary.
Shared runtime clients: shared lifecycle/status/inventory clients for managed MCP backends, kept separate from per-request handling.
This is a draft. Comments, suggestions, and holes to poke are welcome.
Test Plan