Create Contact List

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the behavioral trait 'requires user confirmation recommended,' which is beyond what annotations provide. It also clarifies the resource type ('contact folder/list'). No contradiction with annotations. However, it omits details on permissions or rate limits.

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 purpose, then provides usage context, parameter descriptions, return information, and error details. Each sentence adds value, and the formatting (Args, Returns, Raises) 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?

Given the tool's simplicity (2 params, output schema exists), the description is fairly complete. It explains the function, parameters, return object, and error case. It does not explicitly mention prerequisites like authentication, but since sibling tools include account_authenticate, this is likely understood. A small gap is the lack of uniqueness constraints on list_name.

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 0% schema description coverage, the description fills the gap by providing semantic meaning for both parameters: 'account_id: Microsoft account ID' and 'list_name: Name for the contact list/folder.' This adds necessary context beyond the schema's bare property definitions, though more detail (e.g., allowed formats) could be helpful.

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 creates a contact list (folder) for organizing contacts. It uses a specific verb ('Creates') and resource ('contact list'), and the examples of use cases (distribution lists, project teams) distinguish it from sibling tools like contact_create (which creates individual contacts) and contact_add_to_list (which adds to existing lists).

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 mentions it is 'useful for creating distribution lists, project teams, or other groupings,' giving context for when to use it. However, it does not explicitly state when not to use it or compare it with alternatives like contact_add_to_list for adding contacts to existing lists. The guidance is implied but not sharply differentiated.

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