get_today_events

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

No annotations are provided, so the description carries the burden. It does disclose one useful behavioral trait: aggregation across ALL authorized accounts (vs a single account). However, it doesn't disclose what the return format looks like, whether there are rate limits, or anything about how multi-account aggregation behaves (e.g., deduplication, ordering, timezone handling). The output schema exists, which mitigates some of this, but the description is thin on behavioral context.

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 compact, about 15 words, with no filler. The 'Returns:' section is nearly redundant with the description itself ('Today's events aggregated from all calendar accounts' restates the first sentence), which is minor waste. Could be tighter but is otherwise efficient.

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 zero-parameter read-only aggregation tool with an output schema, the description is adequate. It states what it returns and its scope. Given the tool's simplicity (0 params, read operation), it doesn't need extensive behavioral disclosure. However, it could briefly mention that this spans multiple accounts to justify why it might be more expensive or inclusive than alternatives like get_upcoming_events.

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 tool has 0 parameters with 100% schema coverage (trivially, since there are no params to document). The description is not adding parameter semantics since there are none. The baseline of 4 for 0-param tools applies here - there's nothing to add, and the description correctly focuses on the result rather than inputs.

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 verb+resource: 'Get today's calendar events from ALL authorized accounts.' It explicitly calls out the scope (ALL authorized accounts) which distinguishes it from other event tools like get_upcoming_events and get_week_events. However, it doesn't explicitly name the sibling tools it differs from, so it doesn't fully differentiate.

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 conveys the primary use case (today's events across all accounts) implicitly. It doesn't explicitly state when NOT to use it or mention alternatives like get_upcoming_events or get_week_events for other time ranges. The scope limitation (ALL accounts) implies a contrast with account-specific views, but this is not made explicit.

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