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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as result format, pagination, or error behavior. It simply restates the purpose without enhancing transparency beyond the annotations.

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 a single, clear sentence that front-loads the core purpose. It contains no fluff or redundant information, making it highly concise and well-structured.

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 32 parameters and no output schema, the one-line description is minimal but sufficient to convey the basic purpose. It doesn't explain return values, but the extensive schema and annotations cover parameters and safety. It could be more complete by noting the output type, but it's adequate for basic understanding.

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%, with every parameter having a detailed description including examples and constraints. The tool description itself contributes no parameter-specific meaning, but the baseline for high schema coverage is 3, which is appropriate.

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 clearly states a specific verb ('search') with resource types (addresses, POIs, geographies) and highlights the typo-tolerant aspect, which differentiates it from siblings like geocode and poi-search. However, it doesn't explicitly name alternative tools, so it's not a perfect 5.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention that this should be used for free-form, typo-prone queries or that other tools might be more appropriate for exact matches. The schema offers examples, but the description itself lacks usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one useful behavioral constraint—no POI support—but says nothing about result ambiguity, coordinate format, or response 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 description is a single focused sentence that front-loads the core purpose and includes a meaningful limitation. Every word earns its place, and there is no redundant restating of the tool name or title.

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?

Given the rich 100%-covered schema and clear annotations, the description is mostly complete for safe invocation. The main gap is the lack of explicit routing to sibling tools for POI or fuzzy cases, but the core operation and constraints are sufficiently clear.

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 all 17 parameters with examples and constraints. The tool description adds no parameter-level meaning beyond what the schema provides, matching the baseline for full schema coverage.

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 uses a specific verb and resource: 'Convert street addresses to coordinates'. It also adds a distinguishing scope constraint, 'does not support points of interest', which separates it from POI-oriented sibling tools like tomtom-poi-search and tomtom-fuzzy-search.

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 implies the tool is for address-to-coordinate conversion and explicitly excludes POI lookups. However, it does not name alternatives or give explicit guidance on when to choose this over tomtom-reverse-geocode or tomtom-fuzzy-search.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description's 'retrieve' is consistent with those. It adds the 'internal' access context but does not disclose operational details such as authentication requirements or secret-handling expectations.

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?

One concise sentence names the caller, action, and resource with no filler, repetition, or unnecessary detail.

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 zero-parameter, read-only, idempotent internal lookup, the description covers the essential context. It is slightly incomplete because there is no output schema and no mention of failure behavior if the key is missing or how the key should be handled in responses.

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?

The tool has zero parameters and 100% schema description coverage, so there is no parameter burden for the description to carry. The baseline 4 applies because no parameter ambiguity exists.

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 verb ('retrieve'), a specific resource ('TomTom API key'), and an intended caller ('apps'). It is clearly distinguishable from sibling tools like tomtom-get-app-config and tomtom-get-viz-data.

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 phrase 'Internal tool for apps' provides clear context that this is a back-end credential lookup for applications rather than a general-purpose utility. It does not explicitly name alternatives, but no sibling tool appears to serve this same key-retrieval role.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, lowering the burden. The description adds useful context by labeling the tool 'internal' and giving an example of returned content, going slightly beyond the structured annotations. No contradiction with annotations.

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 a single sentence that is front-loaded with the action and resource and includes a concrete example. No filler, redundancy, or unnecessary detail.

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 and no parameters, the description must carry the burden of indicating what the tool returns. The example ('attribution user-agent') hints at the output payload, and while the full set of config fields isn't enumerated, it is adequate for a simple no-arg config getter.

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?

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The description correctly focuses on purpose rather than parameters, meeting the baseline for zero-parameter tools.

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?

Description states a specific verb ('retrieve') and resource ('client configuration') with a concrete example ('attribution user-agent'). It is clearly distinct from geocoding/routing/map siblings, but it does not explicitly differentiate from other internal config tools like get-api-key or get-viz-data.

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 implies usage for apps needing client configuration, but provides no explicit when/when-not guidance or alternatives. The 'Internal tool for apps' context is present, yet no exclusions or sibling comparisons are offered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds the behavioral nuance that the data is 'cached', which indicates the tool does not perform fresh computations and may return stale data. This is valuable context beyond the annotations.

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 a single, front-loaded sentence that wastes no words. It conveys the tool's purpose, audience, and required input in under 15 words. Perfectly sized for a simple tool with one parameter.

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 is simple (one required parameter, no output schema, no nested objects) and the description, combined with annotations and schema, covers the essentials. The only omission is an explicit description of the return format, but given it is a retrieval tool, the agent can reasonably infer the response contains the visualization data. This is acceptable for an internal 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?

The input schema already provides a clear description for the sole parameter (viz_id: 'Unique visualization ID from the tool response _meta'), giving 100% coverage. The tool description adds no additional parameter-specific information, so it neither enhances nor detracts from the schema. Baseline of 3 is appropriate.

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 clearly states the verb (retrieve), the resource (cached visualization data), and the key identifier (viz_id). It explicitly marks the tool as internal, and none of the sibling tools overlap in function (geocoding, routing, etc.), so it is unambiguous.

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 provides clear context that this tool is for internal apps and for retrieving cached visualization data. While it doesn't explicitly state when not to use it, the absence of any sibling with similar functionality makes the usage scope self-evident. It also implies it should be used only when a viz_id is available from a prior tool response.

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

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. However, the description adds no behavioral context beyond what annotations and schema provide, such as default radius, response format, or typical usage patterns. It offers no additional disclosure about behavior like pagination, filtering, or data scope, so it adds little value given the existing structured metadata.

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 extremely concise—a single sentence—but it is under-specified rather than optimally concise. It does not front-load key information like the fact that it requires lat/lon, uses a radius, or returns POIs. For a tool with 31 parameters, a one-line generic tagline is not adequate structure; it fails to guide the agent toward understanding the tool's purpose without diving deep into the schema.

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?

Given the tool's complexity (31 parameters, 2 required) and the rich schema, the description is far from complete. It does not explain the core use case (finding POIs near a coordinate), how it relates to sibling search tools, or any typical scenarios. The schema is thorough but the description adds no overview or relational context, leaving an agent to puzzle out the tool's role without a high-level map.

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 31 parameters are all individually documented. The tool description does not supplement parameter understanding at all, but since the baseline for high schema coverage is 3, this score is appropriate. The description's single sentence does not clarify any parameter relationships or defaults, but that is not its responsibility given the schema richness.

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 'Discover services within a radius' conveys a nearby search concept, but it is too generic and does not specify that it operates on a center coordinate and radius, nor does it differentiate from sibling tools like tomtom-poi-search or tomtom-fuzzy-search. The verb 'discover' and resource 'services' are present, but the lack of specificity about the exact resource type (e.g., POIs, charging stations) and the lack of comparison to alternatives make it only minimally clear.

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 provides no guidance on when to use this tool versus alternatives. It does not mention that it is appropriate when coordinates are known and the user wants nearby results, nor does it explicitly contrast with tomtom-geocode, tomtom-poi-search, or tomtom-fuzzy-search. An agent would have to infer usage solely from the schema, which lacks contextual routing advice.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already disclose the safety profile. The description adds no extra context about response format, pagination, rate limits, or the nature of the search. It is not contradictory, but it contributes nothing beyond the annotations.

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 a single vague sentence. While concise, it is under-specified and does not earn its place because it conveys almost no actionable information. It is not structured to front-load critical details, as it lacks any.

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 34 parameters, many optional, and no output schema, this description is grossly inadequate. It fails to explain what the tool searches, what inputs are essential (e.g., query or location), or how it differs from similar tools. An agent would struggle to call this tool correctly based on the description alone.

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% with rich parameter descriptions. The description itself adds no parameter-level insight, but the baseline of 3 applies when the schema carries the full burden. No improvement or degradation is warranted.

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 'Find specific business categories' is vague and does not specify the resource (POIs) or the scope of the search. It fails to differentiate from siblings like tomtom-fuzzy-search or tomtom-nearby, which also search for places. It is not a tautology but lacks the specificity needed to understand what the tool actually does.

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 provides no guidance on when to use this tool versus alternatives such as fuzzy search or nearby. It does not mention prerequisites, typical use cases, or exclusions. An agent must infer usage from the name and parameter schema alone, which is insufficient.

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

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

Annotations are rich (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description 'determine the area reachable' is consistent with a read-only operation and doesn't contradict the annotations. However, it adds essentially no behavioral context beyond what the annotations already declare — no mention of response format, boundaries, or calculation characteristics.

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?

A single, front-loaded sentence with no wasted words — efficient and to the point. It's appropriately terse for a tool whose schema carries all the parameter documentation, though it could arguably add one clause about scope without becoming verbose.

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?

Given the tool's complexity (41 parameters, no output schema), the one-sentence description is minimal. The schema compensates well by documenting every parameter including budget exclusivity and required companions. However, the description doesn't mention that origin is required or that exactly one budget parameter must be supplied — important usage constraints an agent would benefit from knowing up front.

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% and the schema itself documents all 41 parameters thoroughly, including critical constraints like 'Use ONLY ONE budget parameter — do not combine with other budget types' and 'REQUIRED companions' for energy/fuel budgets. With full schema coverage, baseline 3 applies and the description correctly adds no redundant param info.

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 'Determine the area reachable within a specified time or driving distance' states a specific verb (determine) and resource (area reachable), clearly conveying the isochrone/reachability concept. However, it doesn't differentiate itself from routing siblings like tomtom-routing or tomtom-waypoint-routing, which could also involve travel time/distance — so it's clear but not distinct.

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?

No guidance on when to use this tool versus alternatives. It never mentions that this is for area-based reachability (isochrones) rather than point-to-point routing, nor names any sibling as an alternative. The 'specified time or driving distance' phrasing could even confuse an agent into choosing this over tomtom-routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context, but it also does not contradict the annotations.

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 extremely concise and front-loaded with the main action. There is no redundant wording, though for a tool with 25 parameters a bit more orienting context could still be useful.

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 core input (coordinates) and output (addresses) are established, which supports a basic successful invocation. However, with no output schema and 25 optional parameters, the description lacks guidance on defaults, result shape, and optional response controls.

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% across all 25 parameters, so the schema already provides detailed parameter semantics. The description adds no parameter-specific meaning beyond the generic phrase 'coordinates'.

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 transformation—'Convert coordinates to addresses'—so the tool's purpose is unambiguous. The direction (coordinates → addresses) clearly distinguishes it from sibling tomtom-geocode and other search tools.

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 usage context is implied: use this when you have latitude/longitude and want an address. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it returns turn-by-turn directions, distance, travel time, and a map image, which matters because there is no output schema. This is meaningful but not exhaustive given the tool's large parameter space.

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 compact and front-loaded, starting with the core purpose, then use cases and return values, and ending with sibling routing. Every sentence earns its place, and the examples make intent concrete. It is not maximally lean due to some redundancy between 'primary tool for directions/routes' and 'calculate optimal routes,' but it is efficient overall.

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 highly complex 50-parameter tool with no output schema, the description covers the essential selection criteria: what the tool does, what it returns, and when to route to siblings. It does not explicitly instruct the agent to geocode place names into lat/lon coordinates first, though the schema does say this. Overall the description is complete enough for an agent to invoke it correctly for basic and moderate routing requests.

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 baseline is 3; the schema documents all 50 parameters in detail. The description adds little parameter-level meaning, only examples like 'route from Amsterdam to Berlin' that imply place-name inputs even though origin and destination are coordinate objects. It neither contradicts the schema nor substantially enriches it beyond 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?

The description states a specific verb and resource: 'Calculate optimal routes between two locations,' and frames it as 'the primary tool for directions, routes, travel time, or distance between places.' It clearly distinguishes itself from tomtom-waypoint-routing and tomtom-dynamic-map, so an agent can separate it from siblings without opening schemas.

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 names alternative tools and the conditions for using them: 'Multi-stop routes with 3+ waypoints are handled by tomtom-waypoint-routing' and 'visualizing multiple routes or combining routes with markers/polygons on a single map image is handled by tomtom-dynamic-map.' This gives clear when-to-use and when-not-to-use guidance.

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

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 clear. The description adds that it generates images but doesn't disclose details like rate limits, image size limits beyond schema, or behavior when both bbox and center are provided. It doesn't contradict annotations.

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 a single concise sentence that front-loads the core purpose. It's efficient and doesn't waste words, though it could benefit from a brief usage note.

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 10 parameters and no output schema, the description is adequate but not complete. The schema covers parameters well, but the description doesn't explain return values (image format details), potential conflicts between bbox and center, or when to prefer this over tomtom-dynamic-map. The annotations cover safety, but behavioral context is thin.

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 all parameters thoroughly. The description adds a general overview but doesn't provide additional meaning beyond what the schema already covers. Baseline 3 is appropriate since the schema does the heavy lifting.

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 clearly states the tool's function: generating custom map images from TomTom Maps with center coordinates, zoom levels, and style options. It distinguishes it from sibling tools like geocoding or routing, though it doesn't explicitly differentiate from the closely related tomtom-dynamic-map sibling.

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 implies usage for generating static map images but provides no explicit guidance on when to choose this tool over tomtom-dynamic-map or other alternatives. The parameter descriptions offer some context (e.g., using geocoding results for center), but there's no direct when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond that: it specifies the return content ('severity, description, delay, and affected roads') and asserts self-sufficiency ('Provides complete traffic incident data on its own'), which informs the agent about output expectations without contradicting any annotation.

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 four sentences, each earning its place: purpose, usage context, return data, and an explicit exclusion. It is front-loaded with the primary function and avoids redundancy, making it efficient and scannable for an agent.

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 compensates by naming key return fields (severity, description, delay, affected roads). It also clarifies that the tool returns complete data on its own, eliminating the need for a mapping tool. All six parameters are fully documented in the schema, and annotations cover safety, so nothing an agent needs to call it correctly is missing.

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% with detailed per-parameter explanations (e.g., bbox example, maxResults bounds and default, categoryFilter enumeration). The description itself adds no parameter-specific meaning, but since the schema already carries the full burden, the baseline score of 3 applies.

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 specific verb-resource pair: 'Find and display traffic incidents in an area.' It further differentiates itself as 'The primary tool for questions about traffic, accidents, road closures, congestion, or dangerous road conditions' and explicitly states that plotting with tomtom-dynamic-map is not needed, making its scope and identity unmistakable.

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 provides explicit when-to-use guidance: it is the primary tool for all traffic-related queries, enumerating example scenarios. It also gives a clear when-not-to-use instruction by stating that tomtom-dynamic-map is not needed for plotting, effectively naming the alternative and the condition that excludes it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it 'returns optimized turn-by-turn directions, total distance, and travel time,' which is useful. However, there is a minor inconsistency: the description says '3 or more waypoints' while the schema allows minItems=2, which could mislead an agent. No contradiction with annotations, but the added behavioral context is modest.

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?

Three sentences with no filler. The primary use case and the key differentiator are front-loaded, and the alternative is named concisely. Every word earns its place.

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 complex tool with 49 parameters, the description adequately covers the core use case and return fields, while the schema handles parameter specifics. It does not mention ordered waypoints or the computeBestOrder option, but those are in the schema. Given annotations and rich schema, nothing critical is missing for an agent to call it 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 description coverage is 100%, so the schema already documents all 49 parameters in detail. The description only mentions 'waypoints' generically and does not add syntax, ordering, or constraint nuances beyond what the schema provides. Baseline 3 is appropriate since schema does the heavy lifting.

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 states a specific verb and resource: 'Plan multi-stop routes through 3 or more waypoints.' It clearly distinguishes itself from the sibling 'tomtom-routing' by specifying the multi-stop scenario, so an agent can tell them apart 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?

It explicitly says 'Use when the user needs to visit multiple locations in sequence' and directs to 'tomtom-routing' for simple A-to-B routes. This gives clear when-to-use and when-not-to-use guidance, naming the alternative tool.

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