update_customer

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it is a write operation and lists non-editable fields, which is useful, but it omits any details on side effects, return payload, authentication requirements, or whether the update is partial or full replacement. For a mutation tool, this leaves significant gaps about what happens when the tool is called.

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 a single, compact sentence that front-loads the verb, resource, and key field list, then states the non-editable exclusions. There is no fluff, repetition, or unnecessary detail. Every word earns its place, making it highly efficient for an agent to parse.

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 mutation tool with no annotations and no output schema, the description is notably incomplete. It does not explain what the tool returns on success or failure, whether it is a partial update (PATCH-like) or full replacement, any required permissions or authentication, or the purpose of the mysterious 'doc' field. An agent calling this tool would have to guess at expected response and error behavior. The description covers the basic operation but leaves too many operational details unstated.

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%, so the description must compensate. It does add meaning by identifying which fields are updatable (name, email, phone) and clarifying that external_id is used as an identifier and not meant to be edited, even though it is required in the schema. However, it references 'doc' which is not present in the schema, creating potential confusion, and it does not provide formats, constraints, or optionality explanations. Partial compensation.

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 action (Atualiza = updates) and resource (cliente = customer), lists the specific fields (nome/email/telefone), and explicitly declares what is not editable (doc and external_id). This distinguishes it from the sibling update_customer_email, which is narrowly focused on email only. Purpose is unambiguous and well-scoped.

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 no explicit guidance on when to use this tool versus alternatives. It mentions 'Escopo write' but that is generic to all mutation tools and does not help an agent decide between update_customer and update_customer_email or other write tools. There is no mention of conditions, exclusions, or preferred scenarios. The usage context is entirely implicit from the purpose.

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