list_appointments

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 reveals non-obvious behavior: the default limit is deliberately set to 100 (the API max) instead of 10, and it instructs how to continue pagination using offset or cursor values. It stops short of explicitly stating read-only semantics, permissions, or response format, but the GET method and 'search' imply read-only.

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 three sentences with a clear front-loaded purpose. Each sentence contributes either purpose, default behavior, or pagination. The mention of 'like notes' in the pagination sentence is slightly extraneous and could be simplified, but overall it is efficient and well-structured.

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 search tool with 7 optional parameters and no output schema, the description covers the essential behavior: pagination and the default limit. It does not explain the response shape, but the resource name implies a list of appointment objects, and the schema already documents parameter semantics. The absence of output schema makes a 4 appropriate – useful gaps remain (e.g., response format, combining start/end), but they are partially covered by the schema descriptions.

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 100% (all parameters have descriptions), so baseline is 3. The description adds value by explaining why the limit default is overridden (FUB's max) and clarifies how offset/next map to pagination modes. This goes beyond the schema's basic parameter descriptions, earning a 4.

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 opens with a specific verb-resource pair: 'Search for appointments,' and the plural resource name combined with the parenthetical GET /appointments clearly distinguishes it from siblings like get_appointment (single resource) and list_appointment_types (different resource). An agent can immediately tell this lists appointment records.

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 provides clear context that the tool is optimized for bulk requests ('bulk requests are the common case here') and explains the pagination strategy for retrieving all results. However, it does not explicitly name alternatives or state when to use get_appointment for a single appointment, so it stops short of full when/when-not guidance.

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