Delete change request

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is fully covered by structured data. The description contributes the error contract (MissingParameterError, ParameterError on invalid params or JSON deserialization failure) and states it returns a parsed Pydantic model, which is modest added value but nothing about the consequences of deletion or permission 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?

The body is mostly Sphinx boilerplate (:type, :rtype, repeated :raises ParameterError) rather than load-bearing content. The single substantive line is front-loaded, but the type/rtype lines restate schema information and the two duplicate ParameterError entries pad the text.

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 destructive, 22-parameter tool with no output schema and zero schema description coverage, the description is far too thin. It hints at a returned Pydantic model without describing it and leaves the majority of parameters and the deletion's side effects unexplained.

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, and the description documents only two of them (change_request_sys_id, change_type), neither with format detail. It never explains the other 20 parameters (sysparm_query, api_parameters, cmdb_ci_sys_ids, etc.) or why a delete operation exposes them, leaving most of the surface undocumented in both schema and prose.

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 verb and resource ("Delete a change request"), so the agent knows exactly what operation is performed. It does not, however, differentiate itself from closely named siblings such as delete_change_request_task or delete_change_request_conflict_scan, leaving ambiguity about which deletion target applies.

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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives (e.g., update_change_request when a record should be modified rather than removed). The only implied usage comes from the MissingParameterError note about change_request_sys_id.

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