Home count for heavy rates

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds domain-specific behavior beyond annotations: statutory exclusions are applied automatically ('불산입 자동 적용'), and the counted number varies by heavy_tier even for the same house. It does not describe return type or performance characteristics, but this is a meaningful addition over structured 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 dense and long, but it is front-loaded with the English purpose sentence followed by Korean statutory details. Almost every clause adds substantive domain information required to invoke the tool correctly, though the English summary and Korean opening are slightly redundant. Overall it is appropriately sized for a complex tax-counting tool.

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 description indicates that the tool returns a home count and connects it to judge_transfer_reliefs's heavy_home_count field, which is enough to understand the return's purpose. It thoroughly covers the input domain and automatic exclusions, but it does not specify the exact return type or boundary cases (e.g., empty items), leaving a minor gap for a tool of this complexity.

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 full parameter burden, and it does. It defines the item object fields with meanings, units, and value domains (e.g., 종류 values, 기준시가 basis differences for 입주권 vs 분양권), explains the small-new-house judgment fields, and describes heavy_tier values 2 and 3 with their different counting rules. This richly compensates for the empty schema descriptions.

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 states a specific verb and resource (count homes for heavy capital gains rates) and scopes it by exclusions. It distinguishes itself from the non-taxable home count by explicitly saying '비과세용 주택수와 별개' and links the result to judge_transfer_reliefs's heavy_home_count. An agent can identify this as the heavy-rate home-counting tool without opening other schemas.

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 clearly frames the tool's use for heavy capital gains rates and explicitly excludes non-taxable home counting ('비과세용 주택수와 별개'). It also explains how to choose heavy_tier (2 vs 3) based on the applicable statutory series. However, it does not name the alternative tool (e.g., count_transfer_homes) for non-taxable situations, so the alternative routing 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.