Enables natural language interactions with Salesforce data and metadata, including querying and managing objects, fields, records, relationships, Apex code, triggers, debug logs, and field-level security permissions across standard and custom objects.
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 fields in the Account object"
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.
An MCP (Model Context Protocol) server implementation that integrates Claude with Salesforce, enabling natural language interactions with your Salesforce data and metadata. This server allows Claude to query, modify, and manage your Salesforce objects and records using everyday language.
Object and Field Management: Create and modify custom objects and fields using natural language
Smart Object Search: Find Salesforce objects using partial name matches
Detailed Schema Information: Get comprehensive field and relationship details for any object
Flexible Data Queries: Query records with relationship support and complex filters
Data Manipulation: Insert, update, delete, and upsert records with ease
Cross-Object Search: Search across multiple objects using SOSL
Apex Code Management: Read, create, and update Apex classes and triggers
Intuitive Error Handling: Clear feedback with Salesforce-specific error details
Switchable Authentication: Supports multiple orgs. Easily switch your active Salesforce org based on the default org configured in your VS Code workspace (use Salesforce_CLI authentication for this feature).
Related MCP server: Salesforce MCP Server
npm install -g @tsmztech/mcp-server-salesforceFor easy setup with Claude Desktop, download the pre-configured extension:
Download salesforce-mcp-extension.dxt from the claude-desktop/ folder
Open Claude Desktop → Settings → Extensions
Drag the .dxt file into the Extensions window
Configure your Salesforce credentials when prompted
For manual Claude Desktop configuration, see Usage with Claude Desktop below.
Search for standard and custom objects:
Search by partial name matches
Finds both standard and custom objects
Example: "Find objects related to Account" will find Account, AccountHistory, etc.
Get detailed object schema information:
Field definitions and properties
Relationship details
Picklist values
Example: "Show me all fields in the Account object"
Query records with relationship support:
Parent-to-child relationships
Child-to-parent relationships
Complex WHERE conditions
Example: "Get all Accounts with their related Contacts"
Note: For queries with GROUP BY or aggregate functions, use salesforce_aggregate_query
Execute aggregate queries with GROUP BY:
GROUP BY single or multiple fields
Aggregate functions: COUNT, COUNT_DISTINCT, SUM, AVG, MIN, MAX
HAVING clauses for filtering grouped results
Date/time grouping functions
Example: "Count opportunities by stage" or "Find accounts with more than 10 opportunities"
Perform data operations:
Insert new records
Update existing records
Delete records
Upsert using external IDs
Example: "Update status of multiple accounts"
Create and modify custom objects:
Create new custom objects
Update object properties
Configure sharing settings
Example: "Create a Customer Feedback object"
Manage object fields:
Add new custom fields
Modify field properties
Create relationships
Automatically grants Field Level Security to System Administrator by default
Use grantAccessTo parameter to specify different profiles
Example: "Add a Rating picklist field to Account"
Manage Field Level Security (Field Permissions):
Grant or revoke read/edit access to fields for specific profiles
View current field permissions
Bulk update permissions for multiple profiles
Useful for managing permissions after field creation or for existing fields
Example: "Grant System Administrator access to Custom_Field__c on Account"
Search across multiple objects:
SOSL-based search
Multiple object support
Field snippets
Example: "Search for 'cloud' across Accounts and Opportunities"
Read Apex classes:
Get full source code of specific classes
List classes matching name patterns
View class metadata (API version, status, etc.)
Support for wildcards (* and ?) in name patterns
Example: "Show me the AccountController class" or "Find all classes matching AccountCont"
Create and update Apex classes:
Create new Apex classes
Update existing class implementations
Specify API versions
Example: "Create a new Apex class for handling account operations"
Read Apex triggers:
Get full source code of specific triggers
List triggers matching name patterns
View trigger metadata (API version, object, status, etc.)
Support for wildcards (* and ?) in name patterns
Example: "Show me the AccountTrigger" or "Find all triggers for Contact object"
Create and update Apex triggers:
Create new Apex triggers for specific objects
Update existing trigger implementations
Specify API versions and event operations
Example: "Create a new trigger for the Account object" or "Update the Lead trigger"
Execute anonymous Apex code:
Run Apex code without creating a permanent class
View debug logs and execution results
Useful for data operations not directly supported by other tools
Example: "Execute Apex code to calculate account metrics" or "Run a script to update related records"
Manage debug logs for Salesforce users:
Enable debug logs for specific users
Disable active debug log configurations
Retrieve and view debug logs
Configure log levels (NONE, ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST)
Example: "Enable debug logs for user@example.com" or "Retrieve recent logs for an admin user"
You can connect to Salesforce using one of three authentication methods:
Set up your Salesforce credentials
Get your security token (Reset from Salesforce Settings)
Create a Connected App in Salesforce
Enable OAuth settings and select "Client Credentials Flow"
Set appropriate scopes (typically "api" is sufficient)
Save the Client ID and Client Secret
Important: Note your instance URL (e.g., https://your-domain.my.salesforce.com) as it's required for authentication
Install and authenticate Salesforce CLI (sf).
Make sure your org is authenticated and accessible via sf org display --json in the root of your Salesforce project.
The server will automatically retrieve the access token and instance url using the CLI.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"salesforce": {
"command": "npx",
"args": ["-y", "@tsmztech/mcp-server-salesforce"],
"env": {
"SALESFORCE_CONNECTION_TYPE": "Salesforce_CLI"
}
}
}
}{
"mcpServers": {
"salesforce": {
"command": "npx",
"args": ["-y", "@tsmztech/mcp-server-salesforce"],
"env": {
"SALESFORCE_CONNECTION_TYPE": "User_Password",
"SALESFORCE_USERNAME": "your_username",
"SALESFORCE_PASSWORD": "your_password",
"SALESFORCE_TOKEN": "your_security_token",
"SALESFORCE_INSTANCE_URL": "org_url" // Optional. Default value: https://login.salesforce.com
}
}
}
}{
"mcpServers": {
"salesforce": {
"command": "npx",
"args": ["-y", "@tsmztech/mcp-server-salesforce"],
"env": {
"SALESFORCE_CONNECTION_TYPE": "OAuth_2.0_Client_Credentials",
"SALESFORCE_CLIENT_ID": "your_client_id",
"SALESFORCE_CLIENT_SECRET": "your_client_secret",
"SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com" // REQUIRED: Must be your exact Salesforce instance URL
}
}
}
}Note: For OAuth 2.0 Client Credentials Flow, the
SALESFORCE_INSTANCE_URLmust be your exact Salesforce instance URL (e.g.,https://your-domain.my.salesforce.com). The token endpoint will be constructed as<instance_url>/services/oauth2/token.
"Find all objects related to Accounts"
"Show me objects that handle customer service"
"What objects are available for order management?""What fields are available in the Account object?"
"Show me the picklist values for Case Status"
"Describe the relationship fields in Opportunity""Get all Accounts created this month"
"Show me high-priority Cases with their related Contacts"
"Find all Opportunities over $100k""Count opportunities by stage"
"Show me the total revenue by account"
"Find accounts with more than 10 opportunities"
"Calculate average deal size by sales rep and quarter"
"Get the number of cases by priority and status""Create a Customer Feedback object"
"Add a Rating field to the Feedback object"
"Update sharing settings for the Service Request object"Examples with Field Level Security:
# Default - grants access to System Administrator automatically
"Create a Status picklist field on Custom_Object__c"
# Custom profiles - grants access to specified profiles
"Create a Revenue currency field on Account and grant access to Sales User and Marketing User profiles""Grant System Administrator access to Custom_Field__c on Account"
"Give read-only access to Rating__c field for Sales User profile"
"View which profiles have access to the Custom_Field__c"
"Revoke field access for specific profiles""Search for 'cloud' in Accounts and Opportunities"
"Find mentions of 'network issue' in Cases and Knowledge Articles"
"Search for customer name across all relevant objects""Show me all Apex classes with 'Controller' in the name"
"Get the full code for the AccountService class"
"Create a new Apex utility class for handling date operations"
"Update the LeadConverter class to add a new method""List all triggers for the Account object"
"Show me the code for the ContactTrigger"
"Create a new trigger for the Opportunity object"
"Update the Case trigger to handle after delete events""Execute Apex code to calculate account metrics"
"Run a script to update related records"
"Execute a batch job to process large datasets""Enable debug logs for user@example.com"
"Retrieve recent logs for an admin user"
"Disable debug logs for a specific user"
"Configure log level to DEBUG for a user"# Clone the repository
git clone https://github.com/tsmztech/mcp-server-salesforce.git
# Navigate to directory
cd mcp-server-salesforce
# Install dependencies
npm install
# Build the project
npm run buildContributions are welcome! Feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues or need support, please file an issue on the GitHub repository.
Execute SOQL queries with GROUP BY, aggregate functions, and statistical analysis. Use this tool for queries that summarize and group data rather than returning individual records.
NOTE: For regular queries without GROUP BY or aggregates, use salesforce_query_records instead.
This tool handles:
GROUP BY queries (single/multiple fields, related objects, date functions)
Aggregate functions: COUNT(), COUNT_DISTINCT(), SUM(), AVG(), MIN(), MAX()
HAVING clauses for filtering grouped results
Date/time grouping: CALENDAR_YEAR(), CALENDAR_MONTH(), CALENDAR_QUARTER(), FISCAL_YEAR(), FISCAL_QUARTER()
Examples:
Count opportunities by stage:
objectName: "Opportunity"
selectFields: ["StageName", "COUNT(Id) OpportunityCount"]
groupByFields: ["StageName"]
Analyze cases by priority and status:
objectName: "Case"
selectFields: ["Priority", "Status", "COUNT(Id) CaseCount", "AVG(Days_Open__c) AvgDaysOpen"]
groupByFields: ["Priority", "Status"]
Count contacts by account industry:
objectName: "Contact"
selectFields: ["Account.Industry", "COUNT(Id) ContactCount"]
groupByFields: ["Account.Industry"]
Quarterly opportunity analysis:
objectName: "Opportunity"
selectFields: ["CALENDAR_YEAR(CloseDate) Year", "CALENDAR_QUARTER(CloseDate) Quarter", "SUM(Amount) Revenue"]
groupByFields: ["CALENDAR_YEAR(CloseDate)", "CALENDAR_QUARTER(CloseDate)"]
Find accounts with more than 10 opportunities:
objectName: "Opportunity"
selectFields: ["Account.Name", "COUNT(Id) OpportunityCount"]
groupByFields: ["Account.Name"]
havingClause: "COUNT(Id) > 10"
Important Rules:
All non-aggregate fields in selectFields MUST be included in groupByFields
Use whereClause to filter rows BEFORE grouping
Use havingClause to filter AFTER grouping (for aggregate conditions)
ORDER BY can only use fields from groupByFields or aggregate functions
OFFSET is not supported with GROUP BY in Salesforce
| Name | Required | Description | Default |
|---|---|---|---|
| objectName | Yes | API name of the object to query | |
| selectFields | Yes | Fields to select - mix of group fields and aggregates. Format: 'FieldName' or 'COUNT(Id) AliasName' | |
| groupByFields | Yes | Fields to group by - must include all non-aggregate fields from selectFields | |
| whereClause | No | WHERE clause to filter rows BEFORE grouping (cannot contain aggregate functions) | |
| havingClause | No | HAVING clause to filter results AFTER grouping (use for aggregate conditions) | |
| orderBy | No | ORDER BY clause - can only use grouped fields or aggregate functions | |
| limit | No | Maximum number of grouped results to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses critical rules: non-aggregate selectFields must be in groupByFields, ORDER BY limits, OFFSET unsupported with GROUP BY, and the distinction between row-level vs group-level filtering. This goes beyond schema details to expose real constraints.
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?
Despite its length, the description is excellently structured with a purpose statement, alternative-tool note, numbered examples covering each feature, and an 'Important Rules' list. Every section is useful; no filler 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?
For a complex tool with 7 parameters and no output schema, the description covers all relevant aspects: what it does, when to use it, parameter semantics, behavioral constraints, and representative examples. The absence of return-value details is acceptable given no output schema and the query nature.
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 baseline is 3. The description adds value beyond the schema by providing concrete examples of selectFields with aliases (e.g., 'COUNT(Id) OpportunityCount') and how groupByFields handle related objects and date functions. These clarify parameter formatting far better than the schema alone.
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 opens with a specific verb-resource pair: 'Execute SOQL queries with GROUP BY, aggregate functions, and statistical analysis.' It clearly scopes the tool to summarizing/grouping queries and explicitly distinguishes it from salesforce_query_records for regular queries.
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: 'For regular queries without GROUP BY or aggregates, use salesforce_query_records instead.' Also explains when to use whereClause vs havingClause (before vs after grouping), and enumerates supported grouping scenarios and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed schema metadata including all fields, relationships, and field properties of any Salesforce object. Examples: 'Account' shows all Account fields including custom fields; 'Case' shows all Case fields including relationships to Account, Contact etc.
| Name | Required | Description | Default |
|---|---|---|---|
| objectName | Yes | API name of the object (e.g., 'Account', 'Contact', 'Custom_Object__c') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states that the tool returns all fields, relationships, and field properties, which clarifies the scope of information. It does not mention side effects, authentication, or output structure, but for a read-only describe operation this is minimal yet acceptable.
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, with the primary action and resource in the first sentence and concrete examples in the second. It is front-loaded and contains no filler, making it highly scannable.
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, the description provides a sufficient overview of both input and output: it explains what the agent must provide (objectName) and what will be returned (all fields, relationships, field properties). It could detail the response format further, but for a simple describe endpoint this is adequate.
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 single parameter objectName is fully described in the schema with examples, yielding 100% schema coverage. The tool description adds its own examples ('Account', 'Case') that are redundant with the schema but do not introduce additional semantics. Thus the description contributes little beyond the structured field definition.
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 uses the specific verb 'Get' and identifies the resource as 'detailed schema metadata' for a Salesforce object. It clearly distinguishes from sibling tools like query_records or search_objects by focusing on object structure rather than data or search results. Examples with 'Account' and 'Case' reinforce the purpose.
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 conveys its use case: retrieving schema metadata for any Salesforce object. It does not explicitly reference alternative tools or when to avoid using it, but the context is clear enough for an agent to select it when needing object structure. The examples provide practical guidance but no exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform data manipulation operations on Salesforce records:
insert: Create new records
update: Modify existing records (requires Id)
delete: Remove records (requires Id)
upsert: Insert or update based on external ID field Examples: Insert new Accounts, Update Case status, Delete old records, Upsert based on custom external ID
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Type of DML operation to perform | |
| objectName | Yes | API name of the object | |
| records | Yes | Array of records to process | |
| externalIdField | No | External ID field name for upsert operations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It adds useful context like 'requires Id' for update/delete and 'external ID field' for upsert, but doesn't disclose potential side effects (e.g., permanent deletion), permission requirements, or error handling behavior. This is a meaningful but incomplete disclosure 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 well-structured with a clear introductory line, a concise bulleted list of operations, and practical examples. Every sentence contributes meaning, and the format is scannable without excessive length.
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 (4 parameters, no output schema, no annotations), the description covers the core operations, prerequisites, and use cases effectively. It lacks details about return values or failure modes, but for a DML tool with clear operation semantics, it provides sufficient context for an agent to select and invoke it correctly.
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 all parameters are documented. The description adds extra semantic value by explaining operation-specific requirements (e.g., update and delete require Id, upsert uses externalIdField), which enhances the schema's basic field 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 identifies the tool as performing DML operations (insert, update, delete, upsert) on Salesforce records, with a specific verb+resource structure. It distinguishes itself from sibling tools like salesforce_query_records and salesforce_search_objects by focusing on data manipulation rather than reading or describing.
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 concrete usage context with examples for each operation (Insert new Accounts, Update Case status, Delete old records, Upsert based on custom external ID). It implicitly contrasts with read-only tools, though it doesn't explicitly state when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute anonymous Apex code in Salesforce.
Examples:
Execute simple Apex code: { "apexCode": "System.debug('Hello World');" }
Execute Apex code with variables: { "apexCode": "List accounts = [SELECT Id, Name FROM Account LIMIT 5]; for(Account a : accounts) { System.debug(a.Name); }" }
Execute Apex with debug logs: { "apexCode": "System.debug(LoggingLevel.INFO, 'Processing accounts...'); List accounts = [SELECT Id FROM Account LIMIT 10]; System.debug(LoggingLevel.INFO, 'Found ' + accounts.size() + ' accounts');", "logLevel": "DEBUG" }
Notes:
The apexCode parameter is required and must contain valid Apex code
The code is executed in an anonymous context and does not persist
The logLevel parameter is optional (defaults to 'DEBUG')
Execution results include compilation success/failure, execution success/failure, and debug logs
For security reasons, some operations may be restricted based on user permissions
This tool can be used for data operations or updates when there are no other specific tools available
When users request data queries or updates that aren't directly supported by other tools, this tool can be used if the operation is achievable using Apex code
| Name | Required | Description | Default |
|---|---|---|---|
| apexCode | Yes | Apex code to execute anonymously | |
| logLevel | No | Log level for debug logs (optional, defaults to DEBUG) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It explains that code runs in an anonymous context and does not persist, that results include compilation/execution success/failure and debug logs, and that user permissions may restrict operations. It also acknowledges the tool can perform data operations or updates, so side effects are not hidden.
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 purpose is front-loaded, and the numbered examples with a notes section make the structure scannable. There is some redundancy between the two fallback notes, but overall the description is appropriately sized for a tool that executes arbitrary code and contains no 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?
For an arbitrary-code execution tool with no output schema and no annotations, the description covers input requirements, execution context, result categories, permission restrictions, and fallback usage. It could specify exact response fields or warn more strongly about irreversible DML side effects, but the provided information is sufficient for an agent to select and invoke the tool correctly.
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 covers both parameters at 100%, including the logLevel enum and default. The description adds value through concrete examples showing that apexCode can contain multi-statement blocks, SOQL queries, loops, and debug logging. This gives an agent a clearer sense of what valid inputs look like beyond the 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 opens with a specific verb-resource statement: 'Execute anonymous Apex code in Salesforce.' Examples reinforce that this tool runs ad-hoc Apex rather than reading or writing stored Apex artifacts, which distinguishes it from siblings like salesforce_read_apex and salesforce_write_apex.
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 notes clearly state when to use this tool: for data operations or updates when no other specific tools are available, and for queries/updates not directly supported by other tools. It does not explicitly name sibling alternatives like salesforce_query_records or salesforce_dml_records, but the fallback condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage debug logs for Salesforce users - enable, disable, or retrieve logs.
Examples:
Enable debug logs for a user: { "operation": "enable", "username": "user@example.com", "logLevel": "DEBUG", "expirationTime": 30 }
Disable debug logs for a user: { "operation": "disable", "username": "user@example.com" }
Retrieve debug logs for a user: { "operation": "retrieve", "username": "user@example.com", "limit": 5 }
Retrieve a specific log with full content: { "operation": "retrieve", "username": "user@example.com", "logId": "07L1g000000XXXXEAA0", "includeBody": true }
Notes:
The operation must be one of: 'enable', 'disable', or 'retrieve'
The username parameter is required for all operations
For 'enable' operation, logLevel is optional (defaults to 'DEBUG')
Log levels: NONE, ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST
expirationTime is optional for 'enable' operation (minutes until expiration, defaults to 30)
limit is optional for 'retrieve' operation (maximum number of logs to return, defaults to 10)
logId is optional for 'retrieve' operation (to get a specific log)
includeBody is optional for 'retrieve' operation (to include the full log content, defaults to false)
The tool validates that the specified user exists before performing operations
If logLevel is not specified when enabling logs, the tool will ask for clarification
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Operation to perform on debug logs | |
| username | Yes | Username of the Salesforce user | |
| logLevel | No | Log level for debug logs (required for 'enable' operation) | |
| expirationTime | No | Minutes until the debug log configuration expires (optional, defaults to 30) | |
| limit | No | Maximum number of logs to retrieve (optional, defaults to 10) | |
| logId | No | ID of a specific log to retrieve (optional) | |
| includeBody | No | Whether to include the full log content (optional, defaults to false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does provide useful details: defaults, user validation, log-level enumeration, and a clarification behavior. However, it contains an internal inconsistency—logLevel is described as optional defaulting to DEBUG, but a later note says the tool will ask for clarification if it is not specified, and the schema says it is required for enable. It also does not describe side effects of enabling/disabling beyond the operation names.
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 longer than average but well-structured: a summary line, concrete examples, and a notes section. Some redundancy exists between the examples and notes, but every section contributes operational value and the main purpose is front-loaded.
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 all seven parameters, operation modes, defaults, log-levels, validation behavior, and optional flags. It does not describe the exact return structure of retrieve or any required permissions, but it is reasonably complete for invoking the tool successfully.
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 documentation covers 100% of parameters, so the baseline is 3. The description adds helpful defaults, examples, and conditional dependencies, but the contradictory statements about logLevel (optional/default vs. required/ask-for-clarification) reduce its reliability for parameter usage.
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 opening sentence explicitly names the resource ('debug logs for Salesforce users') and the action (manage), then enumerates the three concrete operations: enable, disable, retrieve. This makes it clearly distinguishable from all sibling tools, none of which mention debug logs.
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?
Four numbered examples show precisely which parameters are relevant for each operation, and the notes clarify defaults and constraints. There is no explicit 'when not to use' statement, but no sibling tool is a plausible alternative for debug-log management, so selection guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create new custom fields or modify existing fields on any Salesforce object:
Field Types: Text, Number, Date, Lookup, Master-Detail, Picklist etc.
Properties: Required, Unique, External ID, Length, Scale etc.
Relationships: Create lookups and master-detail relationships
Automatically grants Field Level Security to System Administrator (or specified profiles) Examples: Add Rating__c picklist to Account, Create Account lookup on Custom Object Note: Use grantAccessTo parameter to specify profiles, defaults to System Administrator
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Whether to create new field or update existing | |
| objectName | Yes | API name of the object to add/modify the field | |
| fieldName | Yes | API name for the field (without __c suffix) | |
| label | No | Label for the field | |
| type | No | Field type (required for create) | |
| required | No | Whether the field is required | |
| unique | No | Whether the field value must be unique | |
| externalId | No | Whether the field is an external ID | |
| length | No | Length for text fields | |
| precision | No | Precision for numeric fields | |
| scale | No | Scale for numeric fields | |
| referenceTo | No | API name of the object to reference (for Lookup/MasterDetail) | |
| relationshipLabel | No | Label for the relationship (for Lookup/MasterDetail) | |
| relationshipName | No | API name for the relationship (for Lookup/MasterDetail) | |
| deleteConstraint | No | Delete constraint for Lookup fields | |
| picklistValues | No | Values for Picklist/MultiselectPicklist fields | |
| description | No | Description of the field | |
| grantAccessTo | No | Profile names to grant field access to (defaults to ['System Administrator']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses a key side effect: 'Automatically grants Field Level Security to System Administrator (or specified profiles).' It also lists the operations (create/update) and relationship behaviors. It does not mention potential destructive aspects (e.g., updating an existing field could overwrite configuration), but the description is reasonably transparent for a tool of this complexity.
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 structured with a clear opening statement, bulleted capabilities, and examples. It is longer than a two-sentence description but every section adds relevant information. The formatting improves scannability, and there is no redundant repetition of schema details.
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 (18 parameters, no output schema), the description covers the main aspects: field types, properties, relationships, FLS side-effect, and examples. It lacks a description of return values or error behavior, but for a management tool with rich input schema, the description is sufficiently complete.
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 100% of parameters, so the baseline is 3. The description adds value by explicitly linking parameters to use cases, such as 'Use grantAccessTo parameter to specify profiles, defaults to System Administrator,' and providing examples that illustrate how parameters (e.g., type, objectName, fieldName) combine. It does not explain every parameter but enriches the schema with practical context.
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's function with a specific verb and resource: 'Create new custom fields or modify existing fields on any Salesforce object.' It also lists capabilities (field types, properties, relationships) and gives concrete examples ('Add Rating__c picklist to Account'), distinguishing it from sibling tools like salesforce_manage_object (which manages objects) and salesforce_manage_field_permissions (which handles FLS).
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 its use case (when you need to create or update custom fields) and mentions the auto-granting of FLS, which clarifies its relationship to salesforce_manage_field_permissions. However, it does not explicitly state when to prefer this tool over alternatives or provide exclusions, though the context signals (e.g., 'Create Account lookup on Custom Object') effectively guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Field Level Security (Field Permissions) for custom and standard fields.
Grant or revoke read/edit access to fields for specific profiles or permission sets
View current field permissions
Bulk update permissions for multiple profiles
Examples:
Grant System Administrator access to a field
Give read-only access to a field for specific profiles
Check which profiles have access to a field
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Operation to perform on field permissions | |
| objectName | Yes | API name of the object (e.g., 'Account', 'Custom_Object__c') | |
| fieldName | Yes | API name of the field (e.g., 'Custom_Field__c') | |
| profileNames | No | Names of profiles to grant/revoke access (e.g., ['System Administrator', 'Sales User']) | |
| readable | No | Grant/revoke read access (default: true) | |
| editable | No | Grant/revoke edit access (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions grant/revoke actions but omits critical behavioral details such as immediate effect, required permissions, reversibility, or potential side effects on profiles/permission sets.
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 well-structured with bullets and practical examples, making it easy to scan. While slightly verbose, every section adds value and the examples aid comprehension.
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 6 parameters, no output schema, and moderate complexity, the description covers primary use cases and examples adequately. It lacks edge-case details (e.g., behavior when profileNames is omitted), but is sufficient for initial 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?
The input schema already provides descriptions for all parameters (100% coverage), so the description adds little beyond examples. The baseline of 3 is appropriate since the 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 explicitly states 'Manage Field Level Security (Field Permissions)' and lists specific operations (grant/revoke, view, bulk update), clearly distinguishing it from sibling tools like salesforce_manage_field which handles field definitions.
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?
It provides clear operational context through bullets and examples, indicating when to use it for permission management. It doesn't explicitly name alternatives, but the focused scope on field permissions is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create new custom objects or modify existing ones in Salesforce:
Create: New custom objects with fields, relationships, and settings
Update: Modify existing object settings, labels, sharing model Examples: Create Customer_Feedback__c object, Update object sharing settings Note: Changes affect metadata and require proper permissions
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Whether to create new object or update existing | |
| objectName | Yes | API name for the object (without __c suffix) | |
| label | No | Label for the object | |
| pluralLabel | No | Plural label for the object | |
| description | No | Description of the object | |
| nameFieldLabel | No | Label for the name field | |
| nameFieldType | No | Type of the name field | |
| nameFieldFormat | No | Display format for AutoNumber field (e.g., 'A-{0000}') | |
| sharingModel | No | Sharing model for the object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The note 'Changes affect metadata and require proper permissions' discloses the mutation nature and permission requirement. However, the claim 'with fields, relationships, and settings' is not supported by the input schema (no fields or relationships parameters), which could mislead an agent about capabilities. This prevents a higher score.
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 compact and well-structured: a clear verb phrase, bulleted operations, illustrative examples, and a critical permission note. Every sentence contributes meaning without 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 9 parameters, no annotations, and no output schema, so the description must carry more weight. It gives high-level operations but fails to explain return behavior, error conditions, or the full scope of parameter usage. The unsupported 'relationships' claim further reduces completeness and trustworthiness.
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 would be 3. However, the description mentions creating objects 'with fields, relationships, and settings' but the schema offers no such parameters, adding misleading information. This overstates the tool's functionality and could lead to incorrect invocation, warranting a score below baseline.
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 uses a specific verb ('Create', 'modify') and resource ('custom objects in Salesforce'), clearly distinguishing this from sibling tools like search/query/describe. It states the two primary operations (create/update) with concrete examples, making the tool's purpose unmistakable.
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 clear context for when to use the tool (creating or updating objects) with examples and a permission note. However, it does not explicitly exclude alternatives or mention when to choose sibling tools like salesforce_manage_field or salesforce_describe_object, so it falls short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query records from any Salesforce object using SOQL, including relationship queries.
NOTE: For queries with GROUP BY, aggregate functions (COUNT, SUM, AVG, etc.), or HAVING clauses, use salesforce_aggregate_query instead.
Examples:
Parent-to-child query (e.g., Account with Contacts):
objectName: "Account"
fields: ["Name", "(SELECT Id, FirstName, LastName FROM Contacts)"]
Child-to-parent query (e.g., Contact with Account details):
objectName: "Contact"
fields: ["FirstName", "LastName", "Account.Name", "Account.Industry"]
Multiple level query (e.g., Contact -> Account -> Owner):
objectName: "Contact"
fields: ["Name", "Account.Name", "Account.Owner.Name"]
Related object filtering:
objectName: "Contact"
fields: ["Name", "Account.Name"]
whereClause: "Account.Industry = 'Technology'"
Note: When using relationship fields:
Use dot notation for parent relationships (e.g., "Account.Name")
Use subqueries in parentheses for child relationships (e.g., "(SELECT Id FROM Contacts)")
Custom relationship fields end in "__r" (e.g., "CustomObject__r.Name")
| Name | Required | Description | Default |
|---|---|---|---|
| objectName | Yes | API name of the object to query | |
| fields | Yes | List of fields to retrieve, including relationship fields | |
| whereClause | No | WHERE clause, can include conditions on related objects | |
| orderBy | No | ORDER BY clause, can include fields from related objects | |
| limit | No | Maximum number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral transparency. It does disclose relationship query nuances (dot notation, subqueries, __r suffixes) but does not explicitly state whether the operation is read-only, what permissions are needed, or any limits/timeout behavior. 'Query' implies a read, but not all behavioral traits are covered.
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 long but every section earns its place: a clear purpose sentence, a critical exclusion note, four varied examples, and a concise summary of relationship field rules. The structure front-loads the main idea and then layers detail logically. Nothing is redundant or 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?
For a moderately complex tool with no output schema and no annotations, the description covers essential query construction, relationship semantics, and aggregate query alternatives. It does not explicitly describe the shape of the returned records, but that is generally implicit for a query tool. The examples and notes provide enough context to use the tool correctly.
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?
While schema coverage is 100% (baseline 3), the description adds substantial meaning beyond schema property descriptions. It provides detailed multi-level query examples for fields, explains how to construct relationship queries in whereClause, and introduces conventions like dot notation and subqueries that are not captured in the schema. This is exceptional parameter-level guidance.
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 opens with a specific verb-resource-scope statement: 'Query records from any Salesforce object using SOQL, including relationship queries.' It clearly distinguishes itself from sibling salesforce_aggregate_query by explicitly naming the alternative for aggregate queries, and from other tools like describe or search.
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 explicitly states when NOT to use this tool: 'For queries with GROUP BY, aggregate functions (COUNT, SUM, AVG, etc.), or HAVING clauses, use salesforce_aggregate_query instead.' This directly guides tool selection among siblings. Examples also clarify use cases for parent-child and child-parent queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Apex classes from Salesforce.
Examples:
Read a specific Apex class by name: { "className": "AccountController" }
List all Apex classes with an optional name pattern: { "namePattern": "Controller" }
Get metadata about Apex classes: { "includeMetadata": true, "namePattern": "Trigger" }
Use wildcards in name patterns: { "namePattern": "AccountCont" }
Notes:
When className is provided, the full body of that specific class is returned
When namePattern is provided, all matching class names are returned (without body)
Use includeMetadata to get additional information like API version, length, and last modified date
If neither className nor namePattern is provided, all Apex class names will be listed
Wildcards are supported in namePattern: * (matches any characters) and ? (matches a single character)
| Name | Required | Description | Default |
|---|---|---|---|
| className | No | Name of a specific Apex class to read | |
| namePattern | No | Pattern to match Apex class names (supports wildcards * and ?) | |
| includeMetadata | No | Whether to include metadata about the Apex classes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It clearly explains that className returns the full body, namePattern returns matching names without body, includeMetadata adds metadata, and wildcard behavior is specified. This is comprehensive for a read operation.
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 well-structured with examples and notes. While slightly verbose, every example serves a purpose and the notes clarify behavior. The front-loaded main sentence followed by illustrative examples makes it easy to scan.
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 there is no output schema, the description compensates by explaining return behavior for every parameter scenario. It also covers edge cases (no parameters, wildcards) and metadata inclusion. This fully equips an agent to know what to expect from each call.
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 all parameters. The description adds meaningful value beyond the schema by providing examples of combinations, explaining wildcard usage, and clarifying what output to expect for each parameter. This enriches understanding beyond the basic property 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 the tool's purpose: 'Read Apex classes from Salesforce.' It uses a specific verb ('read') and resource ('Apex classes'), and distinguishes from sibling tools like salesforce_write_apex and salesforce_read_apex_trigger by focusing specifically on Apex classes.
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 thorough guidance on when to use each parameter combination (className, namePattern, includeMetadata), including what happens when neither is provided. It lacks explicit mention of when to prefer this tool over alternatives, but the name and context make this clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Apex triggers from Salesforce.
Examples:
Read a specific Apex trigger by name: { "triggerName": "AccountTrigger" }
List all Apex triggers with an optional name pattern: { "namePattern": "Account" }
Get metadata about Apex triggers: { "includeMetadata": true, "namePattern": "Contact" }
Use wildcards in name patterns: { "namePattern": "Account*" }
Notes:
When triggerName is provided, the full body of that specific trigger is returned
When namePattern is provided, all matching trigger names are returned (without body)
Use includeMetadata to get additional information like API version, object type, and last modified date
If neither triggerName nor namePattern is provided, all Apex trigger names will be listed
Wildcards are supported in namePattern: * (matches any characters) and ? (matches a single character)
| Name | Required | Description | Default |
|---|---|---|---|
| triggerName | No | Name of a specific Apex trigger to read | |
| namePattern | No | Pattern to match Apex trigger names (supports wildcards * and ?) | |
| includeMetadata | No | Whether to include metadata about the Apex triggers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description carries the full burden effectively. It discloses exactly what is returned for each parameter combination: full body for triggerName, names only for namePattern, metadata flag, and behavior when neither is provided. Wildcard semantics are also spelled out, giving complete behavioral 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 well-structured with an overview, four illustrative examples, and a list of notes. Every section contributes meaningful information without fluff. It's appropriately sized for a tool with 3 parameters and no output schema, and information is front-loaded with the core purpose.
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?
Even without an output schema, the description explains what the tool returns in every scenario, including specific trigger bodies, matching names, and metadata fields. It also covers wildcard support and default behavior, making it comprehensive for a read-only tool.
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 descriptions for each parameter. The description adds value beyond the schema by clarifying interactions (e.g., triggerName takes precedence, namePattern returns names only) and providing concrete examples of wildcard usage. This enhances parameter semantics without being redundant.
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 opens with 'Read Apex triggers from Salesforce,' using a specific verb and resource. It clearly differentiates from siblings like salesforce_read_apex (likely Apex classes) and salesforce_write_apex_trigger (write operation). The detailed examples reinforce the purpose.
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 comprehensive examples for when to use triggerName vs namePattern vs neither, with notes on wildcards and metadata. However, it lacks explicit comparison to alternative tools (e.g., 'use salesforce_read_apex for classes'), so it falls short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across multiple Salesforce objects using SOSL (Salesforce Object Search Language).
Examples:
Basic search across all objects: { "searchTerm": "John", "objects": [ { "name": "Account", "fields": ["Name"], "limit": 10 }, { "name": "Contact", "fields": ["FirstName", "LastName", "Email"] } ] }
Advanced search with filters: { "searchTerm": "Cloud*", "searchIn": "NAME FIELDS", "objects": [ { "name": "Account", "fields": ["Name", "Industry"], "orderBy": "Name DESC", "where": "Industry = 'Technology'" } ], "withClauses": [ { "type": "NETWORK", "value": "ALL NETWORKS" }, { "type": "SNIPPET", "fields": ["Description"] } ] }
Notes:
Use * and ? for wildcards in search terms
Each object can have its own WHERE, ORDER BY, and LIMIT clauses
Support for WITH clauses: DATA CATEGORY, DIVISION, METADATA, NETWORK, PRICEBOOKID, SNIPPET, SECURITY_ENFORCED
"updateable" and "viewable" options control record access filtering
| Name | Required | Description | Default |
|---|---|---|---|
| searchTerm | Yes | Text to search for (supports wildcards * and ?) | |
| searchIn | No | Which fields to search in | |
| objects | Yes | List of objects to search and their return fields | |
| withClauses | No | Additional WITH clauses for the search | |
| updateable | No | Return only updateable records | |
| viewable | No | Return only viewable records |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses important behavioral details: SOSL syntax, wildcard support, per-object WHERE/ORDER BY/LIMIT, WITH clause types, and access filtering via updateable/viewable. It stops short of stating read-only nature explicitly, but 'search' strongly implies it. Overall, it provides above-average 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 longer than a minimal one, but the length is justified by the tool's complexity. It is front-loaded with a clear purpose, followed by structured examples and a concise bullet list of notes. Every section adds value, though some redundancy exists (e.g., wildcards are mentioned twice).
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 is complex with nested object parameters and optional WITH clauses. The description covers the multidimensional usage thoroughly with examples, notes, and feature lists, providing enough context for an agent to construct valid invocations. Given no output schema, the description is sufficiently complete for this search tool.
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%, providing a solid baseline. The description goes beyond the schema by including two detailed examples that show how objects, withClauses, and wildcards are used together, and it clarifies the meaning of updateable/viewable. This significantly enriches parameter understanding.
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 opens with a precise statement: 'Search across multiple Salesforce objects using SOSL (Salesforce Object Search Language).' This clearly identifies the tool's action, resource, and scope, and distinguishes it from sibling tools like salesforce_search_objects and salesforce_query_records by emphasizing multi-object SOSL search.
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 clear context that this tool is for searching across multiple objects, with examples showing the expected structure. However, it does not explicitly reference alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Salesforce standard and custom objects by name pattern. Examples: 'Account' will find Account, AccountHistory; 'Order' will find WorkOrder, ServiceOrder__c etc.
| Name | Required | Description | Default |
|---|---|---|---|
| searchPattern | Yes | Search pattern to find objects (e.g., 'Account Coverage' will find objects like 'AccountCoverage__c') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It explains the search action and gives examples of matches, but doesn't state whether the operation is read-only, its return format, or any limitations (e.g., case sensitivity, wildcard support). For a simple search tool, the core behavior is disclosed, but additional transparency is lacking.
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 extremely concise: one sentence stating the purpose and one sentence with examples. It is front-loaded with the verb and resource, and every word earns its place. No fluff or repetition.
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 tool with one parameter and no output schema, the description covers the main purpose and gives examples. However, it omits specifics about how the pattern matching works (e.g., substring vs. whole word, case sensitivity) and what the output shape is (e.g., just names or full metadata). These gaps prevent it from being fully complete.
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 only parameter `searchPattern` has a 100% schema description coverage, including an example. The tool description reiterates and supplements with examples ('Account' will find Account, AccountHistory), but doesn't add significant new meaning beyond what the schema already provides. 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 the tool's function: 'Search for Salesforce standard and custom objects by name pattern.' It provides concrete examples ('Account' will find Account, AccountHistory), which further clarifies the scope and distinguishes it from sibling tools like describe or query.
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 a clear context of when to use this tool (searching objects by name pattern) and provides examples of the expected input/output. It doesn't explicitly mention alternative tools or exclusions, but the use case is unambiguous enough for an agent to decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update Apex classes in Salesforce.
Examples:
Create a new Apex class: { "operation": "create", "className": "AccountService", "apiVersion": "58.0", "body": "public class AccountService { public static void updateAccounts() { /* implementation */ } }" }
Update an existing Apex class: { "operation": "update", "className": "AccountService", "body": "public class AccountService { public static void updateAccounts() { /* updated implementation */ } }" }
Notes:
The operation must be either 'create' or 'update'
For 'create' operations, className and body are required
For 'update' operations, className and body are required
apiVersion is optional for 'create' (defaults to the latest version)
The body must be valid Apex code
The className in the body must match the className parameter
Status information is returned after successful operations
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Whether to create a new class or update an existing one | |
| className | Yes | Name of the Apex class to create or update | |
| apiVersion | No | API version for the Apex class (e.g., '58.0') | |
| body | Yes | Full body of the Apex class |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It explains the create/update operations, required inputs, apiVersion default behavior, the className/body matching requirement, and that status information is returned. However, it does not disclose overwrite semantics for updates, error cases, or permission requirements, so it falls short of full 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 well-structured with a summary, two concrete examples, and bullet notes. It is slightly redundant in repeating that className and body are required for both create and update, but overall every section earns its place and the examples are valuable.
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 moderate-complexity write tool with no output schema, the description provides enough context to call it correctly: operation mode, required parameters, optional apiVersion, body constraints, and a note on returned status. The main gap is lack of detail on failure/error behavior and what the status information contains.
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?
Although the schema already documents all parameters, the description adds meaningful semantics beyond it: concrete JSON examples, the default for apiVersion, the requirement that className in the body must match the className parameter, and validation rules for create vs update operations. This substantially helps an agent construct correct calls.
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 opens with a specific verb+resource pair: 'Create or update Apex classes in Salesforce.' This clearly distinguishes it from sibling tools like salesforce_read_apex and salesforce_write_apex_trigger, which are for reading classes or writing triggers instead.
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 makes the intended use explicit: creating or updating Apex classes. It does not explicitly name alternatives or state when not to use the tool, but the class-vs-trigger and read-vs-write distinctions in the sibling list make the context clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update Apex triggers in Salesforce.
Examples:
Create a new Apex trigger: { "operation": "create", "triggerName": "AccountTrigger", "objectName": "Account", "apiVersion": "58.0", "body": "trigger AccountTrigger on Account (before insert, before update) { /* implementation */ }" }
Update an existing Apex trigger: { "operation": "update", "triggerName": "AccountTrigger", "body": "trigger AccountTrigger on Account (before insert, before update, after update) { /* updated implementation */ }" }
Notes:
The operation must be either 'create' or 'update'
For 'create' operations, triggerName, objectName, and body are required
For 'update' operations, triggerName and body are required
apiVersion is optional for 'create' (defaults to the latest version)
The body must be valid Apex trigger code
The triggerName in the body must match the triggerName parameter
The objectName in the body must match the objectName parameter (for 'create')
Status information is returned after successful operations
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Whether to create a new trigger or update an existing one | |
| triggerName | Yes | Name of the Apex trigger to create or update | |
| objectName | No | Name of the Salesforce object the trigger is for (required for 'create') | |
| apiVersion | No | API version for the Apex trigger (e.g., '58.0') | |
| body | Yes | Full body of the Apex trigger |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions that status information is returned after successful operations but does not detail failure modes, side effects (e.g., overwriting on update), permission requirements, or idempotency behavior. Some important behavioral aspects are left implicit.
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 moderately long but well-organized with examples and bullet-point notes. Every section contributes useful information; the examples are particularly helpful for understanding the expected input format. No redundancy or fluff.
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?
While the description covers input semantics and mentions status output, it lacks details about the output structure, error handling, and edge cases (e.g., updating a non-existent trigger). Given the absence of an output schema, a bit more context on expected results would improve 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 input schema provides descriptions for all parameters, and the notes add critical context about required fields per operation, defaulting of apiVersion, and validation rules. This fully clarifies the meaning and usage of each parameter.
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 that the tool creates or updates Apex triggers in Salesforce, which is a specific resource type. It distinguishes itself from siblings by focusing on 'Apex triggers' rather than other objects like classes or queries.
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 notes provide explicit instructions on when to use 'create' vs 'update', required vs optional parameters, and consistency constraints between body and parameters. However, it does not explicitly mention how this tool compares to similar siblings like salesforce_write_apex, though the resource type is clearly different.
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.
salesforce_aggregate_querysalesforce_describe_objectsalesforce_dml_recordssalesforce_execute_anonymoussalesforce_manage_debug_logssalesforce_manage_fieldsalesforce_manage_field_permissionssalesforce_manage_objectsalesforce_query_recordssalesforce_read_apexsalesforce_read_apex_triggersalesforce_search_allsalesforce_search_objectssalesforce_write_apexsalesforce_write_apex_triggerScored across 15 tools
Most tools have distinct purposes, but there is some overlap between salesforce_query_records and salesforce_aggregate_query, which are explicitly disambiguated in descriptions, and between salesforce_execute_anonymous and other data manipulation tools. However, the descriptions help clarify boundaries, preventing major confusion.
All tools follow a consistent snake_case pattern with a clear 'salesforce_' prefix and descriptive verb_noun combinations (e.g., salesforce_query_records, salesforce_manage_object). This uniformity makes the tool set predictable and easy to navigate.
With 15 tools, the server is well-scoped for Salesforce operations, covering data querying, manipulation, metadata management, Apex code handling, and debugging. Each tool serves a specific function without redundancy, making the count appropriate for the domain.
The tool set provides comprehensive coverage for Salesforce, including CRUD operations, metadata management, Apex development, and debugging. Minor gaps exist, such as no direct tool for managing user permissions or workflows, but agents can work around these using existing tools like salesforce_execute_anonymous.
Run SOQL queries to explore and retrieve Salesforce data. Access accounts, contacts, opportunities…
Run SOQL queries against your Salesforce org to retrieve records and insights. Explore objects, fi…
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
Run SOQL queries to explore and retrieve Salesforce data. Inspect records, fields, and relationshi…
