list_calls

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

No annotations are provided, so the description takes on the full burden of behavioral disclosure. It reveals that the user parameter is resolved automatically, warns that only call-specific fields work for sorting (explicitly banning 'created' or 'edited'), and clarifies that contact is an internal ID. These are useful behavioral insights beyond the input schema, though it doesn't cover every possible concern (e.g., permissions, error conditions).

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 well-structured with an initial summary, a usage tip, and a bulleted argument list. Each parameter explanation is concise yet informative, avoiding unnecessary fluff. The content earns its place given the tool's complexity (11 parameters), and the front-loaded purpose makes it easy to scan.

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 11 parameters, no annotations, but an output schema exists, so return values are covered. The description provides the purpose, when to use it, parameter semantics, and warnings about common pitfalls. It also covers pagination defaults and limits. This is complete for a list-type tool, leaving no significant gaps in understanding.

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?

With an input schema description coverage of 0%, the description fully compensates by explaining each of the 11 parameters in detail, including examples, allowed values, date formats, and default values. For instance, it notes that 'user' can be a display name or login name, 'contact' is an internal ID not a person's name, and 'sort' has a warning about invalid fields. This is essential information that the schema alone lacks.

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 lists phone calls with detailed call data (duration, CLID, missed calls, hold time), using a specific verb and resource. It also distinguishes itself from the sibling tool list_activities by noting it provides call-specific fields, making the purpose unambiguous.

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 first paragraph explicitly says to use this tool instead of list_activities(type='CALL') when call-specific fields are needed, providing a clear alternative. Additionally, it gives guidance for parameters like queue (use list_queues to find names) and contact (use list_contacts first), which effectively tells the agent when and how to use the tool correctly.

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