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

The readOnlyHint annotation already indicates a safe read, so the description only needs to add extra context. It does so by enumerating the response fields (coordinates, state, population, timezone) and hinting at ambiguous-name behavior via country disambiguation. It doesn't describe error handling for no matches, but that's acceptable for a simple lookup 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 short sentences that lead with the main action and output, followed by an optional disambiguation tip. 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 lookup tool with no output schema, the description adequately covers what the tool returns and how to handle ambiguous names. Omitting state from the description is acceptable because the schema describes it, and the tool's simplicity limits the need for more extensive context.

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 documents all three parameters with 100% coverage, providing clear descriptions for name, state, and country. The tool description adds marginal value by explaining that country resolves name ties, which enriches the meaning of that parameter, but it doesn't add anything new for name or state.

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 verb and resource: 'Look up a city by name,' followed by the returned fields (coordinates, state, population, timezone). This distinctly frames it as an exact-name lookup, differentiating it from sibling tools like city_search or city_nearest even without naming them.

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 a concrete usage tip: 'Pass country to disambiguate name ties,' which tells the agent when to add an extra parameter. However, it does not explicitly mention when to prefer this tool over city_search or city_nearest, so it lacks exclusion guidance but still gives clear context.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds the behavioral detail that the id is stable and comes from an earlier response, which is useful context. However, it does not disclose additional traits such as error behavior or data freshness.

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 single, front-loaded sentence that states the purpose without any extraneous words. It is appropriately concise and easy to scan.

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 refetch-by-id tool with one parameter and a readOnly annotation, the description is sufficiently complete. It identifies the key input ('stable parse id') and the source ('earlier response'), and no output schema is needed. It lacks explicit edge-case behavior but is complete enough for its simplicity.

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 fully describes the 'id' parameter with a stable city id example, so the description does not need to add parameter semantics. It reinforces 'stable parse id' but does not add information beyond the schema. With 100% schema coverage, a baseline 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 clearly states the action ('Refetch') and the specific resource ('a city by its stable parse id'). It distinguishes this from sibling tools like city_search or city_nearest by emphasizing the stable parse id from an earlier response.

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 'from an earlier response' gives clear context for when to use this tool: after obtaining a stable city id from a previous parse. It does not explicitly name alternatives, but the context is clear enough for an agent to infer this is the refetch-by-id 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?

The only annotation is readOnlyHint=true, which declares safety. The description adds no extra behavioral context, such as return format, how 'nearest' is determined, or behavior in edge cases (e.g., ocean coordinates). Since there is no output schema, the description carries a heavier burden but does not fulfill 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 a single, front-loaded sentence: 'Find the nearest city to coordinates.' It contains no filler, is easy to parse, and is appropriately sized for the tool's simplicity.

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, with complete parameter documentation and a read-only annotation. However, the lack of an output schema and the absence of any description of the result format (e.g., city name, ID, object, distance) leaves a notable gap. The description is adequate for a basic geospatial lookup but not fully self-sufficient.

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 both 'lat' and 'lon' clearly defined in decimal degrees. The description text does not add extra parameter semantics beyond the schema, but the schema already fully specifies the parameters, so baseline 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 clearly states a specific operation: 'Find the nearest city to coordinates.' The verb 'find' and resource 'nearest city' distinguish it from sibling tools like 'city' (which likely queries by ID) and 'city_search' (by name). The geospatial context is explicit.

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?

No guidance is provided on when to use this tool versus alternative geolocation tools such as 'point', 'postal_nearby', or 'city_search'. There are no exclusions, prerequisites, or mention of situations where a different sibling tool would be more 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?

With readOnlyHint=true in annotations, the safety profile is already declared. The description adds the prefix-matching behavior and the exact-name-unknown scope, which is useful context. However, it doesn't disclose return format, ordering, or filter behavior beyond what schema provides, so it adds limited depth.

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 with no fluff. Front-loaded with the core function, and the usage guideline follows immediately.

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 read-only search tool with complete schema descriptions, the description adequately covers purpose, scope, and when to use. The absence of an output schema is mitigated by the tool's simplicity, though it could mention result ordering or additional behaviors. Overall, sufficient 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?

Input schema covers 100% of parameters with descriptions (e.g., q as 'Name prefix', state as 'State code filter', limit with min/max). The description's mention of 'name prefix' reiterates the schema but adds no new syntactic or semantic detail, so baseline 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?

Description states 'Search cities by name prefix' – a specific verb, resource, and scope. The phrase 'Use when the exact name is unknown' distinguishes it from tools like city or city_id, clarifying its unique role.

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: use when the exact name is not known. While it doesn't explicitly name alternatives, the sibling list includes exact-match lookups (city, city_id), implying a when-not. This meets the threshold for clear context but lacks explicit 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?

The readOnlyHint: true annotation already covers the read-only nature. The description adds that the tool returns name, area, and population, which is useful output context, but it does not disclose other behavioral traits such as error handling, rate limits, or what happens with invalid codes. This is on par with the annotation bar, adding some but not rich 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 a single, concise sentence of 9 words. It is front-loaded with the action and resource, and every word earns its place. No fluff 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 low complexity (single parameter, readOnly annotation, no output schema), the description covers the core purpose and even lists the expected return fields (name, area, population). It does not describe the exact return structure or behavior on invalid input, but for a simple lookup tool, this is mostly sufficient. A higher score would require more detail on output format or error handling.

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 fully documents the only parameter 'code' with a list of valid codes (AF, AN, AS, EU, NA, OC, SA), achieving 100% schema_description_coverage. The description adds no extra meaning about the parameter itself beyond referencing 'by code'. Baseline of 3 is appropriate since the schema does the heavy lifting.

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 'Look up a continent by code: name, area, population' clearly states the verb (Look up), resource (continent), and the input method (by code). It is specific enough to understand the tool's function, but it does not explicitly differentiate from sibling tools like continent_countries, which likely serves a related but different 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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or mention sibling tools like continent_countries. The only implied usage is when you need continent details by code, but no clear context or alternatives are given.

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 readOnlyHint annotation already covers the read-only behavior, so the description doesn't need to restate it. It adds the behavioral assertion 'every country', indicating an exhaustive, unpaginated list, which is useful beyond the 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?

Single sentence, six words, directly states the action and scope 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 1-parameter list tool, the description fully explains the purpose. The lack of an output schema is mitigated by the straightforward nature of returning a list of countries; nothing else is needed.

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 fully describes the one parameter with allowed values in its description, so the tool description adds no extra semantic value. Baseline 3 is appropriate since schema coverage is 100%.

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 ('List') and resource ('every country on a continent'), clearly distinguishing it from siblings like country_states (states within a country) and continent (continent 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 clearly implies the use case (fetching countries for a given continent) and the required code parameter provides a direct trigger. It doesn't explicitly mention alternatives or exclusions, but the context is unambiguous for this simple listing 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?

The annotation readOnlyHint=true already signals a safe read operation, and the description does not contradict it. The description adds the specific return fields, which is useful but does not disclose additional behavioral traits such as handling of invalid codes or whether only one country is returned. Given the annotations cover the safety profile, 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 a single, front-loaded sentence that efficiently lists the key return fields without any redundant phrases. Every word contributes to the core purpose, and there is no waste.

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 lookup tool with one well-documented parameter, a read-only annotation, and no output schema, the description sufficiently sets expectations by naming the fields returned. It could optionally mention error handling, but the low complexity means this level of detail is largely 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 input schema already describes the parameter 'code' as an ISO 3166-1 alpha-2 country code with an example, providing 100% coverage. The tool description does not add any further meaning about the parameter beyond what the schema provides, 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 'Look up' and identifies the resource as 'a country', then enumerates the returned fields: names, capital, currency, languages, calling code, timezones. This clearly distinguishes it from sibling tools like country_states or continent, which focus on different aspects.

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 when to use this tool (when you need core country details), but does not explicitly state exclusions or alternatives. For instance, it does not mention that country_states should be used for subnational divisions, though the sibling list hints at that distinction. No explicit when-not-to-use guidance is provided.

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 annotation readOnlyHint=true already discloses the safe read-only nature. The description adds no further behavioral context such as response format or handling of invalid codes, but it does not contradict the 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?

One concise sentence, front-loaded with the verb, and every word adds value. No redundant information.

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 list tool with one well-documented parameter and a read-only annotation, the description fully captures the action. No output schema is needed for this type of operation.

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% with a clear description of the 'code' parameter (ISO 3166-1 alpha-2). The tool description adds nothing beyond the schema, so baseline 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 'List' and clearly identifies the resource: 'states, provinces or regions of a country.' It distinguishes from siblings like 'state' and 'state_districts' by addressing the full set of subdivisions for a country.

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?

Usage is implied: if you need the states of a country, this is the tool. However, it does not explicitly mention alternatives or conditions like 'use state for a specific state' or mention invalid country codes.

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, so the description only needs to add extra context. It discloses the returned data fields (name, symbol, decimal places, countries), giving the agent useful expectations beyond a simple read operation. This is consistent with the 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 a single concise sentence, front-loaded with the core action 'Look up a currency' and immediately lists the key return fields. Every word contributes value 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?

The tool is simple with one parameter, read-only, and no output schema. The description covers the essential return values (name, symbol, decimal places, countries), which is sufficient for most lookup tasks. It does not specify behavior for invalid codes, but this is a minor gap given the tool's simplicity.

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 provides 100% coverage for the single parameter 'code' with a clear description (ISO 4217 code). The tool description adds no additional parameter information, so it stays at 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 purpose: 'Look up a currency' with specific details. It lists the returned fields (name, symbol, decimal places, countries), making it distinct from sibling 'currency_rate' which is about exchange rates. The verb and resource are 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?

The description implies usage: when you need static currency information, use this tool. However, it does not explicitly mention alternatives or when not to use it, so the guidance is implicit rather than direct.

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 annotation readOnlyHint=true already indicates this is a safe read operation, and the description aligns with that. The description adds a small piece of context by specifying 'official central bank data' as the source, but it does not disclose return format, rate limitations, or any other behavioral traits. It's minimally transparent beyond the 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 a single phrase that front-loads the core function ('Exchange rate') and remains concise without extraneous wording. Every word adds value, making it highly efficient.

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 two-parameter tool with no output schema, the description is minimally sufficient but lacks detail on the return type (e.g., numeric rate, object with metadata). It also does not mention whether rates are live or historical. Given the simplicity, this is a marginal but acceptable level of 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 fully describes both parameters (base and quote) as ISO 4217 currency codes with examples. The description adds no extra semantics beyond saying 'between two currencies', which is already implied by the schema. With 100% schema coverage, the baseline 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 clearly states the tool provides an exchange rate between two currencies, sourced from official central bank data. It distinguishes itself from the sibling tool 'currency' by specifying it is a rate lookup. However, it lacks an explicit action verb like 'retrieve' or 'get', making it slightly less specific on that front.

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 offers no guidance on when to use this tool versus alternatives, nor does it mention any exclusions, prerequisites, or context. It simply states the function without indicating whether it should be preferred over the sibling 'currency' tool for certain use 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?

The description is consistent with the readOnlyHint annotation ('look up' implies a read operation). However, it adds no behavioral context beyond the annotation, such as what data is returned, whether a country is required to disambiguate codes, or any 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?

The description is a single concise sentence that immediately communicates the core purpose. No wasted words or redundant information.

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 lookup tool with full schema coverage and a readOnly annotation, the description is minimally viable. However, it lacks usage guidance and does not indicate what the response contains, which would be more important given the absence of an 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%, with 'code' and 'country' both described with examples. The description adds the phrase 'by code' but does not explain the relationship between code and country or the expected format 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 uses the specific verb 'look up' and identifies the resource as 'a district, county or department' with the method 'by code'. This is clear and distinguishes it from sibling tools like state_districts or country, though it does not explicitly name alternatives.

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?

No guidance is provided on when to use this tool versus alternatives like state_districts or city. The description only says 'look up ... by code', leaving the agent to infer the appropriate context from the parameter schema and sibling list.

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 slightly beyond the readOnlyHint annotation by listing the categories of information (registration, DNS, mail setup), which gives a high-level view of what the lookup returns. However, it does not disclose details like rate limits, response format, or potential paid aspects (though the schema mentions deep is paid). 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 a single, well-structured sentence. It front-loads the main action and then adds a brief note about the deep option. Every word contributes to understanding the tool's 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?

Despite having no output schema, the description provides a reasonable overview of the data categories (registration, DNS, mail setup) that would appear in results. This makes the tool usable at a basic level. However, it could be improved by explicitly mentioning that domain is a read-only lookup and perhaps noting any limitations or overlap with sibling tools.

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 both parameters are already documented. The description's mention of 'Deep adds richer checks' reiterates the schema's meaning for the deep parameter without adding new syntax or subtle behavioral details. This baseline score reflects that the description adds little 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 performs a lookup for a domain and specifies the areas covered: registration, DNS, and mail setup. This distinguishes it from sibling tools like ip, email, or mx, which focus on other specific data types.

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?

No guidance is provided on when to use this tool versus alternatives. The sentence 'Deep adds richer checks' hints at the deep parameter usage but does not clarify when to prefer domain over related tools such as mx or email. There are no explicit exclusions or alternative recommendations.

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 description adds marginal transparency by specifying the unit (meters) and the input scope (coordinates). It does not disclose edge cases, data sources, or behavior for invalid inputs, but given the simple read-only nature, a score of 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 a single, front-loaded sentence that efficiently conveys the essential information without redundancy. Every word earns its place, making it highly concise and well-structured.

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 simplicity (2 params, read-only annotation, no output schema), the description adequately communicates what the tool returns (elevation in meters). While it leaves out details like error handling or return format, the overall context is sufficient for a straightforward look-up 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 has 100% description coverage for both 'lat' and 'lon', each clearly defined. The description offers no additional parameter-level meaning beyond restating that coordinates are used, so it does not exceed the baseline of 3.

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 'Elevation in meters at coordinates' clearly indicates the tool returns elevation based on lat/lon coordinates. It uses a specific resource (coordinates) and output (elevation in meters), which distinguishes it from sibling tools like country, city, or weather. However, it lacks a verb such as 'get' or 'retrieve', making it slightly less explicit.

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 no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Sibling tools cover a wide range of location and data types, but the description does not contextualize elevation among them. This is a clear gap in 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=true, so the safety profile is known. The description adds behavioral context by explaining that 'Deep runs a live mailbox verification,' which goes beyond the structured data without contradicting 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 two short sentences, front-loaded with the primary purpose. Every clause adds substance—no 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?

With only two parameters and no output schema, the description sufficiently covers the tool's core behavior and the deep option. It doesn't describe the response format, but for a validation tool this is arguably acceptable given the simple scope.

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 adds value by clarifying that 'deep' triggers a live verification, complementing the schema's generic 'richer fields' wording for the boolean parameter.

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 validates an email address with specific checks (syntax, domain, MX, disposable, role), distinguishing it from sibling tools like phone or mx. The verb 'validate' and resource 'email address' are explicit.

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 for email validation but does not explicitly compare to alternatives or state when not to use. However, the clear focus and the 'deep' option provide context, so it's solid but lacks explicit 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?

Beyond the readOnlyHint annotation, the description discloses that the tool accepts both names and characters and returns unicode, hex, and skin tones. This adds useful behavioral context for a read-only lookup.

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 single, front-loaded sentence with no waste. Every word contributes to understanding the tool's purpose and output.

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 1-parameter, read-only lookup tool, the description adequately covers purpose and expected output. It could mention handling of not-found input, but overall it 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% for the single parameter, so the baseline is 3. The description reinforces the parameter meaning but adds no new parameter-specific details 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 specific verb ('look up') and clarifies the resource (an emoji), plus the output fields ('unicode, hex, skin tones'). It clearly distinguishes from sibling emoji_search by implying exact lookup vs. 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?

The description provides clear context: use when you have an emoji name or character to look up. It doesn't explicitly mention exclusions or alternatives like emoji_search, but the context is strong enough for a single-purpose lookup 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?

The description adds no behavioral information beyond the readOnlyHint annotation. It does not mention return format, pagination, result limits, or any side effects. With annotations already declaring read-only, the description contributes minimal additional 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 a single, efficient sentence: 'Search emoji by keyword.' It is front-loaded and every word earns its place, with zero 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 search tool with complete parameter schema and read-only annotation, the description is adequate but not complete. It does not explain what the return value looks like (e.g., a list of matching emojis) or any edge cases, which would be expected given the absence of an 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%, with both 'q' and 'limit' described. The description's phrase 'by keyword' aligns with the 'q' parameter, but adds no meaning beyond the schema's own parameter descriptions. Baseline 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 'Search emoji by keyword' clearly states the action (search), the resource (emoji), and the scope (by keyword). This distinguishes it from sibling tools like 'emoji' which might be for lookup rather than search, though it does not explicitly name alternatives.

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 no guidance on when to use this tool versus alternatives like 'emoji' or other search tools. There is no mention of use cases, exclusions, or preferred scenarios.

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, so the read-only nature is established. The description adds behavioral detail about the return row structure (each row carries a type field with values 'public' or 'observance'), which enriches beyond annotations. No contradictions detected.

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, front-loaded with the core purpose, and contains no unnecessary words. Every word contributes to understanding.

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 with only two parameters, and the description covers its main function. However, without an output schema, the description does not detail other returned fields (e.g., date, name) or ordering, which would be helpful. It is adequate but leaves some 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 description coverage is 100%: both 'country' and 'year' have descriptive text in the schema. The description itself adds no extra parameter meaning, but with full schema coverage, the baseline 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 clearly identifies the tool's purpose: returning public holidays and cultural observances for a country and year. It mentions the row type (public or observance), which adds specificity. While it lacks a direct verb like 'list' or 'get', the intent is unambiguous and distinct from sibling tools like holiday_date by the country/year 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 implies usage when needing holidays for a country and year, but it does not explicitly state when to prefer this tool over alternatives like holiday_date, nor does it mention exclusions. The context is present but guidance on alternatives is absent.

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 discloses that 'holiday is null when it is not', which clarifies the return behavior. Combined with the readOnlyHint annotation, this provides adequate transparency for a simple read operation.

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 single, well-structured sentence that conveys the core purpose and a key behavioral detail. No fluff, 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 simple look-up tool with full schema coverage and a readOnlyHint, the description is sufficiently complete. It could benefit from clarifying the difference from the sibling 'holiday' tool, but the core functionality is clear.

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 full descriptions for both parameters (date format and ISO country code), covering 100% of the schema. The description adds no additional parameter semantics, so the baseline 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 states the tool checks whether a specific date is a holiday or observance in a country. It is clear and specific about the resource and action, but it does not explicitly differentiate from the sibling tool 'holiday', which could be a related listing tool.

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 usage context is implied: use this tool when you want to check a specific date's holiday status for a country. However, there is no explicit guidance on when to prefer this over the sibling 'holiday' tool or any 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 declare readOnlyHint=true, so the description doesn't need to restate that. It adds useful context that 'deep' returns datacenter, relay, and tor flags, going beyond the schema's generic 'richer fields.' It doesn't mention error handling or rate limits, but the read-only safety is already established.

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 single, concise sentence front-loaded with the action. Every word contributes to understanding the tool's purpose and the deep parameter's effect, 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 2-parameter lookup tool with no output schema, the description covers purpose and key returned fields. The large sibling tool list is not addressed, but the tool's simplicity makes this less critical. Could mention invalid IP handling, but it's adequate as-is.

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% with descriptions for both parameters. The description adds meaning by naming specific fields returned by 'deep' (datacenter, relay, tor) and listing top-level outputs, enriching the semantic value 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 specific verb ('Look up') and identifies the resource (IPv4/IPv6 address) with key output fields (country, region, ASN, timezone). It doesn't explicitly distinguish from sibling 'ip_self' but the generic phrasing conveys looking up an arbitrary 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?

No guidance is provided on when to use this tool vs alternatives like ip_self, state, or city. It doesn't mention exclusions or recommend alternative tools for related use cases, leaving the choice to inference.

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 agent knows it is safe. The description adds the 'machine running this MCP server' context but does not mention potential external network calls or cost details (the 'Paid' note is in the schema, not the description). This is adequate 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 a single, front-loaded sentence that communicates the complete purpose with zero waste. It is highly concise and well-structured.

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?

This is a very simple read-only lookup with strong annotation coverage and a fully documented schema. The description adequately covers the tool's purpose and scope, and no return format explanation is necessary for something as simple as an IP address.

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 covers 100% of the single parameter with a descriptive explanation ('Include the nested deep object with richer fields. Paid on most endpoints.'). The tool description adds no additional parameter information, so it meets the baseline but does not exceed it.

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 action ('Look up') and the specific resource ('public IP of the machine running this MCP server'), which distinguishes it from the sibling 'ip' tool. It 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?

The context is clear: this is for the server's own public IP, distinct from the 'ip' tool which likely handles arbitrary IPs. However, it does not explicitly state when not to use it or name alternatives, so it stops short of 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds behavioral context by specifying the accepted code standards (BCP 47, ISO 639-3) and the output fields, going beyond the structured data.

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?

One compact sentence containing the action, parameter scope, and return content. No wasted words, fully 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?

This is a simple one-parameter lookup tool with no output schema, and the description sufficiently covers inputs, accepted standards, and return fields. No significant 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 already describes the 'code' parameter with examples. The description enriches parameter understanding by naming the exact code standards accepted, which adds semantic precision not present in 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 clearly states the tool's function: 'Look up a language by BCP 47 or ISO 639-3 code' and specifies the returned data: 'names, script, direction'. This is a specific verb+resource with enough detail to 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?

The description implies when to use the tool: whenever a language code needs to be resolved to detailed language info. It doesn't explicitly mention alternatives, but no sibling tool provides language lookup, so the context is 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?

The annotation readOnlyHint=true already signals this is a safe read operation. The description adds the concept of 'mail provider' but does not mention any behavioral details such as DNS lookup behavior, result formatting, or potential errors. It does not contradict the 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 a single short phrase with no wasted words, making it very concise. However, it lacks a verb, which slightly reduces its clarity as a complete statement of what the tool does.

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 one-parameter tool with no output schema, the description gives a reasonable sense of what is returned (MX records and provider). It does not specify the exact format or whether multiple records are returned, but given the simplicity, it is adequate.

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 fully describes the only parameter 'domain' as 'Domain name', and the description echoes that by saying 'for a domain'. Since schema coverage is 100%, the description does not need to add much, and it adds no additional semantic detail beyond what is already 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 identifies the tool as returning MX records and mail provider information for a domain. It distinguishes itself from sibling tools like domain and email by specifying the exact DNS record type, though it lacks an explicit verb such as 'looks up' or 'returns'.

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 'for a domain' implies the tool should be used when needing MX records or mail provider details for a given domain, but it does not give explicit guidance on when to choose this over related sibling tools like domain or email. There are no stated exclusions or alternative recommendations.

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, indicating a safe read operation. The description adds a behavioral note about country usage but does not disclose error handling, rate limits, or side effects. It does not contradict annotations, but it also does not go beyond the provided annotation 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 a single, well-structured sentence that front-loads the primary action ('Validate and parse a phone number') and includes a conditional usage tip. Every word earns its place; 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 the tool's simplicity and lack of output schema, the description provides enough context by mentioning expected outputs (country, type, formats) and the key parameter condition. It does not explain the return structure in detail, but for a basic validation tool with high schema coverage, it is 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?

The schema has 100% parameter description coverage, so the baseline is 3. The description repeats some schema info (e.g., country for national-format numbers) but does not add new meaning to the parameters. The deep parameter is only explained in the schema, not in the description.

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 validates and parses a phone number, listing specific output aspects: country, type, and formats. It is specific with a verb and resource, and it differentiates from siblings like email or domain by focusing on phone numbers.

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 concrete usage guideline: 'Pass country for national-format numbers', which tells the agent when the country parameter is needed. It implies general use for phone number validation without explicitly naming alternatives, but the guidance is clear and actionable.

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 readOnlyHint=true in annotations, the safety profile is covered. The description adds the detail that 'deep' provides richer admin data, but does not disclose response structure or error behavior, which is acceptable for a simple read-only 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?

Two short sentences with no filler. The first sentence states the core function, and the second addresses the optional parameter. Very efficient.

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 read-only reverse geocoder with 3 parameters, the description covers the main purpose and the deep parameter. It lists the output fields, which is helpful given the absence of an output schema. Minor gaps like return format or limitations prevent a perfect score.

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's mention of 'Deep adds richer admin data' adds slight semantic value for the deep parameter, aligning with the schema's 'richer fields' description.

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 performs reverse geocoding from coordinates, listing the specific administrative outputs (country, state, district, nearest city). This distinguishes it from sibling tools that operate on names or identifiers.

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?

Usage is implied: if you have coordinates and need admin hierarchy, this is the tool. However, there is no explicit comparison to alternatives like city_nearest or postal_nearby, nor exclusions for when not to use it.

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 readOnlyHint annotation already signals a safe read operation. The description adds the return fields and the country requirement, which is useful context, but it does not disclose additional behavioral details like coordinate format or potential 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 two concise sentences that front-load the action and enumerate the return fields without any redundant wording 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?

Because there is no output schema, the description sensibly lists the return fields. It also states the country requirement, covering the essential context for a simple lookup, though it leaves minor details (e.g., coordinate format) unspecified.

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 clear descriptions for both code and country. The description only reinforces the required country parameter, adding minimal value 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 specific verb 'look up' with the resource 'postal code' and lists the returned fields (place name, coordinates, state, district, timezone, elevation). This clearly distinguishes it from sibling tools like postal_nearby and postal_distance which imply proximity-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 clearly frames the tool as a direct postal code lookup, and the note 'Country is required' gives a clear prerequisite. However, it does not explicitly mention alternative tools such as postal_nearby or postal_distance, so it provides context without 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?

The readOnlyHint annotation already discloses this is a safe read operation. The description adds the meaningful constraint that both postal codes must be in the same country, but does not disclose return units (e.g., km/miles), behavior for invalid codes, or whether it returns a straight-line or driving distance. 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 a single, front-loaded sentence with zero filler. It conveys the core function and the key constraint without unnecessary words, fully earning 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?

The tool is simple with only three required parameters and no output schema. The description does not mention the return value format or units, which could be a gap for an agent needing to interpret the result. However, the tool's purpose is trivial enough that a skilled agent can infer the output is a distance measure. The missing details about units and error handling prevent a higher score.

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 schema already describes all three parameters. The description adds semantics beyond the schema by emphasizing the 'same country' requirement, which clarifies that the 'country' parameter must match for both 'from' and 'to' postal codes. This extra context is valuable but not extensive.

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: computing distance between two postal codes in the same country. It is unambiguous, though expressed as a noun phrase rather than an explicit verb+resource construction. It distinguishes from siblings like 'postal' and 'postal_nearby' by focusing on distance calculation, but does not explicitly name them.

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 for distance calculations between postal codes but provides no explicit 'when to use this vs alternatives' guidance. It mentions the constraint 'in the same country,' which is a precondition, but does not discuss exclusions or alternatives such as 'postal_nearby' for proximity queries. There is no comparative 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 readOnlyHint annotation already signals a safe read operation. The description adds the behavioral detail that results are sorted by distance, which is useful beyond the annotation. However, it does not disclose other potential behaviors such as default radius, maximum results, or pagination, leaving room for more 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 a single, front-loaded sentence that states the core function and a key behavior (sorting). Every word earns its place, and there is no redundant or missing 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 no output schema, the description could have clarified what the result includes (e.g., postal codes with distances). It also does not mention default units or radius limits, though those are in the schema. Given the schema covers parameters and the sibling context provides some structure, the description is adequate but not rich enough for a higher score.

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 descriptions for all four parameters at 100% coverage. The description does not add much beyond schema semantics—it reiterates the concept of 'near' but does not clarify parameter interactions (e.g., what happens if radius is omitted). Since schema coverage is high, the baseline 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 clearly states the tool's function with a specific verb ('List'), resource ('postal codes near a given one'), and distinguishing detail ('sorted by distance'). This separates it from siblings like postal or postal_distance, which focus on individual codes or distance calculations.

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: use this tool when you need nearby postal codes sorted by distance. However, it does not explicitly mention when to prefer this over alternatives like postal_distance or postal, nor does it state any exclusions or prerequisites. The context is clear but not explicitly differentiated.

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 readOnlyHint annotation already declares that this is a safe read operation, so the description doesn't contradict it. The description adds 'Look up' which aligns, but it doesn't disclose additional behavioral details such as return format or edge cases. For a simple lookup, 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 entire description is a single, focused sentence that directly conveys the tool's purpose without unnecessary words. It front-loads the action and resource.

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 a straightforward read-only lookup with both parameters documented in the schema, so the description doesn't need to elaborate much. It lacks an explicit mention of the return value, but given the sibling structure and the name 'state', this is a minor gap. Overall, sufficient 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 input schema already provides descriptions for both parameters with 100% coverage, including examples (NC, US). The description's 'by its code within a country' adds no new information beyond the schema. Under high schema coverage, the baseline is 3.

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') and clearly identifies the resource (state/province/region) and the lookup key (code within a country). It differentiates from sibling tools like country_states and state_districts, which serve different listing purposes.

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 the required inputs (a code and a country) and the lookup use case. It doesn't explicitly mention alternatives, but the context of sibling tools (e.g., country_states for lists) makes the usage clear. No exclusions are stated, so a 4 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, so the description does not need to assert read-only behavior. It adds the scope of returned entities (districts/counties/departments), but does not disclose other behavioral traits such as response shape or error behavior. This is consistent with annotations, not contradictory.

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 single, concise sentence with no filler. It front-loads the action and resource, making it efficient 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 two-parameter, read-only list tool with full schema coverage and a read-only annotation, the description is adequate. It lacks an explicit mention of return format (e.g., names vs codes), but given the low complexity and available annotations, it is mostly complete. A full score would require more detail on the output structure.

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 both 'code' and 'country' explained. The description does not add additional parameter context beyond what the schema provides, so the baseline 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 verb 'List' and the resource 'districts, counties or departments of a state', making the tool's purpose explicit. It distinguishes from sibling tools such as country_states (states of a country) and district (singular lookup) by specifying the plural subdivision of a state.

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 when you need subdivisions of a state, but it does not explicitly state when to use this tool versus alternatives like country_states or district. No exclusions or prerequisites are mentioned, so guidance is only 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?

The readOnlyHint annotation is consistent with the description, and the description adds behavioral context beyond the annotation by specifying the exact information returned (offset, DST state, local time) and the optional instant parameter. No contradictory or hidden behaviors are omitted.

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 short sentences, front-loaded with the primary action and output. Every word adds value, with no fluff or repetition of schema fields. This is an example of efficient, concise writing.

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 read-only lookup with two parameters and no output schema, the description fully covers the tool's behavior and return values. It explains both the default (current time) and the optional instant, making it complete 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?

The input schema already provides full descriptions for both parameters (timezone and at), achieving 100% schema coverage. The description adds a minimal semantic hint for 'at' ('Pass at for a specific instant') but does little beyond what the schema states, 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 clearly states 'Look up an IANA timezone' with a specific verb and resource, and enumerates the output fields: 'current offset, DST state, local time'. This distinguishes it from sibling tools like weather or country 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 context for when to use the tool and mentions the optional 'at' parameter for evaluating a specific instant. It does not explicitly name alternatives or exclusions, but the tool's purpose is unique among the sibling list, so the guidance is sufficient.

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 behavioral context by listing the extracted categories (browser, OS, device, bot detection), complementing the readOnlyHint annotation. It does not contradict annotations and provides useful information about what the tool returns.

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 single, focused sentence that conveys the essential purpose without unnecessary 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 simplicity of the tool and the presence of annotations, the description covers the core functionality. It does not explain return format, but the listed parse outputs (browser, OS, etc.) give a reasonable picture. A 4 is appropriate.

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 parameters are fully documented in the schema. The description does not add additional parameter-level details beyond stating the tool parses a UA string, so a baseline 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 the specific verb 'Parse' and identifies the resource (User-Agent string) and the outputs (browser, OS, device, bot detection). This clearly distinguishes it from sibling tools that handle locations, email, phone, etc.

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 clearly indicates the tool's purpose but does not explicitly mention when not to use it or name alternatives. However, given the unique domain, the usage context is clear, so it earns a 4.

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 provide readOnlyHint=true; description adds context that data comes from official national agencies, measurements include both metric and imperial, and deep adds forecast/alerts. This goes beyond simple read-only labeling and is consistent 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?

Two sentences, front-loaded with the core function, and no wasted words. Each sentence earns its place, providing main behavior and optional enhancement.

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?

Tool has 3 params, no output schema, and simple read-only nature. Description covers purpose, data source, units, and deep option. It doesn't list specific fields like temperature/humidity, but this is acceptable for a straightforward weather observation 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?

Schema covers all three parameters thoroughly (lat, lon, deep). Description adds semantic value by explaining deep's effect ('adds forecast and alerts') beyond the schema's generic 'richer fields' description, giving agents a clearer use-case.

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?

Description clearly states 'Current weather observation at coordinates' – a specific verb (observation) and resource (coordinates). It distinguishes from sibling geo tools by focusing on weather, with no ambiguity.

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?

Implies usage for current conditions at lat/lon, and mentions 'deep' for forecast/alerts, giving conditional guidance. No explicit alternatives or exclusion criteria, but siblings are clearly not weather tools, making the context clear.

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