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

Beyond annotations, the description discloses important behavior: results are ranked like the referenced best-of pages, every field carries a source, and key fields such as addresses, coordinates, hours, websites, and photos are intentionally omitted. It also warns that open_now depends on owner-supplied or official-site hours and that none are recorded yet, which is critical behavioral context for an agent.

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 three focused sentences, front-loads the core filtering purpose, then adds return-content exclusions and the open_now caveat. There is no obvious wasted text, and the structure supports quick scanning.

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 read-only search tool with complete schema coverage and annotations covering safety and idempotency, the description supplies what the schema does not: ranking behavior, field sourcing, excluded fields, URL-based next steps, and the open_now limitation. No output schema exists, but the description sufficiently explains what is and is not returned.

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 schema already has 100% parameter description coverage, so the baseline is 3. The description adds meaningful parameter-related context by warning that open_now has no currently recorded hours, which materially affects how an agent should use that flag. It otherwise mostly restates the filter dimensions already documented in 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?

The description states a specific verb and resource: filtering Andrew's Kensington places by category, sub-zone, tags, featured picks, or text. It also clarifies that detail fields are excluded and should be fetched via each place URL, which helps distinguish it from a detail-fetch tool. However, it does not explicitly differentiate itself from siblings like nearby_places, list_places, or compare_places.

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 through the filtering dimensions and the note to follow each place URL for addresses, hours, and photos, but there is no explicit guidance on when to prefer this tool over sibling tools such as get_place or nearby_places. The open_now caveat is useful but does not establish broader when-to-use or when-not-to-use rules.

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