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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so 'this is read-only' is largely redundant. The description does add real scope information — it searches only appointments tracked by SkipCalls, not free/busy — but says nothing about result ordering, the 20-item cap behavior, or what happens when all-nullable filters are omitted. With annotations covering the safety profile, this is adequate but thin.

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?

Two sentences, zero waste, with the primary capability front-loaded and the disambiguation trailing. Nothing repeats the schema or the annotations verbatim.

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 5-parameter search tool with no output schema, the description should clarify how filters interact (AND vs. OR across search/period/from/to) and what the result set looks like, since there is no output schema to fall back on. It covers the what and the not-what, but leaves the combination semantics and return shape implicit.

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 80%, so the schema carries most of the load, including the limit cap and the ISO-8601 offset requirement. The description names the searchable fields but adds no meaning for the undocumented 'period' enum (upcoming/past/all) and does not explain how search, period, from, and to combine or what a null value means for each of the five required-but-nullable parameters. Baseline 3 fits.

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?

States a specific verb and resource (find appointments tracked by SkipCalls) and enumerates the search dimensions: guest name, phone, email, title, period, and exact ISO date range. The closing clause ('does not search free time') separates it from the slot-finding sibling, so an agent can distinguish it without opening any schema.

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?

Explicitly rules out two adjacent behaviors: searching free time (the findCalendarSlots territory) and changing calendar configuration (calendar_update_settings territory). That is clear routing context, though it stops short of naming the sibling tools or stating the 'when to use' condition positively (e.g., 'use when you need to look up an existing booking').

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