Zenserp MCP by usefulapi

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

Beyond the annotations, the description discloses the premium cost model, latency of seconds-to-a-minute, quota sensitivity, and plan-gate constraints per engine. It also clarifies the optional brand-tracking behavior and the GET endpoint. These details materially help an agent decide whether the call is worth making.

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 dense but well-organized: purpose first, then cost/latency cautions, then plan gating, then endpoint. Every sentence adds decision-relevant information, and there is no 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?

With no output schema, the description adequately explains the main return shape (answer_text plus citations and optional brand_visibility). It also covers the key operational constraints: cost, latency, quota, and plan-gated engine availability. Nothing critical for correct invocation appears 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%, so the baseline is 3. The description still adds value by mapping the engine enum to plan tiers and by clarifying that passing brand yields a brand_visibility object, which is not fully captured by the schema descriptions. It does not add further meaning for prompt, country, fields, or additional_prompt beyond what the schema already says.

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 gives a specific verb+resource (send a prompt to an AI answer engine), names the engines, and states the primary return values (answer_text with citations and optional brand visibility). It clearly distinguishes this from the sibling search tools, which cover web, image, video, shopping, etc.

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?

It provides strong usage context: it warns that quota is spent at a premium per-answer rate, that responses are slow, and that it must not be repeated needlessly. It also explains plan gating by engine. However, it does not explicitly name an alternative tool for when a cheaper or faster search is more appropriate.

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 only declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true); the description adds the material operational fact that each successful call SPENDS 1 request of the monthly quota and that failed calls are not charged. That cost/quota disclosure is genuinely useful and not present in the structured data. It does not explain the surprisingly destructive hint for a GET endpoint, but it does not contradict it either.

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 short clauses, all load-bearing: the resource, the recommended parameter combination, the alternatives, and the cost warning. The quota warning is placed after the usage guidance but before the endpoint, which is a reasonable order, though the trailing 'GET /v1/flights.' adds little for an agent.

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 9 optional params, no required fields, no output schema and full schema coverage, the description covers the two things an agent can't infer: the correct input mode and the billing consequence. The only real gap is what the response contains (top-level keys the 'fields' param can trim), which is left unexplained.

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 description coverage is 100%, so the baseline is 3, and the description goes beyond it by stating the cross-parameter rule that 'dates and curr are honoured only then' — i.e. only when origin/destination airport codes are supplied. That conditional interaction is the highest-risk gotcha for this tool and is surfaced explicitly.

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 plus title make the resource and action unmistakable: it queries Google Flights options, which cleanly separates it from siblings like zenserp_hotels or zenserp_maps_search. The opening 'Google Flights options.' is terse rather than a stated verb, so it stops just short of a 5, but an agent can route to it without opening the 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?

It gives a clear preferred invocation ('origin and destination as 3-letter airport codes plus departure_date') and explains the two fallback modes (free-text q, or tfs copied from a Google Flights URL). It also warns not to repeat calls needlessly. It stops short of a 5 because it never names a sibling tool as the alternative for non-flight needs.

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, so the safety profile is covered. The description adds genuinely new behavioral context: the call consumes no quota, and it exposes the underlying endpoint (GET /v2/status), which helps an agent treat it as a cheap poll.

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?

Three short, front-loaded clauses: what it returns, what it costs, and the underlying endpoint. No sentence is filler and the key fact (remaining_requests) leads.

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 carries the burden of describing the return value — and it does, naming 'remaining_requests' explicitly. For a zero-parameter, read-only status tool, nothing an agent needs 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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly spends its words on the return value instead of inventing parameter semantics.

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 the specific resource and return value: the number of search requests remaining on the API key's plan. It is unmistakably distinct from the eighteen sibling search tools, which all consume quota rather than report it.

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 phrase 'Free: it spends no quota' implies this is a safe pre-flight check to run before paid searches, but the description never explicitly says when to call it or contrasts it with any alternative. Usage is inferable rather than stated.

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?

Adds behavior the annotations do not carry: 1 monthly quota request spent per successful call, failed calls are free, and the today's-rates fallback when dates are omitted. It does not reconcile the annotations' destructiveHint=true/openWorldHint=true with what is effectively a billed search, but it does not contradict them either.

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?

Three compact sentences, quota cost and the date-pairing rule front-loaded ahead of the endpoint. The opening sentence is grammatically awkward ("offers" used as a noun) but 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 12-parameter, no-output-schema search tool the description covers the cost model and the one cross-parameter dependency. It never hints at what the reply contains, though the fields parameter description (organic, paid_results, related_searches) partially compensates.

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 description coverage is 100%, so the baseline is 3. The description earns an extra point by stating the consequence of omitting check_out alongside check_in (fallback to today's rates), which the schema's "Needs check_out" does not express.

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?

Names the specific resource (Google Hotels offers for a hotel or place) and pins the endpoint (GET /v1/hotels), which distinguishes it from siblings like zenserp_flights, zenserp_maps_search and zenserp_shopping_search. The verb is only implied by "offers" rather than stated as "search," so it falls just short of the crispest form.

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 real operational guidance: send check_in and check_out together or Google falls back to today's rates, and do not repeat a call needlessly because each success burns quota. However, with 18 siblings there is no routing guidance at all, notably nothing distinguishing this from zenserp_maps_search for a hotel lookup or from zenserp_search.

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?

Adds genuinely useful behavior beyond the annotations: exactly 1 quota unit charged per successful call, failed calls free, 100 images per page, and the underlying endpoint (GET /v2/search, tbm=isch). This quota/cost disclosure is the key behavioral fact for a non-idempotent, costly endpoint and pairs sensibly with destructiveHint=true.

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?

Three tight sentences, front-loaded with the resource and payoff, followed by the cost warning and endpoint. Every sentence earns its place, though the endpoint string is somewhat implementation-detail-heavy for a top-level description.

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 an 11-parameter tool with no output schema, the description covers return content, page sizing, and cost, which is most of what an agent needs. Pagination mechanics and location/device effects are left to the schema, acceptable given 100% coverage.

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% and each parameter description is rich (including cross-references to zenserp_list_countries/languages), so the schema carries the semantics. The description only reinforces page size ('Each page holds 100 images'), adding marginal value over the ijn/start docs.

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+resource ('Google image results') and enumerates the payload (thumbnails, source pages, sizes), so an agent knows exactly what this returns. It does not, however, distinguish itself from sibling zenserp_reverse_image_search or zenserp_video_search, leaving that inference to the name.

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 cost-driven usage guidance ('do not repeat a call needlessly') and implies the tool's place in a quota-limited flow, but never states when to prefer it over siblings like reverse_image_search or when-not to use it. Usage is implied rather than spelled out.

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 only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=true; they say nothing about cost. The description adds genuinely useful behavior: each successful call consumes 1 of the monthly quota, failed calls are not charged, and the result set is single-page. This is real value beyond the annotations, though return format and pagination/cache interaction are left to the schema.

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?

Dense and front-loaded: purpose first, then the two operational facts an agent most needs (single page, quota cost). The trailing 'GET /v2/search (ibp=htl;jobs)' is implementation trivia an agent cannot act on, the only wasted clause.

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 six-parameter, no-output-schema search tool, the description covers the essentials: what is returned, that there is no paging, and the quota consequence of calling it. It is slightly thin on the cache/fields cost interaction, but an agent has everything needed to invoke it correctly.

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 description coverage is 100% and every parameter (q, gl, hl, cache, fields, location) is documented in the schema itself, so the baseline is 3. The description only echoes 'for a query' and adds no parameter syntax, defaults, or cross-references the schema lacks.

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+resource ('Google Jobs listings for a query') and even sketches the reply shape (jobs_results: title, company, location, source, apply url). It is unmistakably distinguished from siblings like zenserp_news_search, zenserp_video_search, or the generic zenserp_search without opening any 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 real usage constraint — 'do not repeat a call needlessly' and 'Google returns one page; there is no paging' — which tells the agent not to paginate or retry. However, it never states when to prefer this tool over siblings (e.g. the generic zenserp_search) or any explicit when-not condition, so guidance remains implied.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the underlying endpoint (GET /v2/gl), which is mild context and does not disclose return shape or sizing.

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?

Three terse fragments with the key information front-loaded and zero filler. Nothing is wasted for a simple reference tool.

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 zero-param list endpoint with no output schema, the description conveys what is returned and how it is used. It would be stronger with a note on the return format (e.g., list of code/name pairs), but it is adequate.

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?

With zero parameters, the baseline is 4. The description does tie the output to the 'gl' parameter semantics, adding useful meaning about how the returned codes are consumed, though it gives no example values or format.

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 resource (supported country codes) and its role (values for gl). It is distinguishable from sibling zenserp_list_languages, though it relies on the title for the 'list' framing rather than a verb in the description itself.

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?

Usage is implied: these are the values to feed into the 'gl' parameter of the search tools. However, there is no explicit statement of when to call this versus looking values up elsewhere, and no mention of related siblings like list_languages.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint path but says nothing about the shape of the returned list. Adequate given annotation coverage.

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 short fragments, front-loaded with the resource and the consuming parameter. Efficient, though fragmentary phrasing leaves no room for return-shape guidance.

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?

A parameterless lookup with no output schema; the description states what the values are for and where they come from. Minor gap: it doesn't describe the item format of the returned list.

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?

Zero parameters, so baseline is 4 per rubric. The description usefully names hl as the parameter this enumeration feeds, exceeding the empty schema.

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?

Names the resource precisely (interface language codes) and ties it to the hl parameter, plus the underlying endpoint. Distinguishable from siblings like list_countries and list_search_engines only via the name, not explicit contrast, so not a 5.

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?

Implies clear use: call this to discover the valid values for the hl parameter. No explicit when-not or named alternatives, but context is unambiguous for a static enumerator.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact GET endpoint and, importantly, a cost caveat noting that the docs do not clarify whether these helper lists are billed (though they are not searches). That billing note is real context an agent would not otherwise have.

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?

Three short clauses, front-loaded with the purpose and the parameter linkage before the endpoint and cost note. Tight and waste-free, though the opening fragment is slightly telegraphic.

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 trivial no-parameter, no-output-schema list endpoint, the description supplies purpose, the underlying route, and a billing caveat, which is nearly everything an agent needs. Nothing essential is missing, though the return shape is left implicit.

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 tool takes zero parameters, so the baseline is 4. The description still earns that level by connecting the returned values to the search_engine parameter consumed elsewhere, giving the output meaning relative to the rest of the API.

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 resource (search engine hosts Zenserp supports) and explicitly ties it to its downstream use (values for search_engine). This distinguishes it from sibling list tools like list_countries and list_languages, which enumerate different domains. It stops just short of 5 because the phrasing is a sentence fragment rather than a clean verb+resource statement.

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 parenthetical '(values for search_engine)' implicitly tells the agent this is the endpoint to consult before setting the search_engine parameter, which is useful guidance. However, there is no explicit when-to-use or when-not-to-use framing, and no mention of alternatives.

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 flag destructiveHint=true and non-idempotent, but the description adds the crucial operational trait that each successful call burns one monthly quota unit while failures are free, and warns against redundant calls. That is real cost/behavior context not present in structured fields.

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?

Three short, front-loaded clauses: what you get, the location caveat, and the cost model. Nothing superfluous, though the endpoint notation at the end is slightly tacked on.

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 10-parameter search tool with no output schema and full schema coverage, the description supplies the domain framing and quota model an agent needs. It omits nothing critical, as return shape and pagination are handled by the schema.

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 description coverage is 100%, so the schema already documents all ten parameters, including the cache/quota interaction. The description only redundantly echoes the location hint, adding no syntax or format detail beyond what is structured.

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 names the resource precisely ('Google local/maps results') and enumerates the payload (address, rating, phone, coordinates), plus the underlying endpoint. An agent can distinguish it from generic zenserp_search, though no sibling is named explicitly.

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?

'Set location for accurate results' and the quota warning imply this is for place-dependent business lookups, but there is no explicit when-to-use-this-vs-zenserp_search guidance or stated exclusions. Usage is inferable rather than directed.

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?

The description meaningfully exceeds annotations by disclosing the quota cost model ('SPENDS 1 request of the monthly quota per successful call; failed calls are not charged') and the endpoint protocol (GET /v2/search with tbm=nws). However, it contradicts the destructiveHint=false implication of a read-only search, and it doesn't mention caching or pagination behavior covered elsewhere.

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?

Three tightly packed sentences with zero waste: purpose, behavioral constraint, and protocol details are all front-loaded. Every phrase carries specific information.

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 10-parameter search tool with full schema coverage and no output schema, the description covers the essential behavioral context: quota cost, caching implications, and endpoint. It doesn't explicitly state the return format, but the schema and query behavior are well-described.

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 description coverage is 100%, so the schema already documents all 10 parameters thoroughly. The description adds no parameter-level details beyond what the schema provides, which is acceptable given the high coverage.

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: 'Google News results for a query' with enumerated return fields (title, source, date, snippet). It doesn't explicitly distinguish from siblings such as zenserp_search or zenserp_video_search, but the 'News' qualifier implies the distinction.

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 description implies usage through the quota warning ('do not repeat a call needlessly'), but gives no explicit when-to-use or when-not-to-use guidance relative to sibling tools. The context of search types is left to the agent to infer from the tool name.

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 flag openWorldHint, non-idempotency and destructiveness but say nothing about cost; the description adds the crucial metering rule (1 quota request per success, failures uncharged) and the charged-vs-free cache implication. It still omits what happens on quota exhaustion or error shapes, keeping it below 5.

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?

Three tight clauses with the highest-value information (result type, quota cost) front-loaded; the trailing 'GET /v2/search (image_url)' is mildly redundant but not wasteful.

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 metered query tool with no output schema, the description conveys what is returned and the billing consequence, which is the main risk of misuse; only the absence of explicit sibling-routing guidance leaves a gap.

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 description coverage is 100%, so gl, hl, cache, fields and image_url are fully documented in the schema; the description adds only the endpoint tag and re-cites image_url, which is baseline-3 territory.

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?

Naming the specific result ('pages and sources that contain a given image') plus the method (Google reverse image search) tells an agent exactly what it returns, which cleanly separates it from the sibling zenserp_image_search keyword tool.

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?

It warns that each successful call consumes one monthly request and not to repeat calls needlessly, which is real usage guidance, but it never states when to pick this over zenserp_image_search or any other sibling, so routing must be inferred.

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?

Beyond the annotations it discloses quota economics (1 request per successful call, failures not charged, ai_overview costs 3 when returned), plan requirements, and the cache side effect (stored reply kept 24h, not charged). This explains the non-readonly, non-idempotent side effects the annotations only imply.

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?

Tight and front-loaded with the payload description first, then engine selection, then cost warnings. The semicolon-packed sentences are dense but every clause carries information; slightly telegraphic in places.

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 compensates by naming the top-level response sections an agent will receive, and it covers the operational context (quota, caching, plan tiers) needed to call this tool responsibly. Nothing material is missing for a 12-param, 1-required search tool.

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% so the baseline is 3, but the description adds value the schema does not: default engine behavior, the fact that search_engine accepts alternative hosts, and the ai_overview cost/plan condition. Other params (gl, hl, start, fields) are left to the schema.

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+resource ('Live search-engine result page as JSON') and enumerates the returned sections (organic, paid_results, snippets, related questions/searches, knowledge graph), which distinguishes it from siblings like zenserp_image_search or zenserp_news_search. Engine selection semantics are also spelled out.

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 clear operative guidance: default engine is Google, set search_engine for Bing/Yandex/DuckDuckGo, and 'do not repeat a call needlessly' because each success spends quota, plus the ai_overview plan gate. It does not, however, route the agent to more specialized siblings (image, news, shopping) when those would be the better fit.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the result set is very large ('The list is long') and should be narrowed with query/limit, which an agent cannot infer from the annotations.

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?

Three short sentences, front-loaded with what the tool returns before the usage advice. The trailing 'GET /v2/locations' is mildly redundant metadata but does not bloat the definition.

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 simple, annotation-covered, two-parameter lookup with no output schema, the description covers what is returned, why the result is large, and how to narrow it. Only the relationship to the sibling reference-list tools is left implicit.

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 description coverage is 100%, so the schema already documents both parameters, including the example 'vienna' and the match semantics. The description's 'keep only entries that contain it' and 'cap the count' essentially restate the schema, adding little beyond the baseline.

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 precisely what the tool returns (Google's canonical geo locations) and, crucially, its role as the source of valid values for the `location` parameter used by the search tools. That ties it to a concrete consumer and separates it from sibling lookup tools like list_countries or list_languages.

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?

Explains how to use it ('pass query to keep only entries that contain it, and limit to cap the count'), which is real operational guidance. It implies the context (fetch valid location values) but never explicitly contrasts with the other reference-list siblings, so it stops short of full when/when-not routing.

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?

With annotations present but the description disclosing the cost model ('SPENDS 1 request of the monthly quota per successful call (failed calls are not charged)'), this adds real context beyond the hints. The destructiveHint/readOnlyHint=true-false pair looks miscalibrated for a 'GET /v1/shopping' fetch, but the description's irreversible-quota framing explains why the call is treated as costly rather than claiming any data mutation, so it does not contradict.

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 short sentences plus the endpoint path, front-loaded with what is returned and what the IDs are, then the cost warning. No filler; each clause carries information an agent needs before calling.

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?

No output schema exists, so the description carries the return-value burden and does state the returned shape (description, offers, variations). Combined with 100% schema coverage of all five parameters, an agent has what it needs; only response envelope details (paging/shape beyond the listed keys) are left implicit.

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 already 100%, so the baseline is 3, but the description adds cross-parameter meaning: gpc_id only makes sense paired with product_id and expands the result to 'the whole product cluster across merchants'. That interaction is not spelled out as clearly in the schema itself.

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 names the specific resource and its payload ('Product page data from Google Shopping: description, merchant offers, variations') and explicitly contrasts itself with the sibling zenserp_shopping_search by saying the IDs come from there. An agent can distinguish this from the search tool 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?

It gives clear provenance for inputs ('product_id comes from zenserp_shopping_search', 'gpc_id ... from the same result') and an operational rule ('do not repeat a call needlessly'). It stops short of an explicit when-not/alternative branch, but the routing context is unambiguous.

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?

The annotations mark this destructive (destructiveHint=true), which is unusual for a read-like search, and the description explains the basis: it 'SPENDS 1 request of the monthly quota per successful call' and failed calls are not charged. That quota/cost disclosure adds meaning beyond the structured hints. It does not discuss rate-limit behavior or the 24h cache interaction, so it stops at a 4.

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?

Three compact sentences, front-loaded with the resource and return contents, then cost, then the underlying endpoint. Every sentence carries information an agent needs and there is no 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?

With no output schema, the description usefully enumerates returned fields (product, price, merchant, rating, product_id) so the agent knows what comes back. Combined with the quota disclosure and a fully-covered input schema, it is close to complete; only pagination/result-count expectations and cache behavior are left to the schema.

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 description coverage is 100%, so every parameter is already documented in the schema. The description adds no parameter-level syntax or defaults beyond what is there (the listed items are return contents, not inputs). Baseline 3 applies when the schema does the heavy lifting.

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 ('Google Shopping listings for a query') and enumerates what each listing contains (product, price, merchant, rating, product_id). It also names the sibling zenserp_shopping_product that consumes the product_id, so an agent can distinguish this from zenserp_search and other vertical searches 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 clear context for use (Shopping listings) and an explicit follow-on path via the product_id for zenserp_shopping_product, plus a usage caution ('do not repeat a call needlessly'). It stops short of naming an exclusion — e.g. when to prefer zenserp_search with tbm=shop or a different vertical — so it is clear but not fully routing.

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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely useful behavioral context the annotations lack: it SPENDS 1 monthly-quota request per successful call and failed calls are not charged. It does not explain the odd destructiveHint=true on what reads as a query tool, but it does not contradict it either.

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 short sentences, front-loaded with purpose followed by window limit, quota cost, and endpoint. Every sentence carries information; the trailing 'GET /v1/trends' is marginally redundant but harmless.

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 6-parameter, no-output-schema tool with annotations present, the description covers the critical operational facts an agent needs: the 7-day data ceiling (which explains why longer timeframes collapse) and the quota cost. Nothing essential is missing, though a note on what the response contains would round it out.

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 description coverage is 100% and the schema documents every parameter in detail (cat ids, geo pattern, cache charge semantics, fields, keyword, timeframe enum). The description only restates that keywords and category narrow results and that results are country-scoped, adding little beyond the schema, so the baseline of 3 applies.

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 names a specific verb+resource ('Trending searches from Google Trends') and scopes it ('for a country, optionally narrowed to given keywords or a category'). The purpose is unmistakable and unlike any sibling, but it never explicitly contrasts itself with adjacent tools such as zenserp_search, so it stops short of a 5.

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?

It gives real usage constraints: trending data covers at most the past 7 days, and 'do not repeat a call needlessly' warns against redundant invocations. However, it offers no when-to-use-vs-alternative guidance (e.g. trends vs. a general web search) and no explicit exclusions.

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?

Adds real behavioral context beyond the annotations: the exact cost model ('1 request of the monthly quota per successful call', failures not charged) and the underlying endpoint (GET /v2/search, tbm=vid). The annotations already flag a non-read-only, quota-consuming operation, and the description explains why, so the two are consistent rather than contradictory. It does not describe pagination or result-set limits, which the schema covers instead.

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 tight sentences with the output shape front-loaded and the cost warning immediately after; nothing is padded. The endpoint/parameter fragment '(tbm=vid)' is slightly terse but still earns its place by pinning down the search vertical.

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 10-parameter, no-output-schema tool the description covers the essentials: what it returns, what it costs, and the endpoint. Parameter-level detail is fully delegated to a 100%-covered schema, so nothing critical is missing, though a note on pagination/result limits would round it out.

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 description coverage is 100%, so the schema already documents all ten parameters in detail (gl, hl, lr, tbs, cache, start, device, fields, location). The description adds only 'for a query', which duplicates the required q parameter. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Google video results for a query') and even names the returned fields (title, channel, length, link), so the agent knows exactly what comes back. It stops short of differentiating from the sibling zenserp_youtube_search, which an agent could easily confuse with this Google video-vertical search.

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?

Implies usage ('for a query') and adds a quota-discipline warning ('do not repeat a call needlessly'), which is useful operational guidance. However it gives no explicit when-to-use / when-not guidance against alternatives like zenserp_youtube_search, zenserp_image_search, or plain zenserp_search, leaving the routing decision to inference.

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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description meaningfully extends that by disclosing the billing model (one monthly-quota request per successful call, failures uncharged) and the cache semantics, which the annotations do not convey. It does not contradict the destructiveHint annotation — the quota spend is an observable side effect consistent with a non-read-only classification.

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?

Three dense sentences with zero filler: results scope first, then the cost warning most likely to change agent behavior, then the endpoint. Every clause earns its place and the constraint is front-loaded.

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 7-parameter, quota-metered search with no output schema, the description covers what is returned at a high level (videos, channels, ads), the cost, and the endpoint. Return-shape detail is partially covered by the params' description of top-level keys, but the description itself stops short of describing the response structure an agent would need to consume it.

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 description coverage is 100%, so every parameter (q, gl, hl, sp, cache, fields, location) is already documented in the schema, including cross-references to zenserp_list_countries/languages and locations. The description only adds 'optionally by location', which is redundant with the schema. Baseline 3 applies.

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 resource (YouTube search results: videos, channels, ads) with an optional location qualifier and pins it to the concrete endpoint GET /v2/search with search_engine=youtube.com. It does not explicitly contrast with the sibling zenserp_video_search, so an agent must infer the boundary, but the scope is otherwise unambiguous.

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?

It gives one operational guideline — 'do not repeat a call needlessly' — tied to the quota cost, which is genuinely useful. However, it offers no guidance on when to pick this over zenserp_video_search, zenserp_search, or the other media search siblings, so the alternative-selection decision is left implicit.

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