list_users

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

With no annotations, the description carries the behavioral burden, and it discloses meaningful traits: the default limit is deliberately bumped to 100, _metadata signals remaining results, offset vs cursor pagination, and fields usage. It does not mention auth, rate limits, or return shape, but for a read/list endpoint the most important quirks are covered.

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 information-dense with no filler: action line first, then defaults, pagination, field selection, and custom-field caveat in logical order. Every sentence contributes a distinct operational instruction.

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 read-only list tool with no output schema, the description covers the key operational concerns: pagination, defaults, filtering, and field projection. It omits nothing critical for a correct first call, though it does not describe the overall response envelope or error conditions, leaving a small gap.

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?

Despite 100% schema coverage, the description adds real semantic value: it explains why the limit default is 100, how to paginate with offset or _metadata.next, and how to use fields to trim payloads. It also connects extraQuery custom filters to list_custom_fields, which is exactly the kind of guidance the schema cannot provide.

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-resource pair ('Search for users') and the HTTP endpoint, making the action unmistakable. It does not explicitly contrast with get_user or list_people, so it misses clear sibling differentiation and gets a 4 rather than a 5.

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 clearly frames the common use case ('bulk requests'), explains the pagination strategy, and tells the agent to call list_custom_fields first before custom-field queries. It does not state when to prefer get_user or when not to use this tool, so there are no explicit exclusions.

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