protoflow

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

With no annotations provided, the description carries the full burden and it delivers: it details side effects (freezing artboards to .build/snapshot/, creating versions/<n>/, re-rendering preview.html), prerequisites (doc.md written, screenshots sealed), the constraint that note is required and must not include a version number, and that error-level findings block publication at record_publish. This exceeds what the schema or annotations convey.

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 dense but every sentence carries operational value — mode semantics, prerequisites, side effects, output semantics. It is front-loaded with the core purpose ('构建文档版本，两阶段'), though the single-paragraph wall of text would benefit from bullet separation for the two modes.

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 7-parameter mutation tool with no output schema, the description covers inputs, workflow, prerequisites, side effects, return url, and downstream gating by record_publish. It does not fully specify what 'checks' run or what label/author mean, but overall the agent has enough context to invoke both modes 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 only 29% (dir and projectId documented). The description compensates substantially for mode, explaining both enum values in detail, and for note, adding the requiredness, single-sentence rule, and purpose in the modification table. docId's meaning is implied through file paths. However, label and author receive no explanation in either schema or description, so it does not fully compensate.

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?

Description opens with '构建文档版本，两阶段' (build document version, two stages) — a specific verb+resource+process. It names the two modes, snapshot and finalize, and references the sibling tools build_publish_pack and record_publish, situating build_doc in the workflow. This lets an agent distinguish it from create_doc or export_doc.

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?

Provides explicit guidance on when each mode applies: snapshot only for doc types needing canvas screenshots, finalize after doc.md is hand-written and screenshots sealed, and pure prose changes can finalize directly reusing .build/ artifacts. It does not explicitly list alternative tools to choose instead, but the mode-level workflow is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses several behaviors: it uses headless Chrome, downloads Chrome only if not found (no popup), operates on specific file paths, writes output files, and may skip steps for complex interactions. It doesn't disclose failure modes or side effects (e.g., what happens if captures.json is missing), but the provided detail is substantial and goes beyond what the schema offers. Not a 5 because it omits some edge cases.

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, front-loaded with the overall purpose, but it lacks structure. It uses semicolons and colons to separate modes, but the flow is hard to scan quickly. Each sentence carries technical detail, but it could be broken into bullet points for clarity. It's not verbose, but the density hurts readability and quick parsing for an agent.

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?

This is a complex multi-mode tool with no output schema, but the description covers the main steps: file inputs, rendering, browser interaction, and output files. It doesn't specify return values or success criteria, but the absence of an output schema and the focus on side effects (writing files) means the agent can infer the result from file existence. The main gap is lack of error handling and prerequisites, but given the complexity, the description is largely complete.

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?

The schema covers projectId and dir with descriptions, but docId is undocumented. The description adds meaning by explaining the file paths and the modes, which clarifies the parameters' roles. For instance, it explains that docId is used in paths like docs/<docId>/.build. It compensates for the 50% coverage by providing enough context to infer docId's purpose. Slight deduction because there is no explicit mapping of each parameter to its use, but the paths imply it.

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 what the tool does: it is a three-stage pipeline for taking canvas screenshots and publishing them as assets. It names the specific modes (previews, capture, seal) and the resources involved (docs/<docId>/.build, assets). This clearly distinguishes it from siblings like render_preview or export_canvas, which are likely single-stage operations. The action is specific and the scope is well-defined.

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 explains the three modes: previews for validation, capture for automated screenshots, and seal for finalizing. It mentions that capture is optional for complex interactions and that manual screenshots can be used instead. However, it does not explicitly state when to use this tool versus alternatives like render_preview or export_canvas, and it lacks explicit exclusions or conditions for when NOT to use it. The context is clear but the decision boundary is implicit.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers a solid contract: the output is a per-item list with reason and suggestedAction, sorted by a defined severity hierarchy, and the verb 计算 strongly implies a non-mutating report. It does not explicitly state read-only or no-side-effect guarantees, but for a status tool the behavioral profile is largely disclosed.

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 entire description is a single dense sentence that front-loads the purpose, then enumerates the severity taxonomy and output fields with no filler. The nested parenthetical severity definitions are packed to the point of being slightly hard to skim, which prevents a perfect 5.

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 simple 2-parameter diagnostic tool with 100% schema coverage, the description covers the essentials: what is computed, the sort order, the meaning of each severity tier, and the shape of each result item. With no output schema and no annotations, it would be stronger still if it defined what the '链' is and explicitly confirmed no side effects, but nothing critical is missing.

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 100%: projectId is documented as the project id/folder name, and dir is documented with its default resolution (PROTOFLOW_HOME or startup cwd). The tool description itself adds no parameter-level semantics, so the baseline of 3 applies.

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 highly specific verb+resource — 计算整条链的过期清单 — and then enumerates five severity tiers with definitions (broken > unvalidated > review > drifted > lagging) plus the output contract (每项含 reason 与 suggestedAction). This specificity makes it unmistakable against 20 siblings, none of which perform chain-health diagnosis.

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?

No explicit when-to-use or alternative-routing guidance is provided. The severity ordering implies a diagnostic / pre-flight role before building or publishing, but an agent must infer that context rather than being told which sibling to prefer in which situation.

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

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

No annotations are provided, so the description carries the full burden. It discloses error behavior for unknown kinds, default naming behavior, side effects of title on doc.md and doc.json, and from being recorded in doc.json.origin affecting chain_status. It does not state overwrite behavior when docId already exists, which is a minor gap.

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 purpose is front-loaded and every clause adds necessary operational detail without filler. It is a single dense run-on paragraph and would benefit from bullet structure, but it remains efficient for the amount of behavior it needs to convey.

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?

The description covers all parameters, default behavior, error behavior, file layout, and the next workflow step (build_doc finalize). There is no output schema, but the deterministic file structure and side effects make the result predictable. It lacks explicit mention of the return value or overwrite behavior, but overall it is complete enough for correct 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 only 33%, but the description compensates fully by explaining kind (directory, defaults, errors), docId (default and when to override), title (content constraints and side effects), and from (examples, version semantics, origin field). dir and projectId are already described in the schema, so all parameters are effectively covered.

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 concrete action: creating a new document under docs/ with docs/<docId>/ containing doc.md and doc.json. It clearly identifies the tool's scope and differentiates it from siblings like build_doc by describing creation versus finalization, while detailing kind/docId/title/from semantics.

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?

Provides clear usage conditions: docId defaults to the kind name, explicit docId is only needed for multiple docs of the same type, unknown kinds error out and list available kinds, and the description ends by routing the agent to build_doc(mode:'finalize') for the first version. It lacks explicit 'do not use this tool when...' exclusions but the context is clear.

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

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

No annotations are provided, so the description carries the full burden. It transparently discloses key behaviors: creating a folder in the working directory, automatic numbering on name conflicts, writing two agent-handoff files, and returning the folder name as the project id. It does not mention error handling or permission requirements, but the core side effects are clearly stated.

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 sentence that front-loads the purpose and follows with the conflict-resolution rule, file creation, and return value. No filler words; every clause adds necessary 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?

With no output schema and no annotations, the description compensates by explicitly stating the return value and folder behavior. It covers conflict handling and file creation, which are the key edge cases for a creation tool. Minor gaps like what happens on invalid paths or directory creation failures do not undermine the essential completeness for an agent to use it 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema: it reveals that 'name' is slugified to produce the folder name, and implicitly explains the default directory behavior mentioned in the dir parameter. This extra insight raises the score to 4.

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 states a specific verb and resource: '创建新项目' (create new project), and details what it does: create a self-contained folder named after a slug of the project name, write AGENTS.md/CLAUDE.md, and return the project id. This clearly differentiates it from siblings like import_project or list_projects.

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 implies usage for starting a new project and mentions cold-start handoff for any agent, but it does not explicitly state when to use this tool versus alternatives (e.g., import_project) or provide any exclusions. The usage context is inferable, not explicit.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the destructive mutation, the cascade from page to artboards, the warning when a document-version screenshot references the target, and the need to refresh open canvas tabs. It does not mention reversibility or auth requirements, but the delete semantics are explicit.

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 compact and front-loaded: the core action and id rules come first, followed by the warning edge case and the post-action refresh step. Every sentence carries useful information and none is redundant.

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?

The description covers target types, id prefixes, cascading deletion, the reference warning, and the observable result after deletion. Since there is no output schema, it does not specify the success response shape, but for a destructive delete call this is a minor gap given the clear behavioral details.

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?

The schema describes projectId and dir but leaves targetId undocumented; the description compensates by specifying pg_/ab_ prefixes and the page-vs-artboard distinction. This adds real meaning beyond the schema, though it adds nothing for dir beyond the schema's own coverage.

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 uses a specific verb ('删除'/'delete') and identifies the exact resources: pages with pg_ prefix and artboards with ab_ prefix, including the cascading behavior for pages. This clearly distinguishes it from sibling upsert tools such as upsert_page and upsert_artboard, which create or update rather than delete.

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 makes it clear when to use the tool: to delete a page or artboard by id, with the prefix rule telling the agent which id form maps to which target kind. It does not explicitly name alternatives or when-not-to-use conditions, but no sibling deletion tool exists, so the usage context is effectively implied.

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

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

With no annotations, the description carries the full burden and does well: it discloses where files are written, that annotation positioning/highlighting silently fails under file://, and that html inlines all artboards and libraries. However, it does not mention overwrite behavior or what the tool returns/confirms after writing, which would be useful for a file-export operation.

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 purpose is front-loaded and nearly every clause contributes decision-relevant information. The text is dense and slightly run-on, mixing format tradeoffs and behavioral caveats in one paragraph, but it avoids fluff and is much more useful than a short generic sentence.

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 two-format file-export tool with no output schema, the description covers the essential choices, output structure, known failure mode, and similarity to render_canvas. The main gaps are overwrite semantics and any success/failure return value, which an agent might need to confirm the operation's result.

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%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the zip vs html format consequences in depth, the file:// caveat, and the automatic project-name-based file naming. It adds little for projectId or dir, but those are already well-described 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?

The description opens with a concrete action and resource: '把整张画布导出成一个文件，写到 outDir 下', then enumerates the two formats. It also differentiates from render_canvas by stating the same rendering logic is reused but persisted once, so export and preview cannot be confused.

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 explicit format-selection guidance: zip is the default directory-tree export, while html is the self-contained, double-clickable option with tradeoffs explained. It contrasts with render_canvas and the browser export button, but it does not crisply state when to use export_doc or other siblings instead.

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

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this exceptionally well: it documents what every returned field means, notes that elementHints are statically extracted from source and may be inaccurate, and defines brokenRefs. This is far more transparent than a typical one-line description and gives the agent accurate expectations.

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 sentence with semicolon-separated fields, and every segment adds distinct information. The critical warning about elementHints is embedded without bloat. It is longer than ideal, but the structure is clear and there is no waste, so it earns a high score.

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?

There is no output schema, so the description must explain return values — and it does so comprehensively. It covers all seven return fields, their meanings, provenance, and reliability caveats. For a read tool with this complexity, nothing essential is missing, and the agent can correctly interpret the result.

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?

The schema already describes dir and projectId, covering 67% of parameters. The description adds little direct parameter meaning beyond referring to '这块画板' (this artboard), which implicitly maps to artboardId. Since the description does not compensate for the undocumented artboardId, the score stays at the baseline for moderate schema coverage.

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 '返回这块画板的标注' (Returns annotations for this artboard), a specific verb and resource, then enumerates the exact return fields (md, refs, elementIds, elementHints, sourceHash, validatedHash, brokenRefs). This makes the tool's purpose unmistakable and naturally distinguishes it from write_annotations and other sibling tools.

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 offers practical usage notes, such as warning that elementHints are only guesses and should not be directly used as display names, and it explains dir resolution behavior. However, it never explicitly states when to choose this tool over alternatives like write_annotations or get_guide; the context is implied rather than clearly routed.

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

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

With no annotations, the description carries the burden and it does disclose useful behavior: the exact return contents, the instruction to call before writing, and the error behavior for unknown types. It does not explicitly state there are no side effects, but the read-only nature is strongly implied by '返回'.

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?

Two sentences pack the return contents, usage timing, and error behavior with no filler. The most decision-relevant information is front-loaded.

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 simple retrieval tool with no output schema, the description gives enough to call it correctly and interpret the result: what is returned, when to call it, and how unknown input is handled. A fuller return structure would be nice but is not essential.

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 describes projectId and dir; kind is undocumented. The description partially compensates by clarifying that kind is the document type and that unknown values produce an error listing valid types, but it adds nothing about projectId or dir beyond 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?

The description names a specific verb ('返回') and a specific resource: the starting template, writing guidelines, and metadata for a document type. It is clearly distinct from sibling tools like create_doc or build_doc, though it does not explicitly name an alternative.

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 a clear, actionable precondition for use. It does not mention when not to use it or name alternatives, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the disclosure burden. It discloses the unknown-topic behavior (error lists all available topics) and clarifies that the topic maps to a filename without extension. It doesn't mention output formatting or side effects, but for a simple read-only retrieval this is sufficient.

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?

Two sentences with no wasted words: purpose is front-loaded, the parameter format is stated compactly, and the sibling distinction is included. Every sentence adds value.

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 one-parameter read tool with no output schema, the description covers purpose, parameter semantics, failure behavior, and the relevant alternative. Nothing needed to call it correctly is missing.

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 0%, so the description must compensate. It fully defines the single parameter: topic is the filename under guides/ without .md, and notes that unknown topics produce an error listing all valid topics. This is complete semantic coverage.

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 uses a specific verb ('返回') and resource ('策略文档全文'), and defines the input as a topic corresponding to a filename under guides/. It also explicitly differentiates itself from get_doc_kind, making the tool's purpose 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?

It gives an explicit routing rule: use get_doc_kind for document-type-specific templates/specifications, and not this tool ('不在这里'). This is a clear when-not and alternative, leaving no ambiguity about which sibling to choose.

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

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

With no annotations, the description carries the full behavioral burden. It does add useful context beyond the schema: sourcePath values are absolute and directly readable by file tools, and the health summary contains counts by severity. However, it does not explicitly state that the operation is read-only, what happens for missing projects, or any error/authorization behavior.

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 compact sentence that leads with the action and return type, then packs meaningful specifics into parentheticals. Every element adds value and there is no redundancy.

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?

There is no output schema, so the description must explain return values, and it does: project tree hierarchy, sourcePath semantics, and health summary counts. It could enumerate the exact severity levels or response shape, but it provides enough detail for an agent to know what this tool returns and when to call it.

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 100%, with detailed explanations for both dir and projectId, including dir's fallback resolution behavior. The tool description itself adds no parameter-level meaning, so the baseline of 3 is appropriate.

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 a specific verb and resource: it returns a project tree with page/artboard hierarchy and a pipeline health summary. It conveys concrete contents (sourcePath absolute paths, severity counts) that distinguish it from simpler sibling tools like list_projects, though it never names an alternative.

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?

No when-to-use guidance, exclusions, or alternatives are provided. The reader must infer that this tool is for inspecting a project's structure and health; it does not say when list_projects or other sibling tools would be preferred.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the source directory is read-only, that it writes a fingerprint baseline and AGENTS.md/CLAUDE.md files, and that it errors when the target already contains a project with the same id. This is strong behavioral disclosure, though '补写' could be more explicit about whether existing files are overwritten or appended.

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?

A single dense sentence conveys purpose, source format, safety behavior, side effects, and an error condition without wasted words. All clauses earn their place and the core purpose is front-loaded.

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 moderate complexity, no output schema, and no annotations, the description covers the essential aspects: input format, read-only source behavior, target side effects, and duplicate-id failure. Minor gaps remain around the exact meaning of 'fingerprint baseline' and the return value, but nothing critical is missing for invoking 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 100%, so the schema already documents both parameters well. The description adds contextual meaning about sourceDir being an external existing project and dir being the working directory, but it does not add significant param-level detail beyond the schema. Baseline 3 is appropriate.

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 states a specific verb and resource: importing an external existing protoflow project directory (project.json + pages/ layout) into the working directory. It also distinguishes itself from siblings like create_project by emphasizing the source is an existing external project and by mentioning the duplicate-id error condition.

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 gives clear context for when to use the tool: importing an already-existing external protoflow project. It does not explicitly name alternatives or say 'do not use for blank projects', but the 'external existing project' framing and duplicate-id error imply that create_project is for new projects.

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

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

With no annotations, the description carries full burden. It clarifies that id is the folder name and that dir overrides the default, but it doesn't disclose return format, potential errors, or side effects. This is adequate but not rich.

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 concise and front-loads the main purpose, with the parameter clarification in parentheses. Every sentence earns its place, though it could be more structured.

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 simple listing tool with 1 optional parameter and no output schema, the description is mostly complete. It could mention return format or whether it includes hidden projects, but the essentials are covered.

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%, so the schema fully documents the dir parameter. The description adds context on default resolution and relative path handling, but mostly repeats what the schema already states; baseline 3 is appropriate.

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 lists all projects in the working directory with id and name, and that id is the folder name. It distinguishes from siblings like get_project and create_project, though it doesn't explicitly name alternatives.

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 implies usage for listing projects, and the dir parameter provides context on overriding the default directory. However, it does not explicitly state when to use this versus siblings or any exclusions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses append-history semantics, finalization requirement, execution of type-specific checks, default blocking with a listed checklist, and the acknowledgeFindings bypass. This is substantial behavioral context beyond the tool name and 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?

The description is dense but fully front-loaded: the action appears first, followed by duplicate behavior, a failure condition, and the check gating. Every clause earns its place with no filler.

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 and no annotations, the description supplies the key preconditions, side effects, and error paths an agent needs. The main missing piece is what a successful call returns or how success is confirmed, but this is a minor gap for a registration-style tool.

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 only 29%, so the description must compensate. It does clarify channel/channelDocId/url as the published record and acknowledgeFindings as the check bypass, but it leaves docId's role implicit and provides no detail for dir beyond the schema entry.

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: '登记一次渠道发布到当前文档 head 版本' (register a channel publication to the current document head revision). It also clarifies duplicate-publish behavior, making it clearly distinct from sibling build/export tools.

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?

Provides clear preconditions and routing context: the document must be finalized or the call errors, and error-level findings block by default unless acknowledgeFindings is passed. It does not explicitly name sibling alternatives, so it stops short of a 5.

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

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

The description discloses several important behaviors: it requires the local preview service to be running, it returns a URL (not a file path), the canvas is self-contained, navigation is in-document (no page jumps), zoom/pan interactions are specified, artboards display at real pixel width, and it is a live projection that does not write to disk. Since no annotations are provided, the description carries the full burden, and it does so thoroughly. It could add a bit more about failure modes (e.g., what happens if the preview service isn't running), but the disclosed behaviors are rich and useful.

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 that front-loads the core purpose (open canvas, return URL) and then provides necessary behavioral details. It is long but every sentence adds useful information about how the canvas behaves and when to use it. The structure could be improved with separation of concerns (purpose vs. behavior vs. usage), but it is not bloated or repetitive.

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 tool with 2 parameters, no output schema, and no annotations, the description covers the essential context: what it does, how the returned URL should be used, how the canvas behaves, and how it stays in sync with project changes. It does not describe the exact response format (e.g., JSON shape of the returned URL), but since there is no output schema, a bit more detail on the return value could help. However, the description is largely complete for an agent to invoke it 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 100%, so the schema already documents both parameters (dir and projectId). The description adds context about dir's default resolution (PROTOFLOW_HOME or cwd) and projectId being the folder name, but this is largely restating the schema. The description does not add much beyond the schema, so baseline 3 is appropriate.

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 purpose: open the whole-site canvas and return its http://127.0.0.1 URL. It specifies the resource (整站画布), the action (打开/返回 URL), and distinguishes it from browser tools that cannot open file:// URLs. The description also explains what the canvas contains (all pages and artboards in a self-contained document) and how it behaves, making it distinct from sibling tools like render_preview or export_canvas.

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 explicitly states when to use this tool: when you need the whole-site canvas, and it warns against using browser tools with file:// paths. It also explains that the canvas is a live projection of the project's source/annotations/structure, so after changes you just refresh the opened tab rather than re-calling the tool. This gives clear usage context and implicitly distinguishes it from render_preview (which likely renders a single preview) and export_canvas (which exports rather than opens an interactive canvas).

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses no disk writes ('不写盘'), no need to re-call ('不需要重复调用'), live projection of source/annotations/structure, refresh-to-update behavior, and the historical change away from writing preview.html.

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?

Four dense but purposeful sentences, front-loaded with the main action and URL, followed by behavioral details and a historical caveat. Every sentence adds information needed to call the tool correctly or avoid an outdated workflow.

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 no-output-schema, no-annotation tool, it covers return value, side effects, update semantics, and how to access the alternate view. It does not describe failure behavior if source is missing or the preview service cannot be started, but these are minor gaps given the otherwise rich description.

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 covers projectId and dir; the description adds context that artboardId refers to a board within the project and clarifies the relationship between artboard and project. However, artboardId itself has no schema description and the description does not define its format or provenance, leaving one required parameter only implicitly specified.

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 names a specific action ('确认某画板可以在整站画布里观察'), a concrete resource (artboard in whole-site canvas), and a concrete return (http://127.0.0.1 URL). It explicitly distinguishes itself from an artboard-only address, which separates it from sibling preview/render tools.

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 gives clear context: use this to verify an artboard is visible in the whole-site canvas and to get the whole-site URL. It explains how to get the artboard-only view (hover and open new tab) and states when repeated calls are unnecessary, though it does not explicitly name an alternative sibling tool.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that artboardIds must be a complete permutation limited to the target page, warns against omitting or including foreign IDs, and explains that the open canvas tab must be refreshed to see the new order. It does not mention persistence, reversibility, or error behavior, but the core behavior is clearly conveyed.

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?

Every sentence earns its place: purpose and default behavior, the exact input constraint with a read-before guidance, and how to verify the result. There is no filler or repetition, and the most important call prerequisites are front-loaded.

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 mutation tool with no annotations and no output schema, the description covers the required call flow: which read operation to precede with, the exact contract for artboardIds, and how to confirm the result. The only notable gap is no statement about return values or failure behavior on an invalid permutation, but the description is still sufficient for correct 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 coverage is only 50%, so the description must compensate. It adds crucial semantics for artboardIds, which has no schema-level description: it must be an ordered full permutation of existing artboards on that page, and the current order should be read first. pageId remains implicit, but the overall parameter intent is substantially clarified.

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 states a specific verb and resource: it adjusts the display order of artboards on a page's canvas. It also explains the default behavior (new artboards append to the end) and clearly frames this tool as the one for reordering, distinguishing it from the read-only siblings it references.

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 usage context: use this tool when artboards need reordering, and first call a read operation like loadProjectTree/get_project to see the current order. It does not name an alternative reorder tool or explicitly state when not to use it, so it stops just short of full when/when-not guidance.

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

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

With no annotations, the description carries the behavioral burden and covers it thoroughly: Babel validation failures do not persist, successful calls return sourceHash and idAudit, and saved source is a live projection visible after refreshing tabs. It also discloses the uniqueness requirement for oldText, which is an important failure mode.

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?

Four short, dense sentences each carry a distinct fact: mode choice, validation/no-persist, return payload, and live-render implication. No filler or repetition; the core action is front-loaded.

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 and no annotations, the description covers outputs, failure behavior, mode semantics, and downstream rendering effects. This is sufficient for an agent to invoke save_artboard_source with the required parameters and understand the consequences.

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 low (40%), and the description compensates for the two complex parameters: source is full content, edits are patches with unique-match oldText, and the two modes are mutually exclusive. It does not add artboardId semantics, but the tool name and parent context make that parameter self-evident.

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?

Description opens with a specific verb and resource ('写画板 JSX 源码' / write artboard JSX source) and distinguishes the tool from rendering siblings by stating that refreshed canvas tabs already reflect the latest source and render_preview / render_canvas need not be called again.

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 gives concrete mode-selection guidance ('source 全量 与 edits 补丁 二选一') and an explicit when-not (no need to call render_preview / render_canvas). It does not mention selection against other write siblings like upsert_artboard, but the mode and persistence semantics make the intended usage clear.

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

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

With no annotations, the description carries the full behavioral burden. It discloses upsert semantics, the returned artboard id, canvasWidth default and semantics, and the live canvas projection behavior. It omits edge cases such as behavior with a non-existent id or prerequisite project/page existence, but is otherwise substantive.

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 front-loaded sentences with zero filler: behavior first, key parameter parenthetical second, then return value and rendering note. Each sentence earns its place and no word is wasted.

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 7-parameter upsert with no annotations and no output schema, the description is largely complete: it covers create/update, return value, and post-call rendering. It lacks failure-mode and precondition details, but these are not essential for basic correct 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 coverage is only 29%, but the description compensates by explaining the id create/update behavior, name/description as update fields, and canvasWidth in detail (default 1440, mobile values). PageId is implicitly clarified as the parent page from the opening sentence, and dir/projectId are already documented 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?

The description opens with a precise behavioral statement: no id creates an artboard under a page, while an id updates name/description. This clearly identifies the resource (artboard), the action (upsert), and differentiates it from sibling tools like upsert_page (page-level) and render_canvas (rendering).

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 implicitly defines when to use the tool (create/update artboards) and explicitly tells the agent not to call render_canvas afterward because the canvas updates in real time. However, it does not explicitly compare against page-level or other artboard manipulation alternatives.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the side-effect model (canvas is a real-time projection; refreshing shows new/renamed pages), the return value (page id), and explicitly preempts a redundant render_canvas call. It does not cover error/edge behavior (e.g., duplicate names, failed renames), but the disclosed behavior substantially exceeds a bare 'create or rename a page'.

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?

Two compact sentences with the core upsert logic front-loaded, followed by return value and the canvas side-effect note. Each sentence earns its place — the canvas projection detail is especially valuable because it prevents an unnecessary tool call, and there is zero filler.

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 4-parameter, no-output-schema, no-annotation tool, the description covers the primary calling path well: create/rename conditions, return format, and post-call behavior. It omits edge-case expectations such as duplicate-name handling, whether a rename is reversible, and error conditions, which leaves moderate gaps for an upsert 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 50% (dir and projectId documented; id and name bare). The description compensates for the most semantically important gap by explaining that id selects the create/rename branch — meaningful value beyond the schema. However, name (the rename target) gets no explicit meaning, and dir's behavior relies entirely on the schema description, so compensation is partial.

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 explains the upsert semantics explicitly — 'with no id create a page, with id rename' — giving a specific verb, resource, and behavioral branch. It distinguishes the tool by its page-level operation, but it never explicitly differentiates from the sibling upsert_artboard (or notes the page-vs-artboard boundary), so it stops short of full differentiation.

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 condition-based guidance: presence of id selects rename vs create, and it explicitly tells the agent not to call render_canvas afterward because the canvas is a live projection. However, it does not address when to choose this tool over alternatives such as upsert_artboard or create_project, so usage context is implied rather than fully specified.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the md/edits exclusivity, the absence of groupId/order/revision, all-or-nothing rejection on REF_NOT_FOUND, automatic setting of meta.annotationsValidatedHash, and real-time projection/refresh behavior. It omits return value and explicit overwrite semantics, but the disclosed side effects are substantial.

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 dense and monolithic, but nearly every clause adds operational information, and the first sentence front-loads purpose and the md/edits choice. A bulleted layout would improve scannability, but there is little wasted text.

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 complex write tool with no output schema, it covers formatting, validation, side effects, and freshness thoroughly. However, it never states what the tool returns or confirms on success, and it assumes the agent already knows where to find elementIds/current source, leaving a couple of invocation-critical facts implicit.

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 only 33%, and the description compensates strongly: it explains md's markdown/spec structure, display-name rules, link syntax, the edit patch shape, refs structure with interactionPath, and that element ids must be copied from elementIds. Previously undocumented parameters receive concrete, usable meaning.

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 '写这块画板的标注' (write annotations for this artboard), giving a specific verb and resource, and immediately clarifies the two payload modes (md vs edits). It does not explicitly distinguish itself from siblings like get_annotations or save_artboard_source, but the core action is unambiguous.

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?

There are rich internal usage rules: md vs edits are mutually exclusive, refs are only needed for elements appearing after interaction, and invalid references trigger REF_NOT_FOUND. However, the description never states when to choose this tool over related siblings such as get_annotations for reading or save_artboard_source for writing source, so cross-tool selection is left to inference.

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