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

Beyond the readOnlyHint annotation, the description discloses query behavior, grouping requirements, filtering semantics before and after grouping, supported date functions, and limitations such as OFFSET not being supported. This gives the agent a clear model of how the tool behaves in execution.

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, front-loaded with purpose and usage distinction, followed by examples and rules. Every section earns its place; there is no filler or redundancy that would distract an agent.

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 aggregate-query tool, the description is remarkably complete: it covers supported aggregate functions, date grouping, related-object grouping, HAVING usage, field-aliasing, and key Salesforce-specific restrictions. Without an output schema, the examples and rules still provide enough context to call 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?

Although the schema already documents all parameters, the description adds substantial semantic value: it maps parameters to concrete examples, explains the selectFields alias format, clarifies when whereClause versus havingClause should be used, and states the relationship between selectFields and groupByFields.

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 states a specific verb and resource: execute SOQL queries with GROUP BY and aggregate functions. It clearly distinguishes itself from salesforce_query_records by noting that regular queries without GROUP BY or aggregates should use the sibling tool 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?

It explicitly says when to use this tool versus salesforce_query_records. It also provides detailed guidance through examples and Important Rules for when to apply WHERE versus HAVING, GROUP BY constraints, ORDER BY constraints, and unsupported OFFSET behavior.

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 readOnlyHint annotation already covers the read-only safety profile. The description adds useful context about the returned metadata content (fields, relationships, field properties) but does not disclose behavior such as response size, invalid object handling, or permissions. This is adequate but not rich.

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 core purpose and followed by concrete examples. No filler or redundancy, and every sentence 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 one-parameter, read-only describe tool, the description is complete: it states what the tool returns, gives valid object examples, and is backed by the readOnlyHint annotation. There is no output schema, but the description sufficiently conveys the expected metadata result.

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 documents the single objectName parameter with examples at 100% coverage. The description reinforces the parameter with Account/Case examples but adds no new semantic details beyond what the schema provides, so the baseline of 3 applies.

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 ('Get') and resource ('detailed schema metadata including all fields, relationships, and field properties'). The examples clarify that this is about object structure, not data records, which clearly distinguishes it from query/search/DML siblings.

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 intended use is implied: call this when you need object schema metadata. However, the description does not explicitly say when to choose this over query_records, search_objects, or manage_object, and it provides no exclusions or alternative routing.

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 mentions the operations but omits critical traits such as the irreversibility of delete, required permissions, or potential bulk API limits. The lack of any cautionary or side-effect information leaves an agent under-informed.

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: it opens with a clear purpose, lists operations as bullet points, and concludes with practical examples. No unnecessary words or technical jargon are present, making it easily 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?

While the description includes examples, it omits important usage constraints such as the requirement that delete operations only need the record Id, or that upsert requires an external ID field. Given the tool's multiple modes, an agent would need more context to use it correctly in all scenarios.

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

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

The schema description covers 100% of the parameters, and the descriptions are accurate but minimal. The externalIdField parameter is described as 'for upsert operations', which adds a slight clarification, but otherwise the descriptions do not go beyond the schema's own names and types (e.g., 'records' does not specify the required record format).

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 'Perform data manipulation operations on Salesforce records' and enumerates the four specific operations (insert, update, delete, upsert) with examples. This clearly distinguishes it from sibling tools that focus on querying, searching, or managing metadata.

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 practical examples like 'Insert new Accounts' and 'Update Case status', which hint at usage. However, it does not explicitly contrast this tool with siblings such as salesforce_query_records or salesforce_manage_object, nor does it state when not to use it (e.g., for read-only operations).

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?

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 supplied, the description must carry behavioral disclosure. It usefully discloses a non-obvious side effect: 'Automatically grants Field Level Security to System Administrator (or specified profiles).' It does not disclose prerequisites, error behavior, or whether updates to existing fields have destructive or irreversible consequences, leaving gaps 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: a clear one-sentence purpose, bullet summary of key capabilities, examples, and a note about access defaults. It is economical and readable, though the bullet list overlaps with schema content slightly.

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 18-parameter mutation tool with no output schema and no annotations, this description supplies a solid high-level orientation and flags FLS behavior, but it omits return/result information, permission prerequisites, and conditional parameter requirements (e.g., referenceTo needed for Lookup/MasterDetail). It is adequate for selection but not fully complete for safe invocation in 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?

Schema description coverage is 100%, so the schema already documents all 18 parameters. The description adds useful conceptual grouping and examples, and restates the grantAccessTo default, but it does not add meaningfully new parameter semantics beyond what the schema already provides.

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

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

The description opens with a specific action and resource: 'Create new custom fields or modify existing fields on any Salesforce object.' Concrete examples ('Add Rating__c picklist to Account') anchor the purpose and make it easy to distinguish from sibling tools like salesforce_manage_object or salesforce_manage_field_permissions.

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 clearly implies when to use the tool: whenever custom fields need to be created or modified, and it gives representative examples. However, it does not explicitly contrast this tool with closely related siblings, such as salesforce_manage_object for creating objects or salesforce_manage_field_permissions for permission-only workflows, so an agent gets no explicit when-not-to-use 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 carries the full burden of behavioral disclosure. It mentions grant/revoke/view and bulk updates, but does not disclose consequences of the default editable/readable values, whether operations are reversible, required permissions, or what happens if profileNames is omitted for grant/revoke. For a mutating tool, this is a significant transparency gap.

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

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

The description is well-organized with a clear opening, bulleted capabilities, and concrete examples. It is slightly repetitive in that the examples restate the bullets, but overall it is compact and front-loaded with the most important 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?

The description mentions permission sets, but the input schema only supports profileNames, creating a misleading gap. It also does not clarify operation-specific requirements, such as whether profileNames is needed for view or what defaults apply when readable/editable are omitted. With no output schema and no annotations, an agent lacks enough context to call this tool reliably in all 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 input schema has 100% parameter description coverage, so the baseline is 3. The description adds some practical context through examples, such as using 'System Administrator' and 'read-only access', but it does not explain relationships between operation, readable, editable, and profileNames beyond what the schema already provides.

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

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

The description clearly identifies the tool as managing Field Level Security for custom and standard fields, and enumerates the specific operations: grant, revoke, view, and bulk update. It distinguishes this from sibling tools like salesforce_manage_field by focusing on profile/permission-set access rather than field definitions, though it does not explicitly name an alternative.

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 bulleted capabilities and examples imply when to use the tool: granting access, giving read-only access, and checking access. However, there is no explicit guidance on when not to use it or how to choose between this and the sibling salesforce_manage_field tool, leaving some ambiguity for an agent.

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 disclosure burden. It does disclose that 'Changes affect metadata and require proper permissions,' which is valuable. Still, it omits other relevant behaviors such as side effects of updating existing objects, irreversibility, or what happens on partial failure, leaving the mutation profile only partially transparent.

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, front-loaded, and uses bullets and examples effectively. The structure makes the two operation modes immediately visible. The only questionable element is the unsupported 'fields, relationships, and settings' phrase; otherwise the description is efficient and well organized.

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

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

For a metadata mutation tool with no annotations and no output schema, the description should explain what the agent should expect after a successful call. It provides a permission caveat and examples, but it does not describe return values, failure modes, or update semantics, and it inaccurately hints at field/relationship creation. This leaves the tool incompletely specified for reliable 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?

All 9 parameters have schema descriptions, so the baseline is 3. However, the description's claim that creates involve 'fields, relationships, and settings' is not supported by the input schema, which has no field or relationship parameters. This misleading statement detracts from the schema's otherwise clear parameter documentation, so the score is lowered.

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 a specific verb and resource: 'Create new custom objects or modify existing ones in Salesforce.' The bullets and examples clarify the create/update operations, and the note 'Changes affect metadata' distinguishes this from data operations like salesforce_dml_records. It is easy for an agent to identify this as the metadata object management tool.

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 context for use is implied: create or update custom object metadata. However, the description never explicitly contrasts with sibling tools like salesforce_manage_field or salesforce_dml_records, nor does it provide 'when not to use' guidance. The usage scenario is clear but exclusions and alternatives are left to inference.

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 annotation readOnlyHint: true already indicates the tool is non-destructive. The description adds no contradictory side effects and provides context about querying relationships. Since the annotation covers the main behavioral trait, a score of 4 is appropriate.

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 main statement, a note about alternatives, and examples. While it is somewhat long, the content is relevant and directly supports usage. No fluff is present.

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, combined with the schema and examples, provides complete guidance for querying records including complex relationships. The absence of an output schema is not a gap for this tool as the query results are standard.

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?

All 5 parameters are described in the schema with 100% coverage. The description further clarifies complex usage of fields, whereClause, and orderBy through examples and notes about relationship fields, enhancing understanding 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's function: 'Query records from any Salesforce object using SOQL, including relationship queries.' It is specific and distinct from sibling tools like salesforce_aggregate_query which handles aggregation.

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 a clear usage guideline by noting when to use salesforce_aggregate_query instead (for GROUP BY, aggregates, HAVING). It also gives examples for relationship queries. However, it does not explicitly contrast with search tools like salesforce_search_objects, but the intended use is implicit.

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?

Annotations only declare readOnlyHint=true. The description adds substantial behavioral detail: namePattern results exclude class bodies, includeMetadata adds API version/length/last modified date, wildcard syntax is supported, and the no-argument behavior lists all class names. This goes well beyond what the annotation provides.

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 summary, four relevant examples, and grouped notes. Information is front-loaded and each line contributes to understanding parameter behavior. Despite its length, it remains focused and 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?

The description covers all main input modes, wildcard behavior, metadata enrichment, and the default listing case. The only notable ambiguity is what happens when both className and namePattern are provided together, and whether includeMetadata also applies to exact className lookups. Overall it is highly complete for a read-only tool with no output schema.

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

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

The input schema already describes all three parameters, but the description adds meaningful semantics: how className and namePattern behave differently, how includeMetadata changes the result, default behavior when neither is provided, and concrete wildcard syntax with examples. This adds clear 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 opens with a specific verb and resource: 'Read Apex classes from Salesforce.' This clearly distinguishes the tool from siblings like salesforce_write_apex and salesforce_read_apex_trigger, which target different operations or resources.

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 give explicit usage conditions: className returns a full body, namePattern returns matching class names without bodies, includeMetadata adds metadata, and neither parameter lists all classes. It does not explicitly name alternatives or state when not to use this tool, but the usage context is clearly conveyed.

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 readOnlyHint annotation already signals a safe read operation, but the description goes far beyond that by explaining return behavior differences: triggerName returns the full body, namePattern returns names without body, includeMetadata adds extra fields, and wildcards are supported. This is exactly the kind of behavioral context an agent needs and is not present in the annotations.

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

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

The description is well-structured with a one-line summary, numbered examples, and bulleted notes. It is slightly longer than strictly necessary, but every section contributes useful context and the front-loaded summary ensures quick understanding. It earns a 4, not a 5, due to some redundancy between the examples and notes.

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?

All relevant operational details are covered: the effect of each parameter, the default behavior when neither parameter is given, wildcard syntax, and metadata options. There is no output schema, so the description appropriately clarifies what the tool returns (full body vs. names vs. metadata). Nothing an agent needs to call this correctly is missing.

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?

Even though schema coverage is 100%, the description enriches the parameters with relational semantics: the mutual interaction between triggerName and namePattern, the optionality of includeMetadata, and the wildcard behavior. The examples concretely map JSON inputs to outcomes, adding value beyond the plain 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 pair: 'Read Apex triggers from Salesforce.' This clearly distinguishes it from siblings like salesforce_write_apex_trigger and salesforce_read_apex, and the examples reinforce the resource being acted on. The tool's purpose is unambiguous.

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

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

The description gives clear conditional guidance for parameter combinations (when triggerName is provided, when namePattern is provided, when neither is provided), which effectively tells an agent how to invoke the tool for different intents. However, it does not explicitly mention when to choose this tool over sibling tools, 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?

With only readOnlyHint=true in annotations, the description carries meaningful behavioral detail: wildcard support, per-object clauses, WITH clause options, and updateable/viewable access filtering. It does not describe return format or error behavior, but the added functional context goes well beyond the annotation.

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

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

The description is front-loaded with a clear purpose sentence, followed by well-organized examples and notes. Despite its length, every section carries useful information for invoking a complex tool, and there is no fluff 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?

The tool is complex with six parameters, nested objects, and enums, but the description plus 100% schema coverage covers all invocation aspects thoroughly. It lacks an explicit output contract and sibling routing guidance, but the detailed examples make it nearly complete for correct use.

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 already 100%, so the baseline is 3. The description adds value with concrete request examples and notes that clarify wildcard syntax, per-object WHERE/ORDER BY/LIMIT usage, and WITH clause semantics, going beyond the terse 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 operation ('Search'), the resource ('multiple Salesforce objects'), and the mechanism (SOSL), which is more specific than the tool name. It does not explicitly differentiate from sibling tools like salesforce_search_objects, but the multi-object SOSL focus is evident.

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 examples and notes imply that this tool is for cross-object SOSL search, but there is no explicit guidance on when to choose it over salesforce_query_records or salesforce_search_objects. No exclusions or alternative conditions are stated, so the agent must infer usage from context.

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?

Annotations only declare readOnlyHint, so the description carries the behavioral disclosure burden. It adds meaningful detail about partial-pattern matching and inclusion of custom objects, helping an agent predict that a search may return multiple related object definitions.

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 deliver the core operation first, followed by concrete illustrative examples. There is no filler, repetition of schema fields, or unnecessary detail.

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 single-parameter read-only search tool with no output schema, the description sufficiently explains scope and matching behavior to support correct invocation. It could be slightly stronger by describing the return shape, but that is not essential here.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The tool description reinforces pattern-matching behavior with examples, but the parameter meaning is already fully conveyed by 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?

States a specific verb ('Search'), a specific resource ('Salesforce standard and custom objects'), and a matching criterion ('by name pattern'). The examples make it clear this returns object definitions rather than records, distinguishing it from salesforce_search_all 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 explains what the tool does but gives no guidance on when to use it versus alternatives such as salesforce_search_all or salesforce_describe_object. There are no explicit conditions, exclusions, or recommended usage contexts.

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.