Google Maps

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

Supplements readOnlyHint=true by disclosing default values (DRIVE), result quality factors (granular addresses yield better results), and validation requirements (mandatory user clarification). Does not repeat the WALK beta warning visible in schema enums but adds integration context with sibling tools.

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?

Structured with bold headers and bullet points for scannability. Front-loaded purpose followed by critical constraints. Length is justified by the complexity of polymorphic inputs, though some redundancy exists with schema definitions.

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 complex nested input schema and presence of an output schema (not shown), the description is complete. It covers travel modes, input validation, prerequisite tools, and result quality expectations without needing to describe 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?

Despite 100% schema coverage, adds crucial semantic context: explains the polymorphic 'one of' input pattern for waypoints (address vs lat_lng vs place_id), provides concrete examples for each type, and includes a full JSON example demonstrating nested structure. Clarifies that parameters are mutually exclusive within each waypoint object.

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 action (Computes) and resource (travel route) bounded by origin/destination. It clearly distinguishes scope from siblings by referencing search_places as the source for place_id inputs, implying this tool consumes location data while search_plplaces produces it.

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-not guidance ('If either...missing, you MUST ask the user for clarification') and identifies a prerequisite workflow (obtain place_id from search_places). Lacks explicit contrast with lookup_weather, though the distinction is intuitive.

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 declare readOnlyHint=true, the description adds valuable behavioral context: comprehensive list of returnable data fields (celestial events, QPF, UV index), timezone handling rules (location's local time), and temporal limits (48-hour hourly, 7-day daily) that help the agent constrain inputs appropriately.

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?

Appropriately structured with clear headers (Specific Data Available, Usage Modes, Parameter Constraints) that front-load critical information. Length is justified by the complexity of the location oneof constraint and three distinct usage modes, though slightly 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 presence of an output schema and 100% input schema coverage, the description provides complete contextual coverage including sibling tool dependencies (search_places), all critical constraints (timezones, date ranges), and data availability details without needing to describe 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?

With 100% schema coverage (baseline 3), the description adds substantial operational semantics: location selection rules with examples for the oneof structure, date format clarifications ('separated into {year, month, day} integers'), hour rounding instructions, and units system defaults/override conditions.

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 and resource ('Retrieves comprehensive weather data'), explicitly scopes the functionality (current, hourly, daily forecasts), and distinguishes from sibling tool search_places by noting it as the source for place_id values.

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?

Contains explicit 'Usage Modes' section detailing exact parameter combinations for current weather vs hourly vs daily forecasts, including constraints like 'Hourly forecast beyond 48 hours... is not supported' and 'Historical weather is not supported,' providing clear when-to-use/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?

The description goes beyond the readOnlyHint annotation by detailing batch processing (up to 20 URLs), 1:1 mapping to response indices, the failed_requests map for partial failures, and how to interpret empty entities. This adds significant context for correct invocation.

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 and sections (When to call, Input Requirements, Error Handling). It is appropriately sized for a batch tool, though some redundancy exists (e.g., repeating URL formats). It front-loads the core purpose.

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 has an output schema (so return values are documented separately) and the input schema covers 100% of parameters, the description is complete. It covers input requirements, batch behavior, error handling, and response mapping without 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?

The schema has 100% description coverage, so baseline is 3. The description adds meaning by clarifying that URLs must be valid single-place Google Maps URLs of specific formats (e.g., maps.app.goo.gl) and that up to 20 are allowed, reinforcing and extending 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 Google Maps URLs into canonical Place IDs. It uses a specific verb (resolve) and resource (Maps URLs), and distinguishes from siblings like search_places and resolve_names by focusing on URL-to-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 description includes a 'When to call' section that specifies use when users provide Google Maps sharing links/URLs. It implies when not to use (e.g., for searching places), but does not explicitly name alternative tools like search_places or resolve_names.

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 annotations (readOnlyHint=true), the description details batch processing behavior, mixed results, failed_requests map, and 1:1 index mapping. This fully discloses the tool's operational 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?

The description is well-structured with headings (Input Requirements, Instructions, Error Handling) and front-loaded purpose. It is detailed but not excessively long; each section adds necessary context.

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 complexity (batch, error handling) and existence of output schema, the description covers all necessary aspects: input requirements, optional parameters, usage constraints, and error handling. Nothing missing for effective use.

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 baseline 3. The description adds value by providing examples for 'text', exact format for 'location_bias' using viewport, and region_code details. It enhances 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 first sentence clearly states the tool resolves location queries into Google Maps Place IDs. It explicitly distinguishes from siblings by specifying it handles specific place names/addresses, not general search, which differentiates it from 'search_places'.

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-not-to-use instruction: 'Do NOT call this tool if the downstream tools you plan to invoke already accept raw address or place name strings directly.' Also specifies required specificity of queries, guiding appropriate use.

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?

With annotations declaring readOnlyHint=true, the description adds valuable behavioral context: specifying that results outside the bias region may still be returned, explaining that omitting radius_meters strongly biases toward the center point, and noting that language codes affect display formatting. However, it omits rate limits, pagination behavior, or error conditions that would further aid agent decision-making.

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 hierarchies (Input Requirements vs. Instructions) and front-loaded purpose. While lengthy, every sentence earns its place by providing specific examples or critical constraints. Minor verbosity exists in the repeated 'CRITICAL' labels and heavy formatting, but this is appropriate for the 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 presence of an output schema (relieving the description of return value documentation), the description thoroughly covers all complex input requirements, parameter interactions (noting that explicit locations in text_query override location_bias), and disambiguation rules necessary for successful invocation.

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?

Despite 100% schema coverage (baseline 3), the description adds substantial semantic value through seven diverse text_query examples (including attribute-specific queries like 'opening hours'), explicit JSON syntax for nested location_bias objects, and format clarifications for language/region codes. This goes far beyond the schema's basic 'The text query' 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 explicitly states the tool 'find[s] places, businesses, addresses, locations, points of interest' and identifies it as 'Google Maps related search,' clearly distinguishing it from sibling tools compute_routes (routing) and lookup_weather (weather data). The specific verb+resource combination provides unambiguous 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 explicit invocation criteria ('Call this tool when...') and detailed guidance on parameter selection (text_query vs. location_bias). However, it lacks explicit named alternatives or 'when not to use' exclusions referencing the sibling tools, though the functional scope is distinct enough to imply boundaries.

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