docs(xai): clarify x_search and xurl routing

[Julientalbot]

Summary

Clarifies the boundary between the xAI x_search tool and the xurl skill so agents route X/Twitter work by intent instead of treating both surfaces as interchangeable.

• x_search: read-only public X discovery, reactions, claims, threads, profiles, and synthesized answers with citations.
• xurl: exact/authenticated X API reads plus account actions/writes such as post, reply, like, DM, media upload, delete, timelines, mentions, and raw v2 endpoints.
• Mixed workflow guidance: discover candidate public posts with x_search, then switch to xurl read or a specific xurl action once the target is clear. X writes must be evidenced by xurl output or the X API response, not by an x_search answer.

Changes

• Updates the bundled xurl skill with explicit x_search routing guidance.
• Adds an x_search vs xurl section to the user-facing x_search docs.
• Updates the x_search tool schema, toolset description, and tools config setup note.
• Adds regression tests that pin the routing contract across skill docs, feature docs, schema, and toolset metadata.
• Keeps CI expectations aligned with the newly bundled web-xai provider and makes the update-output test robust to hermes_cli.main reloads in the full suite.

Validation

• uv run --extra dev pytest tests/tools/test_x_search_tool.py tests/test_toolsets.py tests/skills/test_xurl_x_search_routing.py tests/website/test_generate_skill_docs.py -q -> 52 passed
• uv run --extra dev pytest tests/plugins/web/test_web_search_provider_plugins.py tests/hermes_cli/test_update_hangup_protection.py tests/tools/test_x_search_tool.py tests/test_toolsets.py tests/skills/test_xurl_x_search_routing.py tests/website/test_generate_skill_docs.py -q -> 117 passed
• uv run --extra dev pytest tests/plugins/web/test_web_search_provider_plugins.py::TestBundledPluginsRegister::test_all_bundled_plugins_present_in_registry tests/hermes_cli/test_update_hangup_protection.py::TestInstallHangupProtection::test_wraps_stdout_and_stderr_with_mirror -q -> 2 passed
• uv run --extra dev ruff check tools/x_search_tool.py toolsets.py hermes_cli/tools_config.py tests/tools/test_x_search_tool.py tests/test_toolsets.py tests/skills/test_xurl_x_search_routing.py tests/plugins/web/test_web_search_provider_plugins.py tests/hermes_cli/test_update_hangup_protection.py -> passed
• git diff --check -> passed
• PATH="$PWD/.venv/bin:$PATH" python3 website/scripts/extract-skills.py && PATH="$PWD/.venv/bin:$PATH" python3 website/scripts/generate-skill-docs.py && cd website && PATH="../.venv/bin:$PATH" npm run lint:diagrams && PATH="../.venv/bin:$PATH" npm run build -> passed; Docusaurus emitted existing broken-link/anchor warnings in unrelated docs/locales.

Generated skill docs were used only for validation and are not committed; the source skills/social-media/xurl/SKILL.md remains the source of truth.

[teknium1]

Thanks for documenting a real routing gap: current main's tools/x_search_tool.py:455-462 and skills/social-media/xurl/SKILL.md:389-397 do not make this boundary clear.

Problems

• tools/x_search_tool.py:361 statically tells the model to use xurl. AGENTS.md:1234-1235 prohibits cross-tool references in static schemas because the referenced surface may be unavailable; use conditional schema construction in model_tools.py::get_tool_definitions() or keep this guidance in docs/skills.
• tests/skills/test_xurl_x_search_routing.py:13-28 snapshots exact prose. AGENTS.md:1309-1356 requires behavioral contracts rather than change-detector tests.
• The changed schema/toolset text has stale static copies at website/docs/reference/tools-reference.md:219 and website/docs/reference/toolsets-reference.md:86, neither changed by this PR.
• GitHub reports the branch as conflicting; current main already includes xai provider-registry coverage at tests/plugins/web/test_web_search_provider_plugins.py:77-100, so the CI hunk needs selective salvage.

Suggested changes

• Make the schema wording availability-aware or generic, replace prose snapshots with an invariant, and update the two reference pages while resolving conflicts.

Automated hermes-sweeper review.

[teknium1]

Please do not statically name xurl in this tool schema. AGENTS.md:1234-1235 requires cross-surface references to be conditional because the terminal/skill surface may be unavailable; make it availability-aware in get_tool_definitions() or use generic out-of-scope wording here.

[teknium1]

This test freezes exact prose rather than a behavioral contract. AGENTS.md:1309-1356 explicitly rejects change-detector tests; please replace this with a structured invariant or omit the phrase snapshots.

[teknium1]

Merged via PR #70510 — your commit was cherry-picked onto current main with your authorship preserved in git log (a9366376bd).

Thanks for this — the routing doctrine was right and most of it survived verbatim: the read-only schema wording, the toolset description, the tools-config setup note, and the x-search docs comparison table all landed as you wrote them.

One half was redesigned rather than dropped: the routing block inside the xurl SKILL itself. The skill loads even when x_search isn't registered (it's check_fn-gated on xAI credentials), and our convention is that skills/schemas never name other credential-gated surfaces — an agent without the tool would hallucinate calls to it. The skill now describes its search distinctively in its own terms (raw engageable post objects, authenticated account), and your write-evidence rule ("only xurl output / X API response proves a state-changing action") was kept in the Agent Workflow in skill-native wording. The cross-surface comparison lives on the surfaces where both are guaranteed to exist together.

Your routing tests were adapted to pin exactly that placement contract, including a guard that the skill never names gated surfaces again.

[Julientalbot]

Thank you @Teknium !