SerpApi

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, openWorld, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: crawl caps at 10 pages by default and 100 maximum, and each successfully extracted uncached page consumes one credit — a cost disclosure an agent needs before choosing crawl. It also explains how compact mode filters output and when that filtering is skipped, though it never states response size or latency characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then options, then response shaping, then four runnable examples — good ordering for a tool with this many hidden switches. The compact-filtering paragraph is dense and requires re-reading, but nearly every sentence conveys a distinct behavior rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool whose real parameters are hidden inside an open object, the description supplies the semantics the schema cannot express, and the examples resolve the otherwise confusing split between top-level mode and params.mode. Since an output schema exists, the return-value detail is partly duplicative, but it remains useful given the two-tier filtering model.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the params object is an untyped open bag, so the description carries the entire burden — and it does: url required, params.mode enum values with default, params.output values, max_pages default and ceiling, and the interaction where output overrides the response-mode default. It falls short by naming include_markdown and json_restrictor without explaining their accepted values or effects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and three named operations — extract content from a URL, discover site URLs, crawl pages — which maps directly to the scrape/map/crawl modes. This is unmistakably distinct from the search-family siblings, so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit selection logic for the two axes that matter: which mode (scrape default / map / crawl) and which response mode (complete default / compact), plus a decisive rule — 'Use complete with output="json" for full JSON.' It also states url is required. What's missing is any when-not guidance or an explicit contrast with the search siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: compact versus complete response modes, Markdown behavior, output wrapper structure, guided-search interaction for missing parameters, cancellation semantics, and failure wrapper behavior. This goes well beyond what annotations or schema alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized with clear sections, bullet lists, and examples. The engine-discovery instructions are repeated twice, which is mildly redundant, but the overall structure is scannable and every major section earns its place given the tool's breadth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a broad, engine-flexible tool, the description is remarkably complete: it covers when to use the tool, how to discover supported engines, parameter conventions, response modes, output schema, guided-search behavior, and realistic examples. With a rich output schema and annotations present, no critical operational detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaningful guidance beyond the schema: it explains which parameters are common, notes 'q' is required for most engines, gives concrete JSON examples, and points to MCP resources for engine-specific parameter discovery. This helps an agent construct valid params far better than the raw schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: a universal search tool covering 'all SerpApi engines and result types.' It clearly enumerates the kinds of live structured SERP data it retrieves. However, it never explicitly contrasts itself with the sibling tools search_dashboard and search_table, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' section explicitly lists concrete scenarios such as web results, news, product listings, flights, and videos, giving an agent clear selection criteria. It does not mention when not to use the tool or point to sibling alternatives, but the listed conditions are specific enough to guide invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, non-destructive, open-world, non-idempotent), so the description's added value is the rendering behavior: it discloses that output is composed of three distinct rendered artifacts and that engine-specific dashboards are auto-selected (e.g. price intelligence for google_flights). It does not mention latency, token/size cost of the richer output, or fallback behavior when a dashboard is unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the tool's identity and return shape, then the alternate-tool relation, then the engine-selection nuance. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully explains what the caller receives, and the input side is handled by cross-reference to `search`. Minor gaps remain around cost/size of the richer payload and behavior when no engine-specific dashboard exists, but nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single free-form `params` object with 0% description coverage, so the description must carry the load — and 'Same params as `search`' is a meaningful delegation that tells the agent where to find the real contract. It still does not enumerate any parameter names or note whether dashboard-specific keys exist, so an agent must consult `search` before calling.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Interactive dashboard variant of `search`') and immediately enumerates the return composition: summary metrics, source breakdown chart, and results table with a detail panel. This is clearly distinguishable from the siblings `search` (plain results) and `search_table` (table only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection cue — 'Use for a richer visual overview of a query's results' — and anchors itself to `search` by inheriting its parameters. It does not explicitly state when NOT to use it (e.g. cost/latency tradeoffs vs. plain `search`), leaving the agent to infer the exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, open-world, non-destructive and non-idempotent, so the description only needs to add output/rendering behavior — which it does by disclosing that results are rendered as an interactive table rather than returned as raw JSON. That is meaningful context, especially since no output schema exists, though it says nothing about failure modes or fallback when rendering is unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences: identity and output format first, then the selection condition. Nothing is redundant and no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a thin UI-variant wrapper with zero-typed params, the description supplies what an agent most needs: what comes back, when to pick it, and where the parameter documentation lives. Minor gaps are the lack of any fallback guidance if the host cannot render the table.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single `params` property is an untyped anyOf object with additionalProperties true, so the schema conveys nothing. The description partially compensates by pointing to `search` for parameter semantics ('Same params as `search`'), but an agent must load the sibling tool's definition to learn anything concrete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('returns organic results') plus the distinctive output form ('sortable, searchable table rendered in the conversation'), and explicitly frames itself as a variant of `search`, so an agent can distinguish it from the JSON sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection rule: use when the host supports MCP Apps and the user wants to browse visually rather than read JSON, which implicitly names `search` as the alternative. It stops short of explicit exclusionary guidance (e.g. what to do when MCP Apps is unsupported) and never mentions `search_dashboard` as a competing option.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.