Find the right Google Places match for a business name

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is free, has no side effects, returns up to 5 candidates, and can silently resolve to the wrong business if skipped. It also details retry behavior, auto-pick rules, and exact fields returned—highly transparent about behavior and edge cases.

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 longer than average, but every sentence earns its place: it covers the canonical flow, risks, failure handling, and result fields. It is well-structured with clear sections (purpose, requirement, flow, failure). Slightly verbose but not wasteful for a tool that gates a critical workflow.

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?

Despite having no output schema, the description lists the exact fields returned (placeId, name, address, phone, rating, userRatingCount, businessType), explains how to present results to the user, and covers fallback behavior if the tool fails. Given the tool's complexity and central role in disambiguation, the description fully equips an agent to use 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 coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining that 'query' is free-form business text and by strongly recommending 'location' for common names to avoid globally popular wrong matches. It also contextualizes how the parameters interact with the disambiguation purpose, which goes beyond the schema's simple field descriptions.

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 ('Search Google Places for a business by name') and resource ('Google Places'), and clearly distinguishes it from sibling tools like create_site and list_sites by framing it as a lookup/disambiguation step. It also specifies the return candidate count, which concretely defines its function.

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 explicitly declares when to use this tool ('REQUIRED before create_site whenever you have only a business name'), provides a canonical flow, and gives alternative handling for failures (retry once, then ask the user about proceeding without a placeId). It also warns against skipping search even when confident, which is strong usage guidance beyond basics.

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