Listar usuarios de un scope

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that operation is a paginated listing, and the wording 'Lista' implies a read-only, none-destructive action. The required tenant-scope condition is also disclosed. There is no mention of response format or error behavior, but these are not critical for a safe read/list operation.

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 text consists of two sentences with zero filler. The first sentence captures the core action, resource, and key behaviors (pagination, optional search). The second sentence adds a necessary permission precondition. Each sentence earns its place and the core information is front-loaded.

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 4 parameters, no output schema, and no annotations, the description is largely complete: it defines the operation, pagination, optional filtering, and the required tenant permission. It lacks only minor details such as default/limit behavior or response error formats, which are no less predictable for a simple list operation.

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 schema has 100% coverage for parameters, so the baseline is 3. The description adds value beyond the raw schema: it explicitly mentions pagination and the optional search, and adds a semantic constraint on the `id` parameter (the scope must be among the token's tenants), which is not present in the schema description.

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 ('Lista'), a concrete resource ('usuarios de un scope/tenant'), and key functional flags (pagination, optional search). It clearly distinguishes the operation from broader search tools by scoping it to a tenant, and the additional sentence about the token requirement reinforces its specific use case.

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 clear context for when to use the tool (listing users of a tenant, paginated, with optional search) and explicitly states a prerequisite (scope must be within the token's tenants). However, it does not explicitly mention alternatives like search_users or list_invitation_users, nor does it state when not to use it.

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