Contact tags

What it is

Contact tags is the manage_tags native tool. It lets the agent list the tags applied to the current conversation’s external contact, apply an existing tag, create and apply a new tag, or remove an association.

Tags form a catalog shared by the organization. A tag applied to the contact can help the team filter and prioritize conversations. The tool does not rename, recolor, or delete catalog tags.

Contact tag or conversation tag

Use Contact tags for a property of the person, such as customer, hot lead, or awaiting payment. The association follows the same contact record across its conversations.

Use Conversation tags to classify only the subject or process of one conversation, such as negotiation or refund. Contacts represented by separate records do not share tags automatically, even when they belong to the same person; those records must be merged first.

See Contact Tags for catalog, color, filter, and merge behavior. For tags scoped to one conversation, see Conversation Tags.

Before connecting

• Save the agent. In create mode, the Tools section shows Save the agent first until there is an agent to connect the tool to.
• Have write permission for that agent (agents.write). Reading the connection uses agents.view.
• Select a model that supports tools. Connecting the tool makes it available to the model; it does not force the model to call it.

Connect it to the agent

1. Open the agent and go to Tools.
2. Select Add Tool.
3. Under Native Tools, select Contact tags.

Selecting it creates an active connection immediately and returns to the tools list. There is no form or additional configuration. To disconnect it, remove Contact tags from the agent’s list.

Instruct the prompt

Under Prompt, open Available tools, select Contact tags, and use the suggestion containing {{tool:manage_tags}}. The reference does not connect or authorize the tool; it identifies the technical contract in the prompt and prevents the unreferenced-tool warning under Insights.

State the condition, canonical tag name, and expected result. For removal, tell the agent to list first and verify the list afterward. For example:

When the customer asks for a quote, use {{tool:manage_tags}} to list the tags. If hot lead is not already applied, add it. When payment is confirmed, list again, remove awaiting payment only if present, add customer, and verify the final list.

Standardize spelling in the prompt. Catalog uniqueness is case-insensitive, so Customer and customer represent the same name. Avoid variants such as hot-lead and hot lead, and until literal matching is fixed in the current product, do not use % or _ in names sent to the tool.

Available actions

Action	Input	Result
list	none	Returns the tags applied to the current contact, with id, name, and color.
add	required name	Trims surrounding whitespace, creates the catalog tag when needed, and applies the association. Repeating the same addition is idempotent.
remove	required name	Removes only the association between the tag and the contact. The tag remains in the organization’s catalog.

When it creates a tag, SquadOS assigns a deterministic color from the catalog’s eight colors. The agent receives the action result and can use it to continue its response.

Limits and verification

• An external contact is required. If the conversation has no external_contact_id, as in an internal Hub context, the tool returns an error and changes no tags.
• The association belongs to the contact record. It appears in other conversations tied to that same record, not across every identity or channel that seems to belong to the same person.
• Verify removals. In the current product, remove can report success when the tag exists in the catalog but was not applied to the contact. Listing before and after prevents the agent from claiming a change that did not happen.
• Refresh the UI after another source changes tags. An agent action may not update an already-open contact panel. Switch conversations or reload before trying to correct the association manually.
• Manage the catalog through the API. The product contains a Manage tags dialog, but it cannot be opened from the current Conversations interface. Use the Tags API to list, rename, recolor, or delete tags. Deleting a catalog tag removes it from every contact and cannot be undone.
• Test before enabling a channel. Save the prompt and use Test Agent with addition, repetition, and removal cases. The test uses the real tool, persists changes, and may consume credits.