| 1 | # responses_tools.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own conversion of Agent Zero tool prompt files and MCP tool metadata into OpenAI Responses API function tool definitions. |
| 6 | - Keep native Responses function availability synchronized with the text tool prompt surface. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `responses_tools.py` owns runtime implementation. |
| 11 | - `responses_tools.py.dox.md` owns durable notes about responsibilities, prompt-derived contracts, and verification for this helper. |
| 12 | |
| 13 | ## Local Contracts |
| 14 | |
| 15 | - Build local function tools from enabled `agent.system.tool.*.md` prompt files and include `vision_load` when either Main native vision or the effective preset's Vision Model enables the canonical vision prompt. |
| 16 | - Discover local prompt files through `helpers.subagents.get_paths`; this module |
| 17 | owns the Responses-specific prompt-name compatibility rules. |
| 18 | - Local prompt-derived function names use existing bullet declarations that pair a backticked name with `arg` or `args` for multi-tool prompt files, otherwise prefer explicit `"tool_name"` examples, then the first prompt heading, and finally the prompt filename. |
| 19 | - Apply registered tool-prompt render kwargs before deriving native metadata so descriptions never expose unresolved prompt templates. |
| 20 | - Keep emitted schemas provider-neutral; provider-specific strictness belongs at the provider request boundary. |
| 21 | - Use an explicitly embedded JSON input schema when present. Infer only an unambiguous single backticked argument on an otherwise empty `args:` line; all other local tools receive an honest permissive object schema instead of prose-guessed types. |
| 22 | - Native local-tool descriptions reuse the tool catalog's compact prompt |
| 23 | description; Responses retains native-name mapping, schema derivation, and |
| 24 | provider description limits. |
| 25 | - Preserve original Agent Zero tool names through the native Responses name map. |
| 26 | - Keep MCP tool schemas merged after local prompt-derived tools. |
| 27 | - Apply `helpers.tool_policy` before emitting local or MCP schemas; a blocked |
| 28 | capability is absent from provider-native tool definitions. Vision routing |
| 29 | is controlled by the effective model preset rather than Agent Editor. |
| 30 | - Connector remote tools are advertised only when `_a0_connector` runtime metadata says the matching connected CLI capability is currently available. |
| 31 | |
| 32 | ## Work Guidance |
| 33 | |
| 34 | - Keep prompt-derived descriptions bounded by `MAX_TOOL_DESCRIPTION_CHARS`. |
| 35 | - Treat plugin-specific tool gates as optional imports so core helper loading does not require a plugin that is absent or disabled. |
| 36 | |
| 37 | ## Verification |
| 38 | |
| 39 | - Run targeted Responses/tool prompt tests after changing function-tool construction. |
| 40 | - Run connector prompt gating tests when changing remote tool availability. |