datasets_google_map_search

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

With no annotations, the description carries the full behavioral burden and does so well: it disambiguates null vs 0 for rating and review_count, explains the three-state permanently_closed semantics with an explicit warning that any total includes an unknown number of closed businesses, and discloses the credit-based billing model including the 2-credit minimum on empty results. It does not cover return format, pagination behavior, or any auth/rate-limit context beyond cost.

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 front-loads the core definition before moving into sort, null semantics, and billing, and almost every sentence conveys usable information. It loses a point for the redundant opening pair of sentences and for restating schema parameter text rather than pointing to it.

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 21-parameter search tool with no annotations and no output schema, the description covers the highest-risk ambiguities (null semantics, closure tri-state, cost) that an agent could otherwise misread. It omits return shape and pagination behavior, but those are partly constrained in the schema (page * page_size <= 10000) and there is no output schema to describe.

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 21 parameters, and much of the description (category localization, min_rating excluding unrated rows, permanently_closed null meaning unknown) duplicates the schema text nearly verbatim. The genuinely additive piece is the sort behavior, e.g. that rating_desc places unrated businesses last, which is not in the schema. Baseline 3 is appropriate given the heavy schema overlap.

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 plus resource ("Search stored Google Maps businesses") and stresses that the records come from a search index rather than live Google Maps data, which implicitly separates it from live siblings like google_map_search. It never names the closest siblings (datasets_google_map_item, datasets_google_map_nearby, datasets_google_map_facets), so the differentiation is inferred rather than explicit. The second sentence largely restates the first.

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 filter-level guidance (use the category facet to discover exact values, has_geo=false to isolate service-area businesses, permanently_closed=false to drop confirmed-closed ones), which implies usage contexts. However, it never says when to choose this tool over datasets_google_map_nearby, datasets_google_map_item, or the live google_map_search sibling. Guidance is about how to filter, not when to use this tool.

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