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

While annotations already indicate idempotence and non-destructiveness, the description adds context about the tool being the cheapest, but it fails to clarify important behaviors such as whether results depend on location parameters, if any rate limiting or throttling exists, or what happens with ambiguous inputs. Given the presence of annotations, the bar for added value is higher, and the description barely meets it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at two sentences, with no filler. The first sentence clearly states the function and output, and the second provides usage context. Every word adds value.

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 that an output schema exists, the description doesn't need to explain return values. The tool is relatively simple with one required parameter and clear annotations. The description covers usage flow and efficiency, making it mostly complete. A minor gap is the lack of guidance on when not to use it (e.g., if exact match needed) or what distinguishes it from search_places_by_text.

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 description provides no parameter-level details, but since schema description coverage is 0%, it must compensate for this gap. It does offer high-level context that the tool uses partial text (matching the only required input) and mentions optional location parameters implicitly through the tool's purpose. However, it doesn't explain radius_metres or coordinate semantics, so some burden remains.

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 specifies the verb ('Complete'), the resource ('a partial place name or address'), and the output ('up to five candidates, each with a place id'). It distinguishes the tool from siblings by focusing on partial input and id generation.

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 guidance on when to use this tool: before a search or details lookup, and to convert vague names into usable IDs. It also implies exclusivity by noting it's the 'cheapest' way, contrasting with more expensive sibling operations.

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, so safety is clear. The description adds valuable behavioral context: traffic inclusion only for DRIVE and TWO_WHEELER, and the performance note about include_steps increasing response size. No contradictions 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 concise, well-structured, and every sentence adds value. It front-loads the core purpose, then provides key usage details for endpoints, traffic, and a critical performance trade-off. No filler 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?

Given 11 parameters, 0% schema description coverage, and presence of an output schema, the description covers the most critical points (endpoint formats, traffic, steps) but omits details on other parameters like units, alternatives, or departure_time. The output schema can handle return format, so the gap is primarily in parameter semantics.

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 0%, so the description must compensate. It explains origin and destination endpoint formats, traffic by travel mode, and include_steps impact, but does not cover all 11 parameters (e.g., units, avoid_tolls, alternatives, intermediates, departure_time). The provided clarifications are helpful but incomplete.

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 computes a route between two places for multiple travel modes and returns time, distance, and warnings. It distinguishes itself from siblings like compute_route_matrix by focusing on a single route, and from general search tools by its specific route-computation purpose.

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 explains three valid endpoint formats and their precision trade-offs, and notes that include_steps should only be used when needed due to response size. However, it does not explicitly mention when to use alternatives or compute_route_matrix instead, or when not to use this 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 confirm read-only, non-destructive behavior. The description adds valuable context: Google bills per pair and the matrix is capped at 100 origin-destination pairs. This exceeds what annotations provide, though it doesn't detail error behaviors or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no redundancy. The first sentence defines purpose, the second gives use cases, and the third adds a critical constraint. Every sentencence 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?

Covers the high-level concept, use cases, and a key constraint (100-pair cap). However, with 7 parameters and no output schema shown, it fails to specify input format details (e.g., how to represent coordinates or addresses), which is essential for correct 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 0%, yet the description only mentions origins and destinations and vaguely references 'the same three forms as compute_route'. It does not explain the meaning of travel_mode, avoid options, departure_time, or how to format address strings. Relies heavily on external knowledge.

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 'Get travel time and distance for every origin against every destination in one call' and labels it 'the comparison tool'. Specific use cases like picking nearest branch or ranking sites are given, and it distinguishes itself from sibling tools like compute_route by doing all pairs in a single call.

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 usage contexts (nearest branch, ranking sites, reachability checks) and mentions the 100-pair cap. It implicitly contrasts with compute_route for single routes but does not explicitly state when not to use this tool or name 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 and destructiveHint=false, indicating safe read-only behavior. The description adds value by noting that the tool returns multiple candidates for ambiguous text, which is useful behavioral context. However, it does not discuss whether there are rate limits, error conditions (e.g., invalid address), or what happens with partial matches, so a 3 is appropriate.

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 adding distinct value: what it does, when to use it, and a key behavioral trait (multiple candidates). It is front-loaded with the primary action. It could be slightly more concise, but there is minimal waste, so a 4 is fair.

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 has an output schema (not shown), so return value details are handled elsewhere. It has low complexity (2 params, 1 required, no enums). The description covers purpose, usage context, and ambiguous input behavior. It misses clarifying the optional region_code parameter, but overall it is complete enough for the tool's simplicity. A 4 reflects this minor gap.

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 0%, so the description must compensate. The description explains that 'address' accepts addresses, landmarks, or plus codes, adding meaning beyond the schema's simple type. It does not explain the optional 'region_code' parameter (e.g., to bias results), which is a gap, but overall the description provides substantial value for the main parameter. Given zero schema coverage, a 4 is justified for compensating well, though not fully.

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 purpose: converting an address, landmark, or plus code into coordinates, a normalized address, and components. It also mentions handling ambiguous input by returning multiple candidates, which distinguishes it from sibling tools like reverse_geocode or validate_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 says 'Use this before any tool that needs a latitude and longitude,' giving clear when-to-use guidance. However, it does not mention when not to use it (e.g., for specific place lookups where geocode_place_id or autocomplete_places might be better), so it loses one point.

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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about output content (coordinates, normalized address, address components) and quality characteristics (precision, cost). It does not cover edge cases like invalid place_ids, but for a simple read-only lookup with annotations, 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 sentences, front-loaded with the action and resource, and the second sentence adds valuable comparison guidance. Every word contributes meaning; 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?

With only one parameter and an output schema present, the description covers the necessary context: what the tool does, what input it expects (place_id from a prior search), and how it compares to related tools. No additional details are needed for correct 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?

The only parameter, place_id, has no schema description (coverage 0%). The description adds essential semantic meaning by specifying it is 'a place id returned by a place search,' clarifying the source and format expectations. This compensates fully for the missing schema-level documentation.

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 ('Look up') with a clear resource ('place id') and enumerates the return content ('coordinates, normalized address, and address components'). It distinguishes itself from sibling tools by noting it is 'More precise than geocoding the place's name' (geocode_address) and 'cheaper than a full details lookup' (get_place_details).

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 this tool: when you have a 'place id returned by a place search' and need location data. It also names alternatives and trade-offs: 'More precise than geocoding the place's name, and cheaper than a full details lookup when location is all you need.' This gives clear decision guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds meaningful behavioral context: it retrieves current (not historical) data, requires a coordinate, and lists the specific data elements returned. It does not contradict annotations (annotation_contradiction=false).

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: first sentence states purpose and outputs, second sentence adds a crucial prerequisite. Every sentence adds value, there is no redundancy or fluff, and it is front-loaded with the core function.

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 2-param tool with an existing output schema, the description covers purpose, output details, and a relevant prerequisite. It does not mention error conditions or rate limits, but the presence of the output schema reduces the need to explain return values. Slightly lacking in completeness for edge cases.

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 0% for both parameters, so the description must compensate. It mentions 'at a coordinate' but adds no further details about the latitude and longitude parameters (e.g., format, range, required constraints). For a low-coverage schema, this is insufficient compensation.

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 purpose with a specific verb and resource: 'Get current air quality at a coordinate'. It lists the specific outputs (local/universal AQI, dominant pollutant, concentration, health guidance), which distinguishes it from siblings like get_time_zone, get_elevation, and geocoding 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 a clear usage prerequisite: 'Needs the Air Quality API enabled on the project, which is separate from the other Maps APIs.' This sets appropriate expectations. However, it does not explicitly compare this tool to siblings or give when-to-use/not-use guidance, though the context is clear from the purpose.

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 indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral context: return value (elevation in metres), input format, and maximum coordinate count. It does not disclose error handling, rate limits, or behavior for invalid coordinates, but given the annotations, 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 three sentences long, each serving a distinct purpose: purpose statement, input format with limit, and usage examples. No wasted words; the most important information is front-loaded. 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 tool has one required parameter and an output schema (not shown but present), the description covers the key aspects: input format, limit, and practical use. It could mention that results correspond to input order or what happens on error, but overall it is fairly complete for a simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines 'coordinates' as an array of strings with no description. The tool description adds critical meaning: coordinates must be 'lat,lng' strings, limited to 50. This far exceeds the schema's bare type information, making the parameter much more usable.

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 function: 'Get the elevation in metres above sea level at one point or at several.' It specifies the exact input format ('list of 'lat,lng' strings, at most 50') and provides concrete usage scenarios (judge terrain, floodplain, exposure). This clearly distinguishes it from sibling tools which focus on time zones, geocoding, or 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?

The description includes practical use cases ('judge terrain, climb, floodplain, exposure'), implying when to invoke the tool. It also sets a clear limit (at most 50 coordinates). However, it does not explicitly state when not to use the tool or mention alternative tools for elevation data, though no obvious alternatives exist 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?

The description goes beyond the readOnlyHint annotation by explaining that the 'detail' parameter controls which fields are returned (enterprise vs atmosphere) and that atmosphere 'may be disabled'. This provides concrete behavioral context about varying data availability, which is not captured by annotations alone.

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 with no wasted words. The first sentence front-loads the purpose and output, the second specifies the input source, and the third explains the critical parameter. Every sentence adds value and the structure is logical.

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 existence of an output schema, the description does not need to detail return fields. It covers both parameters and notes the behavioral nuance of the atmosphere tier. While it omits explicit error handling or rate limits, the tool is a simple read operation with low complexity, making the description sufficiently 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?

With 0% schema coverage, the description fully compensates by explaining the place_id parameter's source and the detail parameter's effect on cost and returned fields. It adds meaning beyond the schema by describing the trade-offs between enterprise and atmosphere tiers, though it does not enumerate all possible values for detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read' and the resource 'everything Google holds about one place', listing specific fields. It distinguishes from sibling search and geocoding tools by explicitly requiring a place_id from a search or autocomplete, making its specific role evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after obtaining a place_id by stating 'Takes a place id from a search or autocomplete.' It also advises on the detail parameter for cost control. However, it does not explicitly indicate when not to use this tool or point to alternatives like search_places_by_text or geocode_place_id, leaving the guidance implicit.

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, so the safety profile is covered. The description adds useful behavioral context (that the offset depends on the timestamp, implying seasonal DST variations), which is beyond the annotations. However, it does not specify what the tool returns if the coordinate is invalid or over ocean areas, which could be relevant.

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-loads the purpose, and each sentence adds value. The first specifies what the tool does and returns; the second explains the critical usage note about timestamp dependency. 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?

Given the tool's moderate complexity (three parameters, no enums), the description is adequate. The output schema exists, so return values are documented. The description covers the key nuance of DST and provides use-case context. It does not mention edge cases like invalid coordinates, but for a read-only tool with an output schema, this is not a critical gap.

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 0%, so the description must compensate. It explains the semantic significance of the timestamp parameter ('Pass the moment you care about, because the offset changes across the year') and mentions the output includes IANA id and offset, which adds meaning beyond param names. Latitude and longitude are standard, but the timestamp's importance is well-clarified.

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 purpose: to get the time zone at a coordinate, including IANA id, name, and UTC offset with DST. It distinguishes itself from sibling tools like get_elevation and get_air_quality by focusing on time zone retrieval.

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: it tells the agent to use this tool when needing to reason about local times or business hours, and emphasizes the importance of passing the relevant timestamp because offsets change seasonally. This effectively differentiates it from other geographic 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 provide readOnlyHint=true and destructiveHint=false, but the description adds value by detailing the hierarchical address output (street, neighbourhood, city, country). This goes beyond the annotation structure and helps the agent understand the returned data shape. No contradiction found.

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 brief (two sentences) and front-loaded with the core action. Every sentence contributes meaning, with zero 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?

The tool is simple (2 required numeric params) and an output schema exists, so the description need not explain return values. It covers the output concept (address hierarchy) adequately. Minor omission: no mention of potential failure cases (e.g., invalid coordinates) but acceptable given the tool's straightforward nature.

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 0%, so the description must compensate. However, it only mentions 'latitude' and 'longitude' generically without specifying valid ranges, required precision, or formatting. The description adds minimal semantic value beyond the schema's type and name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Turn' (convert) and the resource ('latitude and longitude' into 'addresses'), and specifies the hierarchical output scope. It effectively distinguishes from siblings like geocode_address (address→coords) and geocode_place_id (place ID→coords).

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 says 'Use this to describe where a coordinate is,' which gives clear context. While it does not explicitly mention when not to use it or name alternatives, the sibling list implies those distinctions. Lacks explicit exclusions but is sufficient for a simple 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 indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details beyond annotations: pagination limits (20 per page, max 60), detail levels with cost trade-offs, and the fact that atmosphere detail may be disabled. This is above baseline transparency.

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: the first gives purpose and examples, the second details pagination and detail levels. It is efficient but could be slightly tighter (e.g., 'returns up to 20 places per page and a token...' is clear). No wasted words.

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 10 parameters, 0% schema coverage, and no enum constraints, the description covers the most critical aspects: query, detail, and pagination. It does not elaborate on rank_by, location-based parameters (latitude/longitude, radius_metres), open_now, or min_rating, but the tool is simple enough that these are likely inferred from parameter names. An output schema exists, so return behavior is defined. Slightly more context on location parameters would push to 5.

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 0%, so the description must compensate heavily. It does: it explains the detail parameter's options and trade-offs ('essentials', 'pro', 'enterprise', 'atmosphere') and clarifies pagination semantics (page_size, page_token). The description adds significant meaning beyond the bare 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 specific verb ('Search') and resource ('places'), and clearly distinguishes this tool from siblings like search_places_nearby by emphasizing text-based description queries. Examples make the scope immediately obvious.

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 implicitly guides when to use this tool (for natural language queries) vs. siblings like search_places_nearby (which likely uses coordinates or proximity). It does not explicitly state when not to use it or name alternatives, but context signals and sibling names make differentiation clear.

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, signaling a safe read operation. The description adds critical behavioral details beyond annotations: the radius-based circle constraint, popularity/distance ranking, the 20-result limit (even though the parameter max_results has a default of 10, the description clarifies the absolute ceiling), and the lack of paging. It doesn't mention that results are returned as a JSON array of place objects or any specific output format, but the presence of an output schema alleviates that need.

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, all essential. The first sentence states the core operation and ranking. The second provides sibling differentiation. The third adds critical constraints and examples. This is tight and front-loaded, though the lack of enum details for rank_by and implicitly for detail slightly reduces completeness for a zero-coverage schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, 0% schema coverage, and a relevant sibling, the description covers the most important aspects: spatial use case, alternative tool, output limits, and filter examples. It misses explaining the 'detail' parameter and the exact format for rank_by, but those are less critical for an initial call. The output schema presumably details return fields, so the description's brevity on output is acceptable.

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 0%, meaning the description must fully explain the parameters. The description mentions the circle concept (implying radius_metres and the centre latitude/longitude), the ranking (rank_by), and the filter (included_types with examples). However, it does not explain the 'detail' parameter or the exact valid values for 'rank_by' (e.g., POPULARITY vs. DISTANCE). It also does not explicitly describe the bounds or meaning of latitude/longitude. Despite these gaps, the explanation adds substantial value beyond the bare schema titles.

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 specific verbs ('List places inside a circle') and names the ranking bases ('popularity or by distance'). It clearly distinguishes this tool from its sibling 'search_places_by_text' by contrasting spatial vs. text-based queries.

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 this tool ('when you have a point and want what is around it') and when to use the sibling ('use search_places_by_text when you can describe what you want'). It also notes key constraints: up to 20 results, no paging, and gives examples of valid filter types.

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 indicate readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It goes beyond annotations by disclosing the tool returns a corrected version plus notes about missing/unconfirmed/inferred items. However, it doesn't mention if authentication or rate limits apply; a 4 is appropriate given annotations cover the core behavioral profile and the description adds meaningful 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?

Two concise sentences front-load the key action and return value, then immediately provide usage guidance with an alternative. Every sentence adds value, zero wasted words.

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 only 2 params and an output schema present, the description doesn't need to explain return structure. It covers purpose, when to use, and behavioral output. It doesn't specify parameter formats or required permissions, but for a simple read-only validation tool with few params, this is nearly 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?

Schema description coverage is 0%, so the description must compensate. It doesn't explain what address_lines expects (e.g., format, order) or what region_code means (e.g., ISO code). The schema has two parameters but the description provides zero parameter-specific guidance. Baseline is 3 due to low coverage, but the description adds no parameter detail, so 3 is the maximum possible here.

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: check if a postal address is real and deliverable, and return a corrected, standardized version with notes about missing or inferred information. The verb 'validate' paired with 'address' is specific, and the description clearly distinguishes this tool from siblings like geocode_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 says when to use this tool ('before relying on an address a user typed') and when not to (use geocode_address when you only need coordinates). This direct guidance with a named alternative clarifies decision-making.

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