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?

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.