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

Beyond the readOnlyHint annotation, the description discloses crucial behavioral constraints: non-aggregate fields must be in groupByFields, ORDER BY limitations, OFFSET not supported, and the distinction between WHERE (before grouping) and HAVING (after grouping). These details give the agent a thorough understanding of the tool's behavior, far exceeding what annotations alone provide.

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

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

The description is well-structured with a clear opening, differentiation note, numbered feature list, multiple examples, and an 'Important Rules' section. It is appropriately sized for the tool's complexity, with every sentence contributing essential information and no redundancy. The front-loaded summary immediately conveys the tool's purpose.

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

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

Given the tool's complexity (7 parameters, no output schema), the description is exceptionally complete. It covers the tool's function, usage context, parameter relationships, limitations, and provides concrete examples. It also clarifies the difference between this tool and salesforce_query_records, ensuring the agent can make informed decisions. The absence of an output schema is acceptable as return format is implied for a query 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?

Although the schema already covers all parameters (100%), the description adds significant semantic value by explaining how parameters interact: selectFields format, the mandatory relationship between selectFields and groupByFields, whereClause vs. havingClause, and restrictions on orderBy. Multiple examples illustrate exact parameter usage, making the description highly informative 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 it executes SOQL queries with GROUP BY, aggregate functions, and statistical analysis, using a specific verb ('Execute') and resource ('SOQL queries'). It explicitly distinguishes from the sibling tool salesforce_query_records by noting that regular queries without GROUP BY should use that alternative, making the tool's scope 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?

The description provides explicit when-to-use guidance: 'Use this tool for queries that summarize and group data rather than returning individual records' and names the alternative tool for regular queries. It also includes examples for various scenarios, reinforcing when this tool is appropriate.

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 is consistent with the non-destructive 'Get' description. The description adds useful context about the scope of metadata returned (all fields, relationships, field properties) beyond the annotation, though it does not detail error handling or special behaviors. No contradiction.

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 a single, front-loaded sentence followed by two illustrative examples. Every word earns its place, with no redundancy 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 simple read-only describe tool with one fully documented parameter and no output schema, the description adequately conveys the tool's capabilities and return scope. The examples clarify usage without unnecessary detail.

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 the objectName parameter fully described including examples. The description's examples (Account, Case) duplicate the schema info and provide no additional semantic depth, so the baseline score of 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 with a specific verb ('Get') and resource ('detailed schema metadata'), listing fields, relationships, and field properties. The examples ('Account', 'Case') reinforce the purpose and help distinguish it from query or management tools.

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

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

The description clearly indicates when to use this tool (when needing schema metadata). However, it does not explicitly mention alternatives or exclusions, though the context is unambiguous given sibling tools like salesforce_query_records. This merits a 4 rather than 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, the description carries the burden. It transparently discloses that update/delete require Id and upsert relies on an external ID field. It does not mention permissions or error scenarios, but the destructive nature is clear from 'Remove records'.

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?

Concise, well-structured bullet points with a clear opening sentence. Examples are helpful and no extraneous content exists.

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

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

For a DML tool with no output schema, the description is fairly complete—it covers all operations, prerequisites, and examples. However, it does not describe the return value or response format, which 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 covers all parameters, but description adds meaningful context by explaining each operation's constraints (e.g., 'requires Id', 'based on external ID field'), going beyond the enumerated values.

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

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

The description clearly states the tool performs data manipulation operations on Salesforce records, listing all supported operations (insert, update, delete, upsert) with brief explanations. It distinguishes itself from sibling tools like query/describe by focusing on write operations.

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

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

Usage is implied through the operation list and examples (e.g., 'Insert new Accounts'), but there is no explicit guidance on when to use this tool versus read-only alternatives like salesforce_query_records. No exclusions are stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the code 'does not persist,' execution results include 'compilation success/failure, execution success/failure, and debug logs,' and 'some operations may be restricted based on user permissions.' However, it lacks details on rate limits, timeouts, or specific security restrictions.

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

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

The description is front-loaded with the core purpose, but includes lengthy examples and notes that could be streamlined. While informative, some sentences (e.g., repeating parameter details) don't earn their place given the comprehensive schema. The structure is clear but could be more concise.

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

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

Given the tool's complexity (executing arbitrary code) and lack of annotations and output schema, the description does a good job covering essential context: purpose, usage guidelines, behavioral traits, and parameter examples. However, it could better explain the output format (e.g., what 'execution results' include) since there's 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?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema, mainly through examples that illustrate parameter usage. It confirms apexCode is 'required' and logLevel 'defaults to DEBUG,' but these details are already in 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 purpose: 'Execute anonymous Apex code in Salesforce.' It specifies the verb ('Execute'), resource ('anonymous Apex code'), and context ('in Salesforce'), distinguishing it from sibling tools like salesforce_query_records or salesforce_dml_records that handle specific operations.

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

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

The description provides explicit guidance on when to use this tool: 'When users request data queries or updates that aren't directly supported by other tools, this tool can be used if the operation is achievable using Apex code.' It also notes this is for operations 'when there are no other specific tools available,' helping differentiate from more specialized siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and excels by adding rich context beyond what the input schema provides. It details validation ('validates that the specified user exists'), default behaviors (e.g., defaults for logLevel, expirationTime, limit, includeBody), and interactive aspects ('will ask for clarification' if logLevel unspecified), covering safety, side effects, and system interactions comprehensively.

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

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

The description is well-structured with a clear purpose statement, detailed examples, and notes section, but it is somewhat lengthy due to extensive examples and notes. Every sentence earns its place by providing essential guidance, though it could be more front-loaded; the core purpose is stated first, but the depth of detail might overwhelm initial scanning.

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

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

Given the tool's complexity (7 parameters, multiple operations) and lack of annotations and output schema, the description is highly complete, covering operations, parameters, defaults, validation, and examples. However, it does not describe the return format or error handling, which are gaps for a tool with no output schema, slightly reducing 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?

Despite 100% schema description coverage, the description adds significant value by explaining parameter semantics beyond the schema. It clarifies dependencies (e.g., 'username parameter is required for all operations'), optionality rules, default values, enum meanings ('Log levels: NONE, ERROR...'), and operational contexts through examples, making the tool much more usable than the schema alone would allow.

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

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

The description clearly states the tool's purpose with specific verbs ('enable, disable, or retrieve logs') and resource ('debug logs for Salesforce users'), distinguishing it from sibling tools like salesforce_query_records or salesforce_dml_records that handle different Salesforce operations. The title is null, making the description's clarity even more critical, and it successfully communicates the exact functionality.

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

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

The description provides clear context for when to use this tool (managing debug logs) but does not explicitly state when not to use it or name alternatives among sibling tools. The examples implicitly guide usage by showing different operations, but there's no direct comparison to other tools like salesforce_read_apex for log-related tasks, leaving some ambiguity.

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 present, so the description must carry the burden. It discloses a key side effect – automatically granting FLS to System Administrator (or specified profiles) – and notes the default profile. However, it doesn't mention permissions required, reversibility, or failure modes, leaving gaps.

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

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

The description is well-structured with bullet points, front-loads the purpose, and includes examples. It's appropriately sized, though the note about grantAccessTo slightly duplicates schema info.

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 18-parameter mutation tool with no output schema, the description provides a good overview and examples but omits operational details like prerequisites, reversibility, or error handling. The 100% schema coverage helps, but behavioral context is only partially covered.

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 is 3. The description adds minimal param semantics beyond the schema: it groups field types/properties and gives an example, but does not explain parameter values in more depth than the schema already does.

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 'Create new custom fields or modify existing fields on any Salesforce object' – a specific verb+resource. It distinguishes from siblings like salesforce_manage_object (objects) and salesforce_manage_field_permissions (FLS), and lists supported field 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?

Context is clear: it's for creating/updating fields, with examples. However, it doesn't explicitly say when not to use it or name alternatives such as salesforce_manage_field_permissions, so it misses the top tier.

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 states that the tool can grant/revoke/view permissions, but it does not mention prerequisites (e.g., administrative rights), potential side effects (e.g., changes to field security are immediate), reversibility, or what happens when both readable and editable are false. The description also does not clarify whether the tool is read-only for the 'view' operation. This is a significant gap 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, bullets, and numbered examples. It is slightly verbose but every part adds information, such as the examples demonstrating realistic use cases. The format makes it easy to scan and understand the tool's capabilities 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 6 parameters and no output schema or annotations, so the description should explain return values and parameter behavior more thoroughly. It does not describe what the tool returns (e.g., success/failure, updated permissions), nor does it explain how operation interacts with readable/editable or profileNames for different operations. The examples cover basic scenarios but leave gaps for edge cases like bulk updates or viewing permissions without specific profiles. Overall, the description is not complete enough for a tool of this complexity.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds value by mapping grant/revoke to readable/editable and providing examples like 'read-only access' (editable=false, readable=true). However, it introduces a discrepancy by mentioning 'permission sets' while the schema only provides profileNames, which could mislead users. The description does not fully clarify parameter combinations for operations like 'view' (e.g., whether profileNames is optional).

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's purpose: managing Field Level Security (Field Permissions) for custom and standard fields. It lists specific operations (grant, revoke, view) and distinguishes from sibling tools like salesforce_manage_field by focusing on permissions rather than field definitions. Examples further clarify the scope and usage.

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

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

The description provides clear usage context through bullets and examples, such as granting System Administrator access, giving read-only access, and checking profile access. It implies when to use the tool (for permission changes) but does not explicitly exclude alternatives or mention when not to use it. No alternative tools are referenced, so it lacks explicit differentiation but still offers clear 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?

With no annotations, the description carries the full burden for behavioral disclosure. It mentions that changes affect metadata and require proper permissions, which is useful. However, it does not describe potential side effects, reversibility, or return values, which is a gap 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 concise and front-loaded, using bullets and examples to convey the key operations efficiently. Every sentence adds value, and the note about permissions is a relevant inclusion. It is well-structured 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?

Given the tool's complexity (9 parameters, 3 enums, no output schema), the description is adequate but incomplete. It does not specify which parameters apply to create vs. update, nor does it explain conditional dependencies or return value. The schema covers parameter descriptions, but the overall operational context could be richer.

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 is 3. The description does not add meaningful parameter-level detail beyond what the schema already provides; it only mentions fields/relationships/settings at a high level. No parameter syntax or conditional guidance is added.

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 or updates custom objects in Salesforce, with distinct sub-actions (Create/Update) and examples. This distinguishes it from siblings like salesforce_manage_field (fields) and salesforce_dml_records (records).

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

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

The description provides clear context for using the tool on objects and gives examples, but it does not explicitly state when to prefer this over sibling tools like salesforce_manage_field. The note about metadata changes implies the appropriate use case, but exclusions are 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 readOnlyHint=true annotation, the safety profile is already known. The description adds valuable context about relationship field syntax (dot notation, subqueries, custom relationship fields ending in __r), which is not in the schema or annotations. It doesn't disclose pagination or return format, but the annotation lowers the bar.

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 perfectly structured with a clear purpose, a note for alternative tool, and well-organized examples. Every sentence adds value, and the examples are essential for explaining relationship queries. No 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?

Given the complexity of relationship queries and the absence of an output schema, the description covers the main usage patterns thoroughly. It lacks explicit mention of return format or pagination behavior, but the examples and parameter description provide sufficient context for most use 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?

Although schema coverage is 100%, the description significantly enriches parameter understanding through examples showing how to use fields for parent/child relationships, whereClause for related object filtering, and orderBy with related fields. This is crucial beyond the schema's brief 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 queries records from any Salesforce object using SOQL, including relationship queries. It distinguishes itself from the sibling tool salesforce_aggregate_query by explicitly directing aggregate queries elsewhere, making the purpose 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 explicitly says to use salesforce_aggregate_query for queries with GROUP BY, aggregate functions, or HAVING clauses, providing a clear alternative. The examples also demonstrate when to use relationship queries, giving practical usage 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 description goes well beyond the readOnlyHint annotation by explaining exactly what is returned in each mode: full body with className, only names with namePattern, and additional metadata with includeMetadata. It also discloses the default behavior when neither parameter is provided and documents wildcard support, providing rich behavioral context.

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 summary but then expands into 4 examples and 5 notes. While each point adds information, the length is excessive for a 3-parameter read tool. Some examples are redundant (e.g., example 3 is similar to example 2 with metadata), making it less concise than it could be.

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

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

For a read tool with no output schema, the description covers the main return behaviors (full body, names, metadata) and default listing. It is missing edge-case context like conflicting parameters or not-found behavior, but given the tool's simplicity and the presence of annotations, it is mostly complete.

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

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

Schema descriptions are present for all parameters (100% coverage), so baseline is 3. The description adds value by showing concrete examples of valid input combinations, clarifying the effect of includeMetadata, and explaining wildcards in namePattern. However, it does not describe the behavior when both className and namePattern are provided, which is a slight gap.

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 'Read Apex classes from Salesforce' and provides examples of reading a specific class, listing classes by pattern, and fetching metadata. It distinguishes from write operations and from other read tools by focusing on Apex classes, though it doesn't explicitly differentiate from the sibling salesforce_read_apex_trigger.

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

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

The examples and notes imply when to use each parameter (className for full body, namePattern for listing, includeMetadata for metadata), but there is no explicit guidance on when to choose this tool over alternatives like read_apex_trigger or describe_object. Usage is implied rather than explicitly stated.

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

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

With readOnlyHint=true already providing safety, the description adds valuable behavioral detail: that triggerName returns the full body, namePattern returns only names, includeMetadata toggles metadata, and wildcards are supported. This goes beyond what annotations disclose and helps the agent predict the output for different input combinations.

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-sentence purpose, four clear examples, and a bulleted list of notes. Every sentence serves the goal of explaining the tool's behavior, and the length is appropriate for the tool's complexity. It front-loads the main verb and resource.

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 absence of an output schema, the description adequately explains what the tool returns for each input scenario. It covers all three parameters and their combinations, which is sufficient for a read-only tool. It could mention error handling or permission requirements, but these are not critical for basic usage.

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

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

The schema already describes each parameter (100% coverage), but the description enriches their meaning by explaining the consequences of using them together, such as the fallback when neither triggerName nor namePattern is provided and the effect of includeMetadata. This extra explanation 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 begins with 'Read Apex triggers from Salesforce', which is a specific verb+resource statement. The examples and notes clarify the exact scope (Apex triggers, not classes or other objects) and the behavior, distinguishing it from sibling tools like salesforce_read_apex (for classes) and salesforce_write_apex_trigger (for writing triggers).

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

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

The description provides clear guidance on when to use triggerName vs namePattern vs includeMetadata, including the fallback behavior when neither is provided. It does not explicitly name alternative tools, but the purpose statement itself is sufficient to imply this is the tool for reading triggers rather than other Salesforce objects.

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 goes beyond the readOnlyHint annotation by explaining wildcard usage (* and ?), per-object independent WHERE/ORDER BY/LIMIT clauses, and supported WITH clause types. It provides concrete examples of advanced search configurations, adding useful behavioral context without contradicting 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 two examples and bullet-point notes, making it easy to scan. It is lengthy but each section earns its place given the tool's complexity, though a brief output format note could improve efficiency.

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 thoroughly explains input construction and supported features, covering all parameters with real examples. However, since there is no output schema, a description of the response structure would enhance completeness; this omission prevents a 5.

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

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

Input schema descriptions cover 100% of parameters, so baseline is 3. The description adds value by showing how parameters combine in real examples, such as using searchIn, withClauses, and object-level properties together, which the schema alone does not convey clearly.

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 'Search across multiple Salesforce objects using SOSL (Salesforce Object Search Language)', which identifies the specific verb, resource, and method. It distinguishes from sibling tools like salesforce_query_records by specifying SOSL and 'across multiple objects', making its purpose 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 implies when to use this tool through its focus on SOSL cross-object search, providing clear context for selecting it over SOQL-based siblings. However, it does not explicitly state when not to use it or name alternative tools, so it falls 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?

The description adds behavior beyond the readOnlyHint annotation: it explains the fuzzy/pattern matching behavior with examples ('Account' finds AccountHistory). This gives the agent expectations about partial matches. There is no contradiction with the readOnlyHint, and the description appropriately discloses the search semantics, though it does not detail output format or case sensitivity—still acceptable given 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 only two sentences and front-loaded with the core purpose. The examples are concise and immediately demonstrate behavior. 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?

For a simple one-parameter search tool with no output schema, the description is fully sufficient. It states what the tool searches, how the pattern works, and provides representative examples. No additional context is needed for an agent to use 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?

The schema already describes searchPattern with 100% coverage, so the baseline is 3. The description adds valuable examples and clarifies the pattern-matching semantics (e.g., 'Order' finds WorkOrder, ServiceOrder__c), which goes beyond the schema's generic description. This earns a 4.

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

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

Description clearly states the verb 'Search' and resource 'Salesforce standard and custom objects' with a specific scope ('by name pattern'). It also distinguishes itself from sibling search tools like salesforce_search_all by focusing specifically on object metadata, and the examples reinforce this 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 indicates this is for finding objects by name pattern, which gives clear context for when to use it (e.g., before describing or querying an object) but does not explicitly state exclusions or alternatives. However, the examples and the tool's specificity provide enough implicit guidance; a brief note on when NOT to use it (e.g., for searching records) would be an improvement.

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

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

With no annotations provided, the description carries full burden. It discloses that 'Status information is returned after successful operations' and includes important behavioral constraints like 'The body must be valid Apex code' and 'The className in the body must match the className parameter.' However, it doesn't mention authentication requirements, error handling, or whether operations are reversible/destructive.

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

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

The description is well-structured with clear sections (purpose, examples, notes). Every sentence adds value, though the examples could be more concise. The purpose statement is front-loaded, and the notes section efficiently covers important constraints without redundancy.

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

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

For a write operation with no annotations and no output schema, the description provides adequate but incomplete context. It covers the main operations and constraints but lacks information about authentication, error responses, rate limits, or what 'Status information' specifically includes. Given the complexity of writing Apex code in Salesforce, more behavioral context would be helpful.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value through examples showing how parameters combine in different operations and clarifying that apiVersion is optional for create operations with a default. However, it doesn't significantly enhance understanding 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 states 'Create or update Apex classes in Salesforce' - a specific verb (create/update) with a specific resource (Apex classes) and platform (Salesforce). It distinguishes from siblings like salesforce_read_apex (read vs write) and salesforce_write_apex_trigger (classes vs triggers).

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

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

The description provides clear context through examples showing when to use create vs update operations. It doesn't explicitly state when NOT to use this tool or mention alternatives like salesforce_execute_anonymous for one-off code execution, but the examples provide practical guidance for the two main use cases.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a write/mutation tool ('Create or update'), specifies validation requirements (valid Apex code, parameter matching), mentions default behavior (apiVersion defaults to latest), and indicates what happens after operations (status information returned). It doesn't cover permissions, rate limits, or error handling, but provides substantial operational context.

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 and front-loaded with the core purpose, followed by practical examples and important notes. Every sentence serves a clear purpose: the opening statement defines the tool, examples demonstrate usage, and notes clarify constraints. There's no redundant or unnecessary content.

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 write/mutation tool with 5 parameters, 100% schema coverage, but no annotations or output schema, the description provides strong context. It covers the tool's purpose, usage patterns, parameter requirements, and behavioral expectations. The main gap is the lack of output details (only mentioning 'status information' without specifics), but given the complexity and schema richness, it's mostly 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 description coverage is 100%, so the schema already documents all parameters well. The description adds some value through examples showing parameter usage patterns and notes about required/optional fields for different operations, but doesn't provide significant semantic information beyond what's in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Create or update Apex triggers in Salesforce.' It specifies the exact action (create/update) and resource (Apex triggers), and distinguishes it from sibling tools like salesforce_write_apex (for general Apex code) and salesforce_read_apex_trigger (for reading triggers).

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

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

The description provides clear context for when to use this tool through examples and notes, explaining the required parameters for 'create' vs 'update' operations. However, it doesn't explicitly state when NOT to use it or mention alternatives like salesforce_write_apex for non-trigger Apex code, though the distinction is implied by the tool name.

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