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

With no annotations, the description carries the transparency burden. It does disclose the destructive operation and mentions per-record success status in Returns. However, it does not warn about irreversibility, permission requirements, or partial-failure behavior, which would be valuable for a delete tool with no annotation safety signals.

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 short, structured with Args/Returns, and front-loads the core purpose. The first two sentences slightly overlap ('Bulk delete multiple records' vs 'delete many records efficiently'), but the second does add usage context, so the redundancy is minor.

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 two-parameter tool with an output schema, this is largely complete: both arguments are explained, an example is provided, and return intent is stated. It lacks caveats like bulk limits, permanence, or authorization, but these are not defining for this tool's basic invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: sobject as SObject type with examples, and record_ids as a list of record IDs with a concrete example. This is enough for an agent to construct a valid call.

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

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

The description clearly states a specific action and target: 'Bulk delete multiple records.' The word 'bulk' differentiates it from salesforce_delete_record, but it does not explicitly name or contrast that sibling, 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?

The sentence 'Use this to delete many records efficiently' provides a clear use case: many records, with efficiency as the reason. However, it does not state when not to use it or explicitly point to alternatives like salesforce_delete_record for single records.

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

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

With no annotations, the description carries the behavioral burden, and it does well by disclosing that the Bulk API processes records in batches and returns per-record success, id, and errors. It does not mention rate limits, permissions, or asynchronous timing, but the core operation and result behavior are clearly communicated.

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

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

The description is well-structured with a clear purpose sentence, one usage sentence, and organized Args/Returns sections. Every sentence adds value, and there is no unnecessary repetition or fluff.

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

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

For a tool with two required parameters, no schema descriptions, and no annotations, the description provides sufficient detail to invoke it correctly and interpret results. Some additional context such as maximum batch size, object restrictions, or asynchronous behavior would be useful, but it is not essential for correct basic usage.

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

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

The input schema provides no property descriptions (0% coverage), but the description fully compensates by explaining sobject with examples and defining records as a list of field-value dicts with a concrete example. This gives an agent everything needed to construct valid arguments.

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 starts with 'Bulk insert multiple records,' which names a specific action and resource. It also clarifies the scope by emphasizing multiple records and high volumes, distinguishing it from sibling tools like salesforce_create_record or bulk update/delete tools.

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

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

The description explicitly says 'Use this to create many records efficiently' and states it is 'optimized for high volumes,' giving clear contextual guidance for when to use it. It does not explicitly name alternatives or provide exclusion criteria, which prevents a 5.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does disclose that the Bulk API is asynchronous and optimized for large volumes, which are important traits. However, it does not explain what 'asynchronous' means for the caller—whether it returns a job ID, whether it polls to completion, or how results are delivered—and simply says 'Returns: List of all matching records,' which could be misleading if results are not returned synchronously.

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

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

The description is compact and well organized: a one-line summary, a usage condition, an important behavioral note, and clearly labeled Args/Returns sections. Every sentence contributes useful information, and the key usage threshold is front-loaded.

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

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

For a two-parameter tool with an output schema available, the description covers the essential invocation details: what to pass, when to use it, and what to expect back. The main gap is the incomplete elaboration of asynchronous behavior and result retrieval, which is relevant for an agent deciding whether to call this versus a simpler tool.

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

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

Schema description coverage is 0%, so the description must compensate for the bare input schema. It does so by defining 'sobject' with a concrete example ('Account', 'Contact') and 'soql' as a SOQL query string. This gives the agent enough meaning to invoke the tool correctly, though it could add more detail about SOQL expectations or validation.

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

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

The description clearly states the tool executes a bulk query for large data sets, names the specific resource (Bulk API), and distinguishes it from the regular salesforce_query by the 2,000-record threshold. An agent can tell exactly what this tool does and how it differs from its siblings.

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

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

The description gives a concrete selection criterion: use this for queries that may return more than 2,000 records. This effectively tells the agent when to prefer this over the standard query tool. It does not explicitly name alternative tools or mention when not to use it, but the threshold provides clear contextual 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?

With no annotations, the description carries the full disclosure burden. It correctly emphasizes that each record must include an 'Id' and states that per-record success status is returned, but it does not explain partial-failure behavior, field replacement semantics, or permissions. Useful but 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?

Front-loaded with the core purpose, followed by a usage hint and well-structured Args/Returns sections. The example is compact and functional, with no filler or redundant content.

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

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

For a two-parameter bulk mutation with an output schema, the description covers the essential invocation details: object type, record list, required 'Id', and return shape. It could be more complete by addressing all-or-nothing behavior or batch limits, but it is sufficient for a typical agent to call it correctly.

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

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

Schema description coverage is 0%, but the description compensates thoroughly: 'sobject' is defined with examples, and 'records' is explained with the mandatory 'Id' requirement and a concrete JSON example. This adds critical meaning beyond the bare 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 ('Bulk update') and resource ('multiple records'), and the name plus description clearly distinguish it from single-record update and bulk insert/delete siblings. The phrase 'many records' reinforces that this is the batch update variant.

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 says 'Use this to update many records efficiently', providing clear context for when to choose this tool. It does not name alternatives or state when not to use it, but the batch vs single-record distinction is unambiguous.

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?

There are no annotations, so the description must carry the behavioral transparency burden. It discloses the write effect and the return shape (id, success, errors), which is useful, but it does not mention permission requirements, validation behavior, or failure modes beyond a generic 'errors' field. Adequate but not rich.

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

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

The description is concise and well-organized into Args and Returns sections. Every line carries useful information, and the main purpose is stated first with no filler or repetition.

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

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

For a two-parameter creation tool with an output schema, the description covers the essential invocation details: object type, field data, and expected response. It could add context about required Salesforce fields or validation behavior, but the description is otherwise complete enough for an agent to call the tool correctly.

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

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

The input schema provides only names and types with 0% description coverage, so the description must compensate. It explains that 'sobject' is an SObject type with examples and that 'data' is key-value field values with a concrete example, adding real meaning beyond the bare schema.

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

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

The description opens with a clear, specific verb and resource: 'Create a new Salesforce record.' It names the primary parameters and gives example object types, making the tool's purpose obvious and distinguishing it from update, delete, query, and upsert siblings.

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

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

The description says what the tool does but gives no guidance about when to choose it over alternatives such as salesforce_upsert_record or salesforce_bulk_insert. There are no exclusions, prerequisites, or context about when create is preferable to upsert.

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

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

With no annotations, the description carries the full behavioral burden, but it only says deletion returns a success status. It does not disclose that deletion is typically irreversible, whether special permissions are needed, or what happens when the record does not exist. This is thin for a destructive operation.

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

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

The description is compact and well structured with Args and Returns sections. It front-loads the purpose and contains no filler, repetition, or irrelevant detail.

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

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

The two parameters are well described and an output schema exists, so basic invocation is covered. However, the definition omits important context for a delete tool: irreversibility, permission needs, and the distinction between this single-record delete and the sibling salesforce_bulk_delete. These gaps keep it from being fully complete.

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

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

Schema description coverage is 0%, so the description must add meaning, and it does: it defines 'sobject' as an SObject type with concrete examples and 'record_id' as an 18-character Salesforce ID. This goes well beyond the bare string types in the schema, though it could still add format constraints or valid object names.

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 'Delete a Salesforce record', a specific verb and resource that clearly distinguishes this from siblings like salesforce_create_record, salesforce_update_record, and salesforce_bulk_delete. The singular 'a record' further signals single-record deletion rather than bulk operations.

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

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

The phrase 'a Salesforce record' implies this tool is for deleting one record at a time, which provides some usage signal against the bulk sibling. However, it does not explicitly state when to prefer this over salesforce_bulk_delete or mention any preconditions, so the guidance remains 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?

With no annotations present, the description carries the full burden. It clearly implies a read-only metadata operation and details the return structure, but it does not disclose potential errors, permission requirements, API limitations, or explicitly confirm that no data is modzed. This is adequate but not comprehensive.

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

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

The description is well-organized with a concise summary, an Args section, and a structured Returns list. The only minor issue is slight redundancy between the opening summary and the Returns section, but overall every part is useful and front-loaded.

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

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

For a single-parameter tool with an output schema already present, the description properly covers the parameter and the expected return contents. It does not add sibling-tool routing guidance or error-case context, but the basic calling contract is complete.

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

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

Schema coverage is 0%, so the parameter semantics must come from the description. The Args section fully defines 'sobject' as an SObject type and provides concrete examples ('Account', 'Contact', 'Lead', 'Opportunity'), leaving no ambiguity for the single required parameter.

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

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

The opening sentence uses a clear verb and resource: 'Get metadata for a Salesforce SObject.' The list of returned components (fields, relationships, record types) makes it distinct from siblings like salesforce_list_objects and salesforce_get_object_fields, so an agent can immediately tell what it does.

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

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

The description explains what the tool does but gives no explicit guidance on when to choose it over alternatives such as get_object_fields, list_objects, or query. There are no 'use this when' or 'instead use' statements, so the agent must infer the intended placement among the many sibling tools.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clearly explains the method returns a list of field definitions rather than the full describe response, and it enumerates the included field properties. It does not explicitly state there are no side effects, but 'Get' and 'returns' strongly imply a read-only convenience operation.

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

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

The description is front-loaded with the purpose and differentiator, followed by a concise Args section and a well-structured Returns section. Every line adds meaningful information; the return field list is detailedbut earned because it tells the agent exactly what to expect.

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

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

For a single-parameter read-only getter with an output schema, the description is complete. It covers the parameter semantics, the output structure, and the reason this tool exists relative to the fuller describe call. No critical information needed to invoke it correctly is missing.

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

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

The schema only declares sobject as a string with no description, so the schema coverage is 0%. The description fully compensates by naming the parameter, explaining it is the SObject type, and providing examples like 'Account' and 'Contact'.

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

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

The description clearly states the verb and resource: 'Get field information for a Salesforce SObject.' It further differentiates itself from the sibling salesforce_describe_object by noting it is a convenience method that returns only the fields array from the describe call.

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

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

The description indicates this is useful when just the fields array is needed from the describe call, implying it should be used over a full describe operation. It does not explicitly name the sibling alternative or provide exclusion criteria, but the context is clear enough.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful behavior details: fields is optional, and if omitted the tool returns all accessible fields. This helps the agent understand default behavior. However, it does not mention read-only guarantees, permission requirements, error behavior for invalid IDs, or handling of inaccessible fields, which would be valuable for a no-annotation tool.

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

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

The description is compact and well-structured. The one-line summary is front-loaded, followed by a clean Args section that maps directly to the parameters and a Returns section. Every sentence adds information; there is no filler or repetition.

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

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

For a relatively simple get-by-ID tool, the description covers the essential invocation surface: parameters, formats, optional behavior, and return content. The existing output schema likely covers the detailed response shape. The only notable gap is the absence of explicit guidance on when not to use this tool and what exception cases look like, but overall the description is sufficient for correct selection and invocation.

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

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

The input schema provides only raw property names with no descriptions, so the description fully compensates. It explains that sobject is a Salesforce object type with concrete examples, record_id must be an 18-character Salesforce ID, and fields is an optional list with a clear default behavior. This is exactly the semantic enrichment the schema lacks.

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

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

The description opens with a specific verb and resource: 'Get a single Salesforce record by ID.' It clearly identifies the operation, the object type, and the unique identifier, which distinguishes it from sibling tools like query or bulk operations that retrieve multiple records. The purpose is unambiguous and immediately actionable.

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

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

The tool's intended use is implied clearly: when you have a specific SObject type and a Salesforce record ID and need one record. However, it does not explicitly say when to prefer this tool over alternatives like salesforce_query or salesforce_get_object_fields, and it offers no exclusions or caveats. The guidance is functional but not explicit enough for a 4.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that results are filtered by the current user's access, includes both standard and custom objects, and lists the returned capability flags such as queryable, createable, updateable, and deletable. It does not mention pagination or API limits, but for a zero-parameter listing tool the key behaviors are covered.

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

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

The main purpose is front-loaded in the first sentence, and the follow-up sentences add meaningful detail about scope and return fields. There is minor redundancy between 'List all available SObjects' and 'Returns a list of all objects,' but the overall structure is clear and focused.

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

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

Given the tool's simplicity, zero parameters, and presence of an output schema, the description is largely complete. It explains what the output contains and the access-based filtering. It does not discuss large-org truncation or pagination, but this is a plausibly acceptable omission for a listing tool.

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

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

The tool has zero parameters, so the input schema is already fully complete. The description does not need to explain parameter meaning. The 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?

The description clearly states the tool's action and resource: 'List all available SObjects in the Salesforce org.' It is specific and conveys the scope (all objects accessible to the current user), but it does not explicitly differentiate itself from sibling tools like salesforce_describe_object or salesforce_get_object_fields.

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

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

The description gives clear context for when to use the tool: when you need an enumeration of available standard and custom objects accessible to the current user. It does not mention exclusions or explicitly compare with alternatives, but the 'list all' framing makes the primary use case unambiguous.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It does this well by documenting the return structure, totalSize, done, records, and nextRecordsUrl, and by explaining include_deleted semantics and pagination state. It does not cover authentication, errors, or rate limits, but those are less critical for a read-only SOQL query tool.

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

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

The description is well-structured with a clear one-line purpose followed by Args and Returns sections. Every sentence adds useful information, and the key purpose is front-loaded. No filler or redundant content.

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

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

For a two-parameter query tool with an output schema, the description is largely complete: it covers both parameters and the return shape, including pagination hints. It could be more complete by explicitly directing the agent to salesforce_query_more when nextRecordsUrl is present, but the sibling list makes that inferable.

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 0%, so the description must compensate. It adequately documents soql with a concrete example and include_deleted with its default behavior. This adds meaning beyond the bare schema, though it could provide more detail on SOQL syntax constraints or response limits.

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

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

The description clearly states the tool executes a SOQL query against Salesforce, using a specific verb and resource. It distinguishes itself from search/CRUD/describe siblings, but it does not explicitly differentiate from salesforce_query_all or salesforce_bulk_query, which also run SOQL queries.

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

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

The description implies this is the tool for running a SOQL query via the provided example. However, it gives no explicit guidance on when to choose this over salesforce_query_all, salesforce_bulk_query, or salesforce_query_more for pagination.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully explains that the query includes deleted and archived records, which is the main behavioral distinction. However, it does not explicitly confirm read-only semantics, mention rate limits or pagination, or describe how results behave beyond the return phrase. Given the absence of annotations, a bit more behavioral context would be valuable.

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

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

The description is compact, front-loaded with the essential behavior, and avoids redundant filler. The Args/Returns structure makes the content scannable, and every sentence earns its place. The only slight repetition ('including deleted and archived records' twice) is minor and does not hurt 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?

This is a simple one-parameter tool and an output schema exists, so the description does not need to explain return types in depth. It provides the core behavior, the equivalent underlying call, and the parameter meaning. It could add explicit read-only confirmation or pagination behavior, but those are not critical for a basic SOQL query tool with this simplicity level.

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% and the only parameter is a bare string, so the description's 'soql: SOQL query string' adds real semantic meaning by identifying what the string should contain. It does not provide syntax examples or formatting guidance, but for a single self-explanatory SOQL parameter this is adequate, though not rich.

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

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

The description opens with a specific action and resource: 'Execute a SOQL query including deleted and archived records.' This clearly differentiates the tool from the sibling salesforce_query while still identifying the core query behavior. An agent can immediately know what this tool does and how it differs from related query tools.

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

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

The description explicitly states that this tool is equivalent to salesforce_query with include_deleted=True, which names the relevant alternative and the key condition for choosing this variant. It stops short of saying 'use this when you need deleted/archived records' in explicit terms, but the meaning is clear 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool fetches additional records and requires a nextRecordsUrl from a previous response, but it does not mention potential errors, token expiration, rate limits, or whether the response may still contain done=False. This is acceptable for a simple read operation but not rich.

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

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

Compact and front-loaded with the purpose, followed by a clear usage condition and minimal argument documentation. Every line earns its place with no redundancy.

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

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

For a low-complexity tool with one parameter and an output schema, the description covers the invocation context well: purpose, trigger condition, and parameter origin. It does not explicitly instruct the caller to check done again for further pages, but the output schema likely contains that information.

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 0%, so the description must compensate. It fully explains the only parameter: next_records_url is 'The nextRecordsUrl from a previous query response,' providing essential source context beyond the bare string type in the schema.

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

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

States a specific verb and resource: 'Fetch additional records from a previous query.' This clearly distinguishes it from salesforce_query (which runs an initial query) and salesforce_query_all (which auto-fetches all pages).

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 trigger condition: 'Use this when a query returns done=False and provides a nextRecordsUrl.' This gives unambiguous context for when to invoke the tool, though it does not explicitly name alternatives or 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?

With no annotations, the description carries the transparency burden. It discloses the return format ('List of matching records grouped by object type') and the non-mutating nature of a search, but it does not cover edge cases such as empty results, malformed SOSL, or permission requirements. This is adequate but not expansive.

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 short, well-organized into Args and Returns sections, and has no wasted words. The example is placed directly beside the parameter definition, making the invocation format easy to scan.

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

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

Given a single required parameter, an output schema, and a short description, the definition is nearly complete. It provides the call syntax, the return grouping, and an example. It lacks only explicit sibling routing and edge-case behavior, which are minor for this tool.

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

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

Schema description coverage is 0%, so the description must fully explain the sosl parameter. It does so by defining it as a SOSL search string and providing a concrete, executable example with FIND and RETURNING clauses. This fully compensates for the schema gap.

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

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

The description opens with a specific verb and resource: 'Execute a SOSL full-text search.' It names the SOSL query type, which distinguishes it from the SOQL-based sibling tools such as salesforce_query, and it also states the return shape.

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 does not explicitly state when to choose this tool over salesforce_query or salesforce_query_all. However, 'SOSL full-text search' and the example clearly imply it is for cross-object text/keyword search, so usage is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It confirms that the operation mutates an existing record and vaguely mentions a 'success status', but it omits permissions, side effects, failure behavior, partial-update semantics, and irreversibility. It adds little beyond what the tool name already conveys.

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

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

The description is well-structured with a clear opening line followed by Args and Returns sections. It avoids filler and includes a useful example for the data parameter. The Returns line is somewhat generic but not wasteful.

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

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

All required parameters are documented and the return is mentioned, so a basic invocation is possible. However, with no annotations and fifteen sibling tools, the description omits important context such as what happens when the record does not exist, permission requirements, and how this tool relates to upsert or bulk alternatives.

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

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

The input schema has 0% property descriptions, but the description fully documents all three parameters: sobject with concrete examples, record_id as an 18-character Salesforce ID, and data as a key-value map with a clear example. This completely compensates for the schema gap and adds practical meaning.

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

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

The description states a specific action ('Update') and resource ('existing Salesforce record'), making the core purpose clear. It does not explicitly differentiate from sibling tools like salesforce_upsert_record or salesforce_bulk_update, so it falls short of full sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives such as salesforce_upsert_record for create-or-update behavior or salesforce_bulk_update for multiple records. 'Update an existing Salesforce record' merely restates the tool's purpose and offers no exclusions or selection criteria.

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?

There are no annotations, so the description carries the full burden of disclosing behavior. It clearly indicates mutation through 'updated' and 'created', but it does not cover permission requirements, error behavior, or whether omitted data fields are preserved during an update. The return value is only vaguely described as 'success status'.

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

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

The description is compact, front-loaded with the core behavior, and structured with clear Args and Returns sections. Every sentence earns its place without unnecessary 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?

Given no annotations, the description covers the essential invocation details: operation, conditional behavior, parameter meanings, an example, and return outcome. Minor gaps around permissions, error cases, and update semantics prevent full completeness.

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

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

Schema description coverage is 0%, and the Args section compensates meaningfully with concrete examples and the requirement that data include the external ID field. It explains all three parameters, though external_id_field semantics could be slightly more detailed.

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

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

The opening sentence specifies the action (upsert), the resource (record), and the mechanism (external ID field). The subsequent if/exists/otherwise-create explanation makes the operation unambiguous and clearly distinguishes it from salesforce_create_record and salesforce_update_record.

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 conditional behavior—update when the external ID exists, create otherwise—tells the agent exactly when this tool is appropriate. It does not explicitly name alternative tools or state when not to use upsert, 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.