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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the org-wide scope ('from the org'); it says nothing about log size, truncation, or return format, so it adds limited value 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?

A single tight sentence with the two operating modes front-loaded and no filler. Nothing is wasted, though it is arguably too terse for a tool whose sibling overlap and return semantics need clarification.

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-only tool with annotations covering safety and a schema documenting each nested field, the description is minimally adequate. It leaves the return value shape (log content vs metadata) and the relationship to the sibling apex_log_list unexplained, which matters because no output schema exists.

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 description conveys that either a specific log or a count of recent logs can be requested, which maps onto logId vs recentLogsNumber. But the schema's nested properties already carry the real parameter documentation (including the pointer to apex_get_logs for IDs and the targetOrg default behavior), so the description adds little beyond it.

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

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

States a specific verb (Fetch) and resource (log) and clarifies the two modes: a specific log by ID or the N most recent logs. However it does not differentiate itself from the sibling apex_log_list, which appears to serve a similar listing purpose, so an agent cannot tell the two apart from the description alone.

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

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

No when-to-use guidance is given. There is no mention of how this differs from apex_log_list, nor any prerequisite or context such as needing a log ID first (that hint lives only in the schema's logId description). The agent must infer usage entirely.

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, destructiveHint=false and openWorldHint=true, so safety and idempotency are covered. The description adds only that log IDs are returned; it says nothing about pagination, result limits, or how the default-org fallback affects scope.

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

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

A single compact sentence with the action front-loaded. The trailing clause about IDs is slightly redundant but still informative and wastes little space.

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 list tool with no output schema this is close to adequate, but it omits pagination/limits and any hint about the default-org behavior that the schema only partially documents.

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?

There is one parameter (targetOrg) with schema-level description coverage reported at 0%, and the description adds no information about it at all. Baseline for one undocumented parameter is low, and nothing here compensates.

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

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

States a specific verb and resource: fetches the list of Apex debug logs, and notes the return includes IDs. It implicitly contrasts with the singular sibling apex_get_log, but never names it, so the differentiation is left to inference.

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 word 'list' implies bulk retrieval as opposed to getting one log, which is enough to separate it from apex_get_log in practice. However, there is no explicit when-to-use, no mention of prerequisites (debug logging must be enabled), and no stated alternative.

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 declare destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered by structured data. The description adds useful domain context about CLI username aliases vs the User Alias field, which is not in annotations. However, it doesn't state that the operation requires specific permissions, nor mention the destructive/non-idempotent nature explicitly.

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 assignment sentence is front-loaded, which is good, but the remaining sentences are dense and somewhat repetitive about alias vs Alias field and array syntax, adding length without proportionate clarity.

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 destructive, non-idempotent mutation tool with no output schema and 0% schema coverage, the description omits prerequisites (permissions needed, org authentication), irreversibility, and what happens on partial failure. The alias-domain detail is present, but the risk-relevant information is 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 coverage is 0%, so the description must compensate. It does explain that permissionSetNames accepts multiple names and that onBehalfOf accepts multiple users with the same syntax, plus alias-vs-Alias-field guidance. But it does not explain targetOrg semantics beyond the schema's own description, and the array element syntax guidance is partial – much of the parameter meaning still rests on the schema.

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

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

States a clear verb+resource: 'Assign a permission set to one or more org users.' The sibling assign_permission_set_license is not mentioned, so it lacks explicit differentiation, but the purpose itself is unambiguous.

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

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

No guidance on when to use this tool versus assign_permission_set_license or other permission-related siblings. The description explains CLI alias syntax mechanics but never says when this tool is the right choice.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral caveat (use the CLI username alias, not the User object's Alias field) but says nothing about required permissions, re-assignment behavior, or reversibility.

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

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

The purpose is front-loaded in the first sentence, and every subsequent sentence carries syntax detail. Slight verbosity and mild redundancy in the closing sentence about onBehalfOf, but nothing that fails to earn its place.

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

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

For a destructive, non-idempotent mutation with nested parameters and no output schema, the description covers the input syntax well but omits operational context such as permission requirements and what happens when a license is already assigned. Adequate but with clear gaps.

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?

Top-level schema description coverage is 0% for the sole 'input' wrapper, and the description compensates with real added meaning: alias semantics for targetOrg/onBehalfOf, repeated-array syntax for licenseNames, and quoting rules for names containing spaces. It goes beyond what the nested property descriptions convey.

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

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

States a specific verb and resource ('Assign a permission set license') plus scope ('one or more org users'). It is clear what the tool does, but it never distinguishes itself from the sibling assign_permission_set, which is a subtly different operation an agent could easily confuse with this one.

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?

There is no guidance on when to use this tool versus assign_permission_set or any alternative, and no prerequisites or when-not conditions are given. The only usage-flavored text concerns alias and array syntax, which is parameter mechanics rather than tool selection.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful beyond-annotation context: the effect on subsequent tool invocations requiring explicit targetOrg. It doesn't state whether the prior default is recoverable, which would round it out.

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, front-loaded with the action and followed immediately by the consequence; no filler.

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

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

For a no-argument mutation whose safety profile is carried by annotations and which returns no structured output, the description supplies everything an agent needs, including the cross-tool impact.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to clarify on the input side.

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?

Specific verb (clear) plus resource (default target org in Salesforce CLI config), clearly distinguishing it from siblings set_default_org and get_default_org. An agent can pick this correctly without opening a 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 downstream consequence ('all tools will require an explicit targetOrg parameter until a new default is set') gives clear operational context for when this is appropriate, but it never names the alternative (set_default_org) or an explicit when-not condition.

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 destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that it returns the created record ID on success and that it operates over REST. It does not disclose failure modes, required permissions, or how invalid recordJson is handled, so it adds only modest value over the annotations.

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

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

Two sentences, front-loaded with the core action and return value. The third element (enumerating input keys) is mildly redundant with the schema but still short. No wasted prose overall.

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 mutation tool with no output schema, the description correctly notes the ID is returned. However, it omits permissions/auth requirements and error behavior, and no output schema exists to cover return semantics. Adequate but with visible gaps.

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 description restates the parameter keys (sObject, recordJson, targetOrg) already documented in the nested schema. Because the nested properties carry rich descriptions (field API names, default org behavior, sobject_list/sobject_describe hints), the description's summary is largely redundant rather than additive. Baseline 3 is appropriate.

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

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

States a specific verb+resource (create a new record in a Salesforce org) plus the implementation (REST API) and the success return value (the created record's ID). The create action is inherently distinguishable from siblings like update_record and delete_record by name, though the description never explicitly contrasts them.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives. It never says when to call this versus update_record/query_records, or that a target org must be authenticated. The only procedural hints (run sobject_list/sobject_describe first) live in the schema, not the description.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description reinforces this with 'Permanently removes the specified record,' clarifying irreversibility, but adds no permission requirements, error behavior, or confirmation semantics beyond what the annotations imply.

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 sentences, front-loaded with purpose and the destruction warning, then parameter shape. The final parameter enumeration is slightly redundant with the schema but earns its place given the nested structure and low reported coverage.

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 destructive mutation with full annotation coverage and no output schema, the description covers purpose, irreversibility, and parameter shape. It stops short of permissions requirements or behavior when the record ID is invalid/missing, which would matter for a permanent delete.

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 description enumerates the nested keys (sObject, recordId, optionally targetOrg) and flags which are required, which is valuable given the nested object and the reported 0% schema description coverage at the top level. It does not restate the format hints (15/18-char ID, API name examples) that the nested 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?

States a specific verb (delete) and resource (Salesforce record) plus the mechanism (REST API). The destructive verb inherently separates it from siblings create_record and update_record, so an agent can route correctly without opening a 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?

No when-to-use, when-not-to-use, or alternative guidance is given. It never mentions update_record or create_record as alternatives, nor any precondition such as confirming the record exists first. Usage must be entirely inferred from the verb.

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 destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation/safety profile is conveyed structurally. The description adds essentially nothing beyond that - no note that deployment is long-running, async, returns a deploy id, or modifies the target org's live metadata.

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?

One compact sentence with no filler and the core action front-loaded. It is appropriately sized, though its brevity contributes to the gaps noted elsewhere rather than being a stylistic flaw.

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 destructive, open-world, non-idempotent deploy operation with no output schema, the description omits essential context: authentication/default-org requirement, asynchronous/long-running behavior, and what happens to existing org metadata. An agent could invoke it but with meaningful blind spots.

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

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

The single top-level parameter is a nested object whose inner properties carry their own detailed schema descriptions (tests, dryRun, manifest, testLevel, sourceDirectory, etc.). The description only alludes to 'test execution options' and adds no semantics of its own, so it neither compensates for nor enhances the schema - baseline 3 for a rich nested 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 gives a specific verb (Deploy) and resource (metadata to a Salesforce org), which is clear at a glance. It does not distinguish itself from adjacent siblings such as package_install or run_apex_tests, so it stops short of a 5.

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?

There is no guidance on when to use this versus alternatives like package_install, run_apex_tests, or execute_anonymous_apex, and no prerequisites (e.g., needing an authenticated/default org) are stated. 'With test execution options' hints at the testLevel/tests parameters but not when to pick them.

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/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful behavior: which fields are returned and that username/org ID/URLs are masked for privacy. However, the final alias sentence is muddled ('...of the new user'), which undermines clarity rather than adding it.

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 first two sentences are well front-loaded and earn their place. The trailing sentence about the alias is long, tangential, and confusing, weakening an otherwise efficient description.

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-only tool with no output schema, describing the returned fields and masking is the right move. But the definition omits any auth/org-context behavior (what happens when no targetOrg is given is only in the schema) and the alias note confuses rather than completes the picture.

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 description never mentions targetOrg, so it adds nothing about the single parameter's semantics; the schema's nested targetOrg description (fallback to SF CLI default) does carry that meaning. Reported description coverage is low, but the schema does document the param, so this is a baseline 3 rather than a full 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?

States a specific verb+resource: 'Display information about a Salesforce user.' An agent can distinguish this from list_connected_salesforce_orgs or get_default_org. It stops short of naming when this is preferred over those siblings, but the resource is unambiguous.

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

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

No explicit when-to-use guidance and no alternatives named, despite many sibling org/user tools (get_default_org, list_connected_salesforce_orgs, sobject_describe). The reader must infer the context from the description alone.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the JSON return format and the availability of debug logs, which is genuinely useful since there is no output schema, but it never cautions that arbitrary Apex can mutate Org data.

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?

Four sentences that repeat the core idea ('Execute Apex code' then 'allows you to run Apex code directly') and close with vague filler about 'other Apex-related tasks.' Front-loading is decent but the padding dilutes it.

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

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

For an arbitrary-code-execution tool with no output schema but strong destructive annotations, the description covers return format and debug logging but omits any caution about irreversible Org mutations and says nothing about the parameters. Adequate but with clear gaps.

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 description never mentions the code or targetOrg parameters in text, and reports 0% schema description coverage, so the description does not compensate for the gap. 'Against a specified Salesforce Org' only faintly hints at targetOrg, while the required code argument is not addressed at all.

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

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

States a specific verb and resource ('Execute Apex code in a Salesforce Org') and clarifies that execution happens in the target Org context. It is clear on its own but never differentiates itself from the closely related sibling run_apex_tests, which an agent must choose between.

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?

Offers implied usage contexts ('test Apex code snippets, run batch jobs, or perform other Apex-related tasks') but gives no when-not guidance and never names an alternative tool for those cases. The agent is left to infer that this is for ad-hoc/anonymous scripts rather than tests.

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 destructiveHint=true and openWorldHint=true, so the agent knows this is a writing, non-idempotent operation. The description adds the directory-placement constraint but never says whether an existing class file of the same name is overwritten — the single most important behavioral fact for a destructive generator.

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?

Purpose is front-loaded in one clean sentence, which is good. But the follow-up is garbled ('Either run this command existing directory of this name'), wasting space on awkward and partly unparseable instructions.

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 destructive, open-world generator with no output schema and effectively undocumented nested parameters, the description omits overwrite semantics, success/failure reporting, and reliable parameter naming. What an agent needs in order to call this safely is not 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 coverage is reported at 0% for a nested input object, so the description must compensate. Instead it introduces a CLI-style '--output-dir' flag name that does not match the schema's 'outputDir', and says nothing about the 40-character/letter-start rule for the required name.

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

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

States a specific verb+resource: generates the Apex *.cls file plus its metadata file. That distinguishes it from generate_component and generate_trigger by artifact type, though the description never names those siblings to route the agent explicitly.

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 only guidance is about file placement (files 'must' live in a parent 'classes' directory, or use the flag to create/point to one). There is no when-to-use statement, no prerequisites, and no comparison against alternative generators.

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 destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. However, the description adds nothing beyond that: it does not say whether existing files are overwritten, what files are created, or that it writes to the local filesystem — important for a destructive, non-idempotent generator.

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

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

A single efficient sentence with no filler, front-loading the verb and resource. It is appropriately sized, though it is perhaps too terse for the scope of what the tool does.

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 destructive, non-idempotent file-generating tool with no output schema, the description omits overwrite behavior, what artifacts are produced, and any prerequisites. Annotations cover the safety flags but leave these operational questions unanswered.

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 nested schema actually documents all four sub-parameters in detail (name length limits, type values aura/lwc, template values, outputDirectory semantics), despite the reported 0% coverage metric. The description adds no parameter-level meaning, so the schema carries the burden and 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?

States a specific verb (Generate) and resource (Lightning Web Components / Aura components) with scope modifiers (templates, output directories). It is distinguishable from siblings like generate_class and generate_trigger, though the shared 'generate_*' family pattern is not explicitly contrasted.

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

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

No guidance on when to choose this over generate_class, generate_trigger, or schema_generate_tab, and no prerequisites (e.g., whether a default org or login is required) are stated. The agent must infer usage entirely from the name.

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 declare destructiveHint=true and idempotentHint=false, yet the description never addresses whether existing files are overwritten or how conflicts are handled — the single most important behavior for a generator with those hints. It explains file placement but not the destructive/irreversible implications.

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?

Four sentences, each earning its place about file location, defaults, and placeholder behavior. Front-loaded with the generation action and reasonably free of 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 file-generating tool with no output schema and nested params, the description covers location and default behavior but omits overwrite semantics, return value, and the mismatch around the nonexistent --event flag. Annotations already flag destructiveness but the description should confirm it.

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 reported at 0% for the top-level 'input' object, so the description must carry meaning, and it does map '--output-dir' to outputDir and '--sobject' to sObjectName. But it references a '--event' flag with a 'before insert' default that does not exist as a parameter in the schema, which is misleading.

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

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

States a specific verb and resource: 'Generates the Apex trigger *.trigger file and associated metadata file.' It's clearly distinguishable in content from a generic action, but it never differentiates itself from the closely related siblings generate_class and generate_component, all of which produce source files.

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 contextual instructions about where files must live ('a parent directory called triggers') and how to use --output-dir, which is genuinely useful usage guidance. However, it offers no when-to-use/when-not guidance relative to generate_class/generate_component and no prerequisites such as org auth.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the from-tests/org-wide distinction and the conditional requirement of a test run ID, but says nothing about output shape, latency, or org permissions.

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 compact sentences, front-loaded with the core action, then the two modes, then the motivating use case. No filler, though the third sentence is optional context.

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-only query tool with well-documented nested params and annotations covering safety, the description is nearly sufficient; the absence of an output schema means return values need not be spelled out. Only the lack of routing guidance against sibling tools leaves a small 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?

Top-level coverage is 0% because the schema wraps everything in a nested 'input' object, but the nested properties themselves carry full descriptions (targetOrg default behavior, testRunId requirement, coverageType enum). The description reinforces the two coverage modes but adds no syntax or format detail beyond the nested schema.

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

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

States a specific verb and resource ('get code coverage information for a Salesforce Org') and distinguishes its two modes (org-wide percentage vs. coverage from a specific test run). It doesn't explicitly differentiate from siblings like get_apex_test_results, but the purpose is unambiguous.

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

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

Gives a context for use ('monitor and ensure your code meets the 75% coverage requirement') but does not say when to prefer this over adjacent tools such as get_apex_test_results or run_apex_tests, nor any exclusion conditions.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description adds useful content about what is retrieved (pass/fail status, error messages, stack traces, optional coverage). It omits the polling nuance implied by idempotentHint=false — that an async run may still be in progress and results may be incomplete.

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, with the core action front-loaded and the returned payload enumerated second. Nothing needs trimming.

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 an output schema present, the description need not detail return values, and it covers the async-retrieval workflow adequately. The one gap is the targetOrg behavior (default-org fallback), which is only discoverable from 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 description matches the schema's testRunId and codeCoverage semantics without adding syntax or format detail beyond them, and it never mentions the targetOrg selector, which the schema documents. With the schema carrying the parameter burden, this is baseline-level.

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

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

States a specific verb (Retrieve) and resource (results from a previous asynchronous Apex test run), with the scope narrowed to an existing run rather than starting one. This cleanly separates it from sibling run_apex_tests and from get_apex_code_coverage.

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 this command with a test run ID" states the prerequisite (a previously executed async run) and what the ID is for. It does not explicitly name an alternative tool or a when-not condition, so it stops short of full routing 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false. Beyond that, the description discloses non-obvious output behavior: only the alias is returned, a username-less org yields a masked username plus an alias hint, and usernames, org IDs and instance URLs are never returned. This is exactly the kind of detail annotations cannot convey.

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 tight sentences, front-loaded with the core action, then the return-value contract. No filler or redundancy; each sentence adds a distinct fact.

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

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

With no output schema, the description must define the return value, and it does so precisely (alias, or masked username plus hint, with explicit exclusions). For a zero-parameter read tool with full annotation coverage, nothing an agent needs is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to add on parameter semantics, and it correctly does not invent any.

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

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

States a specific verb and resource ('Get the current default target org configured in the Salesforce CLI') with clear scope. The read-only framing implicitly separates it from set_default_org and clear_default_org, but no sibling is named explicitly, so sibling differentiation is left to inference.

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 notes the alias 'is used as the default when no targetOrg is specified in other tool calls', which implies the context in which this lookup matters. It gives no explicit when-not guidance and never points to alternatives such as set_default_org, clear_default_org, or list_connected_salesforce_orgs.

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, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no mention of auth requirements, whether the read is org-scoped, or what the permission settings actually represent. With annotations doing all the work, the description contributes no extra 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?

A single short sentence with no filler; appropriately sized for a no-argument read tool. It is front-loaded with the verb, though it is too terse to carry much structure.

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 read operation the description is minimally viable, but there is no output schema, so the agent gets no signal about what the returned permission settings look like or in what scope they apply. That gap is small but real.

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?

Zero parameters, so there is nothing for the description to clarify beyond what the empty schema already implies. Baseline of 4 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?

States a verb and resource ("Get current server permission settings"), so the agent knows it's a read of permission configuration. However, "server permission settings" is vague — it doesn't say which server, which scope of permissions, or how it differs from permission-related siblings like assign_permission_set or list_metadata. The purpose is identifiable but not sharp.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling tools. The agent must infer from the name alone whether this is the right tool for inspecting permissions versus assigning them.

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, destructiveHint=false, and the description is consistent with them (it writes a file and persists). It adds useful context beyond the annotations: the precise file path written and cross-session persistence, though it omits what happens on failure or whether the write is project-scoped vs global.

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 action and destination are front-loaded in the first sentence, followed by rationale and persistence. Four sentences are close to ideal; the benefit list is slightly padded but each sentence contributes 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 single-parameter install tool with annotations covering the safety profile and no output schema, the description gives enough to call it correctly: what it writes, where, and that it persists. Only the return/failure semantics are left implicit, 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?

There is effectively one parameter (force), which the input schema documents clearly, but the description never mentions it or the overwrite/skip behavior. Per the baseline rule, when the schema carries the parameter documentation the description need not repeat it, so a 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?

States a specific verb+resource (install the Salesforce MCP Server skill) and pins down the exact destination (.claude/skills/salesforce/SKILL.md), so the action is unambiguous. It does not explicitly distinguish itself from superficially similar siblings like package_install, but the Claude Code skill framing makes the intent clear.

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 conveys the benefit (domain guidance for the 40 tools, 5 prompts, 5 resources) and persistence, implying this is a one-time setup step for a project. However, it never states when an agent should call it versus alternatives, nor any prerequisite such as being in the right project directory.

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, destructiveHint=false and openWorldHint=true, so the safe read-only profile is covered. The description adds nothing beyond 'with details' – no note on how rule discovery scopes to workspace vs config file, or on result volume/pagination.

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 with the purpose front-loaded and the downstream use immediately after. Nothing is wasted and there is no filler.

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

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

For a read-only listing tool, the essentials are present, but with a nested schema and no output schema the description never explains that the returned rules are the input vocabulary for run_code_analyzer, leaving the selection mechanism (selector, view, target) implicit.

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 description gives no guidance on the five nested inputs (view, target, workspace, configFile, ruleSelector) and reports 0% schema description coverage at the top level, so it does not compensate. Although the nested schema properties do carry their own descriptions, the tool-level description adds no parameter meaning of its own.

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

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

States a specific verb+resource: 'List available code analysis rules with details.' It also implicitly separates itself from the sibling run_code_analyzer by naming that tool's run command as the downstream consumer, though it never names the sibling explicitly by tool name.

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 to determine rules for code-analyzer run command' gives a clear triggering context, tying discovery to a subsequent analysis run. It stops short of stating when NOT to use it or naming alternatives by tool name, so it falls just below the top bar.

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 read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds non-obvious value by disclosing that usernames, org IDs, and instance URLs are masked for privacy, and that orgs should be referenced by alias when passed to targetOrg elsewhere.

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?

Four sentences, front-loaded with the core action, and the privacy/alias caveat is well-placed at the end. The first two sentences restate the same idea slightly, costing a bit of tightness.

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 an output schema present and no parameters, the description need not explain return values; instead it supplies the one thing the schema cannot - the masking caveat and alias convention. Nothing an agent needs to call and use this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required and instead guides how the output identifiers should be used downstream.

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

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

States a specific verb and resource ('List connected Salesforce Orgs') and clarifies the scope as Orgs connected to the Salesforce CLI. It is clearly distinguishable from write/mutation siblings, though it does not explicitly name related read tools like get_default_org.

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 this command to see which Salesforce Orgs you have access to and can interact with' gives an implied usage context, but there are no when-not conditions, prerequisites, or named alternatives among the many sibling org tools. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the required org permission ('Modify All Data or Modify Metadata Through Metadata API Functions') is exactly the kind of auth detail annotations cannot convey.

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 sentences, front-loaded with the core action, followed by usage context and then the permission caveat. No filler and each sentence carries distinct 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 read-only listing tool with full annotation coverage and no output schema, the description supplies the purpose, workflow, and auth prerequisite. The only real gap is that it does not clarify the non-metadataType parameters, but that is comparatively 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?

Schema description coverage is reported at 0%, so the description must compensate. It adds meaning for metadataType by naming example values (CustomObject, Layout) but says nothing about folder, targetOrg, apiVersion, or outputFile, leaving most of the nested input object unexplained.

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

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

States a specific verb and resource: 'List the metadata components and properties of a specified type.' It distinguishes itself implicitly from the sibling list_metadata_types (which returns types, not components of a type), though it never names that sibling explicitly.

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 clear usage context: identify components in a manifest or get a high-level view of a metadata type, and describes the follow-on workflow ('then use this information in a retrieve command that returns a subset of these components'). No explicit exclusions or alternative tool named, 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?

Annotations already cover safety (readOnlyHint, idempotent, non-destructive, open world). The description adds genuinely useful context beyond them: the required Modify All Data / Modify Metadata Through Metadata API Functions permission and that output can be directed to a file for manifest extraction.

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 front-loaded sentences that each carry information; only minor filler ('and many other metadata types'). Permission requirement is placed last, which is sensible.

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-only listing tool with no output schema and only one (nested) input object, the description covers purpose, use case, and auth prerequisites adequately. A note on the return shape would be a minor improvement.

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 description adds no meaning about targetOrg, apiVersion, or outputFile; that role is left to the schema's own sub-property descriptions. With the stated 0% coverage metric, the description does not compensate, so it sits at the baseline.

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

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

States a specific verb+resource: displaying details about metadata types enabled for the org, and enumerates examples (Apex classes, custom objects, tab sets). It is distinguishable from the sibling list_metadata, though the distinction is implied rather than explicit.

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 a clear use case: identifying the syntax needed for a <name> element in a package.xml manifest. It also states the required permission level. It does not, however, explicitly contrast this tool with list_metadata or note exclusions.

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 flag destructiveHint=true, openWorldHint=true, and non-idempotent, and the description adds real context: a browser window opens for OAuth and credentials are persisted locally by the CLI. That interactive/persistent side effect is valuable and not derivable from the annotations alone, though auth prerequisites and failure behavior remain unstated.

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?

Purpose, flow, and parameter guidance are front-loaded and readable. The trailing IMPORTANT sentence largely restates the required-parameter fact already implied earlier, which is mild 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?

There is no output schema, so the description must carry the return/behavior burden, and it explains the interactive flow and local credential storage. Given the browser-based, stateful nature of the tool, more detail on timing/timeout or what happens on failure would help, but the essentials are present.

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 reported at 0%, so the description must compensate, and it does explain alias semantics (shorthand for subsequent commands) and isProduction semantics (login.salesforce.com vs test.salesforce.com). It does not address the nested 'input' wrapper object, so it is not fully complete.

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

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

The description opens with a specific verb+resource (authenticate and login to a Salesforce org) and clarifies the mechanism (via web browser / OAuth). This clearly distinguishes it from siblings like logout, list_connected_salesforce_orgs, and set_default_org.

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 selection criteria for the isProduction flag (production/developer vs sandbox/scratch), which is genuine when-to-use guidance. However, it never names sibling alternatives (e.g., list_connected_salesforce_orgs, set_default_org) or when NOT to invoke this 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the --no-prompt flag behavior and the irreversibility warning for scratch orgs whose passwords are unavailable. It does not describe the response, but for a logout that is minor.

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?

Four sentences, each earning its place: purpose, parameter routing, execution behavior, and the critical irreversibility warning. The warning is placed last where it lands hardest, and nothing is 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?

For a nested-object tool with no output schema, the description covers purpose, parameter semantics, execution behavior (--no-prompt) and the key destructive consequence. Return value is undocumented, which is a small gap for a tool whose result is essentially success/failure.

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?

With schema description coverage reported at 0%, the description must carry the parameter burden, and it does: it explains the meaning and interaction of targetOrg and all, including that omitting both causes failure. The nested-object shape is not elaborated further, keeping it below a 5.

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

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

States a specific verb and resource ('Log out of a Salesforce org') that cleanly distinguishes it from the sibling login_into_org. An agent immediately knows the operation 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?

Explicitly routes the agent between the two modes: 'Use targetOrg to logout of a specific org, or set all to true to logout of all orgs.' It covers the failure condition when neither is set. It lacks an explicit statement of when not to use the tool (e.g. vs. clear_default_org), 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds behavior annotations do not capture: that this launches a client-side browser, that path values are appended to the org domain, and that sourceFile routes into a metadata-specific Builder rather than a generic page.

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 sentences, front-loaded with the core action, and each sentence adds a distinct mode or constraint. No filler or restatement of the tool name.

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

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

With no output schema, the description still conveys the observable outcome (a browser opens the org or a Builder). It covers the two primary invocation paths adequately; the only gap is that it does not clarify the return payload or whether the call blocks until the browser launches.

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 signal is 0% at the top level, so the description carries real weight — it explains the expected shape of path (the portion after 'https://mydomain.my.salesforce.com') and constrains sourceFile to ApexPage, FlexiPage, Flow, or Agent metadata. The remaining parameters (browser, targetOrg, privateMode, forceSystemBrowser) are only documented inside the schema, not the description.

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

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

The description states a specific verb and resource — opening a Salesforce org in a browser — and extends it to two concrete modes (a URL path, or a local metadata file in its Builder). It is clearly not a CRUD tool, but it never explicitly distinguishes itself from the sibling open_record, which an agent must infer.

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 conditional usage for the two main modes ('To open a specific page, specify...', 'Use sourceFile to open...'), which is genuinely helpful routing. However, there is no statement of when NOT to use it, no mention of open_record as the alternative for record pages, and no prerequisites (e.g., an authenticated/default org) beyond what the schema implies.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the one behavior not in annotations (that it triggers a browser launch), but says nothing about whether it returns a URL, blocks, or errors when no org is authenticated.

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

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

A single short sentence, front-loaded with the verb and resource, with no padding. It is arguably too terse for a tool with side effects, but nothing is wasted.

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 annotations covering safety and no output schema to reconcile, the definition is minimally adequate for a browser-launch tool. It still omits what the caller gets back and how it behaves against a default vs explicit org, which matters given the targetOrg parameter.

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 reported top-level coverage is 0% (the wrapper 'input' object is undescribed), but the nested schema actually documents recordId, targetOrg defaulting behavior, and forceSystemBrowser in detail, so the structured data carries the semantics. The description itself adds no parameter information at all, so it earns only the baseline.

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

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

The description gives a specific verb (opens) and resource (a Salesforce record) plus the mechanism (in a browser), which is enough for an agent to know what happens. However, it does nothing to distinguish itself from the sibling tool named 'open', so a sibling-aware agent gets no help here.

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?

There is no guidance on when to use this versus the sibling 'open' tool, versus querying/displaying a record, or any prerequisite (e.g. needing a logged-in org). Usage must be inferred entirely from the name.

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 destructiveHint=true, idempotentHint=false, openWorldHint=true, and readOnlyHint=false, so the mutation/safety profile is covered. The description does not add beyond that: it never mentions that installs are long-running (hence the wait/publishWait minutes), that org auth or an installation key may be required, or what happens to existing components on upgrade. Some added value (04t vs alias support) but no real behavioral disclosure.

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, no redundancy. The trailing phrase 'with various configuration options' is vague filler that earns little, keeping it short of 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 a destructive, potentially slow, multi-option installation tool with no output schema, the definition covers the core action but omits invocation-relevant context: the required nesting under 'input', the default-org fallback behavior, and any indication of what is returned or how failures surface. The rich nested schema compensates for parameter gaps, but behavioral context remains thin.

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 nested schema documents all nine options in detail (apexCompile, upgradeType, securityType, installationKey, waits), so the parameter burden is largely carried by the schema rather than the description. However, the top-level 'input' wrapper is undocumented in both the schema and the description, and the description's claim of 'various configuration options' is vague rather than naming the meaningful knobs.

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

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

States a specific verb pair (install/upgrade), the resource (package version), and the target system (Salesforce org), which cleanly separates it from the sibling package_uninstall. It notes accepted identifier forms (04t IDs or aliases), but never names or contrasts any sibling explicitly, so differentiation is inferred rather than stated.

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?

There is no guidance on when to choose this over alternatives (e.g., package_uninstall or deploy_start), no prerequisites such as being logged into a target org, and no exclusions. The agent is left to infer everything about selection context from the tool name.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, covering the safety profile. The description adds that this is for 'second-generation' packages and specifies the target org, but does not elaborate on side effects, permissions, reversibility, or rate limits beyond what annotations state.

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 purpose and followed by a parameter hint. It is efficient with no wasted words, though it could be slightly more informative without becoming 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?

For a destructive mutation tool with no output schema and incomplete parameter coverage, the description is insufficient. It lacks usage guidance, does not mention authentication or permission requirements, does not describe the wait parameter's effect, and provides no information about failure modes or confirmation steps.

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 reported as 0%, so the description must compensate. It only explains the packageId parameter (format and alias) and omits the other three parameters (wait, targetOrg, apiVersion). Moreover, the packageId information duplicates what is already in the nested schema description, adding little new 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 verb ('Uninstall') and resource ('second-generation package from the target org'), making the purpose clear. It implicitly distinguishes itself from the sibling 'package_install', but does not explicitly name alternatives or scope limitations.

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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. The only hint is the implied use case of uninstalling a package, but no explicit when/when-not instructions 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses that SOQL SELECT/WHERE/ORDER BY/LIMIT are executed and that results come back as JSON. It does not mention pagination or query limits, which keeps it from a 5.

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?

Front-loads the core purpose and the exclusion before the implementation detail. Some redundancy – the caps-lock SINGLE/ONE/IMPORTANT and the SOQL clause sentence restate earlier content – but every sentence is functional.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description supplies the routing, prerequisites, and query-capability context an agent needs. Minor gap: no mention of result limits or default-org resolution for targetOrg.

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 reported at 0%, so the description must carry parameter meaning. It does convey the WHERE/ORDER BY/LIMIT clause semantics and the prerequisite for knowing the SObject, but it says nothing about targetOrg (default org behavior) or the shape of selectClause beyond what's obvious. Partial compensation only.

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

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

States a specific verb+resource (query records from a SINGLE Salesforce object) with scope and gives concrete examples of conditions. It explicitly names the sibling it is not (search_records for cross-object text search), so the agent can disambiguate without opening either 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 (precise queries on one object with field criteria), when-not (text searches across multiple objects), the named alternative, and a sequencing prerequisite (run sobject_list first, optionally sobject_describe). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the operation writes a file (a side effect not captured by annotations) and that CSV is the default format, but omits where files land and whether an existing file is overwritten — notable for a file-writing 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 core purpose is front-loaded, but the text repeats itself — 'save the results to a file' is restated twice and CSV-default is stated redundantly with the schema default. Several sentences could be merged without loss.

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

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

With no output schema, the description should clarify what the call returns (a path, a summary, a confirmation) — it does not, saying only that results are saved. Prerequisites and format options are well covered, but the post-write behavior and file destination are left unspecified for a tool whose whole point is producing a file.

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 reported at 0% for the single top-level 'input' parameter, so the description must compensate, and it does: it explains the SELECT clause can hold fields, functions like COUNT(), and aggregations, that WHERE is optional, and that format defaults to CSV. It covers the main nested fields but does not mention orderBy, targetOrg, or outputFileName.

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

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

States a specific verb+resource+terminal action: query a Salesforce SObject and save to a file. This distinguishes it from the sibling query_records, which returns results rather than persisting them. An agent can tell what it produces 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?

Explicitly instructs running sobject_list first and optionally sobject_describe before querying, which is real prerequisite guidance. It does not, however, state when to prefer this over the sibling query_records or search_records, so the routing choice between query tools is left implicit.

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

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

Annotations already declare destructiveHint, openWorldHint, and non-idempotent, so the safety profile is covered. The description adds the sync/async execution choice, which is useful behavioral context, but it says nothing about runtime cost, wait semantics, or how results are surfaced, and does not contradict the annotations.

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

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

Front-loaded with the core action, but four sentences with redundancy — 'Run Apex tests' and 'execute unit tests with various options' restate the same idea, and the option list duplicates the nested schema. One or two sentences would suffice.

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 test-runner with no output schema and rich nested parameter docs, the description covers the main option surface adequately. However, it omits the follow-up path (get_apex_test_results) and any note on execution timing/results, leaving the agent with an incomplete picture of the end-to-end flow.

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?

Top-level schema coverage is 0% (single 'input' wrapper), but the nested properties carry rich descriptions including mutual-exclusion rules (--tests vs --class-names vs --suite-names). The description only lists the option categories at a high level and adds no semantics beyond the nested schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Run Apex tests in a Salesforce Org') and names the concrete options involved (test level, classes, suites, coverage). It is clear what the tool does, though it never explicitly contrasts itself with the sibling get_apex_test_results, so sibling differentiation is only implicit.

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 implied usage ('Use this to validate your Apex code and ensure proper test coverage') but gives no when-not conditions and never points to alternatives such as get_apex_test_results for retrieving results or execute_anonymous_apex. The agent must infer the workflow.

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 declare destructiveHint=true, openWorldHint=true, readOnlyHint=false and idempotentHint=false, but the description describes only analysis and never discloses side effects (e.g., outputFile writes) or that engines/config files on disk can be touched. With annotations carrying the safety profile, the description still adds almost no 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?

Two short sentences, no filler, with the core purpose front-loaded and the prerequisite following immediately. Nothing is wasted.

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 nested-object tool with no output schema and destructive/open-world annotations, the description omits return format, side effects, and supported engines. The rule-selector routing is helpful but only partially covers what an agent needs before invoking it.

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 top-level 'input' object has no schema description (0% coverage at the parameter level), yet the nested properties are documented in the schema. The description adds value only for ruleSelector by pointing to list_code_analyzer_rules for valid values; target, workspace, severity, configFile and outputFile are left entirely to the schema.

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

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

States a specific verb and resource ('Analyze code') plus the scope of analysis ('quality and security issues'). It is clearly distinguishable from siblings like list_code_analyzer_rules or scanner_run, though it does not explicitly contrast itself with scanner_run.

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 prerequisite workflow: run list_code_analyzer_rules first to pick rules for ruleSelector. It does not state when-not to use it or how it differs from scanner_run/scanner_run_dfa, but the ordering guidance is concrete and actionable.

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 declare destructiveHint=true and readOnlyHint=false, but the description's 'Scan codebase' strongly implies a read-only analysis operation. This contradiction is not resolved by any side-effect disclosure (e.g., outfile writes), so the behavioral profile is misleading.

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, no filler. It tells the core action and one default in minimal size.

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 scanner with many nested configuration options and no output schema, the description omits when to use it versus siblings like run_code_analyzer or scanner_run_dfa, and gives no sense of output or side effects. The annotations alone are not enough to make this 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?

Context reports schema description coverage is 0% for the single input object, so the description must compensate. It adds only 'Defaults to all rules if none specified,' leaving the numerous nested engines, formats, and config parameters unexplained.

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 verb 'Scan' and resource 'codebase' are specific, and 'security and quality rules' clarifies the domain. However, it does not distinguish this from sibling scanners such as scanner_run_dfa or run_code_analyzer.

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 only states a parameter default ('all rules if none specified'). It gives no when-to-use guidance, no conditions for choosing this over sibling tools, and no exclusions.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is carried structurally. The description adds nothing behavioral beyond that: no mention that it writes output files, that it is computationally heavy/long-running, or that JVM/thread/timeout tuning affects behavior.

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, front-loaded sentences with no filler, and the core capability leads. It is efficient, though so terse that the brevity becomes under-specification rather than crispness.

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 nested 13-field analysis tool with no output schema, no annotation detail on returns, and heavy runtime configuration, the description is far too thin. It leaves format selection, severity thresholds, and output destinations entirely unexplained.

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?

Reported schema description coverage is 0% and the tool wraps a single nested 'input' object containing 13 tunable fields (target, projectDir, sfgeJvmArgs, pathExpLimit, thread settings, severity thresholds). The one-sentence description mentions no parameter at all, leaving the agent with no semantic guidance from the description side.

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

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

States a specific verb and resource ('Run Graph Engine for Apex data flow analysis') and names the class of defect it finds, which distinguishes it from generic siblings like scanner_run. It stops short of explicitly contrasting with scanner_run, so an agent must infer when DFA is needed over the base scanner.

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

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

No when-to-use guidance, no prerequisites (e.g., requires a project directory, JVM availability), and no routing against the obvious alternative scanner_run. The agent is told what it does but not when to pick it.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds no behavioral context beyond the safety profile — nothing about overwrite behavior on existing tab files, prerequisites, or side effects when the directory already contains files. The 'generate' framing is consistent with the annotations, so no contradiction, but little value is added.

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 and the output artifact. The second sentence is slightly peripheral (a definition of custom tabs) but earns its place by clarifying the artifact for an agent unfamiliar with the Salesforce concept.

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 generation tool with no output schema and full annotation coverage of the safety profile, the description covers purpose but omits prerequisites and what is actually written/returned. Adequate to invoke, but an agent must infer project context and overwrite semantics.

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 nested schema documents all three fields (icon range 1-100 with color/icon semantics, object API name with the MyObject__c example, directory path), so the schema carries the semantic load and the description adds nothing. The top-level 'input' wrapper itself is undescribed, but the meaningful parameters are covered, which keeps this at the baseline 3.

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

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

States a specific verb (Generate) and resource (metadata source files for a custom tab on a custom object), so an agent knows exactly what it produces. No sibling generates tabs, so differentiation is moot, but the second sentence explaining what custom tabs are is competent domain framing rather than a restatement of the name.

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 no when-to-use, no when-not-to-use, and no prerequisites (e.g., must be inside a Salesforce DX project, must reference an existing custom object). It implies the tool creates a tab for a custom object but never states the conditions that select it over manual metadata authoring or the other generate_* 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's added behavioral value is limited to explaining that this is a full-text SOSL search across all searchable fields. It omits useful behavior such as the csv resultFormat writing to disk and any result-size or pagination limits.

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

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

The purpose is front-loaded and the core message is clear, but the text is padded with restatement ('USE THIS TOOL when searching for records that mention, contain, or reference specific text') and marketing language ('Perfect for finding all records mentioning a competitor'). Several sentences could be cut without losing 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 read-only search tool with annotations covering safety and no output schema, the description gives enough to select and call it confidently, including the object scope and the SOSL basis. It stops short of covering result format trade-offs or query-construction guidance for the one nested input object.

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 description supplies no information about the inputs (query string, file path, targetOrg, resultFormat), leaving the nested 'input' wrapper entirely unexplained and offering no SOSL syntax example, which is valuable given SOSL is unusual syntax. The inner properties do carry their own schema descriptions, which keeps this at an adequate rather than failing level.

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

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

States a specific verb and resource ('Search for text across multiple Salesforce objects simultaneously') and names the underlying mechanism (SOSL full-text search across all searchable fields). It is clearly distinguishable from the SOQL-based siblings such as query_records and query_records_to_file.

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 triggers ('records that mention, contain, or reference specific text') and declares itself the PRIMARY tool for cross-object text search, noting it is more efficient than running multiple SOQL queries. It never names the specific sibling to prefer for structured filtering, so routing is clear but not exhaustive.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful persistence context ('persists across sessions'), but does not mention that setting this overwrites any existing default org or note any auth requirements.

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

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

Three short sentences with zero filler, and the core action is front-loaded in the opening clause.

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 mutation tool with annotations covering safety and idempotency and no output schema, the description covers purpose and persistence adequately. It could still note the overwriting behavior and authentication prerequisites, but nothing critical to invocation is missing.

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

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

Schema description coverage is reported at 0%, though targetOrg carries a description ('Username or alias of the org to set as the default target org'). The description adds only the default-target framing and no extra format or alias-syntax detail, so it does not meaningfully compensate for the coverage 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?

States a specific verb (Set) and resource (default target org for the Salesforce CLI) and explains the resulting effect. It reads clearly apart from get_default_org and clear_default_org without naming them, though explicit sibling routing would have earned a 5.

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

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

The description explains downstream behavior ('all tools will use this org by default when no targetOrg is specified') but never says when an agent should call this versus passing targetOrg explicitly or using clear_default_org. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the return format (JSON) and a workflow invariant (must precede query/manipulation), but does not mention auth requirements or org-selection behavior.

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?

Purpose is front-loaded in the first sentence, but the middle sentences are redundant — 'detailed metadata about a specific Salesforce SObject... comprehensive view of the SObject's structure' says the same thing twice. Still readable and appropriately sized.

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 an output schema present, the description need not explain return values, and annotations cover the safety profile. What remains — which SObject and which org — is left to the schema, which is adequate but not ideal.

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 description never mentions sObjectName or targetOrg, and schema description coverage is reported as 0%. For a tool whose only meaningful input is which SObject to describe, the description fails to compensate for the missing parameter documentation.

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

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

States a specific verb (describe) and resource (Salesforce SObject) and immediately scopes the payload ('fields, relationships, and other properties'), making it clearly distinct from siblings like sobject_list, list_metadata, and 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?

Gives explicit triggering conditions ('especially useful when writing Apex code or SOQL queries') and a strong prerequisite ('Always execute this tool before querying or manipulating records'). It does not name an alternative sibling (e.g., sobject_list or list_metadata), so the routing is implied rather than fully 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?

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, so the safety profile is handled. The description adds real value beyond that: the JSON return shape (name, label, metadata) and a hard ordering prerequisite before Apex/SOQL authoring. It omits auth/permission requirements and rate/pagination behavior.

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?

Front-loaded and readable, but three of the five sentences restate the same 'list standard and custom objects' idea, and the return-format sentence duplicates what the output schema already provides. It is padded rather than tight.

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 rich annotations and an output schema, the description does not need to explain returns or safety, yet it supplies the one thing structured data cannot: the workflow prerequisite to run this before generating Apex or SOQL. Only the org-selection parameter is left under-explained.

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

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

The only parameter (targetOrg) is mentioned only obliquely as 'the specified Salesforce Org', with no explanation of the alias format or the default-org fallback — that detail lives in the schema. With a single parameter and no added semantics in the description, this is baseline territory.

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

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

States a specific verb and resource ('List all standard and custom objects in a Salesforce Org') and clarifies the scope as standard plus custom. An agent can distinguish it from describe/query siblings without opening a schema, though it never names them explicitly.

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 a concrete condition: use it to explore objects when you don't know API names, and 'always execute this tool before writing Apex code or SOQL queries.' That is strong when-to-use guidance, but it never names an alternative (e.g. sobject_describe, list_metadata) or states when-not to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds one genuinely useful behavior beyond that: 'Updates specified fields on the record,' implying unspecified fields are untouched, which is a partial-merge semantic not stated in the annotations. It omits permission/error or return behavior.

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, front-loaded with the action and resource, then the input contract. No filler or redundancy, though the second sentence slightly overlaps the first.

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 destructive, open-world mutation tool with rich annotations and no output schema, the description covers what the action is and what input it takes, but says nothing about required permissions, partial-update confirmation, or error/failure modes. Adequate but with clear gaps.

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

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

The single top-level 'input' object is expanded into its sObject/recordId/recordJson/targetOrg keys with types, matching the nested schema, and marks targetOrg as optional. This largely restates what the nested schema already documents, adding no ID format, JSON syntax, or org-resolution detail beyond it.

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

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

States a specific verb (Update) and resource (existing Salesforce record) plus the transport (REST API), which cleanly separates it from create_record and delete_record. It stops short of naming siblings or scoping constraints, but the purpose is unambiguous.

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

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

Says it updates 'an existing record' but gives no when-to-use context, no prerequisites (e.g. resolve the ID first, obtain an authenticated org), and no comparison to alternatives like create_record or sobject_list/describe. Usage is left almost entirely to inference.

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