enrich_address_v1_enrich_address_post

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal two non-obvious traits: the 'LLM Waterfall fallback' for complex international formats and the flat cost of 1 credit per request. It does not, however, explain failure behavior, latency implications of the waterfall, or any rate limits—leaving the agent partially informed. That is a reasonable but not exhaustive disclosure.

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 tight two-sentence structure: first states the core transformation and the standout feature, then the cost. Every sentence earns its place. No fluff, no redundant restatement of the tool name, and it is front-loaded with the primary purpose before mentioning cost.

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 transformation tool with no output schema, the description refers to 'standardized JSON components', indicating the return type. Usage constraints appear in the parameter description, and cost is disclosed. The context parameter's children are well-documented. The only gap is a lack of clarification about what happens when parsing fails (e.g., fallback behavior details, error messages), but overall an agent can call this tool correctly with the given information.

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 50%, but the address_line parameter description adds substantial semantics: it defines the expected input type (full mail-like address), gives examples, and includes explicit usage and negative constraints. The context parameter's child properties each have clear descriptions (locale, timezone, transliterate, target_currency). The tool description itself adds no parameter detail, but the schema's parameter descriptions carry the load effectively, leaving only the context container itself somewhat opaque.

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 verb ('transforms') and resource ('messy, unstructured address strings') into structured JSON components. It uniquely identifies the tool among many enrich_* siblings (enrich_date, enrich_amount, etc.) by focusing on address parsing. The mention of an 'LLM Waterfall fallback' adds a distinct capability, leaving no ambiguity about what this tool does.

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?

While the top-level description lacks explicit usage guidance, the address_line parameter description compensates with direct instructions: 'USE THIS TOOL for any messy or unstructured location data' and a NEGATIVE CONSTRAINT excluding city-only, country-only, or coordinate-only inputs. This gives clear when-to-use and when-not-to-use criteria. However, it does not name alternative sibling tools explicitly, 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.