list_calls

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that results are sorted by most recent first, includes status/duration/outcome but excludes transcript, and explains filter semantics (e.g., NULL for web sessions). This is strong behavioral context, though it does not address pagination, rate limits, or potential errors.

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 and front-loaded with the core purpose, followed by return details and filtering options. Every sentence adds value, including the explicit note about missing transcripts and the parameter breakdown. It is appropriately sized for the tool's complexity without redundancy.

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?

For a list tool with four optional parameters and no annotations, this description is remarkably complete. It covers return contents, ordering, exclusions, and all parameter semantics. Since an output schema exists, the description correctly focuses on behavioral aspects rather than repeating return schemas, making it sufficient for an agent to select and invoke the tool correctly.

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 has no descriptions (0% coverage), so the description compensates thoroughly. Each parameter is explained with allowed values, defaults, and special cases ('channel' options, 'direction' NULL for web, 'limit' range 1-100). This goes beyond the schema and gives the agent everything needed to construct a valid call.

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 begins with a specific verb and resource: 'List recent voice sessions with a summary of each.' It clearly distinguishes itself from siblings by explicitly noting that the transcript is NOT included and directing users to get_call for full transcripts, thereby differentiating from get_call and get_active_calls.

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 context on when to use this tool: for retrieving call history summaries and filtering by channel, direction, or agent. It explicitly points to get_call as the alternative for reading full transcripts. However, it does not mention get_active_calls as an alternative for active/live sessions, so it lacks a complete when-not-to-use guidance.

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