Image Overlays & Annotations
Tools for image overlays and the classifications and user groups they apply to, plus record annotations.
This page covers 8 tools, all of them available on request rather than in the default tool list.
- Status — In the default tool list means the tool is one of the ~200 Aprimo advertises to every agent out of the box, so the agent discovers and calls it on its own. Available on request means the tool is registered and fully callable, but sits outside that default list — call it by name, or ask Aprimo to extend the list your tenant is served.
- Both statuses work identically when called. Status affects discovery, not capability or authorization.
- Visibility is not authorization. Every tool call executes as the authenticated user, and any tool can return an authorization error if that user lacks rights to the record, task, or file. See the MCP Tool Permission Map.
- Destructive tools are labelled as such. They delete or irreversibly overwrite data, and will not act unless the call sets both
confirmedandconfirmedDestructivetotrue. - Activity and Project labels vary by tenant. Where this page says Activity or Project, your tenant's own configured terminology is substituted at runtime.
Aprimo's MCP Server exposes far more tools than most MCP clients handle well — many degrade or truncate their tool list well below the full catalogue. Rather than let a client truncate arbitrarily, Aprimo advertises a curated set of roughly 200 tools covering the tasks customers most commonly automate. Everything outside that set remains fully supported and callable by name; it simply isn't offered up front. If your integration leans on a tool that is available on request, talk to your Aprimo Customer Success Manager about extending the advertised list for your tenant.
Tools at a Glance
| Tool | Status | What it does |
|---|---|---|
create_annotation | On request | Creates a new Aprimo annotation (a comment or XFDF markup) on a file version's page, optionally as a reply to another annotation. |
create_image_overlay | On request | Creates a new Aprimo image overlay. |
get_annotation | On request | Gets one Aprimo annotation's detail (comments, XFDF markup, page number, the file version/collection/parent annotation it belongs to) by id. |
get_image_overlay | On request | Gets one Aprimo image overlay's detail (name, enabled, dates) by id or by name. |
list_annotations | On request | Lists the Aprimo annotations (comments/markup attached to file version pages, used for collaborative review). |
list_image_overlay_classifications | On request | Lists the classification ids an Aprimo image overlay applies to, by id or by name. |
list_image_overlay_user_groups | On request | Lists the user group ids an Aprimo image overlay is scoped to (who can see it), by id or by name. |
list_image_overlays | On request | Lists the image overlays configured in Aprimo — a configurable graphic a rule action can apply on top of an image rendition (e.g. to visually flag its status), shown only to the user groups it's scoped to. |
create_annotation
Available on request
Creates a new Aprimo annotation (a comment or XFDF markup) on a file version's page, optionally as a reply to another annotation. This modifies data. Always confirm the file version, page, and comment/markup content with the user before calling this tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
fileVersionId | string | Yes | The id (GUID) of the file version this annotation is placed on. |
pageNumber | integer | No | Page number the annotation is placed on. Omit if not page-specific. |
comments | string | No | Comment text for the annotation. |
xfdfString | string | No | Required (not actually optional — DAM has no supported plain-comment-with-no-markup annotation shape; DAM's own create-annotation validation rejects an empty/missing value). XFDF markup describing the annotation's shape and position. |
parentAnnotationId | string | No | The id (GUID) of the parent annotation, when this annotation is a reply. Omit for a top-level annotation. |
taggedUserIds | array of string | No | User ids (GUIDs) tagged in this annotation. Omit for none. |
collectionId | string | No | The id (GUID) of the collection this annotation belongs to, if any. |
createdBy | string | No | The id (GUID) of the user creating the annotation. Omit to let DAM default to the caller. |
id | string | No | Optional specific id (GUID) for the new annotation. DAM itself requires a non-empty id and never generates one server-side — when omitted, mcp generates a new GUID client-side so callers don't have to. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
fileVersionId | string | |
pageNumber | integer (optional) |
create_image_overlay
Available on request
Creates a new Aprimo image overlay. This modifies data. Always confirm the name and which user groups/classifications it should apply to with the user before calling this tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name for the new image overlay, exactly as the user stated it. |
enabled | boolean | No | Whether the image overlay is enabled. Omit to use DAM's default. |
userGroupIds | array of string | No | Required (not actually optional — DAM rejects an image overlay with no user groups: "UserGroups: This collection can not be empty."). User group ids (GUIDs) this overlay is scoped to (only these groups will see it). |
classificationIds | array of string | No | Required (not actually optional — DAM rejects an image overlay with no classifications: "Classifications: This collection can not be empty."). Classification ids (GUIDs) this overlay applies to. |
Returns:
| Field | Type | Description |
|---|---|---|
id | integer | |
name | string |
get_annotation
Available on request
Gets one Aprimo annotation's detail (comments, XFDF markup, page number, the file version/collection/parent annotation it belongs to) by id. Use after list_annotations.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
annotationId | string | Yes | The annotation id (GUID), from list_annotations. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
fileVersionId | string (optional) | |
parentAnnotationId | string (optional) | |
collectionId | string (optional) | |
pageNumber | integer (optional) | |
comments | string (optional) | |
xfdfString | string (optional) | |
createdBy | string (optional) | |
modifiedBy | string (optional) | |
createdOn | string (optional) | |
modifiedOn | string (optional) |
get_image_overlay
Available on request
Gets one Aprimo image overlay's detail (name, enabled, dates) by id or by name. Use after list_image_overlays, or pass name directly when the user names the overlay. Use list_image_overlay_classifications/list_image_overlay_user_groups to see what it applies to.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
imageOverlayId | integer | No | The image overlay id (integer), from list_image_overlays. Provide this or name, not both. |
name | string | No | The image overlay's name (case-insensitive, exact match). Provide this or imageOverlayId, not both. |
Returns:
| Field | Type | Description |
|---|---|---|
id | integer | |
name | string | |
enabled | boolean (optional) | |
createdOn | string (optional) | |
modifiedOn | string (optional) |
list_annotations
Available on request
Lists the Aprimo annotations (comments/markup attached to file version pages, used for collaborative review). Use when the user asks what annotations exist on a file version/collection, or to look up an annotation's id before calling get_annotation.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | Optional filter expression (DAM query syntax), e.g. "FileVersionId=...". Omit to list every annotation the caller may see. |
sort | string | No | Optional sort expression, e.g. "createdOn". Omit for the endpoint's default order. |
skip | integer | No | Number of items to skip, for paging. Defaults to 0. |
take | integer | No | Maximum number of items to return. Omit for the endpoint's default page size. |
Returns:
| Field | Type | Description |
|---|---|---|
count | integer | |
items | array of AnnotationPayload | |
items[].id | string | |
items[].fileVersionId | string (optional) | |
items[].parentAnnotationId | string (optional) | |
items[].collectionId | string (optional) | |
items[].pageNumber | integer (optional) | |
items[].comments | string (optional) | |
items[].xfdfString | string (optional) | |
items[].createdBy | string (optional) | |
items[].modifiedBy | string (optional) | |
items[].createdOn | string (optional) | |
items[].modifiedOn | string (optional) |
list_image_overlay_classifications
Available on request
Lists the classification ids an Aprimo image overlay applies to, by id or by name.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
imageOverlayId | integer | No | The image overlay id (integer). Provide this or name, not both. |
name | string | No | The image overlay's name (case-insensitive, exact match). Provide this or imageOverlayId, not both. |
Returns:
| Field | Type | Description |
|---|---|---|
imageOverlayId | integer | |
count | integer | |
items | array of ImageOverlayClassificationPayload | |
items[].classificationId | string |
list_image_overlay_user_groups
Available on request
Lists the user group ids an Aprimo image overlay is scoped to (who can see it), by id or by name.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
imageOverlayId | integer | No | The image overlay id (integer). Provide this or name, not both. |
name | string | No | The image overlay's name (case-insensitive, exact match). Provide this or imageOverlayId, not both. |
Returns:
| Field | Type | Description |
|---|---|---|
imageOverlayId | integer | |
count | integer | |
items | array of ImageOverlayUserGroupPayload | |
items[].userGroupId | string |
list_image_overlays
Available on request
Lists the image overlays configured in Aprimo — a configurable graphic a rule action can apply on top of an image rendition (e.g. to visually flag its status), shown only to the user groups it's scoped to. Use when the user asks what image overlays exist, or to look up an image overlay's id/exact name before calling get_image_overlay by name.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | Optional filter expression (DAM query syntax), e.g. "ModifiedOn in today". Omit to list every image overlay. |
sort | string | No | Optional sort expression, e.g. "createdOn". Omit for the endpoint's default order. |
skip | integer | No | Number of items to skip, for paging. Defaults to 0. |
take | integer | No | Maximum number of items to return. Omit for the endpoint's default page size. |
Returns:
| Field | Type | Description |
|---|---|---|
count | integer | |
items | array of ImageOverlayPayload | |
items[].id | integer | |
items[].name | string | |
items[].enabled | boolean (optional) | |
items[].createdOn | string (optional) | |
items[].modifiedOn | string (optional) |
Related
- Aprimo MCP Server — configuration, connection details, and authentication
- MCP Tool Permission Map — the Aprimo permissions that make each tool visible to your agent
- REST API vs. MCP — choosing the right integration approach for your agent