connector_salesforce_bulk_ingest_upload

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

With annotations already marking destructive, not-read-only, and idempotent behavior, the description adds useful governance context: it "routes only through the exact project/account governed connector authority", effect is verified by Spring, and write resumption requires an approval_ref. This goes beyond the raw annotation booleans and is consistent with them. It does not detail the mutating Salesforce-side consequences, but annotations already signal destructiveness.

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: a routing constraint followed by a clean Args list with no filler. The first line is somewhat redundant with the tool name, but the rest is economical. It is appropriately sized for a wrapper tool.

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 seven-parameter generic connector wrapper with 0% schema description coverage, key operational context is missing: there is no statement of what a valid `arguments` payload looks like, when approval_ref is mandatory, or how this step fits with bulk ingest create/status/results/close. An output schema exists, so return values need not be described, but the missing lifecycle and payload guidance leaves an agent unable to call this tool confidently.

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 Args list provides brief definitions for all seven parameters, which is helpful given 0% schema description coverage: project_id, connector_account_ref, idempotency_key, effect, and approval_ref get useful one-line meanings. However, the central `arguments` parameter is defined only as "JSON string of arguments for the connector operation", which is circular and leaves the actual upload payload unspecified. This is minimum-viable parameter explanation, not rich guidance.

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 line merely restates the tool name as "Salesforce connector operation `bulk_ingest_upload`" and never says what the operation actually does, such as uploading CSV records to a Salesforce bulk ingest job. The only extra behavior is the routing constraint, which is governance context rather than purpose. Compared with the many Salesforce sibling tools, this does not distinguish its function.

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 sentence explains when to choose this tool over connector_salesforce_bulk_ingest_create, _status, _results, or _close. The mention of "approval_ref: Approved platform task UUID when resuming a write" hints at a write workflow, but there is no explicit lifecycle guidance or alternative exclusions. An agent cannot infer the correct call sequence from this description alone.

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