Search Wanderlog travel guides

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

With no annotations supplied, the description carries the whole burden and does substantial work: it discloses the free-text resolution policy (highest-popularity match wins), the soft-hint escape hatch via 'alternative_geos' (up to 2), and the empty-result fallback that returns the top 5 nearby destinations with guides. That is exactly the kind of surprising behavior an agent needs warning about. It stops short of stating a result limit or pagination for the guide list itself, so it is not fully complete.

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-loaded with the purpose, then inputs, then the next-step handoff — a sensible order with no filler sentences. It loses a little economy by restating the geoAutocomplete and alternative_geos mechanics that the schema parameter descriptions already spell out verbatim.

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?

No output schema exists, so the description must name the response surface, and it does: guide_key, alternative_geos, and alternative_geos_with_guides, plus what response_format changes in the payload indirectly through the schema. For a three-parameter read tool this covers what an agent needs to call it and interpret the result.

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 geo_id, destination, and response_format in detail, and paragraph two largely repeats the resolution and alternative_geos behavior already present in the destination parameter. The genuinely additive piece is the mutual-exclusivity constraint ('exactly one of destination or geo_id'), which the schema does not encode via oneOf, plus the downstream use of the returned guide_key.

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?

Opens with a specific verb and resource: 'Lists user-written Wanderlog travel guides for a destination,' and qualifies the content as 'long-form recommendations and itineraries other travellers have published.' It also implicitly separates itself from wanderlog_get_guide by routing full-content reads there, so an agent can pick between the two on purpose alone.

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 states when to reach for it ('user asks for inspiration, an itinerary they can copy, or what guides exist for X') and names the follow-on tool: 'Pass the returned guide_key to wanderlog_get_guide.' It also gives a hard input rule, 'Specify exactly one of destination or geo_id,' which is real selection guidance rather than a restatement of the name.

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