users_write

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real context beyond them: reset_2fa is flagged as a high-impact security action requiring explicit user intent, and deletion is explicitly out of scope. It stops short of describing what gets overwritten on update or any auth requirements.

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?

Three short sentences, front-loaded with the action set and immediately followed by the decision rule and the exclusion. No filler or repetition.

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 19-parameter mutation tool with 0% schema description coverage, the description omits all field-level guidance needed to actually invoke it correctly (which fields are required per action, password_confirmation pairing, etc.). Output schema covers returns, so that is not a gap, but parameter completeness is not.

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 0% across 19 parameters with no enums declared. The description names the action values (create, update, restore, reset_2fa) but explains nothing about which of the 18 data fields apply to which action or how user_id versus creating a new user works, so it fails to compensate for the coverage gap.

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?

States specific verbs and resource: create/update/restore/reset-2FA for a Snipe-IT user, and explicitly excludes deletion. An agent can distinguish this from users_search and delete_resource without opening any schema.

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?

Gives a clear rule for choosing reset_2fa ('only when the user explicitly asks') versus the routine create/update/restore path, and states the tool cannot delete. It does not name sibling tools (e.g. users_search for reads), so routing is implied rather than fully explicit.

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