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

With no annotations, the description carries the full burden and does so well: it discloses ordering, start-point fallback behavior, null map points, source attribution, locked stops, unassigned visits, and role-based visibility. These details go well beyond field names and give an agent the behavioral context needed to interpret the result correctly.

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 dense but front-loaded around the core resource, and nearly every clause adds useful information about returned fields, visibility, or workflow. The first sentence is long and heavily packed, which costs some readability, but there is little wasted text.

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?

The tool has an output schema, so the description need not explain return values, yet it still adds useful interpretation about map points, locking, unassigned visits, and visibility. It leaves some parameter context to the schema, but otherwise gives enough context for an agent to call and interpret this read tool 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 67%: date and person_ids are documented in the schema, while shop_id lacks a description. The description adds no parameter-level meaning beyond implying a one-day, per-worker scope, so the schema does most of the work and the description fails to compensate for the remaining gap.

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 names a specific resource and scope: one day's stops, per worker, in visit-time order, including start points and stop fields. It also distinguishes itself from sibling write/location tools by pointing to routes.setLocation and routes.apply, so an agent can tell what this tool does without opening the schema.

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 frames the tool for route planning and gives a clear workflow: fetch the day here, plan with your own tools, then write back with routes.apply. It also explains that map points are null until saved via routes.setLocation, steering the agent to the right sibling for that step. It does not explicitly list when not to use it or compare against schedule_route, but the intended context is clear.

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