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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is fully covered. The description's only added behavioral insight is that results are joined across the administrative hierarchy, which tells the agent the payload is enriched rather than raw village rows. It says nothing about pagination behavior or total result size.

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, front-loaded with the core action and scope before the filter details. Nothing is padded, though the second sentence is terse enough to border on underspecified.

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 note that records are joined across the full administrative hierarchy is valuable disclosure about return shape. Pagination semantics remain uncovered, which is a real gap for a list tool that could return many rows.

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

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

Schema description coverage is 0%, so the description must carry the load. It usefully translates provinsi_id/kabupaten_id/kecamatan_id into province/regency/district filters, covering three of five parameters, but page and per_page (default 20, maximum 100) are left entirely undiscussed.

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 names a specific verb and resource (list villages with postal codes) and adds that records are joined across the full administrative hierarchy. It is distinguishable from kodepos_get (single lookup) and kodepos_search by the 'list' framing, though it never explicitly contrasts itself with those siblings.

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 states that filters by province/regency/district are optional, which implies the tool can be called bare or narrowed. There is no explicit guidance on when to prefer this over kodepos_search, nor any warning about result volume when no filters are supplied.

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