Retrieves staff users with IDs, names, account types, and outlets so you can query sale totals or search sales by user ID.
Staff users (id, name, account type, outlets). Use ids with get_user_sale_totals or search_sales(user_id=...).
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is fully covered. The description adds the shape of each record (id, name, account type, outlets), but since an output schema exists this is largely redundant rather than new 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?
Two short sentences, front-loaded with the resource and its fields, followed immediately by the actionable chaining advice. No filler or restatement of the tool name.
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?
Annotations and an output schema carry the safety and return-format burden, and the zero-param schema needs no explanation. The only gap is scope: it doesn't say whether all staff users are returned at once or whether results are paginated/limited.
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 tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The guidance about feeding returned ids into other tools compensates slightly for the absence of any filtering options.
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 identifies the resource precisely as 'Staff users' and enumerates the returned fields (id, name, account type, outlets), so an agent can distinguish it from list_outlets, get_customer, or get_user_sale_totals. It lacks an explicit verb ('list' is only implied by the name), but the intent is unambiguous.
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 a useful downstream routing hint: use the returned ids with get_user_sale_totals or search_sales(user_id=...). That is chaining guidance rather than selection guidance — it never states when to call list_users versus another listing tool, nor mentions pagination or scope limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.