fix(docs_tools): filter stale URLs before returning search results

[alwaysahustler]

Summary

While using chat-langchain, the docs search tool returned a stale/broken docs URL in its search results. This suggests URLs constructed from the Mintlify API are not being validated before being returned to the agent and recorded in tracing.

Related to #530, #531.

Evidence (what I saw)

Query / intent

• “what is langchain prompt”
• “langchain.chains”

Stale URL returned

• https://docs.langchain.com/oss/python/langchain/chains

Observed behavior

• The returned URL appears stale (leads to a not-found experience / broken destination), yet it was surfaced as a search result.

Root cause (likely)

_format_search_results() builds full URLs from Mintlify API paths and returns them without validation.

There is already a purpose-built URL validator:

• _check_urls_async() in link_check_tools.py

…but it does not appear to be called anywhere in the search pipeline, so stale URLs can pass through.

Proposed fix

In _format_search_results() (after building the list of URLs):

1. Call _check_urls_async() on the constructed URLs.
2. Filter out any URLs that return 404 or soft-404.
3. Return only validated URLs to:
   • the agent/tool response
   • LangSmith tracking/tracing outputs

Why this is complementary to existing work

• fix: prevent agent from generating stale python.langchain.com URLs #530 (prompt-level ban) and fix(check_links): block deprecated domains before HTTP requests #531 (domain blocklist) mitigate what an LLM might generate from memory.
• This issue addresses a separate vector: broken links originating from the search tool’s API results.

Acceptance criteria

• Search results returned from the docs search tool do not include URLs that are 404 or soft-404.
• Valid URLs continue to be returned unchanged.
• Tests cover a mixed set of valid + stale URLs and verify stale URLs are filtered before results are returned.

Maintainer approval request

If this approach looks correct, can a maintainer please confirm it’s approved so I can open a PR implementing exactly this?