get_us_earnings

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what data is returned (next earnings date + EPS surprise history) and why it matters. No contradiction with annotations. It doesn't disclose limitations like data freshness or ticker-format strictness, but with strong annotation coverage a 3 is appropriate.

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?

Front-loaded with the core purpose before examples. The example queries and the one-line context about US earnings being key events each earn their place. Slightly verbose with the Korean translations of English terms, but nothing is wasted.

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?

Has an output schema, so return-value details don't need description coverage. With a single required parameter that's documented with an example, and clear purpose plus usage examples, an agent has enough to call it correctly. Minor gap: no guidance on how the two data components (date vs surprise history) are shaped.

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 for the undocumented ticker parameter. It does document 'ticker: US 티커 (예: "NVDA")' with a concrete format example. However, this is minimal — it doesn't explain ticker casing rules, exchange suffixes, or validity constraints beyond the example. The description adds some value but doesn't fully compensate for the coverage 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?

States a specific verb+resource: 'US earnings calendar — 다음 실적 발표일 + 최근 EPS 서프라이즈 이력' (next earnings date + recent EPS surprise history). This clearly distinguishes it from price, chart, and financials siblings. However, it doesn't explicitly differentiate from get_us_event_reaction, which could overlap 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?

Provides concrete example queries ('AAPL 실적 언제', 'NVDA earnings date', 'Tesla 다음 실적') that signal when to use it, plus context that US quarterly earnings are key price events. But it never names an alternative tool or states when NOT to use this tool, leaving some ambiguity against get_us_financials or get_us_event_reaction.

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