TomTom Dynamic Map

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the detail parameter's 1MB response limit and JPEG/downscaling behavior, the show_ui parameter's interactive viz_id capability, and auto-calculation of dimensions. Minor gap: no explicit statement about the response format/return value, though the description covers most operational behavior.

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 main description is efficiently written with purpose front-loaded before exclusions. It avoids redundancy with the schema. However, the overall tool definition is lengthy due to the schema, and the description could be slightly trimmed — the routePlans guidance is repeated in both the description and the parameter schema. Still, it earns a 4 for being well-organized and purposeful.

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 tool with 13 parameters, 0 required, and complex nested objects, the description covers the key operational concerns: auto-calculation behavior, the detail/response-size tradeoff, the show_ui interaction, and the routes vs routePlans distinction. No output schema exists, but the description addresses return behavior through the detail parameter. The main omission is not describing the output image format explicitly, though the detail parameter implies it.

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 100%, so the baseline is 3. The description adds real value with concrete examples (Amsterdam coordinates, hex color codes, priority semantics) and clarifies nuanced distinctions like the routes vs routePlans difference (straight lines vs road-following). However, much of the value is also present in the schema descriptions, so the description doesn't dramatically exceed the baseline.

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?

States a specific verb (Render) and resource (custom map image) with concrete elements: markers, drawn lines, polygons, and area overlays. Explicitly distinguishes from siblings (tomtom-routing, tomtom-traffic) by naming what it is NOT for, which is rare and highly valuable for agent selection.

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?

Provides explicit when-to-use guidance ('Intended for map visualization') and when-not-to ('Not intended for route calculations (tomtom-routing) or traffic incidents (tomtom-traffic)'). Also clarifies the edge case of routePlans — when it should be used vs. when to prefer tomtom-routing for standalone queries. This is exemplary routing guidance.

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