Create change request task

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

Annotations already declare the write/idempotency/open-world profile, so the safety burden is lightened. The description adds real value by stating the raises behavior (MissingParameterError when change_request_sys_id or name_value_pairs is absent), which is important because the schema declares zero required parameters. It still omits what a successful call does to the change request and any permission constraints.

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 purpose sentence is front-loaded and clear, but the body is Sphinx docstring boilerplate whose :type: lines merely restate schema types and whose :rtype: adds little. It is not bloated, but several lines do not earn their place.

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 22-parameter creation tool with no output schema and no annotations beyond generic hints, the description should explain required inputs, the shape of 'data', and error/recovery behavior. Instead it covers a fraction of the surface, leaving an agent unable to construct a correct call for most parameters.

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 22 parameters, so the description must carry the param burden and it does not: it documents only change_request_sys_id and data, and mentions name_value_pairs only in a raises clause. The remaining ~19 parameters (state, change_type, template_sys_id, sysparm_* etc.) are undocumented anywhere.

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 opening sentence states a specific verb (Create) and resource (a new task associated with a change request), which is enough to separate it from the sibling servicenow_create_change_request. It does not, however, explicitly contrast itself with update_change_request_task or delete_change_request_task, so an agent must infer the differentiation.

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 never says when to use this tool versus alternatives, nor what preconditions exist beyond a raise note about missing params. There is no guidance on when a task should be created instead of updating an existing one.

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