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

Annotations already cover the read-only, idempotent, closed-world safety profile, yet the description still adds real behavioral detail: exact vs prefix matching semantics, tolerance for hyphens and full-width numerals, the shape of returned candidates (kana, supplementary notes, town representative point), and a data source attribution. It stops short of covering invalid-input or no-result behavior.

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 compact sentences: what it returns first, matching rules second, source last. No filler, and the most decision-relevant information is 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 two-parameter read-only lookup with annotations and no output schema, the description is nearly complete: it describes the returned fields and the input format rules. The only gap is error/no-match behavior and how limit applies to prefix results.

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 baseline would be 3, but the description adds meaning beyond the schema by clarifying that short codes trigger prefix matching and that hyphens/full-width digits are normalized. It does not explain how limit interacts with prefix matches, which keeps it from a 5.

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?

States a specific verb and resource: returns prefecture/city/town-area candidates from a Japanese postal code, with kana readings and representative points. An agent understands exactly what the tool returns, but no sibling is named (e.g., reverse_geocode for the opposite direction), so differentiation is left to inference.

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

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

The description explains matching behavior ('7 digits = all exact matches, 3-6 digits = prefix match') and accepted input forms (hyphens, full-width digits), which implies how to use it. However, it never states when to prefer this over reverse_geocode or what to do when no match is found, so guidance is implied rather than explicit.

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