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

The description indicates a non-read-only operation (update) and that `data` contains fields to change, which implies partial modification. It does not detail side effects like return values, error handling, or atomicity for bulk updates, but the annotations (readOnlyHint false, destructiveHint false) are not contradicted. The description provides basic transparency but lacks in-depth behavioral details.

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 concise, consisting of two sentences that convey the operation, endpoint, parameter role, and bulk capability. It is well-structured and free of unnecessary jargon.

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?

The description covers the core operation and parameter meaning, but it does not mention response format, required vs. optional fields within `data`, or specific constraints. Given the open schema for `data`, a more detailed description could list common fields, but it is not strictly necessary for basic usage. It is moderately complete.

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 description explicitly explains `data` as fields to change, which adds meaning beyond the schema's open object definition. It does not clarify the roles of `id` and `ids` beyond implying they are identifiers (with `ids` for bulk). The schema provides no descriptions for these parameters, so the description partially compensates but leaves some ambiguity about usage and mutual exclusivity.

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 the tool updates appointments (Compromissos/agenda) and specifies the HTTP method (PATCH) and endpoint (/Appointments/{id}). It distinguishes itself from sibling update tools for other entities (contacts, lawsuits, etc.) by explicitly naming the target resource.

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 implies usage for updating existing appointment records and explains the `data` parameter as fields to change. It also mentions bulk support via `ids`, giving clear guidance on when to use the multi-record capability. However, it does not explicitly contrast with create or get tools, but the context makes that implicit.

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