docs(rfd): Requested Tool Categories — optional ClientCapabilities hint for cross-vendor in-LLM tool exposure#1302
Open
s2agi wants to merge 1 commit into
Conversation
Adds a new RFD proposing an optional `requested_tool_categories: Option<Vec<RequestedToolCategory>>` field on ClientCapabilities, gated behind a new `unstable_requested_tool_categories` feature flag. Motivation (full evidence in the RFD body): - ClientCapabilities currently exposes only `fs` + `terminal`. There is no first-class way for a client to express 'I want the LLM to have access to backend tools in category X', and AgentCapabilities has no symmetric tool enumeration. - This is a real gap for agents that gate backend tools by default in isolated stdio mode. We hit it concretely with Grok Build: its interactive (non-ACP) sessions routinely call backend X-search and video-generation tools, but the same model under `grok agent stdio` cannot reach them. A probe-prompt that explicitly asks for X search returns 'no X search tools connected' — the LLM understands the task and tries (via `search_tool`) to find the backend tools by name, then reports they aren't in its registry. - We tried a vendor-specific `_meta.x.ai/requestedBackendTools` workaround on both `initialize` and `session/new`. Grok agent 0.2.3 silently ignores it. The `_meta` extension point isn't sufficient because it has no cross-vendor semantics: each vendor would need its own key, and even when an agent does honour one, no other agent will. Proposal: - Closed `#[non_exhaustive]` enum `RequestedToolCategory` with vendor-neutral variants (`Search`, `SocialSearch`, `MediaGen`, `Web`, `CodeExec`, `Voice`, ...). - Each agent implementation maps a category to whatever concrete backend tools it can offer. - Agents MAY honour the hint; absence / unknown variants are silently ignored. Clients MUST NOT assume any tool is available just because they requested a category. - Optional symmetric `supported_tool_categories` on AgentCapabilities so clients can introspect (nice-to-have, not required). RFD covers FAQ on why closed enum vs free-form strings, why `_meta`-only doesn't generalise, the gate-the-agent concern, and the three alternatives considered + rejected. Per CONTRIBUTING.md the implementation plan is feature-gated (`unstable_requested_tool_categories`) and follows the standard ACP RFD lifecycle: this PR opens dialogue; Phase 2 lands the field behind the flag once a champion picks it up; Phase 3 demonstrates at least one agent honouring at least one category; Phase 4 stabilises and removes the flag. The captured negative-evidence trace for the `_meta` workaround attempt is preserved upstream of this RFD at: https://github.com/sleep2agi/agent-network/blob/main/docs/rfcs/RFC-021-acp-capability-profile-expansion.md (§11)
s2agi
pushed a commit
to sleep2agi/agent-network
that referenced
this pull request
May 28, 2026
…ent-protocol#1302 Phase 2 Path C kickoff complete. Updates RFC-021 §11.6 with the live upstream RFD PR + fork URLs and quotes the proposed Rust schema shape verbatim so the cross-link is permanent. PR follows the ACP RFD process (per CONTRIBUTING.md): the PR contains only docs/rfds/requested-tool-categories.mdx — feature-gated Rust implementation lands in a follow-up after a core team member champions the proposal. Refs: - upstream PR: agentclientprotocol/agent-client-protocol#1302 - fork: https://github.com/s2agi/agent-client-protocol - RFC-021 §11 Phase 2 HARD GATE evidence (Grok agent 0.2.3 silently ignores vendor-specific _meta hints — the negative evidence becomes Exhibit A in the upstream PR body)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Opens an RFD proposing an optional
requested_tool_categoriesfield onClientCapabilities, so a client can hint to the agent which vendor-neutral categories of in-LLM tools it would like exposed during a session.This is purely the RFD document at
docs/rfds/requested-tool-categories.mdx. No Rust changes yet — those would land in a follow-up PR if/when a core team member champions the proposal, per the standard ACP RFD process described inCONTRIBUTING.mdanddocs/rfds/about.mdx.Why this RFD
ClientCapabilitiescurrently exposes onlyfsandterminal. We've hit a real downstream gap: some agents gate backend tools by default in isolated stdio mode, with no spec-blessed way for a client to opt in. The RFD body documents the concrete reproducer — Grok Build's interactive (non-ACP) sessions invoke X-search / video-generation backend tools routinely (27 X-search calls in one user's session history), but the same model undergrok agent stdiocannot reach them. A vendor-specific_meta.x.ai/requestedBackendToolsworkaround was silently ignored by Grok agent 0.2.3.The captured negative-evidence trace lives at https://github.com/sleep2agi/agent-network/blob/main/docs/rfcs/RFC-021-acp-capability-profile-expansion.md §11 — including the LLM's verbatim self-report ("当前会话中没有连接任何 X 搜索相关的 MCP 工具 ... 通过多次 search_tool 查询均未发现") and the dual-position
_metahint that didn't move the needle._metaalone doesn't generalise — each vendor would need its own key, and even when one agent honours one, no other agent will. The RFD proposes a closed-but-#[non_exhaustive]enum of categories (Search/SocialSearch/MediaGen/Web/CodeExec/Voice/ ...) so cross-vendor semantics stay anchored.Backward compatibility
The field is optional. Agents that don't understand it (current behaviour) ignore it without issue. Clients MUST NOT assume any tool is available just because they requested a category — it's purely a hint, never a guarantee.
Implementation plan (from the RFD)
unstable_requested_tool_categoriesin bothsrc/v1/client.rsandsrc/v2/client.rs, JSON schema regenerated, serde round-trip + absent/empty/unknown-variant tests.FAQ covered in the RFD body
_metaalone doesn't generalise (with the Grok probe as exhibit A)_meta-only / mandatory exposure / per-tool allowlist)Author context
Filing on behalf of the sleep2agi/agent-network project — a multi-agent orchestration platform built on ACP. Happy to iterate on the RFD shape, naming, or scope based on feedback.