book_appointment

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

Annotations already declare destructiveHint=true, so the description's 'CONSEQUENTIAL WRITE' adds minimal new behavioral information. No additional side effects, authorization needs, or post-conditions are disclosed, so the description does not significantly extend beyond the structured 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 description is very short (two sentences). The first sentence clearly states the purpose. The second sentence, while redundant with annotations, is not excessively long. No structural issues, but could be slightly more efficient by omitting the redundant note.

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?

Despite having three required parameters with no schema descriptions and an output schema (whose content is unknown), the description provides no parameter details or return value expectations. The agent lacks sufficient context to use the tool correctly without external knowledge.

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%, meaning the input schema provides no parameter descriptions. The tool description fails to explain any of the three required parameters (patient_id, when, reason), leaving the agent without essential semantic context to pass correct values.

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 explicitly says 'Book a new appointment for a patient,' providing a specific verb (book) and resource (appointment). It clearly distinguishes from sibling tools like get_patient, list_appointments, and search_patients, which are read/query operations.

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 does not provide explicit guidance on when to use this tool versus alternatives. It states the basic action but lacks context about prerequisites, availability constraints, or exclusion criteria. Usage is implied by the tool name and sibling contrast.

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