list_texts

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

With no annotations, the description carries the full burden. It reveals pagination behavior (auto-walking pages due to CTM cap), the role of max_items, truncation warnings, and default status filtering. These are meaningful behavioral traits beyond the bare schema.

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 front-loaded with the main purpose, then adds contextual use, then dives into parameter behavior. Every sentence provides distinct value, and the formatting with dashes and semicolons keeps it readable without being bloated.

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 the output schema exists, return format doesn't need explanation. The description covers the most important operational details: pagination, status filtering, truncation, and capacity. The only missing piece is explicit handling of account_ids and date formats, which are secondary for a list operation.

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 coverage is 0%, so the description must compensate. It explains max_items, per_page cap, status values, and suggests using date ranges. However, it does not describe account_ids or date format details, leaving a small gap in an otherwise parameter-aware tool.

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 opens with a specific verb and resource: 'List SMS/text messages across sub-accounts.' This clearly distinguishes it from sibling tools like list_calls or list_numbers, and the scope (across sub-accounts) is explicit.

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?

It provides a concrete use case: 'Useful for auditing text communication across all client accounts.' It also advises on parameter tuning (raise max_items or narrow dates). However, it does not explicitly mention alternative tools or when not to use it, so it stops short of full guidance.

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