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

Annotations only declare it read-only; the description adds the auth dependency, per-call cost ('호출마다 토큰 1소진'), and detailed idempotency-key lifecycle semantics — generate before first request, reuse only to recover a lost response, new key for a new execution. It also distinguishes this key from a provider-specific idempotency_key field, a non-obvious pitfall. Nothing contradicts readOnlyHint=true.

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-loading the session prerequisite is good, but the idempotency guidance spans four sentences and repeats itself ('Without it, calling again remains a new request'), and the phrase 'anonymous taste calls' reads as a typo that could confuse an agent. Serviceable but not tight.

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 exists, and the description does not sketch the shape of results, but it covers everything needed to invoke correctly: auth prerequisite, mandatory identifiers, idempotency handling, and token cost. For a read-only search tool that is close to 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the two required identifiers are mandated by 국세청 and the session TIN cannot substitute for them, which warns against a plausible wrong invocation. It also explains the optional request_idempotency_key's purpose in prose rather than leaving it to 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?

States a specific verb and resource plus scope: 'Search unclaimed tax refunds (최근 5년간 미수령 국세환급금)'. That is enough to separate it from the sibling hometax__tax__refund__search_detail in spirit, though the sibling is never named explicitly, which keeps it short of a 5.

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?

Gives a clear prerequisite ('REQUIRES prior hometax__session__login call with same account_link_id') and a concrete usage constraint ('Both txpr_dscm_no and txpr_nm are required... the session TIN does not substitute'). It does not say when to prefer this over the refund detail sibling or when-not-to-use, so no explicit alternative routing.

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