This server provides AI-powered tools to interact with Salesforce, enabling natural-language querying, opportunity intelligence, pipeline analytics, and standard CRM operations.
Core Salesforce Operations
Execute SOQL queries: Run any SOQL query against your Salesforce org with pagination support
Describe objects: Get full metadata and field schemas for any Salesforce object, with optional intent-based filtering (pipeline, engagement, forecasting, etc.)
Search fields: Discover field API names by searching across labels, names, and help text
Create, update, delete records: Manage records in any Salesforce object, including custom fields
List objects: Browse all available standard and custom Salesforce objects
Get user info: Retrieve information about the currently authenticated user
Download files: Download files by ContentVersionId or ContentDocumentId
Batch operations: Execute multiple operations in a single call, with result chaining between steps
Opportunity Management
Search opportunities: Find opportunities by name, account, or stage with pagination
Get opportunity details: Retrieve full details of a specific opportunity with intent-based field selection
Opportunity Intelligence & Analytics
Analyze conversations: Analyze engagement patterns from calls, emails, and activities tied to an opportunity
Enrich opportunities: Add market intelligence, industry insights, and strategic recommendations
Find similar opportunities: Discover deals similar to a reference opportunity or matching specific criteria, with pattern analysis and similarity scoring
Opportunity insights: Generate pipeline health reports, stage conversion rates, owner performance metrics, and industry trends
Generate business case: Automatically produce a professional markdown business case report for an opportunity, pulling in contacts, conversation insights, and comparable won deals
Run analytics: Perform group-by and aggregation analytics on any Salesforce object with custom computed expressions
Provides tools for interacting with Salesforce, including opportunity intelligence, conversation analysis, business case generation, and standard CRUD operations, enabling AI agents to search, analyze, and manage Salesforce records.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Salesforce MCP Server Show me all opportunities over $100K in proposal stage"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This MCP (Model Context Protocol) server provides AI-powered tools for interacting with Salesforce, featuring opportunity intelligence, conversation analysis, business case generation, and standard CRUD operations. Built with pagination support and optimized response structures for AI workflows.
Imagine having a sales expert that instantly knows everything about your deals and can give you winning strategies. That's what this AI does with your Salesforce data.
You say: "Show me all Microsoft deals over $100K in the proposal stage"
AI does: Searches your entire Salesforce database and returns matching opportunities
You say: "How's the engagement on the Acme deal? Are we talking to the right people?"
AI does: Analyzes all your calls, emails, and activities to give engagement insights
You say: "Find me deals similar to this opportunity that we won"
AI does: Scans your database for similar successful deals and success patterns
You say: "Create a business case document for this opportunity"
AI does: Generates a professional PDF ready for executives
Scenario: "I'm struggling with the Acme Corp deal. It's been stuck in negotiation for 2 months."
AI Response: "Let me analyze the Acme opportunity... I see limited engagement in the past 3 weeks. You've had 2 calls with procurement but haven't connected with the decision maker yet. Similar deals that got unstuck had executive sponsor engagement. I found 3 comparable deals where scheduling an executive briefing moved things forward. Here's a business case document you can use..."
Scenario: "My manager wants to know why our cloud migration deals are taking so long to close."
AI Response: "Analyzing your cloud migration opportunities... The average sales cycle is 40% longer than industry standard. The pattern shows deals stall in the technical evaluation stage. Successful cloud deals had solution architects engaged 2 weeks earlier on average. I recommend involving technical resources sooner..."
đ Smart Search: Find any opportunity with natural language
đŦ Engagement Analysis: Know who you're talking to and who you're missing
đ§ Strategic Insights: Get recommendations based on similar successful deals
đ Pipeline Intelligence: Understand your pipeline health and conversion patterns
đ Professional Documents: Generate business cases and executive summaries
đ Performance Analytics: See what's working and what needs attention
The Magic: You just chat naturally. The AI automatically connects to your Salesforce, analyzes millions of data points, finds patterns, and gives you actionable recommendations. It's like having a sales intelligence team, data analyst, and business consultant all rolled into one AI that knows your Salesforce inside and out.
đ¤ You | Can you look for any open salesforce opportunities where the solution engineer includes Aaron Rochelle? |
đ¤ AI Assistant | Let me help you search for Salesforce opportunities where Aaron Rochelle is involved as a Solution Engineer. I'll run a query in your Salesforce database to find opportunities matching that criteria...đ Found 3 opportunities:âĸ Cloud Migration - Acme Corp ($250K, Proposal)âĸ Digital Transformation - TechFlow ($180K, Qualification)âĸ Infrastructure Upgrade - GlobalTech ($320K, Negotiation) |
đ¤ You | Tell me more about the Acme Corp opportunity |
đ¤ AI Assistant | Here are the key details for the Acme Corp Cloud Migration opportunity:đŧ Opportunity Details:âĸ Account: Acme Corpâĸ Amount: $250,000âĸ Stage: Proposalâĸ Close Date: 2024-03-15âĸ Decision Maker: Sarah Johnson (IT Director)đ Intelligence Insights:âĸ Similar cloud deals average 45 days in proposal stageâĸ 73% win rate when executive sponsor engaged earlyâĸ Competitor: AWS (primary threat)âĸ Next action: Schedule technical deep-dive |
đ¤ You | What similar deals have we won? Show me the patterns |
đ¤ AI Assistant | I found 8 similar cloud migration deals you've won in the past 12 months. Here are the key patterns:đ¯ Success Patterns:âĸ Average deal size: $275K (vs $250K current)âĸ 67% had solution architect engaged by day 14âĸ 89% included a pilot/POC phaseâĸ Executive sponsors attended 78% of demosđ Recommendation: Schedule Aaron for a technical deep-dive with their DevOps team this week. Based on similar wins, proposing a 2-week pilot will increase close probability by 34%.đ Would you like me to generate a business case document for this opportunity? |
Related MCP server: Salesforce MCP Server
The Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools and resources. MCP servers provide specific capabilities that can be used by AI models through a consistent interface. This Salesforce MCP server allows AI models to interact with Salesforce data and operations in a structured way.
# Run directly with npx
npx @aaronsb/salesforce-cloud-mcp
# Or install globally
npm install -g @aaronsb/salesforce-cloud-mcpgit clone https://github.com/aaronsb/salesforce-cloud.git
cd salesforce-cloud
npm install
npm run build
node build/index.jsThe server requires configuration in your Claude desktop app's configuration file. On Linux, this is located at ~/.config/Claude/claude_desktop_config.json. On macOS, it's at ~/Library/Application Support/Claude/claude_desktop_config.json.
Add the following configuration to the mcpServers object in your config file:
{
"mcpServers": {
"salesforce-cloud": {
"command": "node",
"args": ["/path/to/salesforce-cloud/build/index.js"],
"env": {
"SF_CLIENT_ID": "your_client_id",
"SF_CLIENT_SECRET": "your_client_secret",
"SF_USERNAME": "your_salesforce_username",
"SF_PASSWORD": "your_salesforce_password",
"SF_LOGIN_URL": "https://login.salesforce.com"
}
}
}
}SF_CLIENT_ID: Your Salesforce OAuth client ID
SF_CLIENT_SECRET: Your Salesforce OAuth client secret
SF_USERNAME: Your Salesforce username
SF_PASSWORD: Your Salesforce password
SF_LOGIN_URL: Salesforce login URL (optional, defaults to https://login.salesforce.com)
To obtain these credentials:
Go to Setup in your Salesforce org
Navigate to App Manager
Create a new Connected App
Enable OAuth settings
Add necessary OAuth scopes
Save and wait for activation
Copy the generated Consumer Key (Client ID) and Consumer Secret (Client Secret)
When constructing queries or working with Salesforce data, it's important to understand that many fields referenced may be custom fields specific to your Salesforce instance. Here's what you need to know:
Custom fields in Salesforce end with __c in their API names
What appears as "Implementation Status" in the UI might be stored as "Implementation_Status__c"
Custom fields can represent organization-specific business concepts
Object Metadata Analysis:
Use the describe_object tool with includeFields: true to examine both standard and custom fields
Look for fields that match your intent in both standard and custom field lists
Map user-friendly field names to their actual API names
Field Type Consideration:
Custom fields can be various types (text, picklist, lookup, etc.)
Understanding field types helps construct appropriate queries
Custom fields might reference other custom objects through lookup relationships
Query Construction:
Build queries that can handle both standard and custom fields
Use field metadata to validate field existence before querying
Consider relationships between objects, especially with custom lookup fields
If searching for "Project Status":
First, examine the object's fields to find the actual field name:
{
"objectName": "Opportunity",
"includeFields": true
}Look for fields like "Project_Status__c" or similar custom fields that match your intent
Use the discovered field name in your queries:
{
"query": "SELECT Id, Name, Project_Status__c FROM Opportunity"
}Find the field(s) that carry a concept when you know what you want to query but not the API name. Searches the discovered field catalog (ADR-302) by keyword across field API names, labels, and help text, ranked by match strength.
{
term: string; // Required: matched against field name, label, help text
objectName?: string; // Optional: scope to one object (default: all core objects)
includeValues?: boolean; // Optional: return active picklist values for matches (default: false)
minPopulationPct?: number;// Optional: drop fields below this population density (0-100)
limit?: number; // Optional: max matches (default: 25, max: 100)
}Example:
{
"term": "ai",
"objectName": "Opportunity",
"includeValues": true
}The match is lexical, not semantic: it finds fields whose metadata contains the term, so a concept the schema names differently won't surface â read salesforce://field-catalog/{objectName}/all to browse everything.
Execute a SOQL query with pagination support.
{
query: string; // Required: SOQL query to execute
pageSize?: number; // Optional: Number of records per page (default: 25)
pageNumber?: number; // Optional: Page number to retrieve (default: 1)
}Example:
{
"query": "SELECT Id, Name FROM Account",
"pageSize": 10,
"pageNumber": 1
}Get metadata about a Salesforce object with optional field information.
{
objectName: string; // Required: API name of the Salesforce object
includeFields?: boolean; // Optional: Whether to include field metadata (default: false)
pageSize?: number; // Optional: Number of fields per page (default: 50)
pageNumber?: number; // Optional: Page number to retrieve (default: 1)
}Example:
{
"objectName": "Account",
"includeFields": true
}Create a new record in Salesforce.
{
objectName: string; // Required: API name of the Salesforce object
data: Record<string, any>; // Required: Record data as key-value pairs
}Example:
{
"objectName": "Account",
"data": {
"Name": "Test Account",
"Industry": "Technology"
}
}Update an existing record in Salesforce.
{
objectName: string; // Required: API name of the Salesforce object
recordId: string; // Required: ID of the record to update
data: Record<string, any>; // Required: Record data to update
}Example:
{
"objectName": "Account",
"recordId": "001XXXXXXXXXXXXXXX",
"data": {
"Name": "Updated Account Name"
}
}Delete a record from Salesforce.
{
objectName: string; // Required: API name of the Salesforce object
recordId: string; // Required: ID of the record to delete
}Example:
{
"objectName": "Account",
"recordId": "001XXXXXXXXXXXXXXX"
}Get information about the current user. No parameters required.
{}List all available Salesforce objects with pagination support.
{
pageSize?: number; // Optional: Number of objects per page (default: 25)
pageNumber?: number; // Optional: Page number to retrieve (default: 1)
}Search for Salesforce opportunities using flexible criteria and pattern matching.
{
namePattern?: string; // Optional: Pattern to match in Opportunity Name
accountNamePattern?: string; // Optional: Pattern to match in Account Name
stage?: string; // Optional: Exact match for opportunity stage
pageSize?: number; // Optional: Number of records per page (default: 25)
pageNumber?: number; // Optional: Page number to retrieve (default: 1)
}Get detailed information about a specific opportunity including all available fields and related records.
{
opportunityId: string; // Required: The ID of the Salesforce opportunity
}Analyze conversation activity and engagement patterns for an opportunity. Extracts insights from calls, emails, and other activities to provide engagement recommendations.
{
opportunityId: string; // Required: The ID of the Salesforce opportunity
}Example:
{
"opportunityId": "006XXXXXXXXXX"
}Enrich an opportunity with market intelligence, industry insights, and strategic recommendations based on similar deal patterns and best practices.
{
opportunityId: string; // Required: The ID of the Salesforce opportunity
includeCompetitiveIntel?: boolean; // Optional: Include competitive analysis (default: false)
includeBestPractices?: boolean; // Optional: Include best practices (default: true)
}Example:
{
"opportunityId": "006XXXXXXXXXX",
"includeCompetitiveIntel": true,
"includeBestPractices": true
}Find opportunities similar to a reference opportunity or based on specific criteria. Includes pattern analysis and similarity scoring.
{
referenceOpportunityId?: string; // Optional: Reference opportunity for similarity matching
industry?: string; // Optional: Filter by industry
minAmount?: number; // Optional: Minimum opportunity amount
maxAmount?: number; // Optional: Maximum opportunity amount
stage?: string; // Optional: Filter by opportunity stage
isWon?: boolean; // Optional: Filter by won/lost status
closeDateStart?: string; // Optional: Start date (YYYY-MM-DD)
closeDateEnd?: string; // Optional: End date (YYYY-MM-DD)
includeAnalysis?: boolean; // Optional: Include pattern analysis (default: true)
limit?: number; // Optional: Max results (default: 50)
}Examples:
Find similar to a reference opportunity:
{
"referenceOpportunityId": "006XXXXXXXXXX",
"includeAnalysis": true
}Find by criteria:
{
"industry": "Information Technology & Services",
"minAmount": 100000,
"stage": "Closed Won",
"limit": 20
}Generate detailed insights and analytics from opportunity data including pipeline health, performance metrics, and trends.
{
timeframe?: string; // Optional: 'current_quarter', 'last_quarter', etc.
includeStageAnalysis?: boolean; // Optional: Stage distribution analysis (default: true)
includeOwnerPerformance?: boolean; // Optional: Owner performance metrics (default: true)
includeIndustryTrends?: boolean; // Optional: Industry trends (default: true)
includePipelineHealth?: boolean; // Optional: Pipeline health analysis (default: true)
includeConversionRates?: boolean; // Optional: Conversion rates (default: true)
minAmount?: number; // Optional: Minimum amount filter
maxAmount?: number; // Optional: Maximum amount filter
industry?: string; // Optional: Industry filter
owner?: string; // Optional: Owner filter
}Example:
{
"timeframe": "current_quarter",
"includeStageAnalysis": true,
"includeOwnerPerformance": true,
"minAmount": 50000
}Generate a professional business case document for an opportunity. Returns step-by-step instructions for creating a formatted business case using TeXFlow.
{
opportunityId: string; // Required: The ID of the Salesforce opportunity
clientName?: string; // Optional: Client name for the document title
outputFormat?: string; // Optional: 'pdf', 'docx', or 'markdown' (default: 'pdf')
}Example:
{
"opportunityId": "006XXXXXXXXXX",
"clientName": "Acme Corporation",
"outputFormat": "pdf"
}Operations that return multiple records use this format:
{
records: T[]; // Array of records for the current page
totalSize: number; // Total number of records
pageInfo: {
currentPage: number; // Current page number
totalPages: number; // Total number of pages
hasNextPage: boolean; // Whether there are more pages after this one
hasPreviousPage: boolean; // Whether there are pages before this one
}
}All tools return errors in a consistent format:
{
content: [{
type: "text",
text: "Error: [error message]"
}],
isError: true
}To run the server locally for development:
Set up your environment variables in a .env file
Build the project:
npm run buildStart the server:
node build/index.jsđ§ AI-Powered Intelligence: Advanced opportunity analysis, conversation insights, and market intelligence
đ Pattern Recognition: Identify similar opportunities and success patterns in your pipeline
đ Business Case Generation: Automated creation of professional business case documents using TeXFlow
đ Smart Search: Flexible opportunity search with pattern matching and filtering
đ Pipeline Analytics: Detailed insights on pipeline health, conversion rates, and performance metrics
đ§ Standard Operations: Full CRUD operations with custom field support
đ Document Integration: Seamless integration with TeXFlow MCP server for document generation
⥠Optimized for AI: Response structures designed for AI model consumption
The Salesforce API offers numerous expansion opportunities:
Support for more Salesforce objects (Leads, Cases, Contacts, etc.)
Integration with Salesforce Flow and Process Builder
Enhanced competitive intelligence features
Bulk API operations for large datasets
Chatter API integration and social selling insights
Custom report and dashboard access
Advanced forecasting and predictive analytics
We'd love to hear your ideas about what would be most valuable to add next!
We welcome contributions from the community! Whether it's adding new features, improving documentation, or reporting bugs, your input helps make this project better for everyone. Feel free to submit a Pull Request or open an Issue to start a discussion.
This project is licensed under the MIT License - see the LICENSE file for details.
Run analytics on any Salesforce object â group by categorical fields, aggregate numeric fields, and compute custom expressions. Uses field-type metadata for validation.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | SOQL WHERE clause (e.g., "StageName = 'Closed Won' AND Amount > 100000") | |
| object | Yes | Salesforce object API name (e.g., Opportunity, Account, Lead) | |
| compute | No | Computed expressions (max 5). Format: name = expr. E.g., ["win_rate = won / total * 100"] | |
| groupBy | No | Field to group by (must be picklist, boolean, or similar categorical field) | |
| maxGroups | No | Max groups to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses metadata validation but omits side effects, permissions, rate limits, or return format. The absence of these details leaves significant uncertainty about runtime 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?
The description is a single, focused sentence that front-loads the primary purpose. It is concise, readable, and free of unnecessary jargon or redundancy.
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?
The tool has a moderate parameter set and no output schema. While the core functionality is described, the absence of output details and usage guidance leaves room for ambiguity in real-world invocation.
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?
All five parameters have descriptions with concrete examples (e.g., SOQL WHERE clause, expression format, default max groups). The descriptions add meaningful detail beyond the parameter names, achieving high coverage and clarity.
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 clearly states the tool runs analytics on Salesforce objects with grouping, aggregation, and custom expressions. It distinguishes itself from raw SOQL execution and object listing, though it does not explicitly name sibling tools.
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 provides no explicit guidance on when to use this tool versus alternatives like execute_soql or describe_object. It only mentions metadata-based validation, which hints at behavior but not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze conversation activity and engagement patterns for an opportunity. Extracts insights from Gong calls, emails, and other activities to provide engagement recommendations.
| Name | Required | Description | Default |
|---|---|---|---|
| opportunityId | Yes | The ID of the Salesforce opportunity to analyze conversation activity for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It states 'analyzes' and 'extracts insights' implying read-only behavior but doesn't disclose side effects, permissions, or output format.
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?
Two sentences with no wasted words; front-loaded with the core purpose and efficiently structured.
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?
Given a single parameter and no output schema or annotations, the description covers the tool's purpose, data sources, and output type (engagement recommendations). Adequate for the complexity level.
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?
Schema description coverage is 100% with a clear description for 'opportunityId'. The description adds no extra semantics beyond the schema, so baseline 3 is appropriate.
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 clearly states it analyzes conversation activity and extracts insights from specific sources (Gong calls, emails) for an opportunity, which is distinctive from generic siblings like 'analyze'. However, it does not explicitly differentiate from similar siblings like 'enrich_opportunity'.
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 implies usage when needing engagement insights for an opportunity, but lacks explicit guidance on when not to use it or mention of alternatives like 'enrich_opportunity'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute multiple operations in a single call with result references. Use $N.field to reference prior results (e.g., $0.id for the ID from operation 0). Destructive operations require confirm: true.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Response detail level (default: summary) | |
| onError | No | Error handling: bail (default) stops on first failure, continue executes remaining | |
| operations | Yes | List of operations to execute sequentially (max 16) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions sequential execution and the confirm requirement for destructive actions. However, it does not describe error handling behavior, partial failure semantics, or the default onError behavior, which is only covered in the schema parameter description.
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?
The description is concise and well-structured, with two sentences that convey purpose, usage, and a key constraint. The example of result references is helpful and does not bloat the text.
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?
The description is adequate for basic use but lacks an explanation of the output format or return value structure. Since no output schema is provided, agents may be unsure what the response contains (e.g., array of results, status codes). This gap reduces completeness.
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 description adds meaningful value beyond the schema by explaining the $N.field reference syntax with an example and clarifying that confirm is needed for delete operations. Parameter coverage is strong, though the onError and detail parameters are not elaborated in the description itself.
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 clearly states the tool executes multiple operations in a single call, which is a specific verb and resource. It does not explicitly distinguish itself from sibling tools that handle single operations, but the batching concept is inherently clear.
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 provides how-to details (result references, max 16 operations, confirm for destructive ops) but does not explicitly state when to prefer batch over individual calls or explain trade-offs. Usage guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new record in Salesforce. Supports both standard and custom fields in the data object.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Record data as key-value pairs. For custom fields, use the API name with __c suffix (e.g., { "Name": "Test", "Custom_Field__c": "Value" }) | |
| objectName | Yes | API name of the Salesforce object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the basic operation and field support, omitting important details like error handling, return value (e.g., record ID), or side effects. This is insufficient for a mutation tool.
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?
The description is a single sentence of 12 words, very concise. It front-loads the core purpose, but could be slightly more structured (e.g., separating supported fields). Still efficient and to the point.
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?
Given the tool's complexity (create with nested object, no output schema), the description lacks completeness. It doesn't mention the return value (e.g., record ID), potential errors, or behavior for required fields beyond those in the schema. More context is needed for an agent to use this reliably.
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?
Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value by confirming support for custom fields, which is already implied in the schema's custom field example. Baseline 3 is appropriate.
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 clearly specifies the action ('create') and the resource ('a new record in Salesforce'), and differentiates from sibling tools like delete_record or update_record. The mention of supporting both standard and custom fields adds specificity.
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 provides no guidance on when to use this tool versus alternatives such as update_record or batch. No explicit when-to-use, prerequisites, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a record from Salesforce
| Name | Required | Description | Default |
|---|---|---|---|
| recordId | Yes | ID of the record to delete | |
| objectName | Yes | API name of the Salesforce object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Delete', implying destructive action, but without annotations it fails to disclose whether deletion is permanent, reversible, or has side effects on related data.
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?
The description is short and front-loaded, but it lacks important details that could be included without being verbose. It is adequately concise but incomplete.
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?
With no output schema, the description fails to explain what the tool returns or what constitutes success/failure. It lacks completeness for a destructive operation.
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?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what is in the schema.
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 clearly states the action (Delete) and the resource (a record from Salesforce), which is distinct from sibling tools like create_record or update_record.
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?
No guidance on when to use or when not to use this tool. It does not mention that deletion is permanent, nor does it suggest alternatives like update_record for soft-deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an object's full metadata, including every standard and custom field when includeFields is true. Returns the complete schema â exhaustive but unranked, and large on customised objects. To find out which fields this org actually populates, read salesforce://field-catalog/{objectName} instead; it is ranked and far smaller.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | No | Business intent â filters fields to only those relevant for this use case. | |
| pageSize | No | Number of fields per page when includeFields is true (default: 50) | |
| objectName | Yes | API name of the Salesforce object | |
| pageNumber | No | Page number to retrieve when includeFields is true (default: 1) | |
| includeFields | No | Whether to include field metadata (default: false). When true, returns all available fields including custom fields, their types, and relationships. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of conveying behavior. It states that the output is a complete schema, exhaustive but unranked, and potentially large. It does not explicitly say whether the operation is read-only, but the tool name and 'describe' semantics strongly imply no mutation.
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?
The description is concise, well-structured, and front-loads the core purpose. It provides the key distinguishing information about the alternative field-catalog tool without unnecessary filler.
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?
The description gives enough context for an agent to decide when to use this tool, including the caveat that the full schema can be large and that a smaller, ranked alternative exists. There is no output schema, but for a describe/metadata tool the behavior is sufficiently clear.
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 covers all five parameters with 100% description coverage, so the additional description adds limited new semantic value. The includeFields parameter has a useful expanded explanation about custom fields and relationships, but the main description does not elaborate on intent, pageSize, or pageNumber beyond what the schema already provides.
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 clearly states the tool retrieves an object's full metadata, including all standard and custom fields when includeFields is true. It also distinguishes this from the field-catalog alternative, making the purpose unambiguous.
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 gives explicit guidance to use the field-catalog alternative when the agent needs to know which fields are actually populated, rather than the full schema. It could be slightly more explicit about when to choose this tool over other object-listing or search tools, but the main contrast is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a file from Salesforce. Accepts a ContentVersionId (068...) or ContentDocumentId (069...). Saves to a sandboxed workspace directory (default: ~/.local/share/salesforce-cloud-mcp/workspace/, configurable via SF_WORKSPACE_DIR). Text files (CSV, JSON, XML, TXT, etc.) also return content inline. Binary files return the saved path.
| Name | Required | Description | Default |
|---|---|---|---|
| contentId | Yes | ContentVersionId (068...) or ContentDocumentId (069...). Find these by querying ContentDocumentLink: SELECT ContentDocumentId FROM ContentDocumentLink WHERE LinkedEntityId = '<recordId>' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the side effect of saving to a workspace directory and the differing return behavior (inline content vs. saved path). With no annotations provided, this transparency is valuable, though it does not mention potential errors or permissions.
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?
The description is two concise sentences with no redundant wording or fluff. Every sentence contributes useful information.
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 single-parameter tool, the description covers the essential aspects: what it does, where it saves, and how it returns results. It does not mention file size limits or error handling, but these are not critical for basic usage.
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 already provides a thorough description for the single parameter (including ID types and a query example), so the tool description adds little new meaning. Baseline of 3 is appropriate given high schema description coverage.
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 clearly states the action (download) and resource (a file from Salesforce), and is distinct from all sibling tools which focus on records, SOQL, or analysis. It is immediately obvious when this tool is the right choice.
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 explains the ID types accepted and provides a query example to find them, which guides the user on how to obtain the necessary input. It also notes the behavioral difference between text and binary files, but does not explicitly contrast with alternatives (although no alternative download tool exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enrich an opportunity with market intelligence, industry insights, and strategic recommendations based on similar deal patterns and best practices.
| Name | Required | Description | Default |
|---|---|---|---|
| opportunityId | Yes | The ID of the Salesforce opportunity to enrich with intelligence | |
| includeBestPractices | No | Whether to include industry-specific best practices (default: true) | |
| includeCompetitiveIntel | No | Whether to include competitive intelligence analysis (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It does not state whether the operation is read-only, modifies the opportunity, or has side effects, and it lacks any mention of authorization, rate limits, or data sourcing.
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?
The description is a single, focused sentence with no redundant content. It efficiently conveys the tool's core function.
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?
The description explains the purpose but does not mention the return value, output structure, or error behavior. Since there is no output schema, more detail about what the enriched output looks like would improve completeness for an agent.
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?
Schema coverage is 100% with descriptions for all three parameters. The descriptions are largely tautological ('The ID of the Salesforce opportunity to enrich with intelligence'), but they do convey basic meaning and defaults for the boolean flags. No extra format or constraint details are provided.
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 action ('Enrich an opportunity') and the resource ('opportunity'), with a clear outcome (market intelligence, industry insights, strategic recommendations). However, it does not differentiate from overlapping siblings like 'opportunity_insights' or 'find_similar_opportunities'.
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?
No guidance is provided on when to use this tool versus alternatives such as 'opportunity_insights', 'find_similar_opportunities', or 'generate_business_case'. The description mentions based on similar deal patterns and best practices but does not specify conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SOQL query. Supports both standard and custom fields (custom fields end with __c in their API names). To see which fields this org actually populates on an object, read the salesforce://field-catalog/{objectName} resource â it is ranked, far smaller than a full schema, and works for any object. That catalog is a usage filter rather than a field list: standard fields remain queryable whether or not they appear in it. Use describe_object when you want an object's complete schema.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SOQL query to execute. For custom fields, use the API name (e.g., Project_Status__c) | |
| detail | No | Response detail level (default: summary) | |
| pageSize | No | Number of records per page (default: 25) | |
| pageNumber | No | Page number to retrieve (default: 1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It implies a read-only operation (query execution) but does not explicitly state it is non-destructive or safe. The description is not contradictory but lacks explicit behavioral disclosure.
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?
The description is front-loaded with the main action, uses exactly three sentences with no wasted words, and each sentence adds value (purpose, custom field handling, field discovery guidance).
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?
The tool has 4 parameters with full schema descriptions and no output schema. The description provides extra context about field discovery and alternatives, making it more complete. However, it does not explicitly state the return format or pagination behavior, a minor gap.
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?
Schema description coverage is 100% so baseline is 3. The description adds context for the 'query' parameter regarding custom fields and field catalog, but does not significantly enhance understanding of other parameters beyond their schema descriptions.
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 clearly states 'Execute a SOQL query' and specifies support for standard and custom fields, distinguishing it from sibling tools like search_fields or list_objects which serve different purposes.
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?
Provides explicit guidance: to see populated fields, use the field-catalog resource; for complete schema, use describe_object. This clearly tells the agent when and when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find opportunities similar to a reference opportunity or based on specific criteria. Includes pattern analysis and similarity scoring to identify market trends and success patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| isWon | No | Filter by won/lost status | |
| limit | No | Maximum number of results to return (default: 50) | |
| stage | No | Filter by opportunity stage (e.g., "Closed Won", "Proposal") | |
| industry | No | Filter by industry (e.g., "Information Technology & Services") | |
| maxAmount | No | Maximum opportunity amount | |
| minAmount | No | Minimum opportunity amount | |
| closeDateEnd | No | End date for close date range (YYYY-MM-DD) | |
| closeDateStart | No | Start date for close date range (YYYY-MM-DD) | |
| includeAnalysis | No | Whether to include pattern analysis and insights (default: true) | |
| referenceOpportunityId | No | Optional reference opportunity ID to find similar deals based on its characteristics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether the operation is read-only, what side effects occur, or what the return structure looks like. It mentions pattern analysis and similarity scoring but lacks sufficient behavioral detail.
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?
The description is concise, front-loaded with the core purpose, and contains no redundant or irrelevant information.
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?
The description covers the tool's main purpose and analytical nature but lacks information about output format, default behavior beyond the schema, and when a referenceOpportunityId is expected versus using filter criteria. It is adequate but not fully complete for an agent with no additional context.
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?
All 10 parameters are described in the schema and the descriptions are mostly clear, especially referenceOpportunityId and includeAnalysis. However, several descriptions simply restate the parameter names and add little semantic depth, keeping this at the baseline for full schema coverage.
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 clearly states the tool finds opportunities similar to a reference opportunity or based on specific criteria, and mentions pattern analysis and similarity scoring. It does not explicitly name sibling tools like search_opportunities to draw the distinction, so it stops short of a 5.
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?
There is no explicit guidance on when to use this tool versus sibling tools such as search_opportunities or opportunity_insights. The description implies analysis use cases but does not clarify when this tool should be preferred over basic search or dedicated insight tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a markdown business case report for an opportunity. Fetches opportunity details, contacts, conversation insights, and similar won deals to produce a complete report.
| Name | Required | Description | Default |
|---|---|---|---|
| clientName | No | Optional client name to override the account name in the report title | |
| opportunityId | Yes | The ID of the Salesforce opportunity to generate a business case for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool fetches multiple data sources (read operations) to produce a report, but does not mention side effects, authorization needs, or potential performance implications. The behavior is fairly transparent but lacks detail on output handling or error states.
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?
The description is two sentences: first states the core purpose, second details the data sources. No extraneous information, front-loaded with the key verb and resource.
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?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description covers the essential purpose and inputs. It lacks details on output format, error handling, or prerequisites, but overall is sufficiently complete for a straightforward report generator.
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?
Schema coverage is 100% with clear parameter descriptions. The tool description adds context about overall data fetching but does not enhance parameter meaning beyond what the schema already provides. Per calibration, baseline is 3 when schema does the heavy lifting.
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 clearly states it generates a markdown business case report for an opportunity and lists the specific data sources (opportunity details, contacts, conversation insights, similar won deals). This distinguishes it from sibling tools like 'get_opportunity_details' (only details) or 'find_similar_opportunities' (only similar deals).
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 implies use when a complete business case report is needed but does not explicitly state when to use this tool versus alternatives (e.g., 'analyze', 'enrich_opportunity'). No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a Salesforce opportunity including all available fields (both standard and custom), related records, and metadata
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | Response detail level (default: full) | |
| fields | No | Explicit field names to return. Overrides intent if both provided. | |
| intent | No | Business intent â selects relevant fields automatically. Omit for all fields. | |
| opportunityId | Yes | The ID of the Salesforce opportunity to retrieve details for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool returns fields, related records, and metadata, indicating a safe read operation. No side effects mentioned, but none expected.
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?
Single sentence, no redundant information, and directly states the tool's function.
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?
Given no output schema, the description adequately outlines what is returned (fields, related records, metadata). Lacks specifics on structure but sufficient for understanding.
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?
Schema has 100% coverage with clear parameter descriptions. The description adds no extra semantic value beyond the schema.
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 clearly states the tool retrieves detailed information about a Salesforce opportunity, including fields, related records, and metadata. It distinguishes from sibling tools like search_opportunities (searching) and enrich_opportunity (modifying).
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?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies read-only usage but does not address alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only says 'get information', implying a read operation, but does not explicitly state it is non-destructive or describe any other behavioral traits (e.g., no side effects, requires authentication).
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?
The description is a single, efficient sentence with no wasted words. It is front-loaded and appropriately sized for a parameterless tool.
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?
Given no output schema and simple action, the description is minimal. It does not specify what fields are returned, leaving ambiguity about the tool's output. However, for a straightforward user info tool, it is passable.
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?
There are zero parameters, and the schema coverage is 100%. Per guidelines, no-parameter tools get a baseline of 4. The description adds no param-specific info, which is acceptable here.
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 clearly states the tool retrieves information about the current user. It is specific and distinct from sibling tools, but could be improved by hinting at the type of information returned.
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?
No guidance is provided on when to use this tool vs alternatives, nor any context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Salesforce objects, including both standard and custom objects
| Name | Required | Description | Default |
|---|---|---|---|
| pageSize | No | Number of objects per page (default: 25) | |
| pageNumber | No | Page number to retrieve (default: 1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavior. It only states the inclusion of standard and custom objects, omitting details like pagination limits, rate limits, or whether the list is exhaustive of all objects in the org.
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?
Single sentence, front-loaded with the core purpose. No extraneous information.
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?
Given no output schema, the description could hint at the return format (e.g., list of object names or metadata). As is, it is minimally viable but lacks completeness for an agent to fully understand the tool's behavior.
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?
Schema coverage is 100% and both parameters (pageSize, pageNumber) are described in the schema. The description does not add additional meaning beyond what the schema already provides.
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 clearly states the tool lists all Salesforce objects (standard and custom), with a specific verb ('List') and resource ('available Salesforce objects'). This distinguishes it from sibling tools like 'create_record' or 'execute_soql'.
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?
No guidance on when to use this tool versus alternatives. It does not mention scenarios where it is preferable to use sibling tools like 'describe_object' or 'search_opportunities'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate detailed insights and analytics from opportunity data including pipeline health, performance metrics, industry trends, and strategic recommendations.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | Filter analysis to specific owner | |
| industry | No | Filter analysis to specific industry | |
| maxAmount | No | Maximum opportunity amount for analysis | |
| minAmount | No | Minimum opportunity amount for analysis | |
| timeframe | No | Time period for analysis | |
| includeStageAnalysis | No | Include stage distribution and conversion analysis (default: true) | |
| includeIndustryTrends | No | Include industry-specific performance trends (default: true) | |
| includePipelineHealth | No | Include pipeline health and timing analysis (default: true) | |
| includeConversionRates | No | Include stage conversion rate analysis (default: true) | |
| includeOwnerPerformance | No | Include individual owner performance metrics (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only states 'generate insights' without mentioning whether the tool is read-only, does it mutate data, require authentication, or has rate limits. Complete lack of transparency.
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?
The description is a single concise sentence that front-loads the key value proposition. It wastes no words, though it could benefit from bullet points or structured sections for clarity given the tool's complexity.
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?
With 10 parameters and no output schema, the description provides a broad overview of capabilities but misses details like whether results are returned in real-time or stored, and how to optimally combine parameters. Moderately complete for a tool of this complexity.
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?
Schema coverage is 100% with clear parameter descriptions. The description adds context by grouping parameters into categories (pipeline health, performance metrics, etc.), but does not elaborate on how parameters interact or specific formats. Adequate but not exceptional.
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?
Description clearly states the tool generates insights and analytics from opportunity data, listing specific categories like pipeline health and industry trends. However, it does not differentiate from siblings like 'analyze' or 'analyze_conversation', which may cause confusion.
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?
No usage guidelines are provided; the description does not indicate when to use this tool versus alternatives such as 'analyze' or 'get_opportunity_details'. The agent receives no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the field(s) that carry a concept, when you know what you want to query but not the API name. Searches every scored field on the discovered objects â not just the promoted ones â across API names, labels, and help text, ranked by match strength. Searches the core objects by default; pass objectName to scope to one, which discovers it on demand. Set includeValues to get the value set for matched picklists, so you can write the WHERE clause without a second lookup. The match is lexical, not semantic: it finds fields whose name, label or help text contains the term, so a concept this org names differently will not surface, and an object that has not been discovered is not searched. Read salesforce://field-catalog/{objectName}/all to browse everything on an object.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | What to look for, matched against field API names, labels, and help text (e.g. "ai", "renewal date", "region") | |
| limit | No | Maximum matches to return (default: 25, max: 100) | |
| objectName | No | Restrict the search to one object (e.g. Opportunity). Omit to search all discovered core objects. | |
| includeValues | No | Include the active value set for matched picklist fields (default: false). Free â the values come from metadata already discovered. | |
| minPopulationPct | No | Drop fields populated on fewer than this percent of records (0-100). Omit to include sparsely-populated fields, which is often where custom flags live. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Fully discloses limitations: lexical match, only discovered objects, and that includeValues is free. No contradictions.
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?
Single paragraph but well-organized with main purpose first. Each sentence adds value. Could be slightly more structured with bullet points, but still concise and clear.
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?
Covers behavior, limitations, and usage context thoroughly. Does not explicitly describe output format, but given no output schema, it mentions ranking. Slightly lacking in output details.
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?
Schema description coverage is 100%, but description adds meaning beyond schema (e.g., default behavior for objectName, cost-free for includeValues, clarification on minPopulationPct).
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?
Clearly states the tool's purpose: finding fields by concept when API name unknown. Describes what is searched (every scored field on discovered objects) and ranking. No sibling tool duplicates this function.
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?
Explicitly states when to use: when you know what to query but not API name. Provides exclusions (lexical not semantic, only discovered objects). Includes alternative for browsing via field-catalog resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Salesforce opportunities by name, account, and stage. Returns matching opportunities ordered by close date. Results include both standard and custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| stage | No | Exact match for opportunity stage. Common values: "Proposal", "Qualification", "Negotiation", "Closed Won", "Closed Lost". | |
| detail | No | Response detail level (default: summary) | |
| pageSize | No | Number of records per page (default: 25) | |
| pageNumber | No | Page number to retrieve (default: 1) | |
| namePattern | No | Pattern to match in Opportunity Name. Example: "Github" will match "Github Migration" or "My Github Project". | |
| accountNamePattern | No | Pattern to match in Account Name. Example: "Ford" will match opportunities for "Ford" or "Ford Motor Company". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that results are ordered by close date and include both standard and custom fields, giving useful behavioral context. With no annotations provided, this information carries the full burden and is adequate, though it does not mention pagination or error 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?
The description is two concise sentences that directly state the search criteria and result characteristics. No redundant information or filler words, making it easy for an agent to parse quickly.
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?
Given the moderate complexity (6 parameters, no output schema, no annotations), the description is sufficient. It covers search criteria, result ordering, and field scope. It does not detail pagination behavior, but that is not essential for a search tool where pageSize and pageNumber parameters are self-explanatory.
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?
All six parameters have individual descriptions in the schema (100% coverage), and the tool description reinforces the role of name, account, and stage filters. The schema descriptions are clear and include examples, adding meaning beyond simple parameter names.
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 clearly states the action (search for Salesforce opportunities), the search criteria (name, account, stage), and the result characteristics (ordered by close date, includes standard and custom fields). This unambiguously distinguishes it from sibling tools like get_opportunity_details or opportunity_insights.
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 implies usage through its name and criteria but does not explicitly say when to use this tool versus alternatives such as execute_soql or search_fields. No exclusions or conditional guidance are provided, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing record in Salesforce. Supports updating both standard and custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Record data to update as key-value pairs. For custom fields, use the API name with __c suffix (e.g., { "Custom_Field__c": "New Value" }) | |
| recordId | Yes | ID of the record to update | |
| objectName | Yes | API name of the Salesforce object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It confirms mutation ('update') and mentions field support, but lacks disclosure of side effects, permissions, partial update behavior, or error handling.
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?
Single sentence, front-loaded with core action and resource. No wasted words; efficient.
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?
Given no output schema or annotations, the description covers core purpose but omits return values, error conditions, and prerequisites. Sufficient for a simple mutation tool but could be more thorough.
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?
Schema coverage is 100%, baseline 3. Description adds value by explaining data as key-value pairs and providing example for custom fields with __c suffix, which aids correct invocation.
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 clearly states the tool updates an existing record in Salesforce and supports standard and custom fields. This distinguishes it from sibling tools like create_record or delete_record.
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?
No explicit guidance on when to use this tool versus alternatives; it relies on agent knowledge of sibling tool names. Implicitly clear, but no exclusions or examples of situations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.8.2analyzebatchdescribe_objectdownload_fileenrich_opportunityfind_similar_opportunitiessearch_opportunitiesv0.7.2analyzebatchdescribe_objectdownload_fileenrich_opportunityfind_similar_opportunitiessearch_fieldssearch_opportunitiesv0.5.0analyzeanalyze_conversationbatchcreate_recorddelete_recorddescribe_objectdownload_fileenrich_opportunityexecute_soqlfind_similar_opportunitiesgenerate_business_caseget_opportunity_detailsget_user_infolist_objectsopportunity_insightssearch_opportunitiesupdate_recordScored across 18 tools
The generic CRUD/query/metadata tools are distinct, but at least four opportunity-focused tools (opportunity_insights, enrich_opportunity, generate_business_case, analyze_conversation) all describe generating insights/recommendations from opportunity data with blurred boundaries. An agent could easily select the wrong one for a given request.
Most tools follow a clear verb_noun pattern (create_record, delete_record, search_opportunities, describe_object). Minor deviations like opportunity_insights, batch, and bare analyze keep it from being fully consistent.
18 tools is on the heavy side for a cohesive set, and several opportunity-insight tools could be consolidated. It is not excessive, but the surface feels padded rather than tightly scoped.
The set covers record create/update/delete, SOQL querying, object/field metadata, file download, batch operations, and a broad opportunity workflow. The main gap is a generic get_record/list_records tool, though execute_soql can work around it, and file upload is absent.
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
Salesforce-grounded retrieval, diagnoses, and a vetted-Force marketplace for MCP clients.
Ask about your deals, pace to target, and team odds from Stratyfix. Read only, real permissions.
CRM, relationship intelligence, and multi-agent orchestration for AI agents.
