platform_import_export

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly describes that import is destructive and requires confirmation, explains the preview and apply flow, and mentions the accepted input forms (data.files, files, path). It also names the export output (file map + manifest). This is strong coverage for a mutation tool, though it doesn't detail edge cases like rollback behavior or permission requirements.

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 a single dense paragraph with some redundancy (e.g., the opening sentence about Arch Build is not specific to this tool's core function). The key actions are listed but not front-loaded; the description could be restructured to put the import/export purpose and actions first. It is informative but not optimally concise.

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 10 parameters, 4 actions, and nested objects, the description provides a solid high-level overview: it explains the action types, the preview/confirm flow, and the input methods. It does not cover every parameter, but since schema coverage is high and each parameter has descriptive comments, that load is carried by the schema. The description is complete enough for correct tool invocation.

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 description coverage is 90%, so the schema already documents most parameters. The description adds valuable synthesis by grouping the three alternative input mechanisms (data.files, files, path) and clarifying that confirm is for destructive imports. This goes beyond the schema's individual parameter descriptions and helps the agent choose the right input format.

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 is for importing and exporting projects, enumerates the four actions with brief one-line purposes, and distinguishes it from the broader Arch Build operations mentioned in the first sentence. An agent can immediately understand what this tool does and how it differs from siblings like platform_projects or platform_project_builder.

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 provides clear context that this tool handles project import/export and outlines the typical flow (export_preview then export, import_preview then import). However, it does not explicitly compare to sibling tools or state when NOT to use this tool versus alternatives like platform_projects for simple project management. The guidance is clear but lacks explicit exclusions.

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