ghl_contact_get_appointments

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds minimal additional behavioral context: the endpoint, OAuth scopes, and a renaming note. It does not disclose what the response contains (e.g., list of appointments), pagination, or ordering. The description fails to add meaningful behavioral insights beyond 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 relatively short but includes an irrelevant note about renaming ('Renamed from the auto-generated...'), which does not aid the agent. The structure is acceptable: purpose statement followed by technical details. Could be more concise by removing the renaming 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?

For a simple tool with one parameter and no output schema, the description should at least mention that it returns a list of appointments. It does not specify the response format, any filtering options, or what types of appointments are included (e.g., future, past). Without output schema, this leaves the agent uninformed about the tool's output.

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?

The input schema covers the single parameter (contactId) with a description ('Contact Id'), achieving 100% schema description coverage. The description does not add further parameter information, so a baseline of 3 is appropriate.

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 clearly states 'Get Appointments for Contact', using a specific verb ('Get') and resource ('Appointments for Contact'). It distinguishes from sibling tools like ghl_calendar_appointment_get (which gets a single appointment by ID) and other contact tools. The endpoint and OAuth scopes further clarify the purpose.

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?

No guidance is provided on when to use this tool versus alternatives, such as ghl_calendar_appointment_get or other contact-related tools. There is no mention of prerequisites, limitations (e.g., date range), or when not to use it.

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