x_search:
  model: grok-4.5
  reasoning_effort: medium
  timeout_seconds: 180
  retries: 2

Using the Tool

Procedure

1. The agent calls x_search with the required query and any optional parameters.
2. The tool returns a JSON response with the following fields:
   • answer
   • citations
   • inline_citations
   • degraded
   • degraded_reason
   • credential_source
   • model
   • query
   • provider
   • tool
   • success

Handling the Response

• If degraded is true, treat the answer as unsourced. It comes from model knowledge, not the X index. The degraded_reason field provides context.
• If degraded is false and no filters were set, a broad unsourced answer is just an answer (not degraded).
• For state-changing actions (posting, replying, liking, etc.), switch to the xurl skill. Confirm the exact target post via xurl output or X API response before acting. An x_search answer is never evidence that a write happened.

Failure Modes

No xAI Credentials Available

Both auth paths fail. Set XAI_API_KEY in ~/.hermes/.env or run hermes auth add xai-oauth.

x_search Not Enabled for This Model

The configured model lacks x_search tool access. Switch to grok-4.5 or another supported Grok model.

Tool Doesn't Appear in Schema

The toolset is not enabled (check hermes tools) or no xAI credentials are available (check hermes auth status).

Degraded Response with No Citations

Possible causes:

• Typo in a handle.
• Date range too narrow.
• xAI index gap.

Retry with adjusted parameters or use the xurl skill for direct access.

Date Validation Failures

Return a structured error JSON as the tool result. Example:

{"error": "from_date must be YYYY-MM-DD format"}

Invalid reasoning_effort

Fails before the API request. Ensure the value is one of low, medium, high, or xhigh, and that the model supports it.

Constraints and Caveats

• x_search is read-only. It cannot post, reply, like, DM, upload media, delete, or prove account state changes.
• An x_search answer is never evidence that a write happened. Must be confirmed by xurl output or X API response.
• allowed_x_handles and excluded_x_handles are mutually exclusive.
• Each handle list is limited to 10 handles.
• Date parameters are validated client-side. Invalid dates return structured error JSON without an HTTP call.
• degraded: true means filters were set but no citations returned. The answer is unsourced.
• degraded: false when no filters are set (a broad unsourced answer is just an answer).
• reasoning_effort is sent as reasoning: {effort: ...}. Invalid values fail before the API request.
• Both xAI credential paths hit the same endpoint with the same payload. Only the bearer token differs.
• When both credentials are configured, SuperGrok OAuth wins (uses subscription quota).
• The check_fn runs every time the model's tool list is rebuilt. Returns True only if the bearer token is fetchable, non-empty, and successfully refreshed if expired. Revoked tokens with failed refresh hide the tool from the schema.

Examples

Example 1: Searching with Handle Filter

User asks: "What are people on X saying about the new Grok image features? Focus on responses from @xai."

The agent calls x_search with:

• query: "reactions to new Grok image features"
• allowed_x_handles: ["xai"]

The tool returns a synthesized answer with citations. The agent replies with the answer and references.

Example 2: Transitioning to State-Changing Actions

If the next request is "reply to the best one" or "like that post", the agent switches to the xurl skill. It confirms the exact target post using xurl output or X API response before performing the action.

Retry Behavior

The tool automatically retries on 5xx errors, ReadTimeout, and ConnectionError. Each retry backs off at 1.5x the attempt seconds, capped at 5 seconds. The number of retries is configured via the retries setting in ~/.hermes/config.yaml (default 2).

Mixed Workflows

For workflows that require both discovery and action, use x_search for discovery and the xurl skill for exact reads and state-changing actions. This separation ensures that read-only discovery does not inadvertently trigger writes.