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.

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

No annotations are provided, so the description must cover behavioral traits. It describes the output but does not disclose authorization needs, rate limits, or side effects. The read-only nature is implied but not explicit.

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-organized with separate sections for reports and dashboards, plus examples. It is concise yet informative, 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 no output schema, the description explains what is returned for each type adequately. It covers key details but could mention error conditions or edge cases.

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 describes both parameters (type and resourceId). The description adds value beyond the schema by providing examples and clarifying the ID format and the two possible types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets detailed metadata for Salesforce reports or dashboards, specifying the exact metadata returned for each type. This differentiates it from sibling tools like salesforce_run_analytics and salesforce_describe_object.

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 says to use this before running a report with salesforce_run_analytics, providing clear context. It lacks explicit exclusion or alternatives but is sufficient for guidance.

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 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.

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.

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.

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

Without annotations, the description carries the full burden. It clearly explains the read-like behavior (listing items, filtering, returning metadata) and implies no destructive actions. However, it does not mention authentication or permission requirements.

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?

Description is concise and well-structured: a clear opening line, usage guideline, and bulleted examples. Every sentence is informative and 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 simple list operation with two parameters and no output schema, the description is largely complete. It explains the purpose, usage, and sample scenarios. Minor omission: no mention of pagination or result limits, but this is acceptable for the tool's simplicity.

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?

Input schema has 100% description coverage. The description reiterates the parameter meanings but does not add new information beyond the schema. 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 lists Salesforce reports or dashboards and returns IDs, names, and metadata. It distinguishes itself from siblings by explicitly mentioning it is used to find IDs before describing or running them with related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool ('to find IDs') and provides alternative tools ('salesforce_describe_analytics', 'salesforce_run_analytics'). It also gives concrete examples covering typical use cases.

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 fully carries the behavioral disclosure burden. It covers user existence validation, default parameter values, and notes that the tool will ask for clarification if logLevel is missing for enable. However, it does not describe potential side effects like performance impact or what happens to existing logs on disable.

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 bulleted notes. Every section serves a purpose, though the number of examples could be slightly trimmed. Overall, it is efficient and 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 lacks information about the tool's return value or response format, especially critical for the retrieve operation (e.g., what the retrieved logs look like). No output schema exists to compensate, leaving a significant gap in completenss.

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 covers 100% of parameters with descriptions, but the description adds significant value by providing examples that illustrate parameter combinations, defaults, and dependencies (e.g., logLevel required for enable, logId for retrieve). This goes beyond 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?

The description clearly states 'Manage debug logs for Salesforce users - enable, disable, or retrieve logs.' This specifies the verb (enable/disable/retrieve) and resource (debug logs for users), distinguishing it from sibling tools that handle queries, DML, analytics, etc.

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 examples and notes detailing when to use each operation (enable, disable, retrieve), required parameters, and default values. While it does not explicitly list alternatives or when not to use this tool, the context is sufficient given the sibling tool names.

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, 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.

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.

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.

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

Describes pagination behavior (default 200, limit/offset, not snapshot-consistent, stable pagination advice) and relationship query syntax. No annotations provided, so description carries burden; could mention read-only nature but covers key behaviors.

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?

Well-structured with brief intro, note on alternative, pagination details, examples, and syntax notes. Front-loaded with purpose. Could be slightly more concise but every part 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?

Covers input thoroughly but lacks explicit description of return format (though mentions total record count and next offset). No output schema; for a query tool, typical Salesforce response is expected but not documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions, but description adds practical examples for each parameter (e.g., whereClause with relationships, limit/offset for pagination). Adds value beyond 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?

Description clearly states it queries records from any Salesforce object using SOQL, including relationship queries. It distinguishes itself from sibling tool salesforce_aggregate_query by specifying when to use that 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?

Explicitly states when not to use this tool (for GROUP BY, aggregate functions, HAVING) and directs to salesforce_aggregate_query. Provides pagination guidance and relationship query usage notes.

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, the description fully discloses behavior: it states the difference between returning full body vs names only, metadata inclusion, wildcard support, and default pagination. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an introductory sentence, numbered examples, and bullet-point notes. Every sentence adds value, and there is no redundancy. It is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description describes return values vaguely (full body, names, metadata). It covers the essentials but could be more precise about the exact structure. Nevertheless, given the examples, it is sufficient for an agent to understand the output.

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 coverage, the description adds significant value by explaining interactions between parameters (e.g., className vs namePattern behavior), wildcard syntax, and default values. This goes beyond the schema's individual 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 starts with 'Read Apex classes from Salesforce,' which is a clear verb+resource. Examples show specific actions like reading by name, listing by pattern, and including metadata. This distinguishes it from siblings like salesforce_write_apex and salesforce_read_apex_trigger.

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 usage guidance through examples and notes, explaining when to use className vs namePattern, and the effect of includeMetadata. It does not explicitly mention when not to use or compare with other tools, but the context is fairly clear.

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 full burden. It discloses key behaviors: triggerName returns the full body, namePattern returns names without body, wildcard support, includeMetadata effect, and default behavior when no parameters are given. It does not cover rate limits or authentication, but these are implicit in Salesforce API context. The description adds value beyond the input schema.

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 separate sections for examples and notes. It is somewhat lengthy but every part adds value. Could be slightly more concise, but the clarity from examples justifies the 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?

Although there is no output schema, the description clarifies return formats (full body vs. names, metadata inclusion). It also mentions limit and offset for pagination, though not in detail. Error handling is not covered, but for this tool, the description is sufficiently complete to guide an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds significant meaning: it explains the difference between triggerName (returns full body) and namePattern (returns names only), wildcard usage, and the effect of includeMetadata. Examples also illustrate usage patterns. This goes well 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 clearly states the verb 'Read' and resource 'Apex triggers from Salesforce'. It distinguishes from sibling tools like salesforce_read_apex (read Apex classes) and salesforce_write_apex_trigger (write triggers) by focusing on triggers and read-only operation. Examples further clarify the scope.

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 guidance on when to use triggerName (specific trigger with full body), namePattern (listing with pattern), or neither (list all). It explains the outcomes for each scenario, but does not explicitly state when not to use this tool or mention alternatives like SOQL queries. Still, the usage context is well-defined.

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, the description fully discloses behavior: refresh triggers a refresh and returns a status URL; status returns per-component status and data status. It does not cover permissions or side effects, but the tool is informational and non-destructive, so this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear purpose statement, two examples, and a notes section. Every sentence adds value 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?

For a tool with two simple parameters and no output schema, the description covers all necessary information: operations, usage, and post-action steps. It is complete and leaves no ambiguity.

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 through examples and notes, clarifying operation options and the dashboard ID format, but mostly repeats schema info. The examples provide practical context, earning a slightly higher score.

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 the tool's purpose: 'Refresh a Salesforce dashboard or check its refresh status.' It clearly distinguishes the two operations with examples, and differentiates from sibling tools like salesforce_run_analytics by noting its use after refresh.

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 usage guidance for both operations, including when to use each (refresh vs. status). It explicitly advises using salesforce_run_analytics to retrieve updated data, effectively guiding the agent on tool selection after refresh.

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 full responsibility for behavioral disclosure. It does not mention potential side effects (e.g., mutations from POST/PUT/DELETE), authentication requirements, rate limits, or other important behaviors. This is a significant gap for a generic passthrough 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, numbered examples, and bullet points. While it is somewhat lengthy, each section adds value. It is appropriately front-loaded with the main 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?

Given the complexity (6 parameters, no output schema, many sibling tools), the description provides extensive examples and clarifies endpoint construction. It covers key usage scenarios comprehensively, though it lacks information on response format and error handling.

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 describes all 6 parameters with 100% coverage. The description adds value by explaining relative paths, rawPath behavior, and providing concrete examples for parameters like apiVersion and rawPath, going beyond the schema definitions.

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: 'Make direct REST API calls to any Salesforce REST endpoint.' It differentiates from siblings by noting it covers endpoints not handled by other tools, and provides numerous examples of specific APIs.

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 instructs to use this tool for any Salesforce REST API without a dedicated tool, and lists many such APIs. However, it does not explicitly state when not to use it (e.g., preferring dedicated tools when available), though this is implied.

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?

Discloses that reports run synchronously, detail rows are capped at 2,000, aggregates always returned, and includes truncation warnings. For dashboards, it explicitly says no refresh is triggered. All key behaviors are stated.

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 fairly long but well-structured with clear sections for reports and dashboards, plus bulleted examples. Each sentence contributes useful information. Could be slightly more concise, but appropriate for complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers both resource types, all parameters with examples, and behavioral notes. No output schema exists, and the description does not detail return values, which is a minor gap. Overall very complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default behavior (includeDetails default false), cap on detail rows, and filter syntax. Examples demonstrate complex usage. However, the schema already provides good descriptions, so not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes a Salesforce report or retrieves dashboard component data. It distinguishes between the two modes and references sibling tools like salesforce_refresh_dashboard for dashboard refresh.

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 on when to use reports vs dashboards. States that for dashboard refresh, one should use salesforce_refresh_dashboard. Examples cover common use cases and parameter combinations.

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 burden. It discloses that updateable/viewable parameters will return errors and explains wildcard support and WITH clauses. However, it does not state whether the tool is read-only or mention authentication/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 well-structured with examples and notes, but is somewhat lengthy. It front-loads the purpose and arranges information logically, though some redundancy exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and the tool's complexity, the description adequately covers usage scenarios. It explains SOSL specifics and provides enough detail for an agent to invoke the tool correctly, though return format is not described.

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 parameters are already documented. The description adds value by showing example usage patterns, explaining that each object can have its own WHERE/ORDER BY/LIMIT, and clarifying the reserved parameters' behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it uses SOSL to search across multiple Salesforce objects, which distinguishes it from siblings like salesforce_query_records (SOQL) and salesforce_search_objects (likely simpler). The verb 'search' and resource 'multiple Salesforce objects' are specific.

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 examples and notes about reserved parameters, but lacks explicit guidance on when to use this tool vs alternatives like salesforce_query_records or salesforce_search_objects. Usage is implied rather than stated.

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 exist, so the description carries full burden. It states the tool searches by name pattern with substring matching, but does not disclose case sensitivity, wildcard support, or whether it returns API names or labels. The behavior is basic but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with a clear, front-loaded purpose and an illustrative example. Every word adds value 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?

For a simple search tool with well-documented parameters, the description is adequate. However, without an output schema, it does not specify the return structure (e.g., list of object names or full details). The lack of output description is a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description does not add significant extra meaning beyond the schema; it provides an example in the main description but the parameter descriptions in the schema are already clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for Salesforce standard and custom objects'), the method ('by name pattern'), and provides concrete examples. It distinguishes itself from siblings like salesforce_query_records (which searches data) and salesforce_describe_object (which describes a specific object).

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 by giving examples, but it does not explicitly state when to use this tool versus alternatives like salesforce_search_all or the description tools. No guidance on prerequisites or limitations is provided.

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, 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.

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.