get_mainline_distance_per

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add genuinely useful context: update timing (매월 1일, M-2) and the meaning of run_ym as the operating year-month. However, it does not disclose read-only nature explicitly (implied by the 'get' prefix), behavior when run_ym is empty (the schema marks it optional with an empty default), or any pagination or limits. The freshness disclosure partially compensates for the missing annotation layer, but other behaviors remain undocumented.

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 a single efficient sentence that front-loads the purpose before the parameter hint, with zero filler. The refresh-cadence parenthetical and the parameter format are both compact and relevant. It is appropriately short for a single-parameter query tool, though the terse style contributes to the under-specification noted in usage guidance.

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 one-parameter tool with an output schema present (so return values need not be explained), the description covers purpose and format reasonably well. The gaps are sibling disambiguation and empty-parameter behavior. Given the large, heavily overlapping sibling set (especially other mainline 'per' statistics), the lack of any distinguishing guidance makes the definition incomplete for confident tool selection.

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 compensate, and it partially does:run_ym=운행연(YYYYMM)' clarifies the expected format, which is the single most critical semantic for this parameter. However it does not explain that the parameter is optional (schema shows required: 0 with an empty default), what value to use for current data, or provide an example. The format hint is valuable but the optionality and fallback behavior unexplained.

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 purpose: '간선열차 거리별 이용인원 통계' (mainline train distance-based passenger usage statistics), naming both the resource (mainline trains) and the aggregation dimension (distance). This is clear and matches the name's 'distance_per' signal. It does not, however, name any sibling it is distinct from, which weakens differentiation given the many similar 'per' tools in the sibling list (station_per, route_per, grade_per, ticket_stat, person_distance).

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?

There is no guidance on when to choose this tool over its many siblings, such as get_mainline_person_distance (which might appear to overlap on distance) or the other mainline 'per' statistics. The only contextual hint is the refresh cadence (updated 1st of each month, M-2 lag), which speaks to data freshness rather than selection criteria. With 72 siblings including several distance-like tools, the absence of any alternative-routing guidance is a meaningful gap.

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