user_add_ip_whitelist_entry

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It adds some value by noting that it returns a status message and mentions ctx for resource change notifications. However, it omits important behavioral traits like permission requirements, duplicate handling, idempotency, and validation rules for subnet_size.

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 front-loaded with the purpose, followed by an organized Args section and a Returns line. It is concise and scannable, though the inclusion of ctx (not present in the input schema) is slightly extraneous and could cause minor confusion.

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 mutation tool with three parameters, the description is mostly complete: it explains each parameter and the return type. However, it lacks validation constraints, duplicate-entry behavior, and any explicit relationship to sibling whitelist tools, so an agent must make assumptions when deciding whether an entry already exists or how to undo the 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?

Schema description coverage is 0%, so the description must compensate. It clearly explains all three schema parameters: user_id accepts a UUID or email, subnet includes example IP/CIDR-like values, and subnet_size includes examples like 24 for /24 and 32 for single IP. This is exactly the kind of semantic detail an agent needs that the schema lacks.

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 opens with a specific verb and resource: 'Add an IP address or subnet to a user's whitelist.' This clearly distinguishes the tool from its siblings like user_get_ip_whitelist, user_get_ip_whitelist_entry, and user_remove_ip_whitelist_entry. No ambiguity about what action is performed.

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 implies usage through its purpose statement but does not explicitly state when to choose this tool over alternatives such as user_remove_ip_whitelist_entry or user_get_ip_whitelist_entry. There is no when-to-use guidance, prerequisites, or exclusion criteria, so an agent must infer usage from the action name.

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