list_phone_numbers

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

No annotations are present, so the description carries full burden. It lists parameters and defaults (page, page_size) but does not disclose what phone numbers are included, authentication needs, rate limits, or response structure beyond 'Dict[str, Any]'.

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 as a docstring with Args and Returns sections. No unnecessary fluff, but could be shortened by removing redundant parameter type mentions.

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 no annotations, no output schema, and a nearly empty input schema, the description must provide comprehensive context. It offers only parameter list and vague return type, missing details about response fields, scoping of phone numbers, and the required request wrapper.

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 schema only has a required 'request' object with no properties, making it unhelpful. The description lists six optional args with types, defaults, and filter purposes, adding value. However, the mismatch between the described individual args and the schema's request object creates confusion.

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 states 'List phone numbers' which is a clear verb+resource. It distinguishes from get_phone_number (single item) but not clearly from list_available_phone_numbers, a sibling tool.

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 on when to use this tool versus list_available_phone_numbers or get_phone_number. No scenarios or exclusions are provided.

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