沿途搜索

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds real behavioral context: results are deduplicated and sorted by distance from the origin, the corridor is sampled along the polyline, and the Key must be configured first. It does not warn about sampling-induced coverage gaps, rate limits, or cost, which keeps it below a 5.

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?

Purpose is front-loaded, then parameters, then implementation, then the Key prerequisite — a sensible order. The '实现方式' sentence about /v3/direction/driving and /v3/place/around sampling is longer than strictly required for invocation, but it does build justified trust in result quality.

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?

With no output schema, the description still states the return shape (a list of target POIs sorted by distance from the origin) and covers the three required and three optional parameters. It omits expectations around sparse results or how many sample points are used, which is a modest remaining gap for a 6-parameter tool.

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 already 100%, so the baseline is 3. The description nevertheless adds meaning beyond the schema: distance is defined as a corridor that extends distance meters to each side of the route centerline (with a worked example), and it clarifies that origin/destination accept either address text or 'lng,lat'.

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 first sentence gives a specific verb (搜索), resource (目标 POI) and scope (沿驾车路线), plus the return ordering. The route-corridor scope inherently separates it from the point-based search_nearby sibling, but the description never names that sibling, so the differentiation is implicit rather than explicit.

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 supplies concrete selection context (target keyword examples such as 加油站/服务区/充电站) and an explicit operational prerequisite — '需要先配置高德 Key，未配置时调用 set_amap_key 即可' — which routes the agent to a sibling when setup is missing. It never states when NOT to use it or when to prefer search_nearby, so it stops short of full when/when-not coverage.

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