Prepare Spreadsheet Import

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds meaningful non-obvious behavior: idempotency key stability, that browser mode is a handoff for clients that cannot upload bytes, and that direct mode returns an S3 multipart POST. It does not mention auth requirements or the 10MB ceiling, which are left to the schema.

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 tight sentences, front-loaded with the purpose and followed by the mode decision and the scope boundary. No filler, but the fragmented phrasing ('Choose browser handoff...; direct mode returns...') makes it slightly harder to parse than necessary.

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 prepare/creation tool with no output schema, the description explains both modes but never says what the call returns (import id? upload URL?) or which sibling to call next, so an agent cannot fully chain the flow from this text alone.

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?

With 0% schema description coverage, the description must carry parameter meaning. It explains the idempotency_key's purpose and the upload.mode branching semantics well, but leaves campaign_id, byte_size (10MB max), filename constraints, and checksum_sha256 format entirely to the pattern/limit metadata in 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 and resource ('Prepare a CSV/XLSX campaign import') and explicitly scopes itself against the downstream action: 'This does not start the import.' An agent can distinguish this from confirm_campaign_creator_import and get_campaign_creator_import without opening any 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?

Gives explicit mode-selection guidance: 'Choose browser handoff when the client cannot upload bytes; direct mode returns an S3 multipart POST.' It also clarifies the boundary that the import is not started here. It does not name the sibling to call next (confirm_campaign_creator_import), which keeps it from a 5.

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