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

Beyond the read-only, idempotent, open-world annotations, the description discloses important behavior: New York calendar dates, per-day caps, earnings completeness semantics via completeThrough, truncated flags, what null completeThrough means, and the api:read requirement. These are substantive operational caveats not captured by annotations.

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 front-loaded and information-dense, with nearly every clause contributing necessary behavior. However, it is a single long paragraph with many semicolon-separated rules, making it harder to scan than a lightly structured version would be.

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?

For a 12-parameter tool with no output schema, the description is unusually complete: it covers all kinds, date-window rules, response caveats such as completeThrough and truncated, the app_url field, and the required permission. An agent has enough context to call this correctly without external documentation.

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?

Although schema description coverage is already high at 92%, the description adds meaningful semantics beyond the schema: forward windows of 1-90 days, back windows of 0-14 days, explicit from/to requiring both or neither and max 90 days, scope=all lifting the earnings size filter, symbols always included, and exact identifier fields required for macro_take.

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 resource (macro and earnings calendars) and explicitly enumerates the four supported modes via kind. It gives concrete use cases such as 'the call for earnings this week' and distinguishes macro vs earnings vs macro_take vs earnings_priority clearly enough that an agent can select the right invocation.

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?

It gives explicit selection guidance for each kind: macro for scheduled macro events, earnings for upcoming reports, macro_take for a stored shared take on one event, and earnings_priority for tickers followed by the user's open and saved Gambits. It also explains when scope=all applies and what date-window controls are available.

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