update_phone_number

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

No annotations are provided, so the description must disclose behavior itself. It does explain that auto_reply is 'sent to all inbound SMS' and that an empty string disables it, which is helpful. However, it does not clarify whether omitted fields are left unchanged, what null means for friendly_name or auto_reply, or any permission/reversibility aspects.

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 compact docstring with an action sentence and an Args list. Every line adds value—there is no filler, redundancy, or unnecessary detail.

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?

An output schema exists, so return values need not be explained. However, the description leaves ambiguity around update semantics: it doesn't explicitly state whether only provided fields are modified, whether null clears a field, or how to clear friendly_name. For a mutation tool with no annotations, this is a notable gap.

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 covers all three parameters with meaning beyond the schema: phone_number_id is sourced from list_phone_numbers, friendly_name is an optional label, and auto_reply is optional text with empty-string-disable behavior. This fully compensates for the 0% schema description coverage.

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 'Update a phone number's friendly name or auto-reply message,' providing a specific verb, resource, and the exact fields being modified. This distinguishes it from siblings like get_phone_number, list_phone_numbers, and set_phone_number_webhook.

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 the tool is used to update a phone number's label or auto-reply, and it tells the user that phone_number_id comes from list_phone_numbers. It does not explicitly state when not to use it or mention alternative tools, so it falls just short of a 5.

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