Create or update Audiobookshelf API users by sending a POST request with the required user data payload.
Create or act on api users.
POST /api/users
Args: body: Request payload. Read the matching GET or the /schema endpoint first to see the fields this resource expects.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes |
| 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, covering the mutation and safety profile. The description adds the HTTP method and the instruction to consult GET/schema for expected fields, but does not disclose auth requirements, response behavior, or failure modes. With annotations present, this is adequate but not rich.
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, stating the action, resource, and endpoint in the first line. The Args block is minimal and useful. No filler or redundant explanation appears.
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?
The output schema exists, so return values do not need explanation. The description points to the schema endpoint for field discovery, which helps. However, 'matching GET' is ambiguous, and 'or act on' is unclear about the exact scope of operations. It is enough for a basic call but not fully self-contained.
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 coverage is 0%, so the description carries the burden. It names the only parameter 'body', identifies it as the 'Request payload', and directs the agent to the matching GET or /schema endpoint to discover the expected fields. This compensates reasonably for the empty body schema, though it does not enumerate actual fields.
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 action ('Create') and resource ('api users'), reinforced by the explicit POST /api/users endpoint. However, 'or act on api users' is vague and could suggest broader mutation behavior than creation alone, and it does not explicitly differentiate from siblings like patch_users_by_id.
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?
No guidance is given about when to use this tool versus alternatives such as patch_users_by_id, delete_users_by_id, or list_users. The only usage hint is to read the matching GET or /schema endpoint first, which is a prerequisite, not a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.