Salesforce MCP Server

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond the readOnlyHint annotation. It warns 'Always include LIMIT to avoid large result sets' (performance guidance), describes the result structure ('Results include totalSize, done, and records array'), and provides syntax examples for relationship queries. No contradiction with annotations.

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 efficiently structured with zero wasted sentences. It starts with the core purpose, immediately provides usage guidelines, then offers syntax examples and best practices. Every sentence adds essential information for correct tool invocation.

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 complexity of SOQL queries and the absence of output schema, the description provides complete context: purpose, usage guidelines, syntax examples, common objects, relationship query patterns, performance warnings (LIMIT), prerequisite tools (describe_object), and result structure. This fully compensates for the lack of structured output documentation.

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?

With 0% schema description coverage for the single 'query' parameter, the description fully compensates by explaining SOQL syntax, common objects, custom object/field naming conventions, relationship query patterns, and the importance of LIMIT clauses. This provides comprehensive semantic guidance for constructing valid queries.

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 verb 'Execute' and resource 'SOQL query', with specific syntax examples. It explicitly distinguishes from sibling run_sosl_search by stating 'Use SOQL when you know which object to query', providing clear differentiation.

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 explicit guidance on when to use this tool vs. alternatives: 'Use SOQL when you know which object to query. Use run_sosl_search instead when searching by keyword across multiple objects.' It also mentions calling describe_object first if field knowledge is lacking, offering clear prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.