beel_preview_customer_import

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

The prose is genuinely informative about behavior — no writes occur, and the per-record outcome mirrors what the real import would produce, which is valuable context beyond the schema. However, it conflicts with the supplied annotations: readOnlyHint=false and idempotentHint=false imply a mutating, non-repeatable call, while the description says nothing is written and the result is a deterministic parse of the same input.

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 core message is front-loaded in the first sentence and the total length is small. The single-bullet list for one parameter plus the trailing endpoint/docs footer feels slightly over-structured for the amount of content, but nothing is padded.

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 carries the burden of describing the return and does so conceptually ('the same per-record outcome the import would produce'), which is the key fact for a dry-run tool. The nested `body.file` payload shape and any error/limit behavior for large files remain unaddressed.

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 50% and the schema already explains `company_id` in depth and `body.file` as UTF-8 CSV text with a header row. The description only adds that `source` travels in the body exactly as in the import — a small clarification — and says nothing about the `file` payload or the enum values (`csv`, `holded`).

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 leads with a specific verb+resource pair — 'Parses and validates the file without writing anything: no customer is created' — and explicitly separates itself from the write path by naming `POST .../customers/imports`. An agent can distinguish this from beel_create_customer_import without opening either 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?

It states the workflow role clearly: run the preview 'so the caller can correct the data before importing it,' and names the follow-up endpoint as the alternative. There is no explicit when-not guidance (e.g. versus beel_preview_account_import or the bulk-create tool), so it stops just short of full routing.

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