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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (execute aggregate queries), lists supported features (GROUP BY, aggregate functions, HAVING, date grouping), and provides important behavioral rules (e.g., 'All non-aggregate fields in selectFields MUST be included in groupByFields', 'OFFSET is not supported'). However, it doesn't mention performance characteristics, error handling, or authentication requirements, leaving some behavioral aspects uncovered.

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 clear sections: purpose statement, usage guidance, feature list, examples, and important rules. While comprehensive, it's appropriately sized for a complex tool with many parameters and constraints. Some sentences in the rules section could be more concise, but overall it's front-loaded with critical information and each section adds value.

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 (7 parameters, aggregate query functionality) and lack of annotations/output schema, the description does an excellent job of explaining what the tool does, when to use it, and important constraints. The examples and rules provide crucial context for proper usage. The main gap is the absence of output format description, which would be helpful since there's no output schema, but the description compensates well with comprehensive functional coverage.

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 description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds value through examples that illustrate how parameters work together (e.g., showing selectFields with aggregate functions and aliases, groupByFields matching non-aggregate fields, havingClause usage). However, it doesn't provide additional semantic context beyond what the schema descriptions already cover, meeting the baseline for high 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's purpose: 'Execute SOQL queries with GROUP BY, aggregate functions, and statistical analysis.' It specifies the verb (execute), resource (SOQL queries), and scope (GROUP BY, aggregates, statistical analysis). It explicitly distinguishes from sibling 'salesforce_query_records' for regular queries without GROUP BY or aggregates, 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 this tool for queries that summarize and group data rather than returning individual records' and 'For regular queries without GROUP BY or aggregates, use salesforce_query_records instead.' It clearly defines the context (summarize/group data) and names the specific alternative tool, meeting the highest criteria.

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

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 discloses that the tool retrieves metadata (a read operation) and specifies the types of metadata included (fields, relationships, properties). However, it lacks details on behavioral traits such as permissions required, rate limits, error handling, or whether it returns all metadata at once or supports pagination.

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 core purpose in the first sentence, followed by illustrative examples that reinforce usage without redundancy. Every sentence earns its place by adding clarity or context, and there is no wasted verbiage.

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 (single parameter, no output schema, no annotations), the description is adequate but has gaps. It explains what metadata is retrieved but does not cover the return format, error cases, or dependencies. For a metadata tool without annotations or output schema, more detail on behavioral aspects 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 has 100% description coverage, with the parameter 'objectName' clearly documented. The description adds value by providing examples ('Account', 'Case') and clarifying that it includes custom fields and relationships, which enhances understanding beyond the schema's technical definition. This meets the baseline for high 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 specific action ('Get detailed schema metadata') and resource ('any Salesforce object'), with concrete examples ('Account', 'Case') that illustrate the scope. It distinguishes this from sibling tools by focusing on object schema metadata rather than querying, DML, or code management operations.

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 context through examples (e.g., 'Account' shows all Account fields) and mentions what metadata is included (fields, relationships, field properties). However, it does not explicitly state when to use this tool versus alternatives like 'salesforce_search_objects' or 'salesforce_query_records', which could provide overlapping or related functionality.

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

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

With no annotations provided, the description carries full burden. It clearly indicates this is a write/mutation tool (insert, update, delete, upsert) and specifies some requirements (Id for update/delete, external ID for upsert). However, it doesn't mention permission requirements, transaction behavior, error handling, or rate limits that would be important for a DML 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 opening statement followed by bullet points and examples. It's appropriately sized for a multi-operation tool, though the bullet format could be slightly more concise.

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 DML tool with no annotations and no output schema, the description provides good operational clarity but lacks important context about permissions, transactional behavior, error responses, and what happens on partial failures. The examples help but don't fully compensate for missing behavioral 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%, so the schema already documents all parameters well. The description adds some context by explaining what each operation type does and providing examples, but doesn't add significant semantic value beyond what's in 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 clearly states the tool performs 'data manipulation operations on Salesforce records' and lists specific operations (insert, update, delete, upsert) with concrete examples. It distinguishes itself from sibling tools like query or describe tools by focusing on write operations.

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 implicit guidance by listing operation types and their requirements (e.g., 'update requires Id', 'delete requires Id', 'upsert based on external ID field'). However, it doesn't explicitly state when to use this tool versus alternatives like salesforce_write_apex or provide exclusion criteria.

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

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

With no annotations provided, the description carries full burden and does well by disclosing: 'The code is executed in an anonymous context and does not persist' (transient nature), 'Execution results include compilation success/failure, execution success/failure, and debug logs' (return format), and 'For security reasons, some operations may be restricted based on user permissions' (security constraints). It doesn't mention rate limits or specific destructive behaviors, but covers key operational aspects.

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 appropriately structured with purpose statement, examples, and notes sections. While comprehensive, some sentences could be more concise (e.g., the two usage guideline sentences are somewhat repetitive). Overall, it's well-organized and most content earns its place.

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 powerful code execution tool with no annotations and no output schema, the description does well by explaining the anonymous context, persistence behavior, security restrictions, and when to use versus alternatives. It could benefit from more detail about return structure since there's no output schema, but it mentions key result components. Given the complexity and lack of structured metadata, it's quite 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?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description provides examples showing parameter usage but doesn't add significant semantic meaning beyond what's in the schema descriptions. The baseline of 3 is appropriate when 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 'Execute anonymous Apex code in Salesforce' - a specific verb ('Execute') and resource ('anonymous Apex code') with clear scope ('in Salesforce'). It distinguishes from siblings like salesforce_query_records (for queries) and salesforce_dml_records (for data operations) by focusing on arbitrary code execution rather than specific operations.

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: 'This tool can be used for data operations or updates when there are no other specific tools available' and '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.' This clearly defines when to use this tool versus the many sibling tools available.

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

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

With no annotations provided, the description carries full burden and delivers substantial behavioral context. It discloses validation behavior ('validates that the specified user exists'), clarification prompts ('will ask for clarification' when logLevel unspecified), default values, and operational constraints. However, it doesn't mention authentication requirements, rate limits, or error response formats.

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 clear sections (purpose statement, examples, notes) and every sentence adds value. While comprehensive, it could be more front-loaded - the detailed examples come before the general notes that would help the agent understand constraints first. No wasted text, but slightly longer than ideal.

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 7-parameter tool with no annotations and no output schema, the description provides good operational context but has gaps. It covers parameter usage well but doesn't describe return values, error conditions, or authentication requirements. The examples help, but without output schema, the agent doesn't know what to expect from successful operations.

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?

Despite 100% schema description coverage, the description adds significant value through detailed examples showing parameter combinations for different operations, clarification of optional/required status per operation, default values, and operational constraints. The schema provides basic descriptions, but the description adds practical usage context that helps the agent understand how parameters interact.

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 with specific verbs ('enable, disable, or retrieve logs') and resource ('debug logs for Salesforce users'). It distinguishes itself from sibling tools like salesforce_query_records or salesforce_dml_records by focusing specifically on debug log management rather than general data operations.

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 implied usage through examples showing different operations, but lacks explicit guidance on when to choose this tool versus alternatives. There's no mention of prerequisites, error conditions, or comparison to other debug-related tools that might exist in the Salesforce ecosystem.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal important behavioral traits: that it 'Automatically grants Field Level Security to System Administrator (or specified profiles)' and includes a note about the grantAccessTo parameter default. However, it doesn't disclose other critical behaviors like whether this is a destructive operation (modifying existing fields could break dependencies), what permissions are required, rate limits, or what happens on failure. For a field management tool with zero annotation coverage, this leaves significant gaps.

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 bullet points and examples, making it easy to scan. It's appropriately sized for a complex tool with 18 parameters. The information is front-loaded with the core purpose first. There's minimal waste, though the bullet points could be slightly more concise. Every sentence earns its place by adding value beyond the schema.

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 annotations, no output schema), the description provides a reasonable foundation but has notable gaps. It covers the purpose, usage context, and some behavioral aspects (field security granting), but doesn't address important contextual elements like what the tool returns, error conditions, dependencies, or detailed behavioral constraints. For a field management tool that can modify existing fields, more completeness would be expected.

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 description coverage is 100%, so the schema already documents all 18 parameters thoroughly. The description adds some value by grouping parameters conceptually ('Field Types', 'Properties', 'Relationships') and mentioning the grantAccessTo parameter's default behavior. However, it doesn't provide significant additional semantic context beyond what's already in the schema descriptions. The baseline of 3 is appropriate when 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 clearly states the tool's purpose: 'Create new custom fields or modify existing fields on any Salesforce object.' It specifies the verb (create/modify), resource (custom fields), and scope (any Salesforce object). It distinguishes from siblings like salesforce_manage_object (which manages objects, not fields) and salesforce_manage_field_permissions (which manages permissions, not 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?

The description provides clear context about when to use this tool: for creating or modifying fields with specific types and properties. It includes examples ('Add Rating__c picklist to Account, Create Account lookup on Custom Object') that illustrate appropriate use cases. However, it doesn't explicitly state when NOT to use this tool or mention alternatives among the sibling tools, such as when to use salesforce_manage_field_permissions instead for permission management.

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

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

With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions operations (grant/revoke/view) and bulk updates, but doesn't disclose critical traits like required permissions, whether changes are reversible, rate limits, or what the response looks like (no output schema). For a mutation tool with security implications, this is a significant gap.

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 opening sentence followed by bullet points and examples. It avoids redundancy, though the examples partially restate the bullet points. Every sentence contributes to understanding, but slight trimming of the examples could improve efficiency without losing clarity.

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 security management tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on error conditions, side effects (e.g., impact on existing permissions), response format, and integration with sibling tools. The examples help but don't compensate for missing behavioral and operational 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?

Schema description coverage is 100%, providing baseline documentation for all 6 parameters. The description adds minimal value beyond the schema—it mentions 'profiles or permission sets' (hinting at profileNames usage) and 'read/edit access' (relating to readable/editable), but doesn't clarify parameter interactions (e.g., how profileNames interacts with operation='view') or provide syntax examples beyond what the schema already offers.

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 with specific verbs ('Manage Field Level Security', 'Grant or revoke', 'View', 'Bulk update') and resources ('custom and standard fields', 'profiles or permission sets'). It distinguishes itself from sibling tools like salesforce_manage_field or salesforce_manage_object by focusing specifically on field permissions rather than field/object metadata or DML operations.

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 examples (e.g., 'Grant System Administrator access to a field'), but lacks explicit guidance on when to use this tool versus alternatives like salesforce_manage_field for field metadata or salesforce_dml_records for data manipulation. No clear exclusions or prerequisites are stated, leaving the agent to infer context from the examples.

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

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

With no annotations provided, the description carries full burden. It discloses that changes affect metadata and require proper permissions, which is valuable behavioral context. However, it doesn't mention important traits like whether operations are reversible, what happens on partial updates, rate limits, or error behavior. The description adds some value but leaves significant gaps for a metadata 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 appropriately sized with a clear opening sentence followed by bullet points and examples. The note about metadata and permissions is front-loaded. While efficient, the bullet format could be slightly more polished, and the examples could be integrated more smoothly.

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 metadata mutation tool with 9 parameters, no annotations, and no output schema, the description provides basic purpose and permission context but lacks important details. It doesn't explain return values, error conditions, or behavioral nuances. Given the complexity and lack of structured coverage, the description should do more to compensate.

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 all 9 parameters thoroughly. The description mentions fields, relationships, settings, labels, and sharing model in general terms but doesn't add specific semantic details beyond what's in the schema. The baseline of 3 is appropriate when 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 clearly states the tool creates new custom objects or modifies existing ones in Salesforce, specifying both create and update operations with examples. It distinguishes from some siblings like query or read tools but doesn't explicitly differentiate from salesforce_manage_field which handles field-level operations.

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 for object-level metadata operations (create/update custom objects) and mentions permission requirements, but doesn't explicitly state when to use this vs. alternatives like salesforce_manage_field for field operations or salesforce_describe_object for read-only metadata. The note about permissions provides some context but no explicit guidance on tool selection.

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

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 describes the tool's behavior well for querying with SOQL and relationships, including syntax notes for custom fields. However, it lacks details on permissions, rate limits, error handling, or response format, which are important for a query tool with no output schema. The description adds value but misses key behavioral aspects.

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 appropriately sized and front-loaded, with the core purpose stated first, followed by usage guidelines and examples. The examples are detailed but necessary for clarity. It could be slightly more concise by reducing example verbosity, but overall, it's well-structured with no wasted sentences.

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 (SOQL queries with relationships), no annotations, and no output schema, the description is incomplete. It covers usage and syntax well but lacks information on response format, pagination, error cases, or authentication needs. For a tool with 5 parameters and no structured output, more context is needed to be fully helpful.

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 all parameters. The description adds minimal semantic value beyond the schema—it provides examples of how to use parameters like 'fields' and 'whereClause' with relationships, but doesn't explain parameter interactions or constraints not in the schema. This meets the baseline for high 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's purpose: 'Query records from any Salesforce object using SOQL, including relationship queries.' It specifies the verb ('Query'), resource ('records from any Salesforce object'), and method ('using SOQL'), and distinguishes it from sibling tools by mentioning relationship queries. This is specific and comprehensive.

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 versus alternatives. It states: 'For queries with GROUP BY, aggregate functions (COUNT, SUM, AVG, etc.), or HAVING clauses, use salesforce_aggregate_query instead,' naming the specific sibling tool. This clearly defines usage boundaries and alternatives.

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

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

With no annotations provided, the description carries the full burden and does an excellent job disclosing behavioral traits. It explains what gets returned under different conditions (full body vs. names only), wildcard support, default behavior when no parameters are provided, and metadata inclusion details. The only minor gap is lack of information about authentication requirements or rate limits.

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 perfectly structured with a clear purpose statement, numbered examples showing common use cases, and a notes section with behavioral details. Every sentence earns its place by providing specific guidance without redundancy. The information is front-loaded with the core purpose immediately stated.

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 read-only tool with no output schema, the description provides excellent coverage of behavior, parameter interactions, and return formats. It explains what gets returned under different parameter combinations. The only minor gap is the lack of information about authentication or permissions needed to access Apex classes, which would be helpful given the Salesforce 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?

The schema description coverage is 100%, so the schema already documents all parameters well. The description adds some value through examples showing how parameters interact (e.g., includeMetadata with namePattern) and clarifies that className and namePattern are mutually exclusive in their effects, but doesn't add significant semantic meaning beyond what's in 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 clearly states the tool's purpose as 'Read Apex classes from Salesforce' with a specific verb ('Read') and resource ('Apex classes'). It distinguishes itself from siblings like salesforce_write_apex (write operation) and salesforce_read_apex_trigger (different resource type).

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 clear context on when to use different parameter combinations (e.g., className for full body, namePattern for matching names, includeMetadata for additional info). However, it doesn't explicitly mention when NOT to use this tool versus alternatives like salesforce_search_all or salesforce_query_records for different types of Salesforce data retrieval.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It explains key behaviors: what gets returned (full body vs. names only), how wildcards work, default behavior when no parameters are provided, and metadata inclusion details. However, it doesn't mention potential limitations like rate limits or authentication requirements, leaving some gaps.

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 purpose statement followed by numbered examples and bullet-point notes. Every sentence adds practical value—no wasted words. The information is front-loaded with the core purpose, then detailed usage guidance, making it efficient for an agent to parse and apply.

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 read-only tool with no annotations and no output schema, the description provides comprehensive context about behavior and parameter usage. It covers all three parameters thoroughly and explains return variations. The main gap is the lack of output format details (what the return structure looks like), which would be helpful given the absence of an output schema.

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 has 100% description coverage, so the baseline is 3. The description adds significant value beyond the schema by explaining the semantic relationships between parameters (e.g., triggerName returns full body, namePattern returns names only, includeMetadata adds extra info) and providing concrete examples of how parameters interact, elevating the score above 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 clearly states the verb 'Read' and resource 'Apex triggers from Salesforce', making the purpose specific and unambiguous. It distinguishes this tool from siblings like salesforce_read_apex (for Apex classes) and salesforce_write_apex_trigger (for writing triggers), establishing 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 different parameter combinations through detailed examples and notes. It specifies alternatives like using triggerName for full body retrieval vs. namePattern for name-only listing, and clarifies that includeMetadata adds extra information, helping the agent choose the right approach for different scenarios.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining search capabilities (wildcards, WITH clauses, access filtering via 'updateable' and 'viewable'), but doesn't mention important behavioral aspects like rate limits, authentication requirements, error handling, or what the response format looks like. The notes section adds valuable operational context beyond basic functionality.

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 purpose statement upfront, followed by comprehensive examples and organized notes. While slightly lengthy, every section earns its place by providing essential guidance for using this complex tool. The examples are particularly valuable for understanding parameter combinations.

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 search tool with 6 parameters, no annotations, and no output schema, the description does a decent job but has gaps. It explains the search mechanics well but doesn't describe the return format, pagination, error conditions, or performance characteristics. The examples help compensate, but complete behavioral transparency is lacking 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?

With 100% schema description coverage, the baseline is 3. The description adds value through examples that demonstrate how parameters work together (especially the complex 'objects' and 'withClauses' structures) and provides practical guidance about wildcards and WITH clause types, but doesn't significantly enhance understanding beyond what the well-documented 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 specific action ('Search across multiple Salesforce objects') and technology used ('using SOSL'), distinguishing it from sibling tools like salesforce_query_records (SOQL) and salesforce_search_objects. It explicitly identifies the multi-object search capability as its core 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?

The description provides clear context about when to use this tool (searching across multiple objects with SOSL) and includes examples demonstrating different use cases. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the SOSL focus implies differentiation from SOQL-based queries.

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

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 the search behavior and examples of matches, but does not disclose critical traits such as whether this is a read-only operation, if there are rate limits, authentication requirements, or what the output format looks like (e.g., list of object names with metadata). For a search tool with zero annotation coverage, this leaves significant gaps.

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 core purpose in the first sentence, followed by illustrative examples that earn their place by clarifying usage. It is brief, with no redundant or unnecessary information, making it highly efficient for an AI agent to parse.

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 (search with pattern matching), no annotations, and no output schema, the description is adequate but incomplete. It covers the purpose and parameter usage well, but lacks details on behavioral aspects like output format, error handling, or system constraints, which are important for an agent to use it effectively.

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 description coverage is 100%, so the schema already documents the single parameter 'searchPattern'. The description adds value by providing concrete examples ('Account' will find Account, AccountHistory) that illustrate the pattern-matching semantics beyond the schema's generic description, enhancing understanding of how the parameter behaves in practice.

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 specific action ('Search for Salesforce standard and custom objects') and resource ('by name pattern'), with concrete examples that distinguish it from siblings like salesforce_describe_object (which describes a single object) or salesforce_search_all (which searches across all data, not just object names).

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 examples (e.g., searching for 'Account' or 'Order'), but does not explicitly state when to use this tool versus alternatives like salesforce_describe_object for detailed metadata or salesforce_search_all for broader data searches. No explicit exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about required/optional parameters for different operations, validation rules (e.g., body must be valid Apex code, className must match), and that status information is returned. However, it doesn't cover important behavioral aspects like error handling, permissions needed, or whether operations are reversible/destructive.

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 appropriately sized and front-loaded with the core purpose. The examples and notes are well-organized and add necessary detail without redundancy. However, some information in the notes (e.g., 'operation must be either create or update') is already implied by the enum in the schema, making it slightly less efficient than ideal.

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 a write operation with no annotations and no output schema, the description is moderately complete. It covers the basic operations, parameters, and validation rules but lacks details on error responses, authentication requirements, rate limits, or what specific 'status information' is returned. For a mutation tool without structured safety hints, more behavioral context would be beneficial.

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 description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by clarifying parameter semantics through examples and notes: it explains when apiVersion is optional (defaults to latest), distinguishes required parameters for create vs. update operations, and provides validation rules for body and className matching. This compensates well for the schema's basic 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 with specific verbs ('Create or update') and resource ('Apex classes in Salesforce'). It distinguishes itself from sibling tools like salesforce_read_apex (read vs. write) and salesforce_write_apex_trigger (classes vs. triggers), making the scope 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 provides implied usage guidance through examples and notes (e.g., operation must be 'create' or 'update'), but it lacks explicit guidance on when to use this tool versus alternatives like salesforce_dml_records or salesforce_execute_anonymous. No when-not-to-use scenarios or prerequisites are mentioned.

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

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

With no annotations provided, the description carries full burden. It discloses that 'Status information is returned after successful operations' which is helpful behavioral context. However, it doesn't mention important behavioral aspects like required Salesforce permissions, whether this is a destructive operation (it modifies Salesforce metadata), potential rate limits, or error handling for invalid Apex code.

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 purpose statement, detailed examples, and organized notes. While somewhat lengthy, every section earns its place by providing essential information. The front-loaded purpose statement is effective, though the examples could be slightly more concise.

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 that modifies Salesforce metadata (a significant operation) with no annotations and no output schema, the description is adequate but has gaps. It covers the basic operation well but lacks information about permissions needed, potential side effects, error conditions, or what 'Status information' specifically contains. Given the complexity, more behavioral context would be helpful.

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 has 100% description coverage, so baseline is 3. The description adds significant value through examples that clarify how parameters work together for create vs. update scenarios, notes about required/optional parameters per operation type, and validation rules about body content matching triggerName/objectName. This provides practical usage context 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 'Create or update Apex triggers in Salesforce' - a specific verb (create/update) with the resource (Apex triggers) and platform (Salesforce). It distinguishes from siblings like 'salesforce_write_apex' (for general Apex code) and 'salesforce_read_apex_trigger' (for reading triggers).

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 clear context about when to use create vs. update operations with specific parameter requirements for each. However, it doesn't explicitly state when to use this tool versus alternatives like 'salesforce_write_apex' for other Apex code types or mention prerequisites like required permissions.

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