docs(xai): x_search vs xurl routing on gated surfaces (salvage #29423) - #70510
Merged
Conversation
Make the x_search / xurl boundary explicit in the skill, feature docs, toolset metadata, setup note, and reference pages, while keeping the model-facing x_search schema generic (no static xurl name). Regression tests assert behavioral routing invariants rather than frozen prose snapshots. Drop the stale CI-only plugin/hangup hunks already on main so this rebases cleanly.
… gated surfaces Follow-up on the salvaged commit: the xurl skill loads even when x_search isn't registered (check_fn-gated on xAI credentials), so per the cross-toolset reference rule the skill must not name it. Replaced the skill's x_search routing block and workflow step with skill-native wording (raw engageable posts, authenticated context, write-evidence rule). The cross-surface comparison stays on surfaces where both are known to exist: x-search feature docs, toolset description, tools-config setup note, and the x_search tool schema (kept generic, no tool names). Rewrote the routing tests to pin the placement contract, including that the skill never names credential-gated surfaces.
Contributor
alt-glitch
added
type/docs
This was referenced Jul 24, 2026
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
3 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
Salvages @Julientalbot's x_search / xurl routing guidance (PR #29423) onto current main, with the skill-side half redesigned so the xurl SKILL stays self-contained.
The contributor's insight is right — agents holding both X surfaces need routing doctrine — but the original put an explicit
x_searchblock inside the xurl skill, which loads even when x_search isn't registered (check_fn-gated on xAI credentials). Per the cross-toolset reference rule, the routing comparison now lives only on surfaces where both are known to exist together; the skill describes its search distinctively in its own terms (already landed in #70443).Changes
tools/x_search_tool.py: schema states read-only scope generically (no tool names)toolsets.py+hermes_cli/tools_config.py: toolset description + setup note point authenticated work at the xurl skill (setup surfaces, both names legitimate)website/docs(tools-reference, toolsets-reference, x-search feature page): x_search vs xurl comparison table + mixed-workflow guidancex_searchrouting block + workflow step from the xurl SKILL; replaced with skill-native wording carrying the contributor's write-evidence rule ("only xurl output / X API response proves a state-changing action")tests/skills/test_xurl_x_search_routing.pyto pin the placement contract — including that the skill never names credential-gated surfacesValidation
tests/skills/test_xurl_x_search_routing.py+test_xurl_article_ingestion_docs.pytests/tools/test_x_search_tool.py,tests/test_toolsets.pytests/hermes_cli/test_tools_config.pyInfographic