autocomplete_places

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

While annotations already indicate idempotence and non-destructiveness, the description adds context about the tool being the cheapest, but it fails to clarify important behaviors such as whether results depend on location parameters, if any rate limiting or throttling exists, or what happens with ambiguous inputs. Given the presence of annotations, the bar for added value is higher, and the description barely meets 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?

The description is extremely concise at two sentences, with no filler. The first sentence clearly states the function and output, and the second provides usage context. Every word adds value.

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?

Given that an output schema exists, the description doesn't need to explain return values. The tool is relatively simple with one required parameter and clear annotations. The description covers usage flow and efficiency, making it mostly complete. A minor gap is the lack of guidance on when not to use it (e.g., if exact match needed) or what distinguishes it from search_places_by_text.

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 description provides no parameter-level details, but since schema description coverage is 0%, it must compensate for this gap. It does offer high-level context that the tool uses partial text (matching the only required input) and mentions optional location parameters implicitly through the tool's purpose. However, it doesn't explain radius_metres or coordinate semantics, so some burden remains.

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 clearly specifies the verb ('Complete'), the resource ('a partial place name or address'), and the output ('up to five candidates, each with a place id'). It distinguishes the tool from siblings by focusing on partial input and id generation.

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 provides explicit guidance on when to use this tool: before a search or details lookup, and to convert vague names into usable IDs. It also implies exclusivity by noting it's the 'cheapest' way, contrasting with more expensive sibling operations.

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