set_phone_number_block_list

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explicitly states that the tool 'Replaces the existing block list,' which is a destructive overwrite behavior, and that an empty list clears it. This is critical information for safe usage. It does not mention rate limits or permission requirements, but the core replacement behavior is disclosed.

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 and well-structured. It opens with a clear one-sentence purpose, followed by a brief behavioral note, and then a formatted Args section. Every sentence adds value and there is no fluff.

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 tool has an output schema (not shown), so return values are covered elsewhere. The description explains the parameters and the destructive replacement behavior, which is sufficient for a simple two-parameter mutation. It could be slightly more complete by mentioning that an empty list is the way to clear, but it already does. Given the sibling tools, the purpose is clear and the description is complete enough.

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 provides no descriptions, but the description adds full semantics. It explains that phone_number_id is 'The phone number ID (from list_phone_numbers)' and describes numbers as 'List of E.164 phone numbers to block' with an example. This compensates entirely 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 the tool's purpose: 'Set the block list for a phone number (these numbers are rejected).' It uses a specific verb ('Set') and resource ('block list'), and distinguishes it from sibling tools like set_phone_number_allow_list 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 provides clear usage context by explaining that it replaces the existing block list and that passing an empty list clears it. It implies the tool is for managing blocked numbers, which differentiates it from the allow-list sibling, though it doesn't explicitly state 'use this instead of X'.

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