feat: add per-tool result limits and refine compact responses

[adarshdigievo]

Changes

• Added result_limit to every search tool. It limits each top-level result list independently in compact and full modes. The limit is applied after SerpApi returns the response, so it does not change the number of results requested from the engine. Set result_limit=None to retain every returned result.

  Tool	Default result_limit
  web_search	10
  news_search	20
  maps_search	10
  images_search	50
  shopping_search	60
  videos_search	10
  hotels_search	20
  flights_search	10 per flight list
  travel_explore_search	50

• Refined compact responses to remove redundant fields while preserving useful result data, including product links and Amazon alternative-offer links.

• Updated engine-specific response handling for web answer sections, YouTube result families, shopping results, hotels, flights, and travel exploration.

• Updated tests, README, user guides, examples, and cookbook entries for the new response controls and compact-mode behavior.

[Copilot]

Pull request overview

This PR introduces a new result_limit constructor option across the SerpApi search tool factories, applying per-result-family list truncation in both compact and full modes, and refines compact-mode payloads by dropping redundant per-engine fields while preserving key links.

Changes:

• Add result_limit plumbing to SearchRuntime and all tool constructors (query + travel tools), plus validation and per-family truncation.
• Refine compact-mode projections for vertical results (shopping/images/hotels/travel explore) and expand engine-specific compact result families (notably YouTube and Bing).
• Update/add tests, docs, examples, and cookbook snippets to reflect new defaults and compact/full behavior.

Reviewed changes

Copilot reviewed 66 out of 66 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_shared.py	Updates existing runtime/compact/full tests and adds coverage for per-family limiting and compact projections.
tests/test_result_limit.py	New tests validating per-tool defaults, overrides, None, and independence from upstream count params.
tests/test_live.py	Live tests now pass result_limit explicitly and assert result counts against it.
tests/test_live_adapters.py	Adapter live test now uses result_limit instead of upstream num and asserts bounded results.
tests/live_contracts.py	Live test cases gain result_limit to align expected bounds with the new behavior.
src/serpapi_search_tools/_travel_tools.py	Adds result_limit to travel tool factories and passes through to the runtime.
src/serpapi_search_tools/_shared.py	Implements result_limit validation + per-list limiting and compact item projection/drop rules.
src/serpapi_search_tools/_query_tools.py	Adds result_limit to web/news/maps/images/shopping/videos constructors and wires into runtime creation.
README.md	Reworks README guidance to emphasize mode + result_limit over upstream num, plus reorganizes sections.
examples/smolagents_openai.py	Switches example bounding from default_params.num to result_limit.
examples/README.md	Updates narrative around compact output and introduces result_limit.
examples/pydantic_ai_openai.py	Switches example bounding to result_limit.
examples/openai_agents_openai.py	Switches example bounding to result_limit across tools.
examples/microsoft_agent_framework_openai.py	Uses result_limit for predictable bounded outputs.
examples/llamaindex_openai.py	Uses result_limit for bounded results.
examples/langgraph_openai.py	Uses result_limit for bounded results.
examples/langchain_grok.py	Uses result_limit for bounded results.
examples/haystack_openai.py	Uses result_limit for bounded results.
examples/google_adk_gemini.py	Uses result_limit for bounded results.
examples/direct_search.py	Uses result_limit instead of engine num for bounding.
examples/direct_regioned_search.py	Uses result_limit per region tool instance.
examples/direct_multi_search.py	Uses result_limit for consistent bounds across tools.
examples/direct_marketplace_comparison.py	Uses result_limit when comparing marketplaces.
examples/direct_cached_search.py	Uses result_limit when demonstrating cached searches.
examples/crewai_grok.py	Uses result_limit for bounded shopping results.
examples/claude_agent_sdk_sonnet.py	Uses result_limit for bounded news results.
examples/autogen_openai.py	Uses result_limit for bounded news results.
examples/agno_grok.py	Uses result_limit for bounded web/shopping results.
docs/user_guide/20-debugging.qmd	Updates debugging guidance and result-family lists (notably YouTube families).
docs/user_guide/19-managing_llm_context.qmd	New guide documenting mode + result_limit, defaults, and per-list behavior.
docs/user_guide/18-travel_explore_search.qmd	Documents result_limit and clarifies Travel Explore constraints/behavior.
docs/user_guide/17-flights_search.qmd	Documents result_limit and clarifies constraints/behavior.
docs/user_guide/16-hotels_search.qmd	Documents result_limit and compact/full behavior.
docs/user_guide/15-videos_search.qmd	Documents expanded YouTube result families and result_limit.
docs/user_guide/14-shopping_search.qmd	Shifts bounding to result_limit and clarifies per-marketplace defaults/links.
docs/user_guide/13-images_search.qmd	Documents result_limit and compact/full behavior.
docs/user_guide/12-maps_search.qmd	Documents result_limit and compact/full behavior.
docs/user_guide/11-news_search.qmd	Documents result_limit and compact/full behavior.
docs/user_guide/10-web_search.qmd	Documents result_limit and engine-specific notes for web engines.
docs/user_guide/06-recipes.qmd	Updates recipes to use result_limit for bounding.
docs/user_guide/04-configuration.qmd	Adds result_limit to common options and updates compact/full explanation.
docs/user_guide/02-quickstart.qmd	Updates quickstart example to use result_limit.
docs/user_guide/01-introduction.qmd	Updates introduction to describe mode + result_limit behavior.
docs/sdk_examples/semantic_kernel.qmd	Updates SDK example to align with new configuration patterns.
docs/sdk_examples/pydantic_ai.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/openai_agents.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/microsoft_agent_framework.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/langgraph.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/google_adk.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/crewai.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/claude_agent_sdk.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/autogen.qmd	Updates SDK example to use result_limit.
docs/sdk_examples/agno.qmd	Updates SDK example to use result_limit.
cookbook/smolagents/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/semantic-kernel/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/pydantic-ai/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/openai-agents/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/microsoft-agent-framework/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/llamaindex/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/langgraph/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/langchain/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/haystack/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/google-adk/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/claude-agent-sdk/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/autogen/main.py	Updates cookbook scenario to use result_limit per tool.
cookbook/agno/main.py	Updates cookbook scenario to use result_limit per tool.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[adarshdigievo]

both fields exist in responses

[adarshdigievo]

both fields exist in responses