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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses operational behaviors such as the default 09–17 local window, 30-minute slot granularity, and lack of holiday/personal calendar awareness. It also details auth/billing behavior: 'send a prepaid x-credit-token header for unlimited calls, or get 1 free call/day per tool. No wallet or API key required.' This is valuable context not present in the schema or 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 core functionality is front-loaded in the first sentence, followed by required input, a limitation, and pricing/auth notes. Each sentence adds distinct information, though the pricing portion is longer than strictly necessary. It remains concise and free of redundant wording.

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 tool with 4 parameters, 1 required, and an output schema, the description supplies defaults, required input, limitations, and auth requirements. Minor gaps include not specifying what happens if date is omitted or how startHour/endHour are validated, but the default window and required zones are sufficient for most correct invocations.

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 100%, so the baseline is 3. The description adds meaningful interpretation beyond the schema: 'zones= IANA list' clarifies the expected timezone format, 'default 09–17' explains the startHour/endHour defaults, and '30-minute UTC slots' defines the output granularity implied by the tool's purpose. This lifts it above baseline.

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 names a specific verb and resource: 'Find 30-minute UTC slots where every zone is inside a local window (default 09–17) on a given date.' This precisely distinguishes the tool from sibling calendar and timezone tools. The limitation 'Does not know holidays or personal calendars' further separates its scope from tools like holiday_calendar.

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 clearly establishes when to use the tool ('Overlap office hours across timezones') and the required input ('Pass zones= IANA list. Required input: zones.'). It also gives an exclusion: 'Does not know holidays or personal calendars,' which tells an agent when not to use it, though it does not explicitly name alternative sibling tools.

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