remove_external_link

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

The description's 'Remove' matches the annotations' destructiveHint=true and readOnlyHint=false, so there is no contradiction. It adds that the link is an external ticket link and that valid identifiers are the UUIDs produced by specific companion tools. However, it does not add much behavioral detail beyond what the annotations already express, such as irreversibility or failure behavior.

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?

One clear, front-loaded sentence communicates the operation, the target, and the source of the required identifier. There is no filler or redundant restating of the schema.

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 one-parameter destructive tool with an informative annotation set and no output schema, this is sufficiently complete. The annotations establish that it is destructive and non-read-only, and the description supplies the remaining practical context: what kind of link and how to obtain its UUID.

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?

The schema has 0% description coverage, but the description compensates by explaining that linkId is a link UUID and, more usefully, that it comes from add_external_link or list_external_links. This gives an agent concrete guidance on where to find a valid value rather than simply naming the field.

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 ('Remove'), a clear resource ('external ticket link'), and the exact key needed to identify it (link UUID). It also names the source tools that produce the UUID (add_external_link or list_external_links), which disambiguates it from related link-based siblings.

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 effectively tells the agent when this tool is appropriate: when there is an external link UUID, and it explains how to obtain that UUID. It does not explicitly state when not to use it or name alternatives for non-removal operations, but the single-job scope is clear enough.

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