list_friends

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List my friends' and gives a use case; it does not disclose whether the result includes pending friend requests, how the 'include_requests' parameter changes behavior, whether pagination exists, or what fields are returned. The uncovered behavior around requests is significant.

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 a single front-loaded sentence with no filler, and every word contributes to the core purpose. However, it is arguably too short given the schema's lack of parameter descriptions, so it could have used a bit more space to explain behavior without becoming 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?

For a tool with two optional parameters and no output schema, this description is not complete enough. It does not explain include_requests, which appears to be a key behavioral switch, nor does it clarify how lang affects results. It also gives no guidance on choosing this tool over search_users, leaving gaps that an agent would need to guess about.

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 description coverage is 0%, and the description fails to compensate by explaining either 'lang' or 'include_requests'. The only parameter hint is the parenthetical about bill participants, which is unrelated to the actual parameters. An agent has no way to know what these parameters do.

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 a specific verb 'List' and resource 'my SplitBill friends', and immediately frames the purpose ('for picking bill participants'). This clearly distinguishes it from siblings like list_bills (which lists bills) and search_users (which searches arbitrary users), leaving no ambiguity about scope.

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 gives a clear usage context: it is for picking bill participants from one's own friend list. However, it does not explicitly mention alternatives or when not to use it, such as when searching for users outside the friend list with search_users would be more appropriate.

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