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

Annotations already communicate readOnly=false, destructive=false, and idempotentHint=true. The description adds a critical behavioral trait: 'without removing existing values', which directly addresses what is preserved (i.e., nothing existing is destroyed). This adds value beyond the annotations and clarifies the operation's non-destructive nature.

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 short sentences, front-loaded with the action. The first sentence states the purpose and key constraint; the second provides the use case. Every word earns its place with no filler or repetition.

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

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

The tool has only 2 parameters with rich schema descriptions and an open-world annotation. No output schema exists, but the description adequately covers the operation scope and expected outcome. It does not mention error handling or permissions, but for an additive, non-destructive operation this seems sufficient. Minor gap: no mention that adding a duplicate value might fail, but not critical.

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%; all parameters (objectFieldFullName and values) have detailed descriptions in the schema, including the nested value properties (label, fullName, color, etc.). The tool description itself adds no extra parameter information, so baseline 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?

Description uses a specific verb ('Adds') and identifies the resource ('new picklist values to an existing Picklist or MultiselectPicklist field') with a key differentiator: 'without removing existing values'. This distinguishes it from potential update/replace operations and from sibling tools like sf_create_custom_field.

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

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

Provides explicit when-to-use guidance: 'Use when a user wants to add new options to a dropdown.' It does not name alternatives (e.g., for replacing values) but the 'without removing existing values' clause clarifies it is not for editing. This is clear context, though not an explicit exclusion list.

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 already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: what the response includes (statuses, component successes/failures, test results) and the 'recently completed' limitation, implying retention boundaries.

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, zero filler, front-loaded with the action and resource. Every word contributes meaning.

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 tool with no output schema, the description sufficiently explains the return payload, usage context, and relationship to sf_deploy_metadata. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% and the sole parameter deployId is well-described in the schema. The description reinforces the meaning but adds no additional 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 uses a specific verb ('Checks') and resource ('status of a metadata deployment') with the async job ID qualifier. It clearly distinguishes from siblings like sf_deploy_metadata (which performs the deployment) and sf_get_deployment_history (which lists past deployments).

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 states explicit usage context with 'in-progress or recently completed deployment' and 'Use with the deploy ID returned from sf_deploy_metadata.' This gives clear when-to-use guidance, though it does not explicitly contrast with alternative status/history tools.

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 annotations already indicate idempotency and non-read-only behavior. The description adds that it uses the Metadata API and can create or update, but doesn't disclose additional behavioral nuances like the irreversibility of activation (which is only in the schema). 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?

The description is two sentences long, with the action immediately stated. Every phrase adds value—the verb, resource, API method, and key configurable aspects—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?

With 14 parameters and no output schema, the description provides a useful overview of the tool's capabilities, while the rich schema and annotations cover the detailed semantics. It could mention return values or activation warnings, but these are either obvious from the create/update context or present in the 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 provides 100% detailed descriptions of all 14 parameters, so the description doesn't need to add much. It lists high-level categories (submitters, steps, approvers, entry criteria, actions) that map to parameters, but adds no new semantic detail.

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 specific verb 'Creates or updates' and names the resource 'Salesforce Approval Process' via 'Metadata API', clearly distinguishing it from sibling tools like sf_create_validation_rule or sf_create_workflow_rule.

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 identifies the tool's domain (approval processes) and the operation (create/update), making it obvious when to use it. However, it doesn't explicitly mention alternatives or exclusion conditions, 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the mutation safety profile. The description adds only the '__c' naming rule and 'existing object' scope, which are also present in the schema or purpose, so it contributes little new 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 two sentences, front-loaded with the core action, and avoids redundant detail already present in annotations or schema. It is appropriately succinct.

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

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

With 18 parameters, nested objects, and type-specific requirements, the description is far too sparse. It fails to warn that Picklist requires picklistValues, Lookup/MasterDetail requires referenceTo, or that Number fields need precision/scale. No output schema exists, so the description should help guide correct invocation; it does not.

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 repeats the '__c' suffix (already in fieldName's pattern) and lists field types (already in the type enum), adding no new meaning beyond the structured 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 creates a custom field on an existing Salesforce object, using a specific verb and resource. It distinguishes itself from sibling tools like sf_create_custom_object by focusing on fields, and the '__c' suffix constraint adds precision.

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 it is the general tool for creating custom fields ('Supports all field types') but does not explicitly mention when to use it versus specialized alternatives like sf_create_formula_field or sf_add_picklist_values. No exclusions or alternative references are provided.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and idempotent hint. The description adds that the operation uses the Metadata API and enforces the '__c' suffix rule, which are useful behavioral constraints not captured in 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?

Two sentences, front-loaded with the action, and no filler. The second sentence provides selection guidance and a naming constraint efficiently.

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 full schema coverage and annotations that clarify safety, the description provides sufficient context for selection and invocation. It clearly states what it creates and when to use it, though it doesn't describe return values or deployment behavior—acceptable given 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 fully documents all 13 parameters. The description's naming rule is already embedded in the fullName pattern, so it adds no additional semantic value beyond the schema.

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

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

Specifically identifies the action ('Creates') and resource ('Salesforce Custom Object'), and distinguishes from siblings like sf_create_external_object by specifying the custom object type. The phrase 'using the Metadata API' adds technical context.

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?

Gives an explicit trigger: 'Use this when a user asks to create a new object, entity, or table in Salesforce.' This clearly indicates when to select the tool, though it doesn't discuss exclusions or mention alternatives like external 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?

Annotations cover the safety profile (not read-only, not destructive, idempotent). The description adds valuable behavioral context beyond annotations, such as support for all return types, full formula language, cross-object references, and complex multi-line formulas. This helps the agent understand the tool's capabilities 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 front-loaded with the purpose and then expands on capabilities. The second sentence is long but packed with specific useful details (function list, feature support). It is appropriately sized for a tool with complex capabilities, though slightly verbose.

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, the description is fairly complete: it covers return types, formula language features, cross-object references, and multi-line support. It lacks explicit alternatives or prerequisites, but the rich schema and annotations fill in most gaps, making it adequately complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description adds context about supported formula functions and return types, but this largely overlaps with the schema's own parameter descriptions. It does not provide significant additional meaning beyond what the schema already covers.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Creates a formula field on any Salesforce object.' It distinguishes itself from siblings like sf_create_custom_field by explicitly focusing on formula fields and enumerating supported return types and formula language features.

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

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

The description implies usage context: this tool is for creating formula fields. However, it does not explicitly state when to use this over alternatives (e.g., sf_create_custom_field for non-formula fields) or provide exclusions. The context is implied but not spelled out.

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 valuable behavior beyond annotations: it reveals the tool is an upsert ('Creates or updates'), explains the key formula semantics (TRUE = invalid), and names the API method (Metadata API). Annotations already cover read-only/destructive/idempotent flags, so the description complements rather than repeats them.

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?

Three short sentences: the first states the action and scope, the second clarifies the core formula behavior, and the third gives the primary use case. No filler or repetition.

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

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

With a fully described schema and solid annotations, the description is adequately complete. It covers the main behavioral nuance (upsert and formula direction) and use case. It could optionally mention permissions or deployment impact, but the lack is not a glaring 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 description coverage is 100%, so the baseline is 3. The description mentions errorConditionFormula semantics, but this is essentially identical to the schema description and does not add extra parameter meaning.

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 action ('Creates or updates') and resource ('Salesforce Validation Rule') plus scope ('on any object via the Metadata API'). It clearly distinguishes from sibling tools by naming the metadata type and its use for data quality enforcement.

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?

'Use for data quality enforcement' provides clear context for when to invoke the tool, but it does not explicitly exclude alternatives or name sibling tools (e.g., workflow rules) for comparison. Thus it earns a 4 rather than 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?

Annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds that it creates an action and sets a field to a literal, formula, or null, providing contextual behavior. However, it does not disclose potential caveats like required permissions or metadata component creation, though annotations diminish the need for that.

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

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

The description is two concise sentences, front-loaded with the action verb, and every word adds value. No redundant or inflated 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?

Given the 8-parameter schema and good annotations, the description covers purpose, usage context, and value options. It does not explain return values (no output schema) or prerequisites, but this is acceptable for a straightforward create operation with detailed schema descriptions.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful grouping by stating that the field can be set to 'a literal value, formula result, or null', which directly maps to the parameters literalValue, formula, and nullValue. This enriches parameter understanding beyond the individual 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 action: 'Creates a Workflow Field Update action that can be referenced by Approval Processes, Workflow Rules, or Flows.' This is a specific verb+resource, and it also mentions the value-setting behavior (literal, formula, null). It does not explicitly differentiate from the sibling 'sf_create_field_update', but the mention of referencing contexts provides some distinction.

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 implies usage context by noting the action can be referenced by Approval Processes, Workflow Rules, or Flows, but it does not explicitly state when to use this tool versus alternatives like sf_create_field_update or sf_create_workflow_rule. The guidance is embedded but not explicit.

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

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

The description goes well beyond the annotation flags (readOnlyHint=false, destructiveHint=true, idempotentHint=true). It discloses that deletes are independent per fullName, that responses must be checked for partial failures, and that dependency-order requirements exist (e.g., deleting a Bot before its children, CustomField before CustomObject). This rich behavioral detail is not present in the annotations and is crucial for safe usage.

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 every sentence contributes value: it states the core operation, the motivation, the independent-delete behavior, and dependency warnings. It is front-loaded with the purpose and uses clear structure. While it could be slightly more compact, it is not verbose or redundant.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description is quite complete. It covers the operation, supported types, failure mode (check deleted/errors lists), and dependency constraints. It does not fully describe the response structure, but it references the key response fields, which is sufficient for an agent to infer the return format. Overall, it adequately prepares the agent for invoking 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 input schema already has 100% description coverage for both parameters. The tool description adds context beyond the schema by explaining how fullNames are processed independently and how metadataType interacts with dependency rules. It also provides concrete examples (delete CustomField before CustomObject) that enrich the semantic understanding of the parameters.

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: 'Permanently deletes one or more metadata components of a given type via the Metadata API's deleteMetadata call'. It names common metadata types and explicitly contrasts with sf_deploy_metadata, which only adds/updates, clearly distinguishing this delete-oriented tool from its 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 description provides clear context for when to use the tool: when metadata components need to be removed, especially those created previously by the MCP server, noting that sf_deploy_metadata does not support destructiveChanges. It also explains dependency-order prerequisites for certain types, giving practical usage guidance. It does not explicitly enumerate exclusions, but the alternatives are implied by the contrast with sf_deploy_metadata and sibling data-deletion tools.

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 already state readOnlyHint=false and idempotentHint=true, so the tool's mutating nature is known. The description adds valuable behavioral context: it 'Builds a package.xml and deployment zip in memory' and 'Polls until complete or timeout,' plus explains the checkOnly flag avoids changes. This goes beyond annotations without contradicting them.

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 consists of four focused sentences, each with a distinct purpose: core action, in-memory packaging, validation shortcut, and production test requirement plus polling. There is no fluff or redundant 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?

For a complex deploy tool with 7 parameters and no output schema, the description covers the main behaviors (deploy, validate-only, runTests, polling) and operational effects. It omits explicit return-value details and scenarios like combining 'components' with 'componentsXml', but the rich schema fills those gaps. It is reasonably 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics by highlighting 'runTests' as required for production and explaining checkOnly as a validation-only mode. It also references the packaging process that relates to components/componentsXml, but does not over-repeat schema details.

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 'Deploys a set of metadata components directly to the org using the Metadata API SOAP deploy operation,' using a specific verb and resource. It clearly distinguishes this from sibling tools like sf_retrieve_metadata and sf_check_deploy_status by naming the Metadata API deploy operation and the in-memory package.xml/zip construction.

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

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

It provides concrete usage guidance: 'Supports validate-only (checkOnly:true) for pre-deployment validation without making changes' and 'Specify runTests ... required for production.' It implies the primary use case is deploying metadata, but it does not explicitly mention alternatives or exclusions, such as when to prefer individual create tools or sf_check_deploy_status.

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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: it uses the REST Describe API, can return only fields with fieldsOnly, and includes a retry mechanism when waitForFields is used due to Salesforce-side schema cache lag. This is substantive context not available from 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 main description is concise and front-loaded, but the parameter explanations become somewhat lengthy, especially waitForFields. However, each sentence provides valuable context and none is redundant, so it remains well structured.

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

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

For a tool with no output schema, the description fully covers what the response contains, when to use it, and parameter-specific edge cases. It also explains the fieldsOnly and waitForFields behaviors, making the tool self-sufficient for an agent.

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

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

Although the input schema already covers all parameters (100%), the description adds meaningful context: fieldsOnly's performance rationale, waitForFields detailed explanation about Salesforce cache lag and retry behavior, and timeoutSeconds default/max. This goes beyond schema descriptions, though the schema itself also carries clear 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 'Retrieves schema metadata for a Salesforce object via the REST Describe API' and enumerates the specific data returned (fields, child relationships, record type info). This is a specific verb+resource that distinguishes it from sibling tools like sf_get_field_permissions or sf_query_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?

It explicitly advises when to use the tool: 'Call this before querying or creating records on an unfamiliar object, or when a user asks what fields exist on an object.' This provides clear contextual guidance and differentiates from alternatives without 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?

The description discloses a non-obvious side effect beyond the annotations: it searches unloaded toolsets and by default loads whichever toolsets contain matches so they become callable immediately. This adds meaningful behavioral context even though annotations already mark the tool as idempotent.

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 tight sentences plus concrete example queries. The key behavior is front-loaded, and every sentence earns its place without padding.

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 two-parameter discovery tool, the description covers purpose, when to use it, the auto-loading side effect, and query examples. It does not describe the return shape, but that is not critical for an agent to invoke the tool correctly, and the schema covers the parameters.

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%, and the description mostly restates what the schema already documents for 'query' and 'autoLoad'. The example queries add a little flavor but no substantially new meaning 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 names a specific verb ('searches') and a specific resource ('all 228 Salesforce tools by name'), and distinguishes itself by noting it includes tools in unloaded toolsets and auto-loads matching toolsets. This clearly differentiates it from siblings like sf_list_toolsets and sf_load_toolset.

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 gives explicit usage triggers: 'Use this whenever a tool you expect does not appear in the tool list, or when you do not know which toolset a capability lives in.' This is clear context, but it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Adds substantial behavior beyond the annotations: results grouped by type, custom-field record counts as the safety deciding factor, and the critical blindSpots caveat that an empty result means 'nothing found,' never 'safe to change.' The read-only sentence reinforces readOnlyHint=true rather than merely repeating it, and nothing contradicts the annotation set.

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 core purpose is front-loaded in the first sentence, and each subsequent segment (return behavior, param routing, when-to-run, blind spots) adds unique value. It is longer than average, but every sentence earns its place, and paragraph breaks keep it scannable rather than wall-of-text.

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

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

With no output schema present, the description carries the full burden of return semantics and covers it: referenced components grouped by type, custom-field record counts, and the blindSpots list. Nothing an agent needs to invoke it correctly or interpret results safely is missing, including the dual invocation modes derived from the param set.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns the extra point by spelling out the two mutually-exclusive invocation patterns with worked examples (CustomField + 'Account.Revenue__c', ApexClass + 'AccountService') and clarifying when componentId is the correct path. This relationship between parameters is not visible from reading the schema properties in isolation.

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?

Opens with a concrete, question-scoped statement — 'Answers what breaks if I change this?' — then names the resource ('any metadata component') with precise referential semantics. It is plainly distinct from the sibling create/deploy/retrieve/query tools, so an agent can select it correctly without opening the schema.

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?

Gives explicit when-to-use guidance: 'Run this BEFORE deleting or reshaping anything that holds data.' It lacks an explicit when-not-to-use clause or a named alternative, but no sibling competes for this impact-analysis job, so an exclusion statement would be redundant. The guidance is actionable and tied to a concrete workflow moment.

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 already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral context beyond that: partial and case-insensitive matching, ranking order (exact, prefix, substring), default limit, the objectType semantics including 'custom (only __c)', and the returned fields. These details meaningfully improve the agent's ability to predict results.

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 efficiently organized: purpose is front-loaded, usage guidance follows, then a compact parameter summary, then return and ranking behavior. Every sentence adds useful information, and the parameter list is short and directly relevant. No filler or redundancy.

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

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

For a tool with four optional parameters and no output schema, this description is complete. It covers all parameters, default behavior, ranking, returned fields, and the appropriate follow-up action. An agent has enough information to decide when to invoke it and what results to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining 'custom (only __c)', clarifying that omitting searchTerm lists every object, and summarizing the ranking behavior for searchTerm. This goes slightly beyond the structured schema descriptions without fully re-explaining what is already documented.

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: it finds Salesforce objects by partial name or label, positioning itself as the discovery step before sf_describe_object. This distinguishes it from the sibling describe tool, which requires an exact API name. The discovery purpose is explicit and cannot be confused with querying records or modifying 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 gives explicit when-to-use guidance: whenever the user refers to objects loosely rather than by exact API name. It also names the alternative, sf_describe_object, and specifies the follow-up condition—call it once you have an exact name. This is strong routing guidance with a clear exclusion and next step.

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 already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: the server keeps most of its 228 tools unloaded to save context, and unloaded tools are invisible until their toolset is loaded. This explains a non-obvious tool-listing behavior agents need to understand.

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

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

The description is compact and front-loaded: it states the primary function first, then adds necessary context about unloaded tools and a usage trigger. Each sentence contributes a distinct piece of information 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 zero-parameter listing tool, the description is fully sufficient. It specifies what is listed, why some tools are not visible, and when to call it. The output schema is absent, but the description already enumerates the returned information: toolset names, tool counts, and load state.

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

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

The tool takes zero parameters, so the schema is fully covered and parameter semantics are moot. Per the calibration baseline, a zero-parameter tool receives a 4, and the description correctly focuses on behavior and output rather than inventing parameter detail.

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: 'Lists every available Salesforce toolset,' and adds what is returned: tool counts and current loaded state. It also distinguishes itself from sibling sf_load_toolset by explaining that unloaded tools do not appear in the tool list until the toolset is loaded.

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

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

The description gives a clear trigger for use: 'Call this when you need a capability you cannot see.' It also explains the context of unloaded toolsets and directs the agent toward loading via sf_load_toolset, but it does not explicitly state when not to use this tool or compare it directly to sibling tools like sf_find_tool.

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 already establish idempotent, non-destructive, non-read-only behavior. The description adds the state-changing effect: tools become callable and visible in the tool list, and it enumerates all valid toolset names. No contradiction with 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 core behavior is in the first sentence, followed by a closed list and a sibling pointer. The toolset list is long, but it is the only required parameter value set and compensates for the lack of enums in the schema. Slight redundancy with the schema prevents a 5.

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 one required array parameter, the description plus schema covers valid values and the effect of loading. It references the natural alternative for more detail. It does not describe the tool's return or confirmation message, and since no output schema exists, that is a minor omission.

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%; the schema already describes 'toolsets' as 'Toolset names to load' and lists valid values. The description repeats the values but does not add new semantic details such as aliases, ordering, or load behavior.

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

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

States a specific action ('Loads') on a concrete resource ('Salesforce toolsets') and defines the observable effect ('making their tools callable and visible in the tool list'). It also distinguishes itself from sf_list_toolsets by pointing to that sibling for descriptions and tool counts.

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 the trigger: load before using tools from a listed toolset. It gives an explicit alternative for when the agent only needs metadata ('Call sf_list_toolsets for descriptions and tool counts'). It does not spell out when-not-to-use or whether loading is additive, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by explaining aggregate query support and the resulting field-key format (e.g., 'expr0'), which goes beyond 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 concise and front-loaded, with a direct first sentence followed by a concrete aggregate query example. Every sentence earns its place; no redundant or vague 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?

The description covers the core functionality and the special case of aggregate queries, including return format. It does not explain pagination or error behavior, but the schema covers the limit parameter, and the annotations cover safety. Adequate 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?

Schema coverage is 100%, so both parameters have descriptions. The description enhances this with a full SOQL example and explains aggregate result mapping, adding meaning beyond what the schema provides.

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

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

The description clearly states the tool executes a SOQL query against the org and returns matching records, using a specific verb and resource. It distinguishes from sibling tools like sf_get_record and sf_search_records by emphasizing raw SOQL flexibility.

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 lists use cases: reading data, checking existing records before creating, and verifying changes. This gives clear context, but it does not mention alternatives or when not to use this tool, so it stops short of a full 5.

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

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

The description reveals significant runtime behavior beyond annotations: it 'waits for the async retrieve to finish,' 'unpacks the resulting zip,' returns 'each file's path and source,' truncates large files, and requires exactly one parameter form. None of these details are present in the annotations, so they add real value. There is no contradiction with the readOnly/idempotent hints.

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 packs purpose, usage scenarios, async behavior, return format, truncation, and parameter-form constraints into four sentences with no filler. Information is front-loaded with the core action, 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?

Given there is no output schema, the description adequately covers invocation forms, async behavior, return shape, and the truncation edge case. It does not mention error conditions or permission requirements, but the annotations already cover the safety profile for a read-only, non-destructive tool, so the missing details are minor.

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 describes each parameter, the description adds crucial relational semantics: the equivalence of 'metadataType'+'componentName' as a shortcut, the packageXml alternative that overrides components, and the 'exactly one form' constraint. These usage rules are not evident from the schema alone and prevent invalid 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 states a specific verb and resource: 'Retrieves metadata components from the org and returns their actual file contents.' It also distinguishes itself from sibling create/deploy tools by emphasizing 'actual file contents' and checking 'what is really deployed rather than what you think is deployed.' This makes the tool's role clear without needing to open any schema.

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 lists use cases: read existing configuration before making changes, back up metadata, or verify actual deployed state. It does not explicitly name alternative tools or state when-not-to-use, but the contrast with create/deploy siblings and the read-only framing make the appropriate context clear.

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