earnings_calendar

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns earnings dates, estimates, history, and details like EPS, surprise percentage, and price reaction. It also specifies the days_soon parameter's default and maximum. This is good transparency for a read-only tool, though it could explicitly state that it is read-only and does not modify data.

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, consisting of two sentences. The first sentence states the tool's purpose and output details, while the second provides parameter guidance. Every sentence adds value, and there is no unnecessary information. It is front-loaded with the most critical information.

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 has 2 optional parameters, a simple output schema, and no annotations, the description covers the input parameters well and gives a solid overview of the output. However, it doesn't explicitly mention that the output is from the last 4 quarters, which is important context. Also, it lacks a note about the tool being read-only. Nonetheless, for a tool of this complexity, it is sufficiently complete.

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?

The schema has 0% description coverage, but the description adds meaningful semantics: 'tickers' should be a comma-separated string, and 'days_soon' has a default of 7 and max of 90. This clarifies the parameter format and constraints beyond the schema's type and default. However, it doesn't explain what 'days_soon' controls beyond 'near-term window' – is it looking ahead or behind? The context implies forward-looking earnings calendar, but it's not explicit.

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 earnings dates, estimates, and beat/miss history for the last 4 quarters. It specifies EPS actual/estimate, surprise percentage, day-after price reaction, and consecutive beats. This is a specific verb+resource description, though it doesn't use the verb 'retrieve' or 'get', which would be slightly clearer. It effectively distinguishes from sibling tools like equity_analysis or insider_trading by focusing on earnings calendar data.

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 explains how to pass tickers (comma-separated string) and the days_soon parameter (near-term window, default 7, max 90). However, it does not provide guidance on when to use this tool versus alternatives, nor does it mention when not to use it. For example, if the user needs broader financial data, equity_analysis might be more appropriate. No explicit exclusions or alternatives are given.

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