Image Label MCP Server

Remove annotations

remove_annotations

DestructiveIdempotent

Delete specific image annotations by their IDs while keeping all other annotations intact and returning the number removed and updated total.

Instructions

Remove specific annotations from an image by their ids, keeping all the others.

Use it to delete a few annotations; to change many at once (rename labels, fix shapes) use replace_annotations instead. Get the ids from get_image (each annotation's id field). Ids that are not on the image are ignored, and the rest are removed in one save. Returns the number removed and the new annotation count.

Input Schema

Name	Required	Description	Default
`image_id`	Yes	Id of an image in Image Label: the imageId (a UUID string) returned by list_images or an upload.
`annotation_ids`	Yes	Ids of the annotations to delete (the id field of each annotation from get_image); ids not on the image are ignored.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.8.1Oct 28, 2026

addedInput schema / properties / annotation_ids / description

Added value: +"Ids of the annotations to delete (the id field of each annotation from get_image); ids not on the image are ignored."

addedInput schema / properties / image_id / description

Added value: +"Id of an image in Image Label: the imageId (a UUID string) returned by list_images or an upload."

First observedv0.1.0Oct 17, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: unknown ids are silently ignored rather than erroring, and all removals happen in a single atomic save. It does not explicitly restate irreversibility, but the destructive hint covers that ground.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and scope, then the alternative, then edge-case behavior. The final sentence on return values is somewhat redundant given an output schema exists, but the rest of the text is dense and waste-free.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter destructive mutation with full schema coverage, annotations, and an output schema, the description covers scope, alternative routing, id sourcing, and unknown-id handling. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are already documented in detail, including the UUID format and the 'ids not on the image are ignored' note. The description's mention of get_image's id field largely duplicates the schema, so it adds little beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (remove) plus resource (annotations) and the scoping qualifier 'by their ids, keeping all the others,' which makes the partial-deletion semantics unambiguous. It is clearly distinguishable from add_annotations and replace_annotations 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('delete a few annotations') and names the alternative plus its selecting condition ('to change many at once ... use replace_annotations instead'). It also routes the agent to get_image for id acquisition, closing the prerequisite loop.

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