list_users

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

Beyond the readOnlyHint/destructiveHint annotations, the description reveals that the response contains the personal mailaddress, warns against unnecessary transcription, states that no permission level is required, and confirms no thinning/truncation is performed. This is substantive behavioral context.

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 compact and front-loaded: purpose first, then prerequisite, permission, response privacy, and behavioral note. Each sentence contributes distinct information with no filler.

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 simple paginated list endpoint, the description covers purpose, prerequisites, permissions, and a key response field. Without an output schema, it does not enumerate all user fields beyond mailaddress, which leaves a small gap in expected response shape.

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 100%, so the schema already documents tenant_id, page, and per_page fully. The description only repeats that tenant_id comes from list_tenants, which the schema already says, so it adds no meaningful parameter semantics.

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 clear action and object: 'テナントに所属するユーザーの一覧を取得します' (get the list of users belonging to a tenant). This distinguishes it from sibling list_tenants/list_groups/list_devices by resource, though it does not explicitly contrast itself with them.

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 gives actionable context: tenant_id should be obtained from list_tenants first, and it states there is no permission restriction. It does not explicitly say when not to use this tool or name an alternative for a different resource, but the prerequisite workflow is clear.

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