call_krx_api

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns raw JSON without processing and that the API key is auto-injected. However, it doesn't disclose potential failure modes (e.g., what happens if the API returns an error, rate limits, or whether the tool validates parameters). The description adds some behavioral context but not comprehensive transparency.

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 concise and front-loaded: the main purpose is stated in the first sentence, and the API key injection note is a useful addition. The api_id catalog is long but necessary for a tool with 31 possible values. The structure is clear, though the catalog could arguably be moved to the schema (it already is partially there). Overall, every sentence earns its place.

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?

Given the tool's complexity (31 API IDs, nested params object, no output schema), the description is fairly complete. It explains the raw return behavior and key injection. However, it doesn't mention error handling, response format details, or how to discover valid param values for each API ID. Since there's no output schema, a bit more about the return shape could help, but the 'raw JSON' statement covers the basics.

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 100%, so the schema already documents both parameters. The description adds value by explaining the api_id catalog in detail (31 service IDs with Korean labels) and giving examples for params. This goes beyond the schema's basic descriptions, helping an agent understand what values to pass. The description doesn't repeat the schema verbatim but enriches it.

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 ('호출하여'), a specific resource (KRX 공식 오픈API), and a clear behavior (원본 JSON을 가공 없이 그대로 반환). It also mentions automatic API key injection, which distinguishes it from sibling tools like call_dart_api. The description is unambiguous and tells an agent exactly what this tool does.

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?

The description implies when to use this tool: when you need raw KRX open API data without transformation. It doesn't explicitly state when not to use it or name alternatives, but the sibling list (call_dart_api, download_dart_document, search_corp_code) makes the context clear. The description could be stronger by explicitly saying 'use this for KRX data, not DART data', but the resource is clearly identified.

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