bulk_create_records

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

The description discloses behaviors beyond annotations: it returns a rollback_token, tracks all created sys_ids, deletes already-created records on mid-way failure when rollback_on_error=true, supports dry_run, and requires WRITE_ENABLED=true. These are not captured in the annotations.

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

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

Three concise sentences, front-loaded with the primary action. No wasted words; covers purpose, rollback semantics, and prerequisites efficiently.

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 output schema, the description mentions the key return elements (created sys_ids and rollback_token) and covers essential behaviors. Missing details like exact response structure or batch size limits, but overall sufficient for a bulk create operation.

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 100%, and the description adds minimal parameter-specific meaning beyond restating the behaviors of rollback_on_error and dry_run. The schema already describes each parameter, so the description does not significantly enhance parameter understanding.

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 function: bulk-creating records in a single table, distinguishing it from single-record create tools like create_record. It also mentions key outputs (sys_id tracking, rollback_token) and features (dry_run).

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

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

The phrase 'Create many records in one table in a single call' implies when to use this over single-record tools. It also specifies a prerequisite (WRITE_ENABLED=true) and describes rollback behavior when rollback_on_error is set, but doesn't explicitly name alternative tools for single-record creation.

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