list_events

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

No annotations are provided, so the description carries the disclosure burden. It indicates a read-only mapping to GET /events and the tier note, which conveys safety. However, it doesn't disclose pagination behavior, date-range semantics, or what 'scheduling conflicts' entails in the response beyond the listing promise.

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 a single efficient sentence that names the purpose and REST mapping. The tier bracket is compact. No wasted words. Could arguably add more detail, but structural economy is good.

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 4 params, 50% schema coverage, no output schema, and no annotations, a richer description would help. The tool is a read-only listing operation, which is relatively simple, but the absence of pagination/date-range explanation and output-format detail leaves the agent under-informed about expected behavior. Adequate but with clear gaps.

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 50% — start_date and end_date have 'ISO 8601 date' descriptions, but page and page_size lack descriptions entirely. The tool description adds no per-parameter semantics; it doesn't explain that dates likely filter the event window or how paging relates to results. It maps to the GET endpoint but doesn't clarify parameter behavior beyond the 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 states 'List calendar events and scheduling conflicts' — a clear verb+resource pair that distinguishes from siblings like list_jobs or list_estimates. It also maps to a REST endpoint which adds clarity. However, it doesn't emphasize the owner-readonly scoping context beyond the bracketed tier note.

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 includes a tier annotation '[tier: readonly-owner]' that implies context for when this can be called, but provides no explicit guidance on when to use this vs alternatives like get_schedule or list_job_appointments. No exclusions or alternative tool mentions are given; usage context is only implied by the 'list events' framing.

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