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

Annotations already set readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: requires sthan.io API key, each call counts toward rate limit (free tier available), on failure returns error message. No contradictions.

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

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

Three sentences: first states purpose, second provides usage guidance and alternatives, third adds constraints. Every sentence is essential and 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?

Given no output schema, description explains it returns a list of suggestions but omits format details. However, annotations and sibling context compensate. Reasonably complete for an autocomplete 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 100% of the single parameter 'text' with description. Description adds recommendation '3+ characters' and example '123 Main', providing practical guidance beyond schema.

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

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

Clearly states it returns US street-address suggestions for partial input, for type-ahead/autocomplete fields. Distinguishes from sibling tools like sthan_autocomplete_city and sthan_autocomplete_zipcode.

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?

Explicit when to use (while user is typing an address to offer full matches) and when not (for city-only or ZIP-only use other tools; to validate finished address use sthan_verify_address). Also mentions API key requirement and rate limit.

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, idempotentHint=true, destructiveHint=false. The description adds value by stating 'Read-only with no side effects,' mentioning the API key requirement, rate limits, free tier availability, and error behavior. No contradictions with annotations.

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

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

The description is front-loaded with the main purpose, followed by usage guidance, sibling differentiation, and additional context. Each sentence serves a distinct purpose with no redundancy. Two lines in length.

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

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

Given no output schema, the description could specify the output format more explicitly, but the display_type parameter implies the format (City, StateCode or City, State). It covers input, usage, authentication, rate limits, and error handling. Slightly incomplete on exact response structure but sufficient for an autocomplete 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 description coverage is 100% with both parameters having descriptions (text and display_type). The description does not add any additional parameter meaning beyond what the schema provides. 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 the tool returns US city suggestions for partial input. It specifies the use case (city-field type-ahead, resolving partial city name) and distinguishes from sibling tools (sthan_autocomplete_address, sthan_autocomplete_zipcode). The verb 'return' is specific and appropriate.

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?

Explicitly states when to use (city-field type-ahead) and when not (street addresses or ZIP codes), with direct references to alternative tools. Also provides context on API key requirement and rate limits.

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, idempotentHint, etc. Description adds API key requirement, rate limit counting, free tier availability, and error behavior, providing complete 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?

Three concise sentences: purpose, usage guidance, and behavioral notes. Every sentence adds value; 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 read-only autocomplete tool with rich annotations and full schema coverage, the description covers all necessary aspects: purpose, usage, alternatives, authentication, rate limits, and error behavior.

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. Description mentions optional ZIP+4 but does not significantly add meaning beyond what the schema 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?

Directly states it returns ZIP code suggestions for partial input with state and optional ZIP+4, and explicitly distinguishes from sibling tools (sthan_autocomplete_city, sthan_autocomplete_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?

Explicitly says 'Use for ZIP-field type-ahead or to expand a partial ZIP' and provides clear alternatives for city and address lookups, guiding when not to use this tool.

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

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

Annotations already mark it read-only, idempotent, non-destructive. Description adds: requires API key, counts toward rate limit, free tier available, returns error on failure. No contradiction.

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?

Description is concise, front-loaded with action and return values. Every sentence adds value without 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 single-parameter tool without output schema, the description fully covers return fields, authentication, rate limits, and error behavior. No gaps.

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

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

Schema coverage is 100% with description for the address parameter. Description adds an example and format guidance (freeform text), which provides practical context beyond schema.

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

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

Clearly states the tool converts US addresses to latitude/longitude coordinates. Lists return fields (coordinates, formatted address, accuracy type, confidence). Distinguishes from sibling tools like reverse_geocode and verify_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?

Explicitly states when to use (need map coordinates) and names alternatives (reverse geocode, verify address). Provides clear guidance on selection.

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, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: 'Read-only with no side effects,' authentication requirement ('Requires a sthan.io API key'), rate limit info ('each call counts toward your plan's rate limit'), and failure behavior ('On failure it returns an error message'). It also notes that some fields may be null. This goes beyond annotations, though the annotations already cover the core safety profile.

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

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

The description is well-structured with the core purpose front-loaded. Each sentence adds meaningful information: purpose, returned fields (with nullability), use cases, disambiguation from siblings, authentication, rate limits, and error behavior. While slightly verbose, there is no redundancy, and all content earns its place. A minor improvement could be combining the last two sentences for brevity.

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 (one parameter with full schema coverage, no output schema, rich annotations), the description covers all aspects: purpose, inputs, outputs, usage guidance, behavioral traits, authentication, rate limits, and error handling. It is fully complete for effective agent selection and 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?

Schema description coverage is 100%, so baseline is 3. The description includes example IPv4 and IPv6 addresses (e.g., '8.8.8.8', '2001:4860:4860::8888') which add clarity but are also implied by the schema's description. No additional constraints or usage nuances are provided beyond the schema, so the description does not significantly enhance parameter understanding.

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 the approximate geographic location of an IPv4 or IPv6 address.' It specifies the action ('look up'), resource ('geographic location'), and input type ('IPv4 or IPv6'), making it immediately clear. It also lists returned fields and distinguishes from siblings about street addresses, ensuring no confusion with other 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 explicitly provides when-to-use scenarios ('for example for analytics or choosing a default region') and when-not-to-use instructions: 'This locates IP addresses, not postal addresses; to work with a street address use sthan_verify_address, sthan_parse_address, or sthan_geocode.' It cites specific alternative tools, offering clear 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds: 'Read-only with no side effects' and explains failure behavior (error messages for invalid API key or rate limit). This goes beyond annotations and gives the agent complete 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?

Single paragraph but well-structured: purpose, usage, limitations, requirements, failure behavior. Every sentence adds value with no fluff. Information is front-loaded and 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?

No output schema, so description must cover return values. It lists the structured components but does not explicitly state the output format (e.g., JSON object). However, the list and the failure behavior are sufficient. The tool is simple with one parameter, and the context is well-covered. Minor gap in output format detail.

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 100% of parameters with description, baseline 3. Description provides additional context: 'Raw address text to parse. Freeform input, abbreviations OK. Example: ...' This adds practical guidance beyond the schema's brief description, justifying a 4.

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: breaking a freeform US address string into structured components. It lists the specific components (address number, street name, etc.) and distinguishes from sibling tools by stating what it does not do (deliverability confirmation via sthan_verify_address, coordinates via sthan_geocode). This 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?

Explicitly says 'Use when you have messy or unstructured US address text and need the individual fields.' Also clarifies when not to use it (for deliverability or geocoding) and points to siblings. Provides prerequisites (API key) and side effects (rate limits). Comprehensive 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, idempotentHint, destructiveHint. The description adds beyond that: mentions read-only nature ('no side effects'), requires API key ('STHAN_API_KEY'), rate limit, and free tier availability. It also states failure returns an error message but doesn't specify format. Overall good transparency.

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

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

Four sentences, each adding essential information. Front-loaded with purpose. No redundant or verbose content.

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, no output schema, strong annotations), the description covers purpose, usage, limitations, alternatives, side effects, authentication, and error behavior. It is fully adequate 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?

Schema coverage is 100% and both parameters have clear descriptions (latitude, longitude with min/max). The description does not add further semantic detail beyond confirming the coordinate pair. Baseline 3 is appropriate given 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 explicitly states the action (Convert coordinates to address), the resource (US street address), and lists specific return fields (address, distance, accuracy, confidence). It directly distinguishes from the sibling tool 'sthan_geocode' by specifying the reverse direction.

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

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

Provides clear when-to-use guidance: 'Use when you have coordinates and need the closest address.' Also explicitly names the alternative for the opposite operation: 'To go the other way (address to coordinates) use sthan_geocode.' Additionally notes US-only coverage as a limitation.

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, openWorldHint, idempotentHint, destructiveHint=false. Description adds important operational context: requires STHAN_API_KEY, counts toward rate limit, mentions free tier, and describes error responses. 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?

Front-loaded with main purpose, then provides details in a logical order. Efficient use of sentences, though slightly verbose in explaining return fields that could be in output schema.

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

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

No output schema, but description thoroughly explains return values (standardized address, ZIP+4, county, deliverability status, dpvConfirmation code with meanings). Addresses key considerations: API key, rate limits, 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?

Schema has 100% coverage for the single parameter 'address' with a clear description. The tool description adds examples of input formats, which is helpful but not substantial beyond schema.

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

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

Clearly states it verifies US street addresses for deliverability, lists specific return fields (standardized address, ZIP+4, county, deliverability status, dpvConfirmation code), and distinguishes from siblings like sthan_geocode and sthan_parse_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?

Explicitly says when to use (confirm address, clean data, before shipping) and when not to (non-US, get map coordinates, split address without checking), and includes explicit alternatives (sthan_geocode, sthan_parse_address).

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