Google Maps

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

The description discloses important behavioral requirements: both origin and destination are required, and each must be specified via address, lat_lng, or place_id. It also notes that the output must be attributed using the 'attribution' field. These go beyond the readOnlyHint annotation, which already indicates the operation is safe. It does not contradict 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 well-structured with clear sections (purpose, input requirements, example, attribution note). It is somewhat repetitive when stating that origin and destination are required, but the example and formatting aid understanding. It is not excessively long, and the critical 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?

For a tool with nested waypoint objects, an enum parameter, and an output schema, the description covers the essential usage details: input methods, combination rules, and an example. It lacks explicit mention of the response structure, but an output schema exists to fill that gap. The naming inconsistency is a notable gap that affects completeness.

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 detailed descriptions for all parameters (100% coverage), so the baseline is 3. The description adds useful semantics like the flexibility to mix input types and the note about address specificity. However, it introduces potential confusion by using snake_case names ('lat_lng', 'place_id', 'travel_mode') in the example, while the schema uses camelCase ('latLng', 'placeId', 'travelMode'). This inconsistency could lead to incorrect tool invocation.

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: 'Computes a travel route between a specified origin and destination.' It provides a specific verb and resource, and distinguishes itself from sibling tools (e.g., search_places, resolve_names) by focusing on route computation. It also lists supported travel modes, further clarifying its scope.

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 on when to use the tool (when a route is needed) and includes explicit instructions to ask for user clarification if origin or destination is missing. It references search_places for obtaining place IDs, which helps with workflow. However, it does not explicitly state when not to use this tool or name alternative tools for other cases.

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?

While annotations already indicate readOnlyHint=true and destructiveHint=false, the description adds crucial behavioral constraints beyond those: timezone handling ('relative to the location's local time zone'), forecast limits ('Hourly forecast beyond 120 hours... not supported', 'Daily forecast beyond 10 days... not supported'), and the requirement to attribute output using the attribution field. These details meaningfully enrich the agent's understanding of edge cases and limitations.

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 long but well-structured with bold headers, bullets, and code examples. Every section addresses a distinct aspect (data available, location rules, usage modes, constraints) without redundancy. The core purpose is front-loaded in the first sentence, and the formatting makes complex information easily scannable.

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 (multiple modes, three location types, timezone handling) and the presence of an output schema, the description covers all essential contextual aspects: available data, location selection rules, usage mode conditions, forecast limits, and attribution. It addresses practical edge cases like rounding minutes down to the nearest hour and clarifying today's date when absent, making the tool complete for an agent to 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?

Even though schema documentation covers all 4 parameters, the description adds significant semantic value: it explains the 'oneof' requirement for location sub-fields with concrete JSON examples, specifies address formatting rules (city with region, full street address, postal code requiring country), and clarifies unit defaulting ('Defaults to METRIC. Set units_system to IMPERIAL...'). This goes far beyond the schema's field-level definitions.

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 'Retrieves comprehensive weather data including current conditions, hourly, and daily forecasts,' which clearly states a specific action (retrieves) and resource (weather data), and explicitly distinguishes the three forecast modes. This differentiates lookup_weather from sibling tools like compute_routes and search_places, which address different domains.

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 highly explicit guidance on when to use each mode: 'Current Weather: Provide location only. Do not specify date and hour.' 'Hourly Forecast: Provide location, date, and hour...' It also gives decision rules for ambiguous terms ('next few hours', 'later today'), and instructs to clarify when today's date is not in context. This exceeds simple context by providing precise usage criteria for each scenario.

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 destructiveHint=false. The description adds substantial behavioral detail: batch processing can yield mixed results, entities map 1:1 to input indices, failed URLs produce empty Entity messages, and the failed_requests map must be checked for specific failures. This prevents misinterpreting partial failures as total failures.

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 well-structured with clear headers and bullet points, and the main purpose is front-loaded. It is somewhat verbose, especially the repeated 'CRITICAL' sections and redundancy with the schema, but the detailed error-handling guidance earns the length.

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 read-only annotation, one parameter, and an output schema, the description covers all essential aspects: when to use, batch behavior, error handling, and index mapping. It leaves no significant operational gaps.

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% and the schema's 'urls' description already includes examples, constraints, and limits. The description's input requirements section largely repeats the same information, adding only emphasis on mandatory status. No meaningful additional semantics beyond 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 states 'Resolves a list of Google Maps URLs into canonical Google Maps Place IDs' – a specific verb and output. It clearly distinguishes from siblings like resolve_names and search_places by focusing on URL-to-Place-ID conversion.

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 'When to call this tool' section explicitly defines the exact scenario: when the user provides Google Maps links and you need Place IDs. It also notes the batch limit of 20 URLs. However, it does not mention alternatives or conditions when not to use it, so it lacks full when-not 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses critical batch behavior: mixed results, 1:1 index mapping, empty Result for failed queries, and the failed_requests map. This is valuable context that annotations alone do not 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 well-structured with clear headings (Input Requirements, Instructions, Error Handling) and bullet points. It is long but every section serves a purpose, and the key purpose statement is front-loaded. The formatting aids readability and agent comprehension.

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 batch-processing complexity and the presence of an output schema, the description covers all necessary operational aspects: input requirements, param formats, constraints, partial failure handling, and mapping guarantees. It is complete for an agent to 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?

While schema coverage is 100% and already documents all parameters, the description adds meaningful context with concrete examples for `text`, the exact JSON structure for `location_bias`, and a note on precedence between `location_bias` and `region_code`. This enriches the schema beyond 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 opens with a clear, specific statement: 'Resolves a batch list of specific location queries (landmark names or exact addresses) into canonical Google Maps Place IDs.' This immediately establishes the verb, resource, and scope, and distinguishes it from siblings like search_places and resolve_maps_urls.

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 usage guidance, including a direct 'Do NOT call this tool if...' exclusion and details on supported vs unsupported queries. This gives the agent concrete criteria for when to use this tool versus alternatives or downstream tools.

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 destructiveHint=false. The description adds useful behavioral context: language and region codes can affect results, location_bias prioritizes but does not limit results, and attribution must be included. It also explains that location_bias usage should be restricted to certain conditions.

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 long but well-structured with sections, numbered lists, and examples. Every paragraph serves a purpose, though some examples could be trimmed. It remains appropriately sized for a tool with four parameters and complex usage rules.

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 and the presence of an output schema, the description covers all essential aspects: when to use, parameter semantics, location handling, and attribution. It could mention potential return behavior (e.g., multiple results), but the output schema sufficiently covers return values.

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%, but the description adds meaningful examples for each parameter: text_query examples include 'restaurants in New York' and 'SF MoMA', location_bias is shown with explicit JSON formats, and language_code/region_code have format details. This goes beyond the schema's basic 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 a clear call-to-action: 'Call this tool when the user's request is to find places, businesses, addresses, locations, points of interest, or any other Google Maps related search.' This provides a specific verb and resource, and it distinguishes from sibling tools like compute_routes and lookup_weather by focusing on place 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?

It explicitly states when to use the tool and gives detailed instructions for handling ambiguous locations and when to use location_bias. However, it does not explicitly mention when NOT to use it or point to alternatives, so it lacks the 'when-not/alternatives' element required for a 5.

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