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

With no annotations, the description carries the full burden, and it does well: it discloses that the tool reads the Sforce-Limit-Info header when available, avoids an extra request, and falls back to /limits otherwise. It does not describe the exact output shape, but the read-only, no-side-effect nature is clear.

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 sentence front-loads the main purpose, and the second adds only the implementation/fallback detail that matters for understanding cost and behavior. Every sentence contributes; there is no fluff.

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

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

For a zero-parameter, read-only info tool, the description is nearly complete: it explains what is reported, the source of the data, and the fallback edge case. It does not specify the return fields or format, which would be a small improvement given there is no output schema.

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

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

The tool has zero parameters and an empty input schema, so there is nothing for the description to add about argument semantics. The 0-parameter baseline applies, and the description correctly focuses on behavior instead.

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

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

The description uses a specific verb ('Report') and resource ('Salesforce REST API usage against the org's daily limit'), making the tool's purpose unambiguous. It also differentiates from sibling CRUD/query/search tools, none of which report API quota consumption.

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

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

The description clearly frames when the tool is useful: checking current API usage against the daily limit. It also explains the conditional behavior (header vs /limits fallback), but it does not explicitly contrast it with a similar sibling such as sf_org_health or state 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?

Without annotations, the description carries the transparency burden. It clearly discloses the mutating/destructive operations and some per-operation requirements, but it does not mention asynchronous Bulk API job behavior, polling, rate limits, partial success, or failure semantics. Some behavioral context is present, but meaningful gaps remain.

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, front-loaded with the core action, and every sentence adds value. The when-to-use guidance and operation-specific constraints are tightly packed without 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 bulk write operation with no annotations and no output schema, the description lacks important contextual details such as asynchronous job handling, result retrieval, error behavior, and batch size considerations. It is sufficient for initial tool selection and basic invocation, but not fully complete for real-world Bulk API 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?

Schema description coverage is 0%, so the description must compensate. It explains the operation values, that external_id_field is required for upsert, and that delete records only require an Id. This covers most parameters meaningfully, though sobject is not explicitly defined beyond the overall batch-records context.

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 clear, specific action: insert/update/upsert/delete a batch via Bulk API 2.0. It names the resource type (records) and differentiates itself from one-record-at-a-time sibling tools like sf_create_record and sf_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 description explicitly says when to use this tool: for record volumes too large for the one-record-per-call REST endpoints. It names the alternatives and provides operation-specific conditions such as external_id_field being required for upsert and delete records needing only an Id key.

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?

Although no annotations are provided, the description carries the behavioral burden well: it discloses that the operation is job-based, polls until completion, is slower, and bypasses interactive per-request limits. It could go further by describing response shape or error conditions, but the core runtime behavior is transparent enough for agent invocation.

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, front-loaded with the key use case, and every sentence adds value: purpose, behavioral trade-off, and explicit routing guidance. 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?

Given the simple one-parameter schema, absence of annotations, and absence of an output schema, the description covers the most critical decision factors: what it does, when to use it, and how it behaves. The only notable gap is that it doesn't specify what the successful response contains, but that is a minor omission for a bulk query tool.

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

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

The input schema has 0% description coverage and the description does not add detailed parameter documentation beyond implying that 'soql' is the query string. However, with a single self-descriptive required parameter, the description's mention of 'SOQL query' is minimally adequate for an agent to understand what to pass.

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 ('Run a SOQL query via Bulk API 2.0') and a specific resource, immediately differentiating it from sf_query by targeting result sets too large for interactive queries. This makes the tool's purpose unambiguous even without inspecting 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?

The description explicitly tells the agent when to use this tool versus sf_query: prefer sf_query for everyday lookups, use sf_bulk_query when expecting very large result sets. It also gives a key trade-off ('Slower... not subject to sf_query's interactive per-request limits') which helps the agent make an informed 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It is candid that this is a 'thin, generic pass-through' with no knowledge of what a custom endpoint expects or returns. It also warns that behavior is entirely dependent on the org's Apex class, preventing an agent from assuming the tool provides validation or endpoint-specific handling.

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

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

The description is front-loaded with the core purpose, then gives a concrete path example, then closes with an honest pass-through warning. Each sentence earns its place, though the middle section could be tightened slightly without losing 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 deliberately generic pass-through tool, the description covers the essential knowledge an agent needs: the use case, how to construct the path, the HTTP method constraint, and the limitation that endpoint-specific behavior is unknown. The main gap is that `body` and `params` are not explicitly defined, but the tool's generic nature makes that less critical than it would be for a domain-specific API.

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 adds meaningful semantics for `path` by giving a concrete `@RestResource` URL mapping example, and for `method` by tying it to the Apex class's HTTP handler. However, `body` and `params` are left unexplained; the agent must infer whether `params` means query parameters, headers, or something else.

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: 'Call a custom Apex REST endpoint exposed by the org.' It also clearly contrasts this tool with the server's built-in standard-API tools, making it easy to distinguish from the sibling CRUD and query tools even without opening their schemas.

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

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

The description states when this tool is appropriate: for any org-specific capability beyond the built-in standard-API tools. It explains that `path` is the `@RestResource` URL mapping and that `method` must match the HTTP method handled by the Apex class. It does not explicitly name alternative sibling tools or give exclusion rules, but the intended use case 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, the description carries the disclosure burden and does well: it explains the default all_or_none=true behavior, rollback on failure, and how reference IDs can be interpolated into later sub-requests. It does not mention request limits, response structure, or error details, but the core behavioral contract is clear.

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

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

The description is compact and front-loaded; the opening sentence states purpose, then the example and atomic behavior follow. Every sentence contributes useful information without padding.

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

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

For a complex composite API tool with no annotations and no output schema, the description explains the main invocation pattern and atomicity but omits operational constraints such as maximum sub-request count, allowed HTTP methods, response shape, and error behavior. It is usable but not fully complete for a two-parameter tool with high domain complexity.

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

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

Schema coverage is 0%, so the description must compensate. It does: the requests array is explained via a concrete sub-request example with method, url, referenceId, and body, and all_or_none is defined along with its default. Some sub-request constraints and failure semantics remain implicit, but both parameters gain real 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 and resource: 'Bundle multiple sub-requests into one atomic Salesforce API call.' The example and atomicity wording make it clear this is the composite API tool for combining operations, distinct from single-record CRUD and bulk 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 implies usage for multiple related Salesforce sub-requests that need to be executed atomically with reference chaining, but it never explicitly names sibling tools or states when not to use it, such as for large volumes that belong in bulk_load. An agent must infer the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely restates the create operation and does not mention return values, duplicate handling, field validation, permissions, or error behavior. This is a meaningful gap for a mutation tool.

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

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

The description is a single compact sentence that front-loads the core action and contains no filler. It is appropriately brief, but the terseness means it relies on the schema for any additional meaning.

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

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

For a creation tool with no annotations and no output schema, the description omits important details such as whether the created record ID is returned, what happens on validation failure, how to specify field values, and how this differs from sf_upsert_record. It is minimally sufficient for selecting the tool but not for confident 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 needed to compensate for the bare parameter schema. It references 'object type' and 'field values,' which lightly echo the sobject and fields parameters but add no detail about API names, value formats, nested structures, or required-field behavior. The description does not meaningfully enrich 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 ('Create') and resource ('a new record of the given object type with the given field values'), making the core operation clear. It generally distinguishes itself from query/delete/update siblings, though it does not explicitly differentiate from upsert, which can also create 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?

No guidance is provided about when to use this tool versus alternatives like sf_upsert_record or sf_update_record. There is no mention of prerequisites such as required fields, API names, or when a create should be preferred over an upsert. Usage is only implied by the tool name and action.

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 must disclose consequences and context. It only states the raw operation and gives no information about permanence, Salesforce recycle-bin behavior, required permissions, failure behavior, or return value. For a destructive operation, this is a significant transparency gap.

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

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

The description is very brief and front-loaded, with no wasted words. It conveys the primary action immediately, though the extreme brevity contributes to the lack of contextual detail penalized elsewhere.

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 tool with no annotations, no output schema, and no parameter documentation, a single sentence is insufficient. Key context is missing: what object type is targeted, what happens after deletion, whether it is recoverable, and what response the agent should expect.

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

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

Schema description coverage is 0%, yet the description adds no real parameter meaning. 'By ID' merely restates the 'Record Id' property name, and the required 'sobject' parameter is not explained at all, leaving the agent to guess its format and purpose.

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

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

The description names the specific verb 'Delete' and the resource 'a record by ID,' which clearly states the tool's core function. It is naturally distinguished from siblings like sf_get_record, sf_update_record, and sf_query because deletion is a distinct operation.

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 about when to choose this tool over alternatives, when not to use it, or how it relates to sibling tools like sf_bulk_load or sf_composite. The intended use must be inferred entirely from the name and the one-line 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. 'Return' indicates a read-only metadata operation, but the description does not explicitly state that it is side-effect-free, does not mention authentication requirements, or describe failure behavior. It is minimal but not 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?

A single clear sentence with no filler. The action and target are front-loaded, and every word contributes to understanding.

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 describe operation, the description conveys the main purpose and return content. Yet with no annotations and no output schema, it leaves out explicit notes on read-only behavior, permissions, and error conditions, making it adequate but not 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%, and the description only says 'for one object,' which adds some meaning by linking the parameter to the target object. However, it does not clarify that sobject is the Salesforce API name, provide examples, or list accepted values. The compensation is partial.

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 ('Return') and resource ('field metadata ... for one object'), making the operation clear. It does not explicitly differentiate from siblings like sf_list_objects or sf_query, but the intent 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 prefer this tool over alternatives such as sf_list_objects, sf_query, or sf_get_record. The only implied use case is needing field metadata for a single object, with no explicit when-to-use or when-not-to-use guidance.

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

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

With no annotations, the description alone must carry the behavioral burden; 'Fetch' and 'single record' convey read-only, single-record semantics. However, it does not disclose behavior on missing IDs, default field selection beyond the implicit 'restrict', permissions, or Salesforce-specific side effects.

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, with the core operation front-loaded and the optional parameter guidance in the second sentence. Every word earns its place; no redundant schema or annotation material is repeated.

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 single-record getter, the description covers the core selection and invocation needs and the main optional parameter. It is slightly incomplete only because there is no output schema or annotation to carry return/error behavior, and `sobject` is left to inference.

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 parameter meaning. It usefully explains that `fields` limits returned fields and 'by ID' clarifies `record_id`, but it never explains what `sobject` refers to (e.g., an object APi name like Account), leaving a required parameter under-specified.

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

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

The description uses a specific verb ('Fetch'), a clear resource ('a single record'), and an explicit retrieval key ('by ID'), which lets an agent distinguish it from bulk/list/mutation siblings like sf_query, sf_search, or sf_update_record even without naming 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?

It clearly frames the tool for the single-record-by-ID case and even gives a usage tip for the optional `fields` parameter. It does not explicitly name alternatives or say when not to use it, so it falls just 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?

No annotations are provided, so the description carries the full disclosure burden. It does this well by revealing the trimmed output shape, the potential scale of 800+ objects, and filter behavior. It does not mention auth, errors, or exact return envelope, but for a read-only listing tool the provided behavioral detail is strong.

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. The 800+ objects detail justifies why the result is trimmed, and the filtering guidance is compact. Every sentence earns its place and 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?

Given no annotations and no output schema, the description supplies the necessary context: what the tool lists, what fields it returns per object, how large the result may be, and how to narrow it. An agent has enough information to select and invoke this tool correctly without additional inference.

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 schema. It does: custom_only is explained as a boolean filter for limiting to custom objects, and name_contains is defined as a case-insensitive match on name or label. Both optional parameters are fully semantically described despite the empty schema descriptions.

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

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

States a specific action: 'List objects available in the org (global describe)' and explicitly frames the use case as 'for discoverability.' The global-scope wording distinguishes it from single-object siblings like sf_describe_object, and the tool name reinforces the resource. Purpose is unambiguous and not tautological.

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?

Clearly describes when to use the tool (discoverability) and how to narrow results with custom_only and name_contains, including exact matching semantics. It does not explicitly name alternatives or say when not to use this tool versus sf_describe_object, so it stops short of a 5.

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

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

With no annotations, the description carries the behavioral burden. It signals a read-only report operation and warns that it is 'heavier' and 'broader', implying a potentially costly call. It lists exactly what data will be collected, which is useful for setting agent expectations.

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 tightly written in two clear parts: what the tool reports, then when to use it versus the sibling. Every sentence adds either content or routing guidance, and the key distinction 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 no-argument, read-only diagnostic tool, the description fully covers what the agent needs to select and invoke it appropriately. It names the included data categories, warns about cost, and directs the agent away from inappropriate use. No output schema exists, but the description compensates by describing the report scope.

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 there is nothing for the description to explain about arguments. Without any invocation parameters, the description's focus on scope and purpose suffices.

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

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

The description uses the specific verb 'Report' with the resource 'org's overall health' and enumerates concrete content areas: org type, API/storage/async limits, and license seat usage. It clearly distinguishes itself from sibling sf_api_usage by framing itself as a heavier, broader report.

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?

Explicit usage guidance is provided: use this for 'what does this org have and how much of it is used' and not for a quick mid-conversation limit check. The alternative sf_api_usage is named and its narrower scope is described.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses an important behavior: automatic following of nextRecordsUrl to return the full result set despite Salesforce page limits. This goes beyond what a basic 'run query' description would provide.

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

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

The description is concise, front-loaded with the primary purpose, and uses a second sentence for an important behavioral detail. Every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description covers the core invocation detail and the key pagination behavior. It is slightly incomplete around when to prefer sf_bulk_query for very large result sets, but otherwise adequate.

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 description does little to compensate. It mentions 'SOQL query' but provides no examples, syntax hints, constraints, or additional meaning for the 'soql' parameter beyond its 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?

The description uses a specific verb ('Run a SOQL query') and names the resource and outcome ('return matching records'). It is clear about what the tool does, though it does not explicitly differentiate itself from siblings like sf_search or sf_bulk_query.

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 is given about when to use this tool versus alternatives such as sf_search or sf_bulk_query. The description provides no context for choosing between the query, search, or bulk query 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?

With no annotations, the description carries the full burden. It discloses the core behavior: executing a raw SOSL query and grouping results by object type. The example also clarifies expected input format. However, it does not address potential side effects, error behavior, permissions, or rate limits; the read-only nature is implied by 'search' but never stated.

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 tight and well-structured: a one-line definition, a concrete example, and a comparative note about sf_query. Every sentence adds value and the example is placed immediately after the core statement, making the tool's usage understandable at a glance.

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 no output schema, the description covers the operation, the result shape, and how it differs from a sibling. The example further grounds the expected input. It is not fully exhaustive—missing explicit mention of authentication or error handling—but for this tool's simplicity it is sufficiently complete.

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

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

The input schema provides only the parameter name 'sosl' with no description, so the description must compensate. It does so by explaining the tool runs a raw SOSL search and giving a concrete SOSL example with FIND, IN, and RETURNING clauses. This is sufficient for an agent to understand that the parameter expects a full SOSL query string, though a direct parameter description would have been ideal.

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: 'Run a raw SOSL search' and states the output behavior ('return matching records grouped by object type'). It clearly differentiates from sibling sf_query by noting SOSL searches keywords across multiple object types and text fields, whereas SOQL requires exact object and field matches.

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 useful decision guidance by positioning itself as a complement to sf_query and explaining the difference between SOSL and SOQL. It implies when to use this tool (multi-object keyword search) but does not explicitly state when not to use it or name fallback conditions, though the contrast with sf_query is fairly clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the action. It does not explain whether the update overwrites all fields, how missing records are handled, whether field-level security applies, or what the response contains. The mutation impact is disclosed only at the most basic level.

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

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

The description is a single precise sentence with no wasted words and the verb is front-loaded. It is not bloated or repetitive, though it omits explanatory detail that would improve usability. Within the conciseness dimension alone, it is strong.

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

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

The tool has three required parameters, no output schema, and no annotations, so the description needs to provide enough context to invoke it correctly and understand the result. It covers only the core purpose, leaving out parameter semantics, response shape, and update behavior. An agent would need additional documentation to use this confidently in a complex CRM workflow.

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 should compensate, but it only hints at 'field values' for the fields parameter. It does not explain that record_id is a Salesforce ID, that sobject must be an API object name, or that fields is a map of field names to values. The parameter names are self-explanatory, but the description adds little meaning beyond them.

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 clear action ('Update') on a clear resource ('an existing record's field values'). It distinguishes from create/delete siblings by emphasizing 'existing record', but it does not explicitly contrast with upsert or query tools. The meaning is unambiguous for a basic update operation.

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 is provided about when to use this tool instead of sf_upsert_record, sf_create_record, or sf_query. There is no mention of prerequisites, record existence checks, or suitability relative to composite operations. The agent must infer usage from the tool name 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?

There are no annotations, so the description must carry the behavioral burden. It does disclose the idempotent behavior and duplicate-free guarantee, which is valuable. However, it does not mention what happens on error, whether existing field values are overwritten, or any permission/response details.

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 brief and front-loaded: the first sentence states the core action, and the second adds the critical idempotency guarantee. Every sentence earns its place with 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?

With no annotations, no output schema, and 0% parameter schema coverage, this is incomplete for an agent to invoke reliably. It lacks information about return values, error cases, required field behavior on create, and what happens when the external ID matches multiple records.

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 would need to explain the parameters, but it only clarifies the external ID concept. It does not define sobject, fields, or the exact relationship between external_id_field and external_id_value well enough to fully compensate for the missing schema 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?

The description uses a specific verb phrase 'Create or update a record identified by an external ID field,' clearly naming the resource and the identifying mechanism. It also distinguishes itself from the sibling tools sf_create_record and sf_update_record by combining both operations into an upsert.

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 clear usage context: the standard idempotent create-or-update integration pattern, and explicitly states it is safe to call repeatedly with the same external ID. It does not explicitly name alternative tools or exclusion cases, but the context is strong enough for an agent to infer when this tool is appropriate.

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