Tools

​

What is a Tool?

1. Represents a Specific Action: A Tool performs a discrete operation, such as get_contact_details, create_calendar_event, post_message_to_channel, query_database_records, or summarize_document.
2. Is Provided by a Connector: Every Tool is exposed by a specific Connector. The Connector is responsible for implementing the Tool’s logic and translating the ACP request into the native API calls of the target system.
3. Has a Clear Definition (Schema): Tools are described by a schema that typically includes:
   • Name: A unique identifier for the Tool (e.g., salesforce_get_contact_by_email).
   • Description: A human-readable explanation of what the Tool does, often used by Agentforce agents to understand its purpose.
   • Input Parameters: A defined set of inputs the Tool expects, including their names, data types, and whether they are required or optional.
   • Output/Response Format: A description of the data structure the Tool will return upon successful execution.
4. Is Discoverable via the ACP Registry: Tools are listed in a central place (the ACP Registry). This makes it easy for agents to discover them or for you to find them when building Flows.
5. Automatic Agentforce Actions: Each Tool is automatically available as an ‘Action’ within Agentforce Agent Builder, grouped under its parent Connector’s ‘Topic’. This makes it incredibly easy for administrators to add specific skills to Agentforce Agents without manual configuration of individual agent actions.

​

Key Characteristics of Tools

• Action-Oriented: Tools are designed to do something. They are the verbs in an agent’s vocabulary.
• Standardized Interaction: Agents interact with all Tools using the same ACP request/response flow, regardless of the underlying system or Connector.
• Granular: Tools typically represent fine-grained capabilities, allowing agents to compose more complex behaviors by combining multiple Tool invocations.
• Self-Describing: The schema associated with each Tool provides enough information for an agent (or a developer) to understand its purpose and how to use it.

​

How Agents Use Tools

1. Discovery: An AI agent, often guided by a user’s request or a predefined workflow, queries the ACP Registry to find Tools relevant to its current task. It might search by Tool name, description, or the type of Connector it needs.
2. Parameter Preparation: Once a suitable Tool is identified, the agent prepares the required input parameters based on the Tool’s schema and the information it has.
3. Invocation: The agent sends an ACP request to the appropriate Connector, specifying the Tool name and providing the prepared input parameters.
4. Response Handling: The Connector executes the Tool’s logic (interacting with the target system) and returns a standardized ACP response to the agent. The agent then processes this response to continue its task.

​

Finding the Right Tool

• Agentforce Agents: When an administrator configures an Agentforce Agent, they can easily browse available ‘Topics’ (representing Connectors) and add their associated ‘Actions’ (representing Tools) directly in Agentforce Agent Builder. This grants the agent the skill. When a user interacts with the agent, it then intelligently selects the appropriate Action (Tool) based on the request.
• Salesforce Flow: When you’re building a Flow, you’ll see a list of available ACP Tools (as Flow Actions) that you can add to your automation, typically discovered via the ACP Registry.

​

Examples: Using Tools

​

Example 1: Creating a Campaign Draft in Marketing Cloud

• Connector: MarketingCloudConnector
• Tool Name: create_campaign_draft
• Description: “Creates a new draft campaign in Marketing Cloud with the specified details.”
• Input Parameters:
  • campaignName (string, required): The desired name for the campaign (e.g., “Summer Sale 2024”).
  • campaignType (string, required, enum: [“Email”, “SMS”, “Push”]): The type of campaign.
  • targetAudienceId (string, optional): The ID of a pre-defined audience segment.
  • startDate (date, optional): The proposed start date for the campaign.
• Output: A JSON object containing campaignId (the ID of the newly created draft campaign) and status (“Draft”).

1. The agent identifies the need to create a campaign.
2. It discovers the create_campaign_draft Tool via the ACP Registry.
3. It prepares inputs, for example: {"campaignName": "Q3 Product Launch Teaser", "campaignType": "Email", "targetAudienceId": "SEGMENT_001XYZ"}.
4. It invokes the Tool via the MarketingCloudConnector.
5. It receives a response like {"campaignId": "MC_CAMP_789123", "status": "Draft"} and can then proceed to add content or schedule the campaign using other Tools.

​

Example 2: Getting Audience Insights from Data Cloud

• Connector: DataCloudConnector
• Tool Name: get_audience_segment_insights
• Description: “Retrieves key insights and calculated metrics for a specified audience segment in Data Cloud.”
• Input Parameters:
  • segmentId (string, required): The unique identifier of the Data Cloud segment (e.g., “DC_SEG_ABC789”).
  • requestedInsights (array of strings, optional): A list of specific insights to retrieve (e.g., ["average_purchase_value", "preferred_communication_channel", "propensity_to_churn"]). If omitted, a default set of insights is returned.
• Output: A JSON object containing the segmentId and a nested insights object with key-value pairs for the requested (or default) insights, like {"average_purchase_value": 75.50, "preferred_communication_channel": "Email", ...}.

1. The agent is preparing a personalized offer for segment “DC_SEG_ABC789”.
2. It discovers the get_audience_segment_insights Tool.
3. It prepares inputs: {"segmentId": "DC_SEG_ABC789", "requestedInsights": ["average_order_value", "top_product_category_interest"]}.
4. It invokes the Tool via the DataCloudConnector.
5. It receives a response with the requested insights and uses this data to tailor the offer.