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?

With no annotations provided, the description carries full burden of behavioral disclosure. It reveals important behaviors such as automatic conversion of date range filters to timeFrameFilter and auto-prefixing custom fields with the object name. However, it does not mention permission requirements (beyond folder access) or what the API call returns, leaving minor 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 long but well-structured with clear headings, bullet points, and examples. It is front-loaded with key information like the IMPORTANT sections. While every section adds value, some repetition (e.g., field naming rules appear in multiple places) could be trimmed slightly, but overall it remains highly readable and efficient.

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

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

Given the tool's complexity (10 parameters, nested objects) and no output schema, the description covers the input thoroughly with workflows, examples, and conventions. However, it does not describe what the tool returns (e.g., report ID or success confirmation), which would be helpful for an agent to confirm the result. This is a minor gap.

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

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

Schema coverage is high (90%), and the description adds substantial value beyond the schema by providing field naming rules (UPPERCASE for standard, __c for custom), examples of valid values for reportType (object names vs custom report types), and detailed usage patterns for filters (date ranges). This makes the parameters much clearer and easier to use correctly.

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 a Salesforce report using the Metadata API, specifying supported formats (tabular, summary, matrix) and features like groupings, filters, and charts. This distinguishes it from sibling tools such as salesforce_read_report (which reads reports) or salesforce_list_reports (which lists reports). The verb 'Create' and resource 'Salesforce report' are specific and actionable.

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 includes a dedicated 'WORKFLOW TO CREATE A REPORT' section with step-by-step instructions, prerequisites (using salesforce_describe_report_type to discover fields), and explicit guidance on folder requirements and field naming conventions. It clearly tells the agent when and how to use this tool, including what to do before invoking it, making it easy to select this tool over 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 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?

No annotations are provided, and the description only states it returns details and fields, without disclosing read-only nature, rate limits, or other behavioral traits.

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?

A single sentence that is concise and directly states the purpose without any extraneous information.

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

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

Given the simple nature of the tool (one parameter, no output schema needed), the description adequately explains what to expect.

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 repeats the schema description without adding extra meaning beyond what's already in the parameter description.

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 'Get', resource 'specific report type', and includes 'available fields that can be used in reports', making it distinct from siblings like list_report_types.

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 retrieving field information for report building, but does not explicitly exclude cases or mention alternatives like list_report_types.

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?

No annotations are provided, so the description carries full burden. It usefully discloses that only folders created by the user and the 'unfiled$public' folder are visible, and that standard folders may not appear depending on permissions. This adds valuable behavioral context beyond the 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 concise with two clear sentences plus a note. Every sentence adds value: the first states the action, the second gives usage guidance, the note provides transparency. No wasted words.

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 simple nature of a list tool with no parameters, the description is fairly complete. It explains the purpose and important visibility constraints. However, it lacks information about the output format (e.g., list of folder names/IDs), which would be helpful for a complete understanding.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter information, and it doesn't. No schema description coverage is relevant here.

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

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

The description clearly states the tool lists report folders in Salesforce. It uses a specific verb ('List') and resource ('report folders'), and distinguishes from sibling tools like salesforce_list_reports which lists reports.

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 advises to use this tool to discover available folders before listing reports, providing a clear usage context. It also includes a note about permissions and visibility, which implies when it may not be fully reliable, though it does not explicitly state when not to use it.

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, description fully discloses key behaviors: default folder checking ('unfiled$public' and 'Private Reports'), inability to list all reports across all folders, and the organizational structure (reports in folders). Could add more about potential rate limits or response format, but overall strong.

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?

Every sentence provides value, organized with clear headers and bullet points. Properly front-loaded with the core purpose. No redundant or unnecessary text.

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

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

Given the tool's simplicity (2 params, no output schema, no annotations), the description comprehensively covers purpose, behavior with examples, limitations, and complementary tools. Leaves no significant gaps for an agent to misuse.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining the default behavior of the folder parameter (checks common folders if not specified) and reiterating the optional nature of searchPattern. This goes beyond the schema's 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?

Clearly states it lists reports in Salesforce folders and distinguishes from siblings by suggesting using salesforce_list_report_folders first. The verb 'list' and resource 'reports in folders' are specific and 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?

Provides explicit when-to-use: suggests listing folders first, explains behavior with and without folder parameter, and mentions the Salesforce API limitation that prevents listing all reports across folders in one call.

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 description implies a read-only listing operation, which is appropriate. No annotations are provided, so the description carries the burden; it is minimal but accurate.

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 with two sentences, front-loading the action and providing brief context. No unnecessary words.

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 tool with one optional parameter and no output schema, the description adequately covers the purpose and basic context. It could mention output format but is not required.

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% coverage for the single parameter 'searchPattern', which is described as optional and for filtering by name. The description adds no extra semantic value beyond the schema.

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

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

The description clearly states the tool lists available report types and explains what report types are. However, it does not explicitly differentiate from sibling tools like 'salesforce_describe_report_type' or 'salesforce_list_reports'.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for decision-making.

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

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

With no annotations, the description carries the full behavioral burden and does provide useful details: defaults, user validation, log-level enumeration, and a clarification behavior. However, it contains an internal inconsistency—logLevel is described as optional defaulting to DEBUG, but a later note says the tool will ask for clarification if it is not specified, and the schema says it is required for enable. It also does not describe side effects of enabling/disabling beyond the operation names.

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

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

The description is longer than average but well-structured: a summary line, concrete examples, and a notes section. Some redundancy exists between the examples and notes, but every section contributes operational value and the main purpose is front-loaded.

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

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

The description covers all seven parameters, operation modes, defaults, log-levels, validation behavior, and optional flags. It does not describe the exact return structure of retrieve or any required permissions, but it is reasonably complete for invoking the tool successfully.

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

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

Schema documentation covers 100% of parameters, so the baseline is 3. The description adds helpful defaults, examples, and conditional dependencies, but the contradictory statements about logLevel (optional/default vs. required/ask-for-clarification) reduce its reliability for parameter usage.

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

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

The opening sentence explicitly names the resource ('debug logs for Salesforce users') and the action (manage), then enumerates the three concrete operations: enable, disable, retrieve. This makes it clearly distinguishable from all sibling tools, none of which mention debug logs.

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

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

Four numbered examples show precisely which parameters are relevant for each operation, and the notes clarify defaults and constraints. There is no explicit 'when not to use' statement, but no sibling tool is a plausible alternative for debug-log management, so selection guidance is strong.

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

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?

No annotations are provided, so the description carries the burden of behavioral transparency. It does disclose relationship query nuances (dot notation, subqueries, __r suffixes) but does not explicitly state whether the operation is read-only, what permissions are needed, or any limits/timeout behavior. 'Query' implies a read, but not all behavioral traits are covered.

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

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

The description is long but every section earns its place: a clear purpose sentence, a critical exclusion note, four varied examples, and a concise summary of relationship field rules. The structure front-loads the main idea and then layers detail logically. Nothing is redundant or filler.

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

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

For a moderately complex tool with no output schema and no annotations, the description covers essential query construction, relationship semantics, and aggregate query alternatives. It does not explicitly describe the shape of the returned records, but that is generally implicit for a query tool. The examples and notes provide enough context to use the tool correctly.

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

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

While schema coverage is 100% (baseline 3), the description adds substantial meaning beyond schema property descriptions. It provides detailed multi-level query examples for fields, explains how to construct relationship queries in whereClause, and introduces conventions like dot notation and subqueries that are not captured in the schema. This is exceptional parameter-level guidance.

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

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

The description opens with a specific verb-resource-scope statement: 'Query records from any Salesforce object using SOQL, including relationship queries.' It clearly distinguishes itself from sibling salesforce_aggregate_query by explicitly naming the alternative for aggregate queries, and from other tools like describe or search.

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

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

The description explicitly states when NOT to use this tool: 'For queries with GROUP BY, aggregate functions (COUNT, SUM, AVG, etc.), or HAVING clauses, use salesforce_aggregate_query instead.' This directly guides tool selection among siblings. Examples also clarify use cases for parent-child and child-parent queries.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It clearly explains that className returns the full body, namePattern returns matching names without body, includeMetadata adds metadata, and wildcard behavior is specified. This is comprehensive for a read operation.

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

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

The description is well-structured with examples and notes. While slightly verbose, every example serves a purpose and the notes clarify behavior. The front-loaded main sentence followed by illustrative examples makes it easy to scan.

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

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

Given there is no output schema, the description compensates by explaining return behavior for every parameter scenario. It also covers edge cases (no parameters, wildcards) and metadata inclusion. This fully equips an agent to know what to expect from each call.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful value beyond the schema by providing examples of combinations, explaining wildcard usage, and clarifying what output to expect for each parameter. This enriches understanding beyond the basic property descriptions.

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

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

The description clearly states the tool's purpose: 'Read Apex classes from Salesforce.' It uses a specific verb ('read') and resource ('Apex classes'), and distinguishes from sibling tools like salesforce_write_apex and salesforce_read_apex_trigger by focusing specifically on Apex classes.

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

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

The description provides thorough guidance on when to use each parameter combination (className, namePattern, includeMetadata), including what happens when neither is provided. It lacks explicit mention of when to prefer this tool over alternatives, but the name and context make this clear.

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

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

No annotations are provided, but the description carries the full burden effectively. It discloses exactly what is returned for each parameter combination: full body for triggerName, names only for namePattern, metadata flag, and behavior when neither is provided. Wildcard semantics are also spelled out, giving complete behavioral transparency.

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

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

The description is well-structured with an overview, four illustrative examples, and a list of notes. Every section contributes meaningful information without fluff. It's appropriately sized for a tool with 3 parameters and no output schema, and information is front-loaded with the core purpose.

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

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

Even without an output schema, the description explains what the tool returns in every scenario, including specific trigger bodies, matching names, and metadata fields. It also covers wildcard support and default behavior, making it comprehensive for a read-only tool.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds value beyond the schema by clarifying interactions (e.g., triggerName takes precedence, namePattern returns names only) and providing concrete examples of wildcard usage. This enhances parameter semantics without being redundant.

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

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

The description opens with 'Read Apex triggers from Salesforce,' using a specific verb and resource. It clearly differentiates from siblings like salesforce_read_apex (likely Apex classes) and salesforce_write_apex_trigger (write operation). The detailed examples reinforce the purpose.

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

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

The description gives comprehensive examples for when to use triggerName vs namePattern vs neither, with notes on wildcards and metadata. However, it lacks explicit comparison to alternative tools (e.g., 'use salesforce_read_apex for classes'), so it falls short of full 5.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It describes a read-only operation but lacks details on authentication, rate limits, error handling, or what happens if the report does not exist. This is minimal 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?

Two sentences, front-loaded with the main action and purpose. Every sentence adds value with no redundant or wasted words.

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 has one parameter, no output schema, and no annotations, the description covers the purpose and what metadata it retrieves. It is reasonably complete for a simple read tool, though it could briefly mention the return format.

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 'reportName' has full schema description coverage (100%), providing an example format. The description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Read' and the resource 'detailed metadata for a Salesforce report', listing specific details like columns, filters, groupings, and chart configuration. This distinguishes it from sibling tools like salesforce_list_reports (which lists report names) and salesforce_create_report (which creates reports).

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 says 'Use this to inspect existing reports and understand their structure', implying when to use it, but does not explicitly state when not to use it or provide alternatives among sibling tools. Guidance is implied but not explicit.

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 transparency burden. It discloses important behavioral details: SOSL syntax, wildcard support, per-object WHERE/ORDER BY/LIMIT, WITH clause types, and access filtering via updateable/viewable. It stops short of stating read-only nature explicitly, but 'search' strongly implies it. Overall, it provides above-average transparency.

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

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

The description is longer than a minimal one, but the length is justified by the tool's complexity. It is front-loaded with a clear purpose, followed by structured examples and a concise bullet list of notes. Every section adds value, though some redundancy exists (e.g., wildcards are mentioned twice).

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

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

The tool is complex with nested object parameters and optional WITH clauses. The description covers the multidimensional usage thoroughly with examples, notes, and feature lists, providing enough context for an agent to construct valid invocations. Given no output schema, the description is sufficiently complete for this search tool.

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

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

Schema coverage is 100%, providing a solid baseline. The description goes beyond the schema by including two detailed examples that show how objects, withClauses, and wildcards are used together, and it clarifies the meaning of updateable/viewable. This significantly enriches parameter understanding.

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

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

The description opens with a precise statement: 'Search across multiple Salesforce objects using SOSL (Salesforce Object Search Language).' This clearly identifies the tool's action, resource, and scope, and distinguishes it from sibling tools like salesforce_search_objects and salesforce_query_records by emphasizing multi-object SOSL search.

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

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

The description gives clear context that this tool is for searching across multiple objects, with examples showing the expected structure. However, it does not explicitly reference alternatives or state when not to use it, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It explains the search action and gives examples of matches, but doesn't state whether the operation is read-only, its return format, or any limitations (e.g., case sensitivity, wildcard support). For a simple search tool, the core behavior is disclosed, but additional transparency is lacking.

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

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

The description is extremely concise: one sentence stating the purpose and one sentence with examples. It is front-loaded with the verb and resource, and every word earns its place. No fluff or repetition.

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

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

For a tool with one parameter and no output schema, the description covers the main purpose and gives examples. However, it omits specifics about how the pattern matching works (e.g., substring vs. whole word, case sensitivity) and what the output shape is (e.g., just names or full metadata). These gaps prevent it from being fully complete.

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

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

The only parameter `searchPattern` has a 100% schema description coverage, including an example. The tool description reiterates and supplements with examples ('Account' will find Account, AccountHistory), but doesn't add significant new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search for Salesforce standard and custom objects by name pattern.' It provides concrete examples ('Account' will find Account, AccountHistory), which further clarifies the scope and distinguishes it from sibling tools like describe or query.

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

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

The description gives a clear context of when to use this tool (searching objects by name pattern) and provides examples of the expected input/output. It doesn't explicitly mention alternative tools or exclusions, but the use case is unambiguous enough for an agent to decide when to call it.

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

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.