openclaw - 💡(How to fix) Fix feat(web_search): expose Perplexity `search_context_size` (low/medium/high content-budget)

Summary

The web_search tool's JSON schema (in dist/openclaw-tools-*.js → WebSearchSchema) accepts: query, count, country, language, freshness, date_after, date_before, search_lang, ui_lang, domain_filter, max_tokens, max_tokens_per_page.

It does not expose Perplexity's search_context_size parameter (added by Perplexity in 2026) — the content-budget knob that controls how deeply Sonar searches: low, medium, high. When the active provider is Perplexity (e.g. sonar / sonar-pro / sonar-deep-research), agents have no way to ask for a deeper search via the tool surface.

Effect we're seeing

In three-cubes/tc-agent-zone, agents doing research that requires depth (TAM analysis, competitor cards, regulatory review) end up issuing many shallow shotgun queries because they can't ask Sonar for a high content budget. Workarounds we use today: switch the agent's model mid-session to perplexity-proxy/sonar-deep-research, or fall back to manual Kairix + web_fetch against primary sources. Both work but neither is the right shape.

Proposed change

Add search_context_size to WebSearchSchema:

search_context_size: {
  type: "string",
  enum: ["low", "medium", "high"],
  description: "Provider-specific content budget hint. For Perplexity (sonar/*) this maps to web_search_options.search_context_size. Other providers may ignore."
}

Plumb it through to the Perplexity provider call as web_search_options.search_context_size. For non-Perplexity providers, the schema field can be silently ignored at the adapter level (or rejected with an actionable fix: per agent-actionable-feedback.md).

Reference

• Perplexity API doc: https://docs.perplexity.ai/api-reference/chat-completions-post — see web_search_options.search_context_size
• Our local workaround issue: filing as we go through the third-party-research review

Happy to PR the schema + adapter plumbing if helpful.