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

With no annotations, the description carries the full burden and delivers unusual depth: session durability when map_push_status=viewer_not_connected, status=already_on_map validated against the live render payload, status=refreshed with a map_refresh block and render_ack check, blocked_by=needs_route, non-destructive compose with a later ingest_accounts, and dual in-chat/map_url surfaces under the same session id.

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 structure is sensible — When, Prerequisites, dispatch behavior, then scenario tags — and the routing constraints are front-loaded. But it is a dense wall of near-run-on sentences with a lot of trailing edge-case detail (SSE paint, merge strategy, route recovery notes) that could be tightened considerably without losing meaning.

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 an 11-parameter, zero-required dispatch tool with no annotations, this is close to complete: prerequisites, dispatch rules, return fields (overlay_kind, overlay_id, viewer_hint, visibility block), failure/blocked states, and the dual-surface behavior are all covered. An output schema exists, so return-value explanation is bonus rather than obligation.

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 0% across 11 parameters, so prose must compensate. It does explain ts_handle, inline ts, map_session_id (including why it is preferred for points), user_request, overlay_kind (enumerating part_layer/point_layer/tal/route), overlay_id, and route_id semantics. However merge_strategy, guidance_handle, expected_revision, and expected_content_hash are never mentioned, leaving roughly a third of the surface undocumented in both schema and description.

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 opens with a Tier-scoped statement of exactly what the tool does: resolve the four MC overlay families (part_layer, point_layer, tal, route) and dispatch to the correct underlying step. It differentiates from siblings by name — 'Prefer this over raw configure_map', 'use delete_route', 'calculate_route already draws its own result' — so an agent can route without opening any 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?

Explicit When clause with literal user phrasings, prerequisites (ts_handle from get_map_visualization, connected viewer), and conditions for calling configure_map first ('when the user already named a center and zoom') versus skipping it ('Skip that call when no center was named, and do not invent one'). It also states when NOT to use it for route deletion and route editing, naming the correct alternatives.

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