export_doc

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

With no annotations provided, the description carries the full behavioral burden. It discloses the side effect of writing files to outDir, describes how each format behaves (zip directory tree, self-contained html, markdown with inlined images), and states that it exports only the current head version (no history or version switching). It does note that files are written directly, though it omits explicit statements about overwriting behavior; still, it is transparent about core behaviors.

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 block but is efficiently packed: it starts with the core action, then enumerates the three format behaviors, and closes with the comparison to the browser download button. Every sentence adds value (format details, service independence, and comparison), and there is no filler. It is slightly dense but appropriately structured for the needed information.

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 the tool's complexity (multiple output formats, 5 parameters) and the absence of an output schema and annotations, the description is remarkably complete. It covers all format behaviors, file naming, directory handling, the non-requirement of the preview service, and its relationship to the UI export button. It does not mention the return value (e.g., written file path), which is a minor gap, but overall it equips an agent to invoke the tool correctly.

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 80%, and the description compensates by elaborating each format enum with concrete output details (e.g., zip exports preview.html + lib/ + assets/ without history; html is self-contained with inlined images; markdown uses data URIs and is importable elsewhere). It also explains outDir resolution relative to dir and the default directory logic from the 'dir' parameter. The only parameter without a schema description, docId, is contextualized in the description as the document identifier, bridging the gap.

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 opens with a precise verb+resource statement: '把一篇文档的当前（head）版本导出成一个文件' (export a document's current head version to a file). It specifies the output destination (outDir) and file naming rule (auto from title). It also distinguishes itself from the related 'export_canvas' sibling by noting it shares logic with the document page's export button, making its scope unmistakable.

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 gives clear context for use: it writes to a specified directory rather than triggering a browser download ('直接写到你指定的目录'), and clarifies it does not require the preview service ('不需要 protoflow 的预览服务'). It implicitly directs users to this tool when programmatic file export is needed, but it does not explicitly name an alternative or state when *not* to use it, so a 4 is appropriate.

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