get_urban_train_facility

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

With no annotations, the description carries the full behavioral burden and covers it well: it warns that some facility types may return empty results per operator, requires reporting data recency based on _meta's '데이터수정일' with tone varying by freshness, and explicitly forbids fabricating data when results are empty. Side-effect, auth, and error behavior are not addressed, keeping it below 5.

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 purpose is front-loaded and the parameter reference block is compact, but roughly half the description is a verbose answer-guidelines section covering response tone, phone-number policy, and deduplication rules — behavior that arguably belongs in a system prompt rather than a tool definition. It is well-organized but oversized for its tool-selection and invocation purpose.

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?

All four parameters are documented, the output schema covers return values, empty-result behavior is specified, and the prerequisite sibling get_urban_train_composition is named. Missing is an explicit distinction from get_urban_train_environment and operator-code formatting details, but the tool is invocable without them.

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%, and the description fully compensates: it expands facility_type into all 10 enum values with Korean labels, defines operator as '운영기관 코드/명', maps scar_seq to scarSqno with an example ('1'), and maps composition_type to cpsTpCd. Every parameter receives meaning the schema does not provide.

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 opening line '도시철도 차량(호차)별 시설 조회 (역 무관)' names a specific verb (조회/lookup) and resource (facilities by urban railway carriage), and the '(역 무관)' qualifier distinguishes it from the many station-based sibling tools. It stops short of a 5 because it does not explicitly differentiate itself from the similar-sounding get_urban_train_environment.

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?

One explicit routing instruction is present: 'get_urban_train_composition으로 먼저 확인한다' (verify composition type with get_urban_train_composition first), and the caution that operators differ so some facility types return empty results sets interpretation expectations. However, there is no explicit when-to-use versus alternatives, no exclusions, and no guidance on how to choose between this and get_urban_train_environment.

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