sentence_statistics

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

Annotations already mark the tool read-only and idempotent, so the description adds substantial behavior beyond them: sample-size-dependent output (30+ aggregated stats vs status=low_n_grid individual cases), status values, the prohibition on combining charge distributions, the Criminal Act 38 caveat, and the citation-link rule. This goes well beyond what annotations provide.

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 long and dense, but it is well structured with numbered modes, a usage-context sentence, warnings, and an Args section. Some sentences, such as the Criminal Act 38 explanation, are verbose, but they carry necessary misuse warnings. It is front-loaded with the core purpose and required-parameter condition, though it could be tightened.

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 5 parameters, 0% schema coverage, and an output schema present, the description covers all essential operational aspects: required parameter choice, mode switching, sample-size thresholds, output statuses, and output citation rules. Nothing critical an agent needs to call it correctly is missing.

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 0%, so the description is the only source of parameter meaning. It explains charges (candidate search, accepts colloquial/category/statute names), charge_id (pool id, mutually exclusive with charges), year_from/year_to (judgment year range), and reference_year (base year, None=recent). This fully compensates for the schema gap.

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 opens with '양형 선고 통계' and immediately explains the two-mode flow: charges returns charge candidates (status=candidates) and charge_id returns sentencing distribution for a single charge. It explicitly distinguishes itself from compute_sentencing_range by noting it complements that formula with real data. The verb+resource is specific and the two modes are clearly differentiated.

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 gives explicit when-to-use context: '형량 전망·구형/양형 근거·자기 사건 위치를 가늠할 때 결론 전에 호출' and names the alternative compute_sentencing_range as being complemented. It also provides when-not guidance: candidates are not statistics, one charge at a time, and do not combine distributions across charges. This is strong usage guidance even though it does not explicitly mention precedent_search or statute_lookup.

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