find_meeting_times

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

With no annotations, the description carries the burden of behavioral disclosure. It does reveal that the tool returns suggestions with a specific structure, including suggestions and an empty_reason field, but it does not explain what 'confidence' or 'order_hint' mean, nor does it clarify whether attendee calendars are read or if this is a read-only operation. This is partial transparency but lacks important semantic detail.

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 efficient and well-structured: a one-sentence purpose followed by clearly labeled Args and Returns sections. Every line contributes necessary information for a tool with seven parameters and no schema descriptions, and the return shape is valuable because there is no output schema.

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?

The description covers most parameters and the return structure, which is critical given the absence of schema descriptions and output schema. However, it leaves gaps: semantics of confidence/order_hint/empty_reason are undefined, mailbox and include_raw are not described, and there is no guidance on when to use this relative to sibling scheduling tools. It is usable but not fully 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?

Schema description coverage is 0%, so the description's Args section is essential. It clarifies five parameters well (e.g., attendees as email addresses, duration in whole minutes, ISO 8601 windows, max_candidates default), but it omits two schema parameters, mailbox and include_raw, leaving them unexplained. This partial coverage keeps it from being complete.

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 verb ('Suggest'), a clear resource ('meeting times'), and a target audience ('given attendees'), making it immediately clear what the tool does. This also distinguishes it from sibling calendar tools like list_events or create_event, which focus on retrieving or creating actual events rather than suggesting availability.

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 implies a scheduling use case and specifies the required inputs, but it does not explicitly say when to use this tool versus alternatives such as create_event or list_calendars. It provides context but no exclusions or comparative guidance, so an agent must infer the appropriate scenario.

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