ThinAir Geo

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, reducing the burden on the description. The description adds useful behavioral context by noting 'structured per-record results,' which indicates the response format for individual addresses, and reiterates the 'Max 50 per batch' limit. It doesn't specify error handling for partial failures, but with annotations covering safety, this is adequate.

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 two concise sentences: the first states the core purpose, the second gives usage guidance and the batch limit. No wasted words, making it efficiently front-loaded and easy to parse.

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 simple batch tool with one parameter, an output schema, and strong annotations, the description is complete. It covers the key operational constraints (bulk usage, max batch size, per-record results) without needing to elaborate on return values, which are presumably documented in the output schema.

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%: the single 'addresses' parameter is fully described as 'Array of addresses to geocode (max 50 per batch).' The tool description repeats this limit and doesn't add any additional semantic detail beyond what the schema already provides, so it meets the baseline for high 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 clearly states the tool's function: 'Geocode multiple addresses in one request with structured per-record results.' It uses a specific verb ('geocode') and resource ('multiple addresses'), and distinguishes itself from the sibling 'geocode' tool by emphasizing batch processing.

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 explicitly directs use: 'Use for bulk operations instead of repeated single geocode calls.' This provides both a when-to-use (bulk) and a when-not-to-use (as a substitute for repeated single calls), clearly differentiating it from the alternative geocode tool.

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?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses meaningful behavioral details: live traffic is post-route enrichment that does not alter the path, truck traffic adjustments are slowdown-only, ETAs are ISO 8601 in the destination timezone, and the response echoes applied dimensions in costing_options.truck. These are non-obvious facts that materially affect how the agent interprets results.

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 dense paragraph, but every sentence carries information essential to safe and correct use. It front-loads the core purpose, then layers important caveats (traffic behavior, presets, geometry formats) without repetition. It is longer than minimal, but the length is justified by the tool's 21-parameter complexity.

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 (21 parameters, 6 enums, output schema), the description is remarkably complete: it covers vehicle profiles, hazmat, tolls, traffic behavior, geometry selection with encoding details, elevation, waypoint limits (via maxItems), and units aliases. The output schema covers return structure, so the description adequately fills the knowledge gap for an agent to call this 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?

Though schema coverage is 100% and all parameters have descriptions, the tool description adds substantial semantic value: it explains that vehicle_profile presets set multiple dimensions in one parameter, gives concrete examples (DRY_VAN_53 = 4.11m tall, 36.3t, etc.), clarifies that individual truck_* parameters override a single field, and details the include_geometry options including auto-downgrade behavior and polyline6 decoding requirement. This goes well beyond the schema's per-field descriptions.

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 'Generate routes, ETAs, and turn-by-turn directions between locations,' which is a specific verb-resource statement that clearly distinguishes it from sibling tools like geocode, distance_matrix, and isochrone. It further differentiates by enumerating supported vehicle types and commercial routing presets.

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 provides explicit guidance for the truck use case ('Use vehicle_profile presets ... when routing trucks') and explains when to set hazmat, toll avoidance, and live traffic enrichment. It does not explicitly state when not to use this tool versus alternatives, but the context is clear enough that an agent can infer its primary role as the route generator.

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, and idempotentHint. The description adds valuable behavioral context: endpoints accept free-text addresses or 'lat,lon' strings, and N×M is capped at 625 pairs. This goes beyond annotations without contradicting them.

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 concise sentences, each earning its place: core function, input constraints, and use cases. No filler or redundancy, and the most important information is front-loaded.

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 a rich output schema and annotations, the description covers purpose, input constraints, and usage contexts. It lacks explicit error-handling details, but the output schema supplied separately fills the return structure gap, making it sufficiently complete for an agent.

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 all parameters (origins, destinations, units, costing) fully documented. The description's mention of address formats and the 625-pair cap adds only marginal value beyond the schema, which already specifies maxItems and parameter formats.

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 exactly what the tool does: 'Compute road distances and travel times for every origin → destination pair.' This specific verb and resource clearly distinguish it from siblings like 'directions' (single route) and 'geocode' (address lookup).

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 use cases: 'fleet dispatch, nearest-depot, and bulk ETA tables.' It does not explicitly name alternatives or state when not to use, so it misses the top bar for explicit exclusions, but the context is unmistakable.

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral context: it mentions population filtering, sorting modes, layer filtering, and even warns that larger radii return 400 INVALID_QUERY. This extra detail about error conditions and customization goes beyond what annotations provide.

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 concise (3 sentences) and front-loaded with the primary purpose. It packs in usage guidance, feature highlights, and an alternative tool without unnecessary filler. Every sentence contributes 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 a tool with 9 parameters, an output schema, and a rich set of features, the description is remarkably complete. It covers the core purpose, when to use it, key capabilities, limitations (radius error), and alternatives. The output schema exists, so return values need not be described. This is a fully self-sufficient description.

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 schema already documents all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description adds functional context by explaining how parameters like population filtering, sorting, and layers work together (e.g., 'cities > 100k' implies min_population). This adds value beyond the schema, hence a 4.

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 identifies the tool as a browsing/discovery search for cities, neighbourhoods, or mixed venues near a location. It distinguishes itself from sibling tools by explicitly stating it is for exploring a region rather than a specific category, and names search_places as the alternative for specific POI categories.

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 provides explicit guidance on when to use this tool ('when the user is exploring a REGION rather than looking for a specific category') and names an alternative tool (search_places) for different use cases. This is clear, actionable 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 openWorldHint. The description adds useful behavioral context beyond these: street-level resolution and proximity biasing. This helps the agent understand capabilities not captured in the annotations. No contradictions.

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 three well-structured sentences: the first states the primary function, the second gives the canonical use case, and the third highlights additional capabilities. No fluff or repetition, every sentence 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?

Given the rich input schema, detailed parameter descriptions, existing annotations, and output schema, the description covers the tool's purpose, usage context, and key behaviors sufficiently. The agent has everything needed to select and invoke the tool correctly without needing additional return-value explanation.

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 provides 100% coverage of all 6 parameters with detailed descriptions, so the baseline is 3. The description adds only a high-level mention of 'proximity biasing' and 'street-level resolution' which loosely map to focus_lat/focus_lon and layers, but does not detail parameter syntax beyond what the schema already provides.

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 converts addresses, place names, streets, or intersections into coordinates and structured location results. It uses a specific verb with a precise resource and output, and implicitly distinguishes itself from siblings like geocode_structured (structured input) and reverse_geocode (coordinates to address).

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 explicitly states when to use the tool: when input is text and coordinates are needed before routing, weather, or search. However, it does not name alternative tools or provide explicit when-not conditions, though 'Use when input is text' implies structured input should go elsewhere.

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, and idempotentHint. The description adds valuable context beyond annotations: 'At least one component is required' and 'No cross-street field' clarifies a functional limitation. It doesn't over-promise or contradict the read-only nature.

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, each earning its place: the first defines what it does, the second gives use cases and benefit, the third states a constraint and alternatives. No redundancy.

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 a rich output schema and detailed per-parameter descriptions, the tool description fully covers purpose, usage context, constraints, and alternatives. It is complete for an AI agent to select and invoke 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%, giving each parameter a clear meaning. The description adds the cross-parameter constraint that at least one component is required, which is not encoded in the schema's required list. However, it mostly restates component names already present in the schema.

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 geocodes from discrete address components rather than a free-text string, and explicitly distinguishes it from the sibling geocode and resolve_intersection tools. The verb 'Geocode' plus resource noun is specific and 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?

Provides explicit when-to-use guidance ('Use when the input is already fielded') and an exclusion ('for named intersections use resolve_intersection or geocode'). This directly helps the agent choose among siblings.

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses boundary point containment ('boundary points count as contained'), return shape ('Returns one boolean per input point'), and an error condition ('Errors when the polygon is structurally invalid'). This adds substantial behavioral context.

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, all information-dense and front-loaded with the primary purpose. Every sentence adds value: purpose, geometry types/purity, boundary behavior, return format, and error condition. No redundancy or fluff.

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 description covers return format ('one boolean per input point'), boundary semantics, accepted geometry variants, and error behavior. Combined with the output schema and annotations, an agent has sufficient context to select and invoke this 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 description coverage is 100% for both parameters, so the baseline is 3. The description does not add meaningful parameter-level detail; it merely restates the polygon types already listed in the schema. No additional semantics about point format or polygon properties are provided.

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 'Test one or more points for containment inside a caller-supplied GeoJSON polygon', which clearly states the specific action and resource. It also enumerates supported geometry types and distinguishes this tool from the geocoding/routing siblings by focusing on pure geometric containment.

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 'Pure geometry' implies this is for geometric queries rather than place lookups, but no explicit 'use this instead of X' guidance is provided. There is no clear statement of when not to use the tool or how it compares to alternatives like reverse_geocode or search_places.

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, and idempotentHint, covering the safety and idempotency profile. The description adds meaningful behavior beyond annotations: multiple bands return nested polygons in a single response, and output is GeoJSON ready for Mapbox/Leaflet. This gives the agent useful operational context without contradicting 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 four sentences, each earning its place: core function, multi-band efficiency tip with example, intended use cases, and output format. It is front-loaded with the primary purpose and contains zero filler or redundancy.

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 presence of helpful annotations, an output schema, and full schema description coverage, the description supplies the essential extra context: clear use cases, multi-band round-trip optimization, and GeoJSON output. There is no need for it to restate parameter details or return value structure already captured elsewhere.

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 each parameter is already documented. The description supplements this with a concrete example (`contours_minutes:[10,20,30]`) and explains the efficiency advantage of multiple bands, which adds semantic value beyond the schema's basic descriptions. It doesn't explain the truck parameters, but the schema covers them adequately.

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 'Generate travel-time or travel-distance reachability polygons from an origin,' which is a specific verb and resource. It clearly distinguishes this tool from siblings like directions or distance_matrix by focusing on reachability polygons, and reinforces with concrete use cases like 'service coverage' and 'territory design.'

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 gives strong context for when to use the tool: 'Use for service coverage, dispatch range, territory design, how far can I get in X minutes questions, and concentric zone visualizations.' It also provides a practical efficiency tip about passing multiple bands in one call. However, it does not explicitly name alternative tools or when not to use it, so it doesn't earn a 5.

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?

The description adds useful context beyond the annotations by noting the key is 'tied to your existing plan' and 'Counts as 1 query against your daily quota.' It also clarifies the authenticated context. This provides auth and rate-limit information not present in the sparse 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?

Three concise sentences, each adding unique value: the action, use cases, and side effects. No fluff or repetition.

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 tool with an output schema, the description is fully complete. It covers purpose, use cases, plan linkage, and quota impact, leaving no ambiguity about what the tool does or when to use 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?

The tool has zero parameters and the schema coverage is 100%, so the baseline is 4. The description doesn't need to explain parameters, and it doesn't attempt to.

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: 'Mint a fresh API key for your current authenticated user/tenant.' This uses a specific verb ('mint') and resource ('API key'), and clearly distinguishes it from sibling tools, which are all geocoding or spatial services.

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 lists use cases: 'CLI workflows, key rotation, or MCP clients that hide the configured Bearer.' While it doesn't name alternatives (none of the siblings are relevant), it gives clear contexts for when this tool is appropriate.

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. The description adds valuable behavioral details: it never guesses when no routable road is near, returns a 'matched:false' flag, and explains that grade_pct is a forward-compatible field that stays null for now, plus elevation may be null with a warning. This goes beyond the annotation hints.

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?

Four sentences, each earning its place: the first states purpose and output fields, the second gives use cases, the third covers parameter behavior, and the fourth explains the no-result case. It is dense yet well-structured, with the most critical information front-loaded.

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 moderately complex (5 params, output schema present). The description covers purpose, use cases, and edge cases, and the output schema handles return structure. It could have mentioned unit auto-detection or costing defaults, but those are already in the schema, so the description is complete enough.

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% (all params already documented). The description adds semantic depth for include_elevation (terrain-sourced) and explicitly states grade_pct is a placeholder, clarifying forward compatibility. This improves on the schema alone.

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 begins with a specific verb ('Snap') and identifies the precise resource (road network) and the rich context returned (name, class, speed limit, etc.). It clearly answers 'what road is this point on and what are its rules?', distinguishing itself from sibling tools like reverse_geocode and map_match by focusing on road rules and single-point snapping.

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 explicitly names usage contexts: 'fleet/telematics snapping, geofence edge checks, or enriching a GPS fix'. It also clarifies the failure behavior ('Returns matched:false... never a guess'), but does not explicitly name alternatives or state when not to use this tool. This is clear context without formal exclusions.

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 behavioral context by explaining the snapping process and what the output contains (matched geometry, distance, time, road names, confidence). It also frames the result as 'the road-accurate route that was actually driven,' which clarifies the nature of the operation beyond the annotations. However, it doesn't address rate limits or authorization nuances, though these are not necessarily expected given the 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 three sentences long, each earning its place: the first defines the core action, the second describes inputs and outputs, and the third gives use cases and a cross-reference to an alternative. It is front-loaded with the main purpose and contains no fluff or redundant details.

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 (4 parameters, output schema, annotations), the description is remarkably complete. It covers purpose, use cases, an explicit alternative, input constraints (2–100 points), and a summary of outputs. The output schema details the full return structure, and annotations cover safety and semantics, so the description does not need to repeat those. It also implicitly differentiates from other trace-related siblings like 'trace_attributes' by focusing on map matching to a road network, though it doesn't mention that tool by name – still acceptable because the explicit 'directions' alternative is the most likely confusion point.

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 description restates the shape constraint ('2–100 points') but does not add additional meaning for 'costing', 'search_radius', or 'vehicle_profile' beyond what the schema already provides. It also doesn't explain parameter interactions (e.g., vehicle_profile implying costing=truck) that are in the schema. Thus, the description adds marginal value over the schema.

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 'Map matching snaps raw GPS breadcrumbs to the road network' with a specific verb and resource. It also distinguishes itself from the sibling 'directions' tool by explicitly noting that for route planning, one should use 'directions' instead. This makes the purpose unambiguous and well-differentiated.

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 use cases: 'Use for fleet trace cleanup, mileage from GPS logs, and reconstructing routes from telemetry.' It also gives a clear exclusion: 'For planning a route between places, use `directions` instead.' This directly tells the agent when to pick this tool over an alternative, fulfilling the highest bar for usage 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 and idempotentHint, lowering the burden. The description adds meaningful behavior: ids survive re-serves (idempotency), return value contents, and error handling for unknown/expired ids with re-search guidance. This goes well beyond the annotations and gives the agent a clear model of what happens.

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 three sentences, each contributing unique information: purpose, id source/stability, and return/error behavior. It is front-loaded with the core action and avoids redundancy with 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?

For a simple single-parameter lookup tool with an output schema and rich annotations, the description is complete. It covers purpose, id provenance, stability, return content, and error behavior. No significant gaps remain.

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 schema already provides full parameter coverage (100%) including the id format and constraints. The description adds value by naming the exact source tools (geocode, reverse_geocode, search_places, resolve_intersection) and highlighting id stability and determinism, which are not in the schema. This enriches the semantics beyond the schema.

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 clear verb ('Look up') with a specific resource ('place by its stable ThinAir id') and identifies the id format (ta_place_… / ta_intersection_…). It also names the sibling tools that produce these ids, which distinguishes this lookup tool from geocoding and 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 description provides clear context for when to use this tool: when you have an id from geocode, reverse_geocode, search_places, or resolve_intersection, and want canonical data. It emphasizes the ids are deterministic and safe to store, implying reuse over repeated lookups. It doesn't explicitly state when not to use alternatives, but the context is strong enough.

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?

Beyond the readOnlyHint annotation, the description reveals a critical behavioral trait: the call never counts against quota and is never blocked by it. This is valuable context not present in annotations and directly influences the agent's willingness to call the tool.

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 two sentences, front-loaded with the core purpose, then a high-value clarifying detail about quota impact. Every word earns its place with no redundancy.

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 simple, parameterless tool, the description fully covers what it returns (usage, limits, plan, breakdown) and when to call it. The output schema exists to detail return structure, so the description is complete.

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, so no parameter descriptions are needed. The schema already fully covers this aspect (100% coverage with no properties), meeting the baseline for no-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?

The description clearly states the tool's function: 'Check current usage, remaining limits, plan, and quota breakdown for the caller.' It uses a specific verb ('Check') and precise resource identifiers, distinguishing it from sibling tools like issue_api_key or geocoding services.

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: 'Use this proactively when the user asks about usage or seems near limits.' Also adds that it is 'FREE TO CALL — never counts against your quota, never blocked by it,' reinforcing why it should be used without hesitation.

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 read-only and idempotent hints, so the bar is lower. The description adds useful behavioral details: confidence score, fleet-safe fallback, and tiered matching for US-metro highways versus geocoder fallback for non-highway streets.

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?

Two sentences, front-loaded with purpose, no fluff. Every clause adds value, including the fallback behavior and sibling differentiation.

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 annotations and output schema presence, the description adequately covers the tool's purpose, behavioral nuances, and alternative use cases. It could mention the return format in more detail, but output schema likely covers that.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds minimal extra meaning, reinforcing that inputs are street names scoped by locality/region/country, but does not materially enhance understanding beyond the schema.

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 resolves a NAMED cross-street to a coordinate with confidence score and fleet-safe fallback. It distinguishes from the geocode sibling by explicitly saying 'For free-form streets use geocode.'

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: use for named cross-streets, use geocode for free-form streets. Also describes internal fallback behavior, giving context on tool selection.

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 communicate read-only and idempotent behavior, so the description doesn't need to repeat those. The description adds behavioral detail by specifying the output types (address, street, place) and the 'nearest' qualifying behavior, which goes beyond the tool name and 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 two sentences long, with the primary purpose stated first and usage guidance in the second sentence. Every word earns its place; there is no redundancy or filler.

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 presence of a complete input schema, output schema, and annotations (readOnlyHint, idempotentHint), the description covers the essential context. It does not need to explain return values or parameter details since the schema and annotations already do so, and the description is adequate for tool selection.

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 all four parameters (lat, lon, size, layers) already clearly described in the schema. The tool description adds no additional parameter meaning beyond the schema, so the baseline score 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 uses a specific verb ('Convert coordinates into') and identifies the resource ('nearest address, street, or place'), which clearly defines the tool's function. It distinguishes itself from the sibling 'geocode' by emphasizing the reverse direction (starting from coordinates), making the purpose 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 explicitly says 'Use when starting from GPS coordinates or a map position,' providing clear context for when the tool is appropriate. It does not mention alternatives or exclusions, but the guidance is sufficient for this simple reverse-geocoding tool.

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 read-only, idempotent, and open-world behavior. The description adds the categorical and proximity-based nature of the search, and how it differs from `explore`, which is useful context beyond the annotations without contradicting them.

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?

Two sentences, front-loaded with the core purpose and examples. The second sentence provides sharp usage guidance and an explicit alternative. There is zero redundancy or fluff.

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 an output schema, detailed input schema, and annotations, the description covers the essential context. It explicitly distinguishes from the most similar sibling (`explore`) and provides category examples, making it sufficiently complete for an agent to select and invoke the 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 description coverage is 100%, with detailed parameter descriptions and defaults. The description adds practical query examples but doesn't introduce new parameter semantics beyond what the schema provides, so 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 'CATEGORY-specific POI search near a point', which clearly identifies the tool's action, resource, and scope. Concrete examples like 'gas stations, truck stops, restaurants' and the explicit contrast with `explore` distinguish it from sibling 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?

It provides explicit when-to-use guidance: 'Use this when the user has a specific TYPE of place in mind' and for broader discovery, 'use `explore` instead.' This clearly names the alternative and sets a crisp boundary, which is ideal for agent selection.

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. The description adds behavioral context by revealing the matcher confidence score and the segment-level output, and the audit use case. No contradictions.

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, each earning its place: function, output/use case, and sibling alternative. Front-loaded with the main verb and resource, no filler.

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 a strong output schema and detailed parameter schema, the description covers purpose, use case, and alternatives. It is complete for a read-only trace-analysis tool with good annotations.

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 baseline is 3. The description doesn't add parameter-specific meaning beyond what the schema already provides; it only summarizes the input (GPS breadcrumb) and output. No new semantics over the schema.

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 it 'return road/network attributes for matched traces' and lists the concrete attributes (road names, classes, speed limits, etc.). Explicitly distinguishes from sibling `map_match` by saying 'For just the matched route line, use `map_match`'.

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 clear when-to-use context: 'Use to audit what roads a vehicle actually used (speed-limit compliance, truck-route adherence, surface checks)'. Also explicitly names the alternative `map_match` for route-line-only needs.

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?

The description goes well beyond annotations by disclosing coverage limitations (~30 major US metros), degraded/empty values outside those areas, and instructing to qualify responses for rural locations. This adds significant behavioral context that annotations (readOnlyHint, openWorldHint, idempotentHint) do not cover.

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 three sentences, each serving a distinct purpose: core function, usage context, and coverage caveat. It is front-loaded and concise, with no filler.

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 simple location-based tool, the description covers the essential caveat (coverage limitation) and usage context. An output schema exists, so return values are already specified, and annotations provide safety hints. The description is complete enough for an agent to select and invoke 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 parameters are already well-documented (lat/lon, units with auto-detection and aliases). The description adds no meaningful parameter information beyond the schema, so 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 clearly states the tool retrieves live traffic conditions, congestion, and speed for a location, with a specific verb and resource. It distinguishes this tool from siblings by noting 'independently of routing', which separates it from directions and routing-focused 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?

Explicitly states when to use the tool ('when traffic is needed independently of routing') and provides use cases (corridor monitoring, area congestion, incident checks). It also includes guidance for handling rural coordinates, which shows thoughtful usage instructions beyond alternatives.

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, so the tool is known to be safe. The description adds feature context (alerts, minutely precipitation) but does not disclose behaviors like geocoding of location strings or how conflicts between lat/lon and location are resolved. This is acceptable but not rich.

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 two sentences, front-loaded with the primary action, then relevant use cases. Every word earns its place with no redundancy or filler.

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 8 parameters and presence of an output schema, the description covers the tool's purpose and use cases well. It lacks a note about how the tool geocodes location or how lat/lon vs. location interact, but this is not critical given the schema and typical usage.

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 no parameter-specific information beyond what the schema already provides. It correctly implies location and forecast related parameters but does not elaborate on their semantics.

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 ('Get') and resource ('current and forecast weather') and highlights distinguishing features (severe weather alerts, minute-by-minute precipitation). It clearly sets the tool apart from sibling tools like geocoding and directions.

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 use cases are provided ('destination conditions, travel planning, or route risk assessment'). However, it does not mention when not to use the tool or suggest specific alternative tools, so it falls short of a full 5.

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