get_us_sector

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it returns top companies and market share, but does not disclose other behavioral aspects like pagination, rate limits, or what happens with invalid sector keys. Given the annotations cover safety, this is adequate but not rich.

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 reasonably concise, with a clear opening line, example queries, and a parameter list. There is some redundancy between English and Korean phrases, but it does not detract from readability. The structure is front-loaded with the 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?

With an output schema present, return values are likely documented elsewhere. The description covers the tool's purpose, parameter values, and example usage, making it fairly complete for a simple two-parameter tool. It lacks error-handling details but those are probably not essential for this kind of read-only overview.

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 must compensate. It does so effectively by listing all valid sector_key values (technology, healthcare, etc.) and explaining top_n as 'top 기업 수 (기본 20)' (number of top companies, default 20). This fully documents both parameters beyond the bare schema.

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 clearly states the tool provides a US sector overview with top companies and market share ('US sector overview — 미국 섹터별 top 기업 + 시장 비중'). It also gives example queries to clarify intent. However, it does not explicitly differentiate from sibling tools like get_sector_stocks or list_sectors, which could be similar in scope.

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 provides example queries ('기술주 섹터', 'healthcare top companies', '섹터 비중') that indicate when to use the tool. However, it does not mention alternatives or explicitly state when not to use it, leaving the agent to infer from context.

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