Bulk Import Records (Bulk API 2.0)

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

Annotations already indicate readOnlyHint false and destructiveHint false, so the tool is known to be mutable but not purely destructive. The description adds useful behavioral context by stating it polls until the job completes and returns success/failure counts, but it does not disclose failure handling or authorization requirements. This is acceptable but not exceptional given annotation coverage.

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 four sentences and front-loaded with the core purpose, but the CSV instruction is both inaccurate and unnecessary, adding noise. The structure flows logically from purpose to operations to special handling, but the extraneous sentence and lack of error handling details make it only average.

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

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

With no output schema, the description should explain return values; it only says 'returns success/failure counts' without detailing the structure. It covers operation types, large datasets, external ID, and polling, but misses critical context like requiring record IDs for delete operations and how to interpret failure details. Given the tool's complexity and the presence of specialized siblings, this is a moderate gap.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds an explanation for externalIdField, but it also states 'Provide CSV data with a header row,' which directly contradicts the schema's expectation of an array of record objects. This misleading instruction undermines parameter clarity, reducing the score below baseline.

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

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

The description clearly states the tool bulk imports records using Salesforce Bulk API 2.0 and supports insert, upsert, update, and delete operations, distinguishing it from specialized bulk tools like sf_bulk_insert_records. However, the mention of 'Provide CSV data with a header row' conflicts with the JSON array schema, slightly muddying the core purpose.

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

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

The description implies usage for large datasets and notes that it polls until completion, but it does not explicitly mention when to use this tool over specialized siblings (e.g., sf_bulk_insert_records) or exclude scenarios. The guidance is contextual but lacks clear when-not-to-use instructions.

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