ghl_invoice_schedule_update

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

Annotations already indicate that the tool is not read-only (readOnlyHint=false), not destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds OAuth scopes and endpoint details but does not disclose any additional behavioral traits beyond what annotations provide. It does not clarify whether the update overwrites all fields or merges, nor does it mention side effects.

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 concise, containing only two sentences and a few technical details. It is front-loaded with the purpose ('Update schedule') but lacks structure and focuses on endpoint details that may not be essential for an AI agent. Every sentence serves a purpose, but it could be more organized.

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?

Given the complexity of the input schema (nested objects, many required fields) and the presence of multiple sibling schedule tools, the description is insufficient. It does not explain the effect of updates, constraints, or how this tool differs from similar ones. Without an output schema, an AI agent cannot understand what the tool returns.

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 has 100% coverage, meaning all parameters have descriptions. However, the description of the 'body' parameter is generic ('Request body (schema carried verbatim from the official OpenAPI spec)') and adds no meaning beyond the schema. The schema itself is detailed, so the description does not need to compensate, but it also does not enhance understanding.

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 that the tool updates a schedule by schedule ID. However, it does not distinguish this from sibling tools like ghl_invoice_schedule_update_and_activate, which also updates schedules. The verb 'update' and resource 'schedule' are specific, but the lack of differentiation from similar siblings prevents a perfect score.

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_invoice_schedule_create, ghl_invoice_schedule_activate, or ghl_invoice_schedule_update_and_activate. An AI agent would have no context to choose this specific tool over others for update operations.

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