Semscraper

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior the annotations lack: computation happens on the server, the result is 'free', and it is derived from source URLs rather than brand names, which prevents misreading the output. It does not discuss failure modes when searches are still running, but wait_seconds in the schema partly covers that.

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: the compute-and-return semantics come first, then cost, then the routing sentence. A few fragments ('Free.', 'Based on source URLs, not on brand names.') are short but each carries a real disambiguation point, so little is wasted.

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 return-value burden and does so by enumerating per-domain metrics and the AI-Overview count. Combined with annotations covering the read-only profile and a fully documented schema, an agent has everything needed to call 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%, so ids, top, and wait_seconds are already fully documented in the schema. The description adds no syntax, ordering, or constraint detail beyond that (e.g. it never mentions the 500-id cap or the 55s wait ceiling), 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?

States a specific verb and resource — computes which domains Google cites in AI Overviews for already-created google_search IDs — and enumerates the returned aggregates (keyword count, mentions, keywords, best position). An agent can distinguish it from get_serp_results or list_searches 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?

Explicitly frames the use case as 'best tool to answer which sites Google cites... one small answer instead of every SERP,' which routes the agent away from fetching full SERPs. It stops short of naming the sibling by name or stating when-not-to-use conditions (e.g. pre-search vs. post-search), so it is clear context rather than a complete decision rule.

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 openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context not present in structured data: the currency (euros) and that the call is free of charge, which affects an agent's decision to invoke it.

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?

A single front-loaded sentence plus a one-word cost qualifier. Nothing is redundant and the resource and unit are stated immediately.

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-parameter read with no output schema, the description covers what the call is and its cost profile. It does not hint at the shape of the returned value (e.g., a balance field), which is the only remaining minor 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the schema, and it correctly makes no attempt to describe inputs.

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 (Returns), resource (the balance of the Semscraper account), and the unit (euros). This is unambiguous and clearly distinct from every sibling, all of which are search/queue/listing tools.

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 trailing 'Free' implies this call consumes no credits, which is a mild cost-based usage signal, but there is no explicit statement of when to call it or what alternatives exist (there are none, so no exclusion is needed). Usage is implied 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the call is free, each account has its own queue, and robots serve accounts in turn so large batches drain gradually — this explains why the counters may move slowly.

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 the return content, then cost, then queue mechanics. Every sentence carries information, though the queue-flow sentence is slightly more context than strictly required for selection.

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 parameters, no output schema, and read-only annotations, the description is nearly sufficient: it tells the agent what the counters mean and why values change slowly. Only the exact return shape (e.g., whether counts are returned as an object) is left unspecified, which is acceptable given the simplicity.

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 the baseline is 4; there is nothing parameter-wise for the description to explain and it does not pretend otherwise.

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 (returns) and a precise resource: counts of searches that are pending, processing, or done for the account. This is clearly distinct from the sibling list_searches (which enumerates searches) and get_balance (which covers credits), though it never names those siblings 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?

Usage is only implied: the agent must infer that this is the tool to poll when monitoring a large batch, and the 'Free' note hints at cost-driven selection without saying so. No explicit when-to-use/when-not or named alternative is given.

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=true and openWorldHint=false, and the description adds genuinely new context: the call is free because cost was incurred at search-creation time. It also implies the retry pattern via the schema's 'Call again while pending_ids remain', useful for an agent polling a queue.

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, front-loaded with what is returned and what input it expects. The cost note is appended compactly with 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 could say more about the returned shape is described by the blocks enum in the schema ('organic', 'ai_overview*'). Given the rich input schema and read-only annotations, what's present is largely sufficient for correct invocation.

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 all five parameters are already documented in the schema, including the filter, domain, and wait semantics. The description only re-frames ids as 'pending_ids of a previous call', adding little beyond the schema's own text, so the 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 verb+resource ('Returns searches already created') and constrains it to google_search/google_maps results keyed by serp_ IDs. It contrasts implicitly with the sibling creation tools (google_search, google_maps), though it doesn't name the sibling list_searches, which is the closest alternative.

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 concrete usage trigger ('the pending_ids of a previous call') and a decision-relevant fact (it's free because searches were paid at creation). It stops short of explicit when-not guidance or naming list_searches as the way to discover IDs in the first place.

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 (readOnly=false, idempotent=false, openWorld=true) signal a non-free, non-cacheable external fetch, and the description adds real value on top: it is paid from the account balance, priced like google_search, and exposes only rating/review count rather than full review text. It does not restate annotation claims, and the pending_ids/wait_seconds behavior is covered by 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?

Four front-loaded sentences: what it collects, what each listing contains, who it is for, and cost/return caveats. Nearly every clause earns its place, though the field enumeration overlaps slightly with the return-value caveat.

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 the returned fields (rank, name, CID, category, address, website, rating, review count, opening status, snippet) and delimits reviews to counts only. Cost model and ordering are stated; only cross-sibling disambiguation for web-vs-maps intent remains thin for a 9-param 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 description coverage is 100% across all 9 parameters, so depth, domain, geolocation, priority, language/location pairing, and max_items_per_block are already fully documented. The description adds no parameter-level syntax or constraint beyond what the schema provides, which is the baseline-3 case.

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 (collects), resource (Google Maps listings), ordering guarantee, and per-listing fields. The use-case clause ('local SEO, local competition, market research') implies it is the local/maps counterpart to google_search, but it never explicitly contrasts the two, so sibling differentiation is left partly to inference.

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 use-case list ('local SEO, local competition and market research') and references google_search only for pricing parity, not as an alternative to route away from. There is no 'when not to use' and no named alternative for web SERP intent, even though google_search and ai_overview_sources are obvious 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?

Goes well beyond the annotations by disclosing the pricing model (EUR 0.0003 first page, 0.0002 per extra page), latency (~30s/keyword, ~a minute for 10 pages), that the tool blocks waiting for results, the pending_ids handoff path, and the output boundary (titles/snippets/URLs, not page content). This is exactly the operational context an agent needs before invoking a slow, metered call.

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 but front-loaded: what it does first, then how to use it, then cost and duration, then the output boundary. The mid-sentence enumeration of block types is long, though it earns its place by naming the returned structures; nothing is padded or repeated.

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 11 parameters, no output schema and a metered async call, the description covers the missing pieces: cost, duration, blocking-vs-pending behavior, and what the response actually contains. An agent has everything needed to call it correctly and to decide whether to wait or poll.

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 baseline is 3, but the description adds real meaning on top: cost/time scaling with depth, the domain parameter reframed as 'where does this site rank', priority as a queue-jumping lever, and the async contract of wait_seconds. It stops short of adding anything for blocks/geolocation beyond what the schema already documents.

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 concrete verb and resource: collects the real Google SERP for keywords in a real browser, enumerates the block types returned and the per-item ranking fields (rank_type, rank_serp, page, pixel position). This is specific enough that an agent can distinguish it from get_serp_results (pending fetch) and google_maps 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?

Explicitly says when to reach for it ('to know what Google actually shows for a query, in a given country, language, city and device') and routes batched work to get_serp_results and wait_seconds=0. It does not contrast itself against siblings like google_maps or ai_overview_sources, so it is clear context but without full alternative 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 already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description still adds non-annotation behavior: the operation costs nothing, the reference set is a fixed 186/117 enumeration, and filtering exists specifically to bound response size. What is missing is any statement about ordering or how the pairs are formatted in the payload.

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, all front-loaded: identity/scope first, then purpose, then the optional filter. The clipped 'Free.' fragment carries real selection information with almost no token cost, 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 carries the return-value burden and does reasonably well — it names the returned unit (location/language pairs) and the universe size. It stops short of describing how a caller should consume or match those values against the parameters of other tools, which would fully close the loop for a reference-data lookup.

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 the schema already gives the substring-match semantics plus examples ('google.de', 'br', 'Deutsch'). The description's 'filter with a country domain, a code or a language name' restates those same three value classes, adding only the rationale that it keeps the answer short — marginal value, so the 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 verb and resource ('Lists the supported Google versions') and immediately narrows what a version is: location/language pairs with concrete cardinality (186 domains, 117 languages). The stated purpose ('to pick valid location and language values') separates it cleanly from the data-fetching siblings like google_search and get_serp_results.

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?

Tells the agent the operative context: use it to obtain valid location/language values, and filter to keep responses short. 'Free' is a useful selection signal when weighed against paid siblings. It does not explicitly name an alternative tool or a when-not-to-use condition, so it falls short of 5.

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 and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior: it is free, results are excluded, and it covers every search made via this server or the API. It stops short of describing pagination semantics beyond the schema's cursor field.

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-loads the core action and scope before the usage guidance, and every clause carries information (field list, cost, failure recovery). It is a single dense paragraph, slightly heavy, but no sentence is wasted.

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?

There is no output schema, so the description compensates by enumerating the returned fields (ID, engine, keyword, device, location, etc.). Combined with the annotations and full schema coverage, an agent has everything needed to call 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%, so all four parameters (date, limit, cursor, status) are fully documented in the schema with format, defaults and bounds. The description adds no additional parameter meaning beyond what the schema already provides, making the baseline 3 appropriate.

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 (lists the account's searches), adds scope (most recent first, no results) and enumerates the returned fields. It distinguishes itself from siblings by routing to get_serp_results instead of re-searching.

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?

Explicit when-to-use cases: to find IDs ('the last 10 searches', 'today's searches') and specifically after a google_search or google_maps call failed, timed out or lost its answer. It names the alternative (get_serp_results) and the reason to prefer it (searches were already created and paid).

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